diff --git a/site/en/_book.yaml b/site/en/_book.yaml index b2365412d83641..c437486d061bb0 100644 --- a/site/en/_book.yaml +++ b/site/en/_book.yaml @@ -86,7 +86,7 @@ upper_tabs: - title: Platforms path: /concepts/platforms - title: Hermeticity - path: /concepts/hermeticity + path: /basics/hermeticity - name: User guide heading: Guides and tutorials for learning to use Bazel @@ -229,7 +229,7 @@ upper_tabs: - name: Query language contents: - title: Query reference - path: /reference/query + path: /query/language - name: Glossary contents: - title: Glossary @@ -344,7 +344,7 @@ upper_tabs: - title: Bazel users path: /community/users - title: Nominate a recommended rule - path: /contribute/recommended-rules + path: /community/recommended-rules - title: Remote execution services path: /community/remote-execution-services - name: Getting help diff --git a/site/en/about/faq.md b/site/en/about/faq.md index e74ab4b7361b07..7d6ef7870e64d2 100644 --- a/site/en/about/faq.md +++ b/site/en/about/faq.md @@ -43,7 +43,7 @@ A long time ago, Google built its software using large, generated Makefiles. The ## Does Bazel require a build cluster? -Bazel runs build operations locally by default. However, Bazel can also connect to a build cluster for even faster builds and tests. See our documentation on [remote execution and caching](/docs/remote-execution) and [remote caching](/docs/remote-caching) for further details. +Bazel runs build operations locally by default. However, Bazel can also connect to a build cluster for even faster builds and tests. See our documentation on [remote execution and caching](/remote/rbe) and [remote caching](/remote/caching) for further details. ## How does the Google development process work? @@ -160,17 +160,17 @@ Further details on exit codes are in the [User Manual](/docs/user-manual). ## What future features can we expect in Bazel? -See our [Roadmaps](/community/roadmaps). +See our [Roadmaps](/about/roadmap). ## Can I use Bazel for my INSERT LANGUAGE HERE project? Bazel is extensible. Anyone can add support for new languages. Many languages are supported: see the [build encyclopedia](/reference/be/overview) for a list of recommendations and [awesomebazel.com](https://awesomebazel.com/){: .external} for a more comprehensive list. -If you would like to develop extensions or learn how they work, see the documentation for [extending Bazel](/rules/concepts). +If you would like to develop extensions or learn how they work, see the documentation for [extending Bazel](/extending/concepts). ## Can I contribute to the Bazel code base? -See our [contribution guidelines](/contribute/guide). +See our [contribution guidelines](/contribute/). ## Why isn’t all development done in the open? diff --git a/site/en/about/intro.md b/site/en/about/intro.md index 8e33166b3fa152..0a41569e925d93 100644 --- a/site/en/about/intro.md +++ b/site/en/about/intro.md @@ -69,7 +69,7 @@ To build or test a project with Bazel, you typically do the following: places your outputs within the workspace. In addition to building, you can also use Bazel to run -[tests](/reference/test-encyclopedia) and [query](/docs/query-how-to) the build +[tests](/reference/test-encyclopedia) and [query](//query/guide) the build to trace dependencies in your code. ## Bazel build process {:#bazel-build-process} @@ -80,7 +80,7 @@ When running a build or a test, Bazel does the following: 2. **Analyzes** the inputs and their [dependencies](/concepts/dependencies), applies the specified build - rules, and produces an [action](/rules/concepts#evaluation-model) + rules, and produces an [action](/extending/concepts#evaluation-model) graph. 3. **Executes** the build actions on the inputs until the final build outputs @@ -89,24 +89,24 @@ When running a build or a test, Bazel does the following: Since all previous build work is cached, Bazel can identify and reuse cached artifacts and only rebuild or retest what's changed. To further enforce correctness, you can set up Bazel to run builds and tests -[hermetically](/concepts/hermeticity) through sandboxing, minimizing skew -and maximizing [reproducibility](/docs/build#correct-incremental-rebuilds). +[hermetically](/basics/hermeticity) through sandboxing, minimizing skew +and maximizing [reproducibility](/run/build#correct-incremental-rebuilds). ### Action graph {:#action-graph} The action graph represents the build artifacts, the relationships between them, and the build actions that Bazel will perform. Thanks to this graph, Bazel can -[track](/docs/build#build-consistency) changes to +[track](/run/build#build-consistency) changes to file content as well as changes to actions, such as build or test commands, and know what build work has previously been done. The graph also enables you to -easily [trace dependencies](/docs/query-how-to) in your code. +easily [trace dependencies](//query/guide) in your code. ## Getting started tutorials {:#getting-started-tutorials} -To get started with Bazel, see [Getting Started](/start/getting-started) or jump +To get started with Bazel, see [Getting Started](/start/) or jump directly to the Bazel tutorials: -* [Tutorial: Build a C++ Project](/tutorials/cpp) -* [Tutorial: Build a Java Project](/tutorials/java) -* [Tutorial: Build an Android Application](/tutorials/android-app) -* [Tutorial: Build an iOS Application](/tutorials/ios-app) +* [Tutorial: Build a C++ Project](/start/cpp) +* [Tutorial: Build a Java Project](/start/java) +* [Tutorial: Build an Android Application](/start/android-app ) +* [Tutorial: Build an iOS Application](/start/ios-app)) diff --git a/site/en/about/roadmap.md b/site/en/about/roadmap.md index 44f4d417c3dacc..ff8b0c36af819c 100644 --- a/site/en/about/roadmap.md +++ b/site/en/about/roadmap.md @@ -20,7 +20,7 @@ Q4 brings Bazel 6.0 — the new [long term support (LTS)](https://bazel.build/re ### Bzlmod: external dependency management system -[Bzlmod](https://bazel.build/docs/bzlmod) automatically resolves transitive dependencies, allowing projects to scale while staying fast and resource-efficient. Introduced experimentally in Bazel 5.0, Bzlmod will be generally available and provide a solution for the [diamond dependency problem](https://docs.google.com/document/d/1moQfNcEIttsk6vYanNKIy3ZuK53hQUFq1b1r0rmsYVg/edit#heading=h.lgyp7ubwxmjc). +[Bzlmod](https://bazel.build/build/bzlmod) automatically resolves transitive dependencies, allowing projects to scale while staying fast and resource-efficient. Introduced experimentally in Bazel 5.0, Bzlmod will be generally available and provide a solution for the [diamond dependency problem](https://docs.google.com/document/d/1moQfNcEIttsk6vYanNKIy3ZuK53hQUFq1b1r0rmsYVg/edit#heading=h.lgyp7ubwxmjc). * Bzlmod goes from ‘experimental’ to ‘generally available’ * [Bzlmod Migration Guide](https://docs.google.com/document/d/1JtXIVnXyFZ4bmbiBCr5gsTH4-opZAFf5DMMb-54kES0/edit?usp=gmail) provides tools, scripts, and documentation to teams looking to adopt Bzlmod @@ -41,7 +41,7 @@ Bazel 6.0 will include improved tooling and merged-in community feature contribu ### Optional toolchains -Our Developer Satisfaction survey showed that rule authors want support for further toolchain development. Bazel 6.0 will allow authors to write rules using an [optional, high performance toolchain](https://bazel.build/docs/toolchains#optional-toolchains) when available with a fallback implementation for other platforms. +Our Developer Satisfaction survey showed that rule authors want support for further toolchain development. Bazel 6.0 will allow authors to write rules using an [optional, high performance toolchain](https://bazel.build/extending/toolchains#optional-toolchains) when available with a fallback implementation for other platforms. ### Bazel-JetBrains\* IntelliJ IDEA support diff --git a/site/en/about/vision.md b/site/en/about/vision.md index 45df1ffd1e4332..caca09f82838f2 100644 --- a/site/en/about/vision.md +++ b/site/en/about/vision.md @@ -85,7 +85,7 @@ any language. ["Bazel sandwich"](https://github.com/bazelbuild/bazel-website/blob/master/designs/_posts/2016-08-04-extensibility-for-native-rules.md) principles. 1. The rules need to be **remote-execution ready**. In practice, this means - **configurable using the [toolchains](/docs/toolchains) mechanism**. + **configurable using the [toolchains](/extending/toolchains) mechanism**. 1. The rules (and Bazel) need to interface with a **widely-used IDE** for the language, if there is one. 1. The rules need to have **thorough, usable documentation,** with introductory diff --git a/site/en/basics/artifact-based-builds.md b/site/en/basics/artifact-based-builds.md index 1a648e6eb8925b..6e055664a0a862 100644 --- a/site/en/basics/artifact-based-builds.md +++ b/site/en/basics/artifact-based-builds.md @@ -172,7 +172,7 @@ at a known location. Just like any other dependency, if the Java compiler changes, every artifact that depends on it is rebuilt. Bazel solves the second part of the problem, platform independence, by setting -[build configurations](/docs/build#build-config-cross-compilation). Rather than +[build configurations](/run/build#build-config-cross-compilation). Rather than targets depending directly on their tools, they depend on types of configurations: * **Host configuration**: building tools that run during the build @@ -185,7 +185,7 @@ box, but engineers will always want to do more—part of the benefit of task-bas systems is their flexibility in supporting any kind of build process, and it would be better not to give that up in an artifact-based build system. Fortunately, Bazel allows its supported target types to be extended by -[adding custom rules](/rules/rules). +[adding custom rules](/extending/rules). To define a rule in Bazel, the rule author declares the inputs that the rule requires (in the form of attributes passed in the `BUILD` file) and the fixed diff --git a/site/en/basics/hermeticity.md b/site/en/basics/hermeticity.md index 69d5daa70871c1..f6538d22c46d30 100644 --- a/site/en/basics/hermeticity.md +++ b/site/en/basics/hermeticity.md @@ -72,18 +72,18 @@ non-hermetic actions. step twice or on different systems, compare a hash of the file contents and get results that differ, the build is not reproducible. * Run steps to - [debug local cache hits](/docs/remote-execution-caching-debug#troubleshooting-cache-hits) + [debug local cache hits](/remote/cache-remote#troubleshooting-cache-hits) from a variety of potential client machines to ensure that you catch any cases of client environment leaking into the actions. * Execute a build within a docker container that contains nothing but the checked-out source tree and explicit list of host tools. Build breakages and error messages will catch implicit system dependencies. * Discover and fix hermeticity problems using - [remote execution rules](/docs/remote-execution-rules#overview). + [remote execution rules](/remote/rules#overview). * Enable strict [sandboxing](/docs/sandboxing) at the per-action level, since actions in a build can be stateful and affect the build or the output. -* [Workspace rules](/docs/workspace-log) +* [Workspace rules](/remote/workspace) allow developers to add dependencies to external workspaces, but they are rich enough to allow arbitrary processing to happen in the process. You can get a log of some potentially non-hermetic actions in Bazel workspace rules by diff --git a/site/en/build/external.md b/site/en/build/external.md index 80fcf565ded3ea..8e340641b75e8e 100644 --- a/site/en/build/external.md +++ b/site/en/build/external.md @@ -10,7 +10,7 @@ projects are called _external dependencies_. Note: Bazel 5.0 and newer has a new external dependency system, codenamed "Bzlmod", which renders a lot of the content on this page obsolete. See [Bzlmod -user guide](/docs/bzlmod) for more information. +user guide](/build/bzlmod) for more information. The `WORKSPACE` file (or `WORKSPACE.bazel` file) in the [workspace directory](/concepts/build-ref#workspace) @@ -257,7 +257,7 @@ Specifically: * Use `--host_jvm_args=-Djava.net.preferIPv6Addresses=true` [startup option](/docs/user-manual#startup-options), for example by adding the following line in your - [`.bazelrc` file](/docs/bazelrc): + [`.bazelrc` file](/run/bazelrc): `startup --host_jvm_args=-Djava.net.preferIPv6Addresses=true` @@ -265,7 +265,7 @@ Specifically: as well (integration tests sometimes needs that), also use `--jvmopt=-Djava.net.preferIPv6Addresses=true` [tool flag](/docs/user-manual#jvmopt), for example by having the - following line in your [`.bazelrc` file](/docs/bazelrc): + following line in your [`.bazelrc` file](/run/bazelrc): `build --jvmopt=-Djava.net.preferIPv6Addresses` @@ -361,7 +361,7 @@ Prefer [`http_archive`](/rules/lib/repo/http#http_archive) to `git_repository` a 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](/docs/build#repository-cache), but not +* `http_archive` works with the [repository cache](/run/build#repository-cache), but not `git_repository`. See [#5116](https://github.com/bazelbuild/bazel/issues/5116){: .external} for more information. diff --git a/site/en/community/_index.yaml b/site/en/community/_index.yaml index d417ff906f65ce..40e79e7818092d 100644 --- a/site/en/community/_index.yaml +++ b/site/en/community/_index.yaml @@ -99,7 +99,7 @@ landing_page: - heading: Bazel users path: /community/users - heading: Nominate a recommended rule - path: /contribute/recommended-rules + path: /community/recommended-rules - heading: Remote execution services path: /community/remote-execution-services - heading: Support channels diff --git a/site/en/community/recommended-rules.md b/site/en/community/recommended-rules.md index c1a5061062bd4a..7fc4d9a1dd71fd 100644 --- a/site/en/community/recommended-rules.md +++ b/site/en/community/recommended-rules.md @@ -18,7 +18,7 @@ If a ruleset meets the requirements below, a rule maintainer can nominate it to be part of the _recommended rules_ by filing a [GitHub issue](https://github.com/bazelbuild/bazel/){: .external}. -After a review by the [Bazel core team](/contribute/contribution-policy), it +After a review by the [Bazel core team](/contribute/policy), it will be recommended on the Bazel website. ## Requirements for the rule maintainers {:#requirements-rule-maintainers} diff --git a/site/en/community/roadmaps-configurability.md b/site/en/community/roadmaps-configurability.md index 7cba10f36d6b62..ac1a1546c59234 100644 --- a/site/en/community/roadmaps-configurability.md +++ b/site/en/community/roadmaps-configurability.md @@ -55,7 +55,7 @@ Book: /_book.yaml * Builds scale well, particularly w.r.t graph size and action caching. We also support -[`cquery`](https://bazel.build/docs/cquery), [`Starlark +[`cquery`](https://bazel.build/query/cquery), [`Starlark configuration`](https://bazel.build/rules/config), and [`select()`](https://bazel.build/docs/configurable-attributes). @@ -71,7 +71,7 @@ interest of accurate expectations.
Q3 2021**Android rules use the new [platforms -API](https://bazel.build/concepts/platforms-intro)** +API](https://bazel.build/concepts/platforms)** IN PROGRESS ([#11749](https://github.com/bazelbuild/bazel/issues/11749)) * This is our main priority for the beginning of 2021. @@ -82,7 +82,7 @@ platforms](https://docs.google.com/document/d/1U9HzdDmtRnm244CaRM6JV-q2408mbNODA IN PROGRESS ([#11748](https://github.com/bazelbuild/bazel/issues/11748))
-paused**C++ rules use the new [platformsfall API](https://bazel.build/concepts/platforms-intro)** +paused**C++ rules use the new [platformsfall API](https://bazel.build/concepts/platforms)** IN PROGRESS ([#6516](https://github.com/bazelbuild/bazel/issues/6516)) * This is blocked on Android platforms. We can turn this on with a simple flag flip. diff --git a/site/en/community/sig.md b/site/en/community/sig.md index ccb88725f93765..fc0327c166da5e 100644 --- a/site/en/community/sig.md +++ b/site/en/community/sig.md @@ -7,7 +7,7 @@ Book: /_book.yaml Bazel hosts Special Interest Groups (SIGs) to focus collaboration on particular areas and to support communication and coordination between [Bazel owners, -maintainers, and contributors](/contribute/contribution-policy). This policy +maintainers, and contributors](/contribute/policy). This policy applies to [`bazelbuild`](http://github.com/bazelbuild){: .external}. SIGs do their work in public. The ideal scope for a SIG covers a well-defined diff --git a/site/en/concepts/build-files.md b/site/en/concepts/build-files.md index cf75f655a944d6..9bcc8d29d9af16 100644 --- a/site/en/concepts/build-files.md +++ b/site/en/concepts/build-files.md @@ -36,7 +36,7 @@ allowed in `BUILD` files; instead list all the arguments explicitly. Crucially, programs in Starlark can't perform arbitrary I/O. This invariant makes the interpretation of `BUILD` files hermetic — dependent only on a known set of inputs, which is essential for ensuring that builds are reproducible. -For more details, see [Hermeticity](/concepts/hermeticity). +For more details, see [Hermeticity](/basics/hermeticity). `BUILD` files should be written using only ASCII characters, although technically they are interpreted using the Latin-1 character set. diff --git a/site/en/concepts/labels.md b/site/en/concepts/labels.md index ffda7d8caec7e7..d4b04b215fca80 100644 --- a/site/en/concepts/labels.md +++ b/site/en/concepts/labels.md @@ -100,14 +100,14 @@ repository that refer to targets in the main repository, and will be used from external repositories. For information about the different ways you can refer to targets, see -[target patterns](/docs/build#specifying-build-targets). +[target patterns](/run/build#specifying-build-targets). ### Lexical specification of a label {:#labels-lexical-specification} Label syntax discourages use of metacharacters that have special meaning to the shell. This helps to avoid inadvertent quoting problems, and makes it easier to construct tools and scripts that manipulate labels, such as the -[Bazel Query Language](/reference/query). +[Bazel Query Language](/query/language). The precise details of allowed target names are below. @@ -215,7 +215,7 @@ the build. This directed acyclic graph over targets is called the _target graph_ or _build dependency graph_, and is the domain over which the -[Bazel Query tool](/docs/query-how-to) operates. +[Bazel Query tool](//query/guide) operates. diff --git a/site/en/concepts/platforms.md b/site/en/concepts/platforms.md index acd61888cf0bfc..45da91bbf52246 100644 --- a/site/en/concepts/platforms.md +++ b/site/en/concepts/platforms.md @@ -107,7 +107,7 @@ or opt in early depends on your specific value / cost needs: flags on the command line. * Simpler language design. All languages share a common API for defining toolchains, using toolchains, and selecting the right toolchain for a platform. -* Targets can be [skipped](/docs/platforms#skipping-incompatible-targets) in the +* Targets can be [skipped](/extending/platforms#skipping-incompatible-targets) in the build and test phase if they are incompatible with the target platform. ### Costs {:#costs} @@ -299,7 +299,7 @@ platforms If you're designing rules for a new language, use platforms to select your language's toolchains. See the -[toolchains documentation](/docs/toolchains) for a good walkthrough. +[toolchains documentation](/extending/toolchains) for a good walkthrough. ### `select()` {:#select} @@ -438,8 +438,8 @@ contact * [`hlopko/bazel_platforms_examples`](https://github.com/hlopko/bazel_platforms_examples){: .external} * [Example C++ custom toolchain](https://github.com/gregestren/snippets/tree/master/custom_cc_toolchain_with_platforms){: .external} -[Platforms]: /docs/platforms -[Toolchains]: /docs/toolchains +[Platforms]: /extending/platforms +[Toolchains]: /extending/toolchains [Inspiration]: https://blog.bazel.build/2019/02/11/configurable-builds-part-1.html [C++ Rules]: /docs/bazel-and-cpp [Android Rules]: /docs/bazel-and-android @@ -451,11 +451,11 @@ contact [constraint_value Rule]: /reference/be/platform#constraint_value [constraint_setting Rule]: /reference/be/platform#constraint_setting [Starlark rule]: /rules/rules -[Starlark provider]: /rules/rules#providers +[Starlark provider]: /extending/rules#providers [target_compatible_with Attribute]: /reference/be/platform#toolchain.target_compatible_with [exec_compatible_with Attribute]: /reference/be/platform#toolchain.exec_compatible_with [register_toolchains Function]: /rules/lib/globals#register_toolchains [extra_toolchains Flag]: /reference/command-line-reference#flag--extra_toolchains [Starlark transitions]: /rules/config#user-defined-transitions -[Defining Constraints and Platforms]: /docs/platforms#constraints-platforms -[Configuring C++ toolchains]: /tutorials/cc-toolchain-config +[Defining Constraints and Platforms]: /extending/platforms#constraints-platforms +[Configuring C++ toolchains]: /tutorials/ccp-toolchain-config diff --git a/site/en/configure/attributes.md b/site/en/configure/attributes.md index 40e88dfce46475..23383569a410b6 100644 --- a/site/en/configure/attributes.md +++ b/site/en/configure/attributes.md @@ -265,7 +265,7 @@ For even clearer errors, you can set custom messages with `select()`'s While the ability to specify multiple flags on the command line provides flexibility, it can also be burdensome to individually set each one every time you want to build a target. - [Platforms](/docs/platforms) + [Platforms](/extending/platforms) let you consolidate these into simple bundles. ```python @@ -360,7 +360,7 @@ This saves the need for boilerplate `config_setting`s when you only need to check against single values. Platforms are still under development. See the -[documentation](/concepts/platforms-intro) for details. +[documentation](/concepts/platforms) for details. ## Combining `select()`s {:#combining-selects} @@ -627,7 +627,7 @@ select({"foo": "val_with_suffix"}, ...) This is for two reasons. First, macros that need to know which path a `select` will choose *cannot work* -because macros are evaluated in Bazel's [loading phase](/docs/build#loading), +because macros are evaluated in Bazel's [loading phase](/run/build#loading), which occurs before flag values are known. This is a core Bazel design restriction that's unlikely to change any time soon. @@ -637,14 +637,14 @@ this. ## Bazel query and cquery {:#query-and-cquery} -Bazel [`query`](/docs/query-how-to) operates over Bazel's +Bazel [`query`](//query/guide) operates over Bazel's [loading phase](/reference/glossary#loading-phase). This means it doesn't know what command line flags a target uses since those flags aren't evaluated until later in the build (in the [analysis phase](/reference/glossary#analysis-phase)). So it can't determine which `select()` branches are chosen. -Bazel [`cquery`](/docs/cquery) operates after Bazel's analysis phase, so it has +Bazel [`cquery`](/query/cquery) operates after Bazel's analysis phase, so it has all this information and can accurately resolve `select()`s. Consider: @@ -705,7 +705,7 @@ details. The key issue this question usually means is that select() doesn't work in *macros*. These are different than *rules*. See the -documentation on [rules](/rules/rules) and [macros](/rules/macros) +documentation on [rules](/extending/rules) and [macros](/extending/macros) to understand the difference. Here's an end-to-end example: @@ -958,7 +958,7 @@ located at `@alternative//:ssl`. ### Why doesn't my select() choose what I expect? {:#faq-select-choose-condition} If `//myapp:foo` has a `select()` that doesn't choose the condition you expect, -use [cquery](/docs/cquery) and `bazel config` to debug: +use [cquery](/query/cquery) and `bazel config` to debug: If `//myapp:foo` is the top-level target you're building, run: @@ -999,7 +999,7 @@ Fragment com.google.devtools.build.lib.rules.cpp.CppOptions { Then compare this output against the settings expected by each `config_setting`. `//myapp:foo` may exist in different configurations in the same build. See the -[cquery docs](/docs/cquery) for guidance on using `somepath` to get the right +[cquery docs](/query/cquery) for guidance on using `somepath` to get the right one. Caution: To prevent restarting the Bazel server, invoke `bazel config` with the diff --git a/site/en/configure/best-practices.md b/site/en/configure/best-practices.md index 422823d9187f3e..651af0dbc4f13d 100644 --- a/site/en/configure/best-practices.md +++ b/site/en/configure/best-practices.md @@ -68,7 +68,7 @@ then the `BUILD` files are misleading. ## Using the `.bazelrc` file {:#bazelrc-file} For project-specific options, use the configuration file your -`{{ '' }}workspace{{ '' }}/.bazelrc` (see [bazelrc format](/docs/bazelrc)). +`{{ '' }}workspace{{ '' }}/.bazelrc` (see [bazelrc format](/run/bazelrc)). If you want to support per-user options for your project that you **do not** want to check into source control, include the line: diff --git a/site/en/configure/integrate-cpp.md b/site/en/configure/integrate-cpp.md index 257bcfe3e72542..7f1c84e961ef0d 100644 --- a/site/en/configure/integrate-cpp.md +++ b/site/en/configure/integrate-cpp.md @@ -11,8 +11,8 @@ This page describes how to integrate with C++ rules on various levels. Because of [ongoing migration of C++ rules](https://github.com/bazelbuild/bazel/issues/6516){: .external} -to [platforms](/docs/platforms) and -[toolchains](/docs/toolchains), you +to [platforms](/extending/platforms) and +[toolchains](/extending/toolchains), you should use the helper function available at [@bazel_tools//tools/cpp:toolchain_utils.bzl](https://source.bazel.build/bazel/+/main:tools/cpp/toolchain_utils.bzl;l=23), which works both when toolchains are disabled and enabled. To depend on a C++ diff --git a/site/en/configure/toolchain-resolution.md b/site/en/configure/toolchain-resolution.md index 91b5b53190ce38..2713c2105932e7 100644 --- a/site/en/configure/toolchain-resolution.md +++ b/site/en/configure/toolchain-resolution.md @@ -8,7 +8,7 @@ Book: /_book.yaml **Note:** This section is intended for Bazel developers, and is not needed by rule authors. -Several SkyFunction classes implement the [toolchain resolution](/docs/toolchains) process: +Several SkyFunction classes implement the [toolchain resolution](/extending/toolchains) process: 1. [`RegisteredToolchainsFunction`](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/skyframe/RegisteredToolchainsFunction.java) and [`RegisteredExecutionPlatformsFunction`](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/skyframe/RegisteredExecutionPlatformsFunction.java) @@ -38,7 +38,7 @@ Several SkyFunction classes implement the [toolchain resolution](/docs/toolchain 1. If the execution platform is already set by the toolchain transition, it will be selected first as described below. -As discussed in [Toolchains and Configurations](/docs/toolchains#toolchains_and_configurations), +As discussed in [Toolchains and Configurations](/extending/toolchains#toolchains_and_configurations), the dependency from a target to a toolchain uses a special configuration that forces the execution platform to be the same for both. Despite the name "toolchain transition", this is not implemented as a configuration diff --git a/site/en/contribute/codebase.md b/site/en/contribute/codebase.md index 7072e1506780e7..d9b3f6aac36d2d 100644 --- a/site/en/contribute/codebase.md +++ b/site/en/contribute/codebase.md @@ -638,7 +638,7 @@ necessitates the following additional components: Aspects are a way to "propagate computation down the dependency graph". They are described for users of Bazel -[here](/rules/aspects). A good +[here](/extending/aspects). A good motivating example is protocol buffers: a `proto_library` rule should not know about any particular language, but building the implementation of a protocol buffer message (the “basic unit” of protocol buffers) in any programming @@ -689,7 +689,7 @@ Bazel supports multi-platform builds, that is, builds where there may be multiple architectures where build actions run and multiple architectures for which code is built. These architectures are referred to as _platforms_ in Bazel parlance (full documentation -[here](/docs/platforms)) +[here](/extending/platforms)) A platform is described by a key-value mapping from _constraint settings_ (such as the concept of "CPU architecture") to _constraint values_ (such as a particular CPU @@ -702,7 +702,7 @@ different compilers; for example, a particular C++ toolchain may run on a specific OS and be able to target some other OSes. Bazel must determine the C++ compiler that is used based on the set execution and target platform (documentation for toolchains -[here](/docs/toolchains)). +[here](/extending/toolchains)). In order to do this, toolchains are annotated with the set of execution and target platform constraints they support. In order to do this, the definition of @@ -1375,7 +1375,7 @@ attribute of the first test that is executed. ## The query engine {:#query-engine} Bazel has a -[little language](/docs/query-how-to) +[little language](//query/guide) used to ask it various things about various graphs. The following query kinds are provided: diff --git a/site/en/contribute/index.md b/site/en/contribute/index.md index 18265c10bf68b4..8eb018a758e44c 100644 --- a/site/en/contribute/index.md +++ b/site/en/contribute/index.md @@ -15,7 +15,7 @@ You can help by [reporting issues](http://github.com/bazelbuild/bazel/issues){: when: - Bazel crashes or you encounter a bug that can [only be resolved using `bazel - clean`](/docs/build#correct-incremental-rebuilds). + clean`](/run/build#correct-incremental-rebuilds). - The documentation is incomplete or unclear. You can also report issues from the page you are viewing by using the "Create issue" link at the top right corner of the page. @@ -69,7 +69,7 @@ Bazel is organized as follows: and some utilities. * Built-in rules are in `com.google.devtools.build.lib.rules` and in `com.google.devtools.build.lib.bazel.rules`. You might want to read about - the [Challenges of Writing Rules](/docs/rule-challenges) first. + the [Challenges of Writing Rules](/rules/challenges) first. * Java native interfaces are in `src/main/native`. * Various tooling for language support are described in the list in the [compiling Bazel](/install/compile-source) section. @@ -81,4 +81,4 @@ To quickly search through Bazel's source code, use [Bazel Code Search](https://source.bazel.build/). You can navigate Bazel's repositories, branches, and files. You can also view history, diffs, and blame information. To learn more, see the -[Bazel Code Search User Guide](/contribute/searching-codebase). +[Bazel Code Search User Guide](/contribute/search). diff --git a/site/en/contribute/maintainers-guide.md b/site/en/contribute/maintainers-guide.md index 1d241210a09b31..0329791259501b 100644 --- a/site/en/contribute/maintainers-guide.md +++ b/site/en/contribute/maintainers-guide.md @@ -17,7 +17,7 @@ The objectives of this page are to: 1. Set expectations between the community contributors and the project maintainers. -Bazel's [core group of contributors](/contribute/contribution-policy) has dedicated +Bazel's [core group of contributors](/contribute/policy) has dedicated subteams to manage aspects of the open source project. These are: * **Release Process**: Manage Bazel's release process. diff --git a/site/en/contribute/patch-acceptance.md b/site/en/contribute/patch-acceptance.md index 753d2ddbdd7384..34b1b8faf46b8d 100644 --- a/site/en/contribute/patch-acceptance.md +++ b/site/en/contribute/patch-acceptance.md @@ -8,7 +8,7 @@ Book: /_book.yaml This page outlines how contributors can propose and make changes to the Bazel code base. -1. Read the [Bazel Contribution policy](/contribute/contribution-policy). +1. Read the [Bazel Contribution policy](/contribute/policy). 1. Create a [GitHub issue](https://github.com/bazelbuild/bazel/){: .external} to discuss your plan and design. Pull requests that change or add behavior need a corresponding issue for tracking. diff --git a/site/en/docs/android-build-performance.md b/site/en/docs/android-build-performance.md index fcd3e638886888..ca83f79e0b93c8 100644 --- a/site/en/docs/android-build-performance.md +++ b/site/en/docs/android-build-performance.md @@ -12,7 +12,7 @@ apps specifically. For general build performance optimization with Bazel, see ## Recommended flags {:#recommended-flags} The flags are in the -[`bazelrc` configuration syntax](/docs/bazelrc#bazelrc-syntax-semantics), so +[`bazelrc` configuration syntax](/run/bazelrc#bazelrc-syntax-semantics), so they can be pasted directly into a `bazelrc` file and invoked with `--config=` on the command line. diff --git a/site/en/docs/android-instrumentation-test.md b/site/en/docs/android-instrumentation-test.md index 0006d0205b1ac2..669ed674b238b5 100644 --- a/site/en/docs/android-instrumentation-test.md +++ b/site/en/docs/android-instrumentation-test.md @@ -6,7 +6,7 @@ Book: /_book.yaml {% include "_buttons.html" %} _If you're new to Bazel, start with the [Building Android with -Bazel](/tutorials/android-app) tutorial._ +Bazel](/start/android-app ) tutorial._ ![Running Android instrumentation tests in parallel](/docs/images/android_test.gif "Android instrumentation test") diff --git a/site/en/docs/android-ndk.md b/site/en/docs/android-ndk.md index d50cd902427bb1..1ac0b26b24043a 100644 --- a/site/en/docs/android-ndk.md +++ b/site/en/docs/android-ndk.md @@ -6,7 +6,7 @@ Book: /_book.yaml {% include "_buttons.html" %} _If you're new to Bazel, please start with the [Building Android with -Bazel](/tutorials/android-app) tutorial._ +Bazel](/start/android-app ) tutorial._ ## Overview {:#overview} @@ -247,8 +247,8 @@ cc_library( ## Integration with platforms and toolchains {:#integration-platforms} Bazel's configuration model is moving towards -[platforms](/docs/platforms) and -[toolchains](/docs/toolchains). If your +[platforms](/extending/platforms) and +[toolchains](/extending/toolchains). If your build uses the `--platforms` flag to select for the architecture or operating system to build for, you will need to pass the `--extra_toolchains` flag to Bazel in order to use the NDK. @@ -323,7 +323,7 @@ any special flags, except for `--fat_apk_cpu` and `--android_crosstool_top` for ABI and STL configuration. Behind the scenes, this automatic configuration uses Android [configuration -transitions](/rules/rules#configurations). +transitions](/extending/rules#configurations). A compatible rule, like `android_binary`, automatically changes the configuration of its dependencies to an Android configuration, so only @@ -388,7 +388,7 @@ With this approach, the entire build tree is affected. Note: All of the targets on the command line must be compatible with building for Android when specifying these flags, which may make it difficult to -use [Bazel wild-cards](/docs/build#specifying-build-targets) like +use [Bazel wild-cards](/run/build#specifying-build-targets) like `/...` and `:all`. These flags can be put into a `bazelrc` config (one for each ABI), in diff --git a/site/en/docs/bazel-and-android.md b/site/en/docs/bazel-and-android.md index 9797c27f6c0075..2e0e1f67543bed 100644 --- a/site/en/docs/bazel-and-android.md +++ b/site/en/docs/bazel-and-android.md @@ -13,7 +13,7 @@ Android projects with Bazel. The following resources will help you work with Bazel on Android projects: -* [Tutorial: Building an Android app](/tutorials/android-app). This +* [Tutorial: Building an Android app](/start/android-app ). This tutorial is a good place to start learning about Bazel commands and concepts, and how to build Android apps with Bazel. * [Codelab: Building Android Apps with Bazel](https://developer.android.com/codelabs/bazel-android-intro#0){: .external}. diff --git a/site/en/docs/bazel-and-apple.md b/site/en/docs/bazel-and-apple.md index cddf900b716762..3c750fdb495a63 100644 --- a/site/en/docs/bazel-and-apple.md +++ b/site/en/docs/bazel-and-apple.md @@ -13,7 +13,7 @@ using Bazel to build and test for those platforms. The following resources will help you work with Bazel on macOS and iOS projects: -* [Tutorial: Building an iOS app](/tutorials/ios-app) +* [Tutorial: Building an iOS app](/start/ios-app)) * [Objective-C build rules](/reference/be/objective-c) * [General Apple rules](https://github.com/bazelbuild/rules_apple){: .external} * [Integration with Xcode](/install/ide) @@ -31,7 +31,7 @@ in the migration guide to start building them with Bazel: You do not need it when getting started with Bazel. The following modules, configuration fragments, and providers will help you -[extend Bazel's capabilities](/rules/concepts) +[extend Bazel's capabilities](/extending/concepts) when building your macOS and iOS projects: * Modules: diff --git a/site/en/docs/bazel-and-cpp.md b/site/en/docs/bazel-and-cpp.md index b8332e8e794ad1..aab47cdcccd08d 100644 --- a/site/en/docs/bazel-and-cpp.md +++ b/site/en/docs/bazel-and-cpp.md @@ -13,7 +13,7 @@ projects with Bazel. The following resources will help you work with Bazel on C++ projects: -* [Tutorial: Building a C++ project](/tutorials/cpp) +* [Tutorial: Building a C++ project](/start/cpp) * [C++ common use cases](/tutorials/cpp-use-cases) * [C/C++ rules](/reference/be/c-cpp) * Essential Libraries @@ -21,12 +21,12 @@ The following resources will help you work with Bazel on C++ projects: - [Boost](https://github.com/nelhage/rules_boost){: .external} - [HTTPS Requests: CPR and libcurl](https://github.com/hedronvision/bazel-make-cc-https-easy){: .external} * [C++ toolchain configuration](/docs/cc-toolchain-config-reference) -* [Tutorial: Configuring C++ toolchains](/tutorials/cc-toolchain-config) -* [Integrating with C++ rules](/docs/integrating-with-rules-cc) +* [Tutorial: Configuring C++ toolchains](/tutorials/ccp-toolchain-config) +* [Integrating with C++ rules](/configure/integrate-cpp) ## Best practices {:#best-practices} -In addition to [general Bazel best practices](/docs/best-practices), below are +In addition to [general Bazel best practices](/configure/best-practices), below are best practices specific to C++ projects. ### BUILD files {:#build-files} diff --git a/site/en/docs/bazel-and-java.md b/site/en/docs/bazel-and-java.md index 51793706fb1124..0fb9f114d9a741 100644 --- a/site/en/docs/bazel-and-java.md +++ b/site/en/docs/bazel-and-java.md @@ -13,7 +13,7 @@ Java projects with Bazel. The following resources will help you work with Bazel on Java projects: -* [Tutorial: Building a Java Project](/tutorials/java) +* [Tutorial: Building a Java Project](/start/java) * [Java rules](/reference/be/java) ## Migrating to Bazel {:#migrating-to-bazel} @@ -86,7 +86,7 @@ For more details, see ## Best practices {:#best-practices} -In addition to [general Bazel best practices](/docs/best-practices), below are +In addition to [general Bazel best practices](/configure/best-practices), below are best practices specific to Java projects. ### Directory structure {:#directory-structure} @@ -128,7 +128,7 @@ Follow these guidelines when creating your `BUILD` files: not need it when getting started with Bazel. The following modules, configuration fragments, and providers will help you -[extend Bazel's capabilities](/rules/concepts) when building your Java +[extend Bazel's capabilities](/extending/concepts) when building your Java projects: * Main Java provider: [`java_common`](/rules/lib/java_common) diff --git a/site/en/docs/configurable-attributes.md b/site/en/docs/configurable-attributes.md index f494d3cc5e9081..ff7936958cae6a 100644 --- a/site/en/docs/configurable-attributes.md +++ b/site/en/docs/configurable-attributes.md @@ -265,7 +265,7 @@ For even clearer errors, you can set custom messages with `select()`'s While the ability to specify multiple flags on the command line provides flexibility, it can also be burdensome to individually set each one every time you want to build a target. - [Platforms](/docs/platforms) + [Platforms](/extending/platforms) let you consolidate these into simple bundles. ```python @@ -360,7 +360,7 @@ This saves the need for boilerplate `config_setting`s when you only need to check against single values. Platforms are still under development. See the -[documentation](/concepts/platforms-intro) for details. +[documentation](/concepts/platforms) for details. ## Combining `select()`s {:#combining-selects} @@ -627,7 +627,7 @@ select({"foo": "val_with_suffix"}, ...) This is for two reasons. First, macros that need to know which path a `select` will choose *cannot work* -because macros are evaluated in Bazel's [loading phase](/docs/build#loading), +because macros are evaluated in Bazel's [loading phase](/run/build#loading), which occurs before flag values are known. This is a core Bazel design restriction that's unlikely to change any time soon. @@ -637,14 +637,14 @@ this. ## Bazel query and cquery {:#query-and-cquery} -Bazel [`query`](/docs/query-how-to) operates over Bazel's +Bazel [`query`](//query/guide) operates over Bazel's [loading phase](/reference/glossary#loading-phase). This means it doesn't know what command line flags a target uses since those flags aren't evaluated until later in the build (in the [analysis phase](/reference/glossary#analysis-phase)). So it can't determine which `select()` branches are chosen. -Bazel [`cquery`](/docs/cquery) operates after Bazel's analysis phase, so it has +Bazel [`cquery`](/query/cquery) operates after Bazel's analysis phase, so it has all this information and can accurately resolve `select()`s. Consider: @@ -705,7 +705,7 @@ details. The key issue this question usually means is that select() doesn't work in *macros*. These are different than *rules*. See the -documentation on [rules](/rules/rules) and [macros](/rules/macros) +documentation on [rules](/extending/rules) and [macros](/extending/macros) to understand the difference. Here's an end-to-end example: @@ -958,7 +958,7 @@ located at `@alternative//:ssl`. ### Why doesn't my select() choose what I expect? {:#faq-select-choose-condition} If `//myapp:foo` has a `select()` that doesn't choose the condition you expect, -use [cquery](/docs/cquery) and `bazel config` to debug: +use [cquery](/query/cquery) and `bazel config` to debug: If `//myapp:foo` is the top-level target you're building, run: @@ -999,7 +999,7 @@ Fragment com.google.devtools.build.lib.rules.cpp.CppOptions { Then compare this output against the settings expected by each `config_setting`. `//myapp:foo` may exist in different configurations in the same build. See the -[cquery docs](/docs/cquery) for guidance on using `somepath` to get the right +[cquery docs](/query/cquery) for guidance on using `somepath` to get the right one. Caution: To prevent restarting the Bazel server, invoke `bazel config` with the diff --git a/site/en/docs/external.md b/site/en/docs/external.md index 80fcf565ded3ea..8e340641b75e8e 100644 --- a/site/en/docs/external.md +++ b/site/en/docs/external.md @@ -10,7 +10,7 @@ projects are called _external dependencies_. Note: Bazel 5.0 and newer has a new external dependency system, codenamed "Bzlmod", which renders a lot of the content on this page obsolete. See [Bzlmod -user guide](/docs/bzlmod) for more information. +user guide](/build/bzlmod) for more information. The `WORKSPACE` file (or `WORKSPACE.bazel` file) in the [workspace directory](/concepts/build-ref#workspace) @@ -257,7 +257,7 @@ Specifically: * Use `--host_jvm_args=-Djava.net.preferIPv6Addresses=true` [startup option](/docs/user-manual#startup-options), for example by adding the following line in your - [`.bazelrc` file](/docs/bazelrc): + [`.bazelrc` file](/run/bazelrc): `startup --host_jvm_args=-Djava.net.preferIPv6Addresses=true` @@ -265,7 +265,7 @@ Specifically: as well (integration tests sometimes needs that), also use `--jvmopt=-Djava.net.preferIPv6Addresses=true` [tool flag](/docs/user-manual#jvmopt), for example by having the - following line in your [`.bazelrc` file](/docs/bazelrc): + following line in your [`.bazelrc` file](/run/bazelrc): `build --jvmopt=-Djava.net.preferIPv6Addresses` @@ -361,7 +361,7 @@ Prefer [`http_archive`](/rules/lib/repo/http#http_archive) to `git_repository` a 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](/docs/build#repository-cache), but not +* `http_archive` works with the [repository cache](/run/build#repository-cache), but not `git_repository`. See [#5116](https://github.com/bazelbuild/bazel/issues/5116){: .external} for more information. diff --git a/site/en/docs/user-manual.md b/site/en/docs/user-manual.md index 37a06d084b7459..647eb8b6143c7d 100644 --- a/site/en/docs/user-manual.md +++ b/site/en/docs/user-manual.md @@ -7,13 +7,13 @@ Book: /_book.yaml This page covers the options that are available with various Bazel commands, such as `bazel build`, `bazel run`, and `bazel test`. This page is a companion -to the list of Bazel's commands in [Build with Bazel](/docs/build). +to the list of Bazel's commands in [Build with Bazel](/run/build). ## Target syntax {:#target-syntax} Some commands, like `build` or `test`, can operate on a list of targets. They use a syntax more flexible than labels, which is documented in -[Specifying targets to build](/docs/build#specifying-build-targets). +[Specifying targets to build](/run/build#specifying-build-targets). ## Options {:#build-options} @@ -62,7 +62,7 @@ Package path elements may be specified in three formats: `/home/bob/clients/bob_client/bazel/foo` directory. If you use a non-default package path, specify it in your -[Bazel configuration file](/docs/bazelrc) for convenience. +[Bazel configuration file](/run/bazelrc) for convenience. _Bazel doesn't require any packages to be in the current directory_, so you can do a build from an empty bazel @@ -455,7 +455,7 @@ variable across multiple `--action_env` flags, the latest assignment wins. #### `--experimental_action_listener={{ "" }}label{{ "" }}` {:#experimental-action-listener} Warning: Extra actions are deprecated. Use -[aspects](/rules/aspects) +[aspects](/extending/aspects) instead. The `experimental_action_listener` option instructs Bazel to use @@ -465,7 +465,7 @@ insert [`extra_actions`](/reference/be/extra-actions#extra_action) into the buil #### `--[no]experimental_extra_action_top_level_only` {:experimental-extra-action-top-level-only} Warning: Extra actions are deprecated. Use -[aspects](/rules/aspects) instead. +[aspects](/extending/aspects) instead. If this option is set to true, extra actions specified by the [ `--experimental_action_listener`](#experimental-action-listener) command @@ -474,7 +474,7 @@ line option will only be scheduled for top level targets. #### `--experimental_extra_action_filter={{ "" }}regex{{ "" }}` {:#experimental-extra-action-filter} Warning: Extra actions are deprecated. Use -[aspects](/rules/aspects) instead. +[aspects](/extending/aspects) instead. The `experimental_extra_action_filter` option instructs Bazel to filter the set of targets to schedule `extra_actions` for. @@ -829,7 +829,7 @@ be created remotely from in-memory manifests. When this option is enabled, Bazel will discard the analysis cache right before execution starts, thus freeing up additional memory -(around 10%) for the [execution phase](/docs/build#execution). +(around 10%) for the [execution phase](/run/build#execution). The drawback is that further incremental builds will be slower. See also [memory-saving mode](/docs/memory-saving-mode). @@ -1155,7 +1155,7 @@ during the compile-edit-test cycle) and a large group of targets regression tests). In the former case, the result information is very useful whereas in the latter case it is less so. As with all options, this can be specified implicitly via -the [`.bazelrc`](/docs/bazelrc) file. +the [`.bazelrc`](/run/bazelrc) file. The files are printed so as to make it easy to copy and paste the filename to the shell, to run built executables. The "up-to-date" @@ -1309,7 +1309,7 @@ reduces input volatility and maximizes build caching. Use these options to control the host and target platforms that configure how builds work, and to control what execution platforms and toolchains are available to Bazel rules. -Please see background information on [Platforms](/docs/platforms) and [Toolchains](/docs/toolchains). +Please see background information on [Platforms](/extending/platforms) and [Toolchains](/extending/toolchains). #### `--platforms={{ "" }}labels{{ "" }}` {:#platforms} @@ -1432,10 +1432,10 @@ engineers using Bazel. When using Bazel for release builds, the same issues arise as for other scripts that perform a build. For more details, see -[Call Bazel from scripts](/docs/scripts). In particular, the following options +[Call Bazel from scripts](/run/scripts). In particular, the following options are strongly recommended: -* [`--bazelrc=/dev/null`](/docs/bazelrc) +* [`--bazelrc=/dev/null`](/run/bazelrc) * [`--nokeep_state_after_build`](/reference/command-line-reference#flag--keep_state_after_build) These options are also important: @@ -1708,7 +1708,7 @@ filter args to the test runner. #### Other options for `bazel test` {:#bazel-test-other-options} The syntax and the remaining options are exactly like -[`bazel build`](/docs/build). +[`bazel build`](/run/build). ## Running executables {:#running-executables} @@ -1841,14 +1841,14 @@ rather than using `clean`. Bazel includes a query language for asking questions about the dependency graph used during the build. The query language is used by two commands: query and cquery. The major difference between the -two commands is that query runs after the [loading phase](/docs/build#loading) -and cquery runs after the [analysis phase](/docs/build#analysis). These tools are an +two commands is that query runs after the [loading phase](/run/build#loading) +and cquery runs after the [analysis phase](/run/build#analysis). These tools are an invaluable aid to many software engineering tasks. The query language is based on the idea of algebraic operations over graphs; it is documented in detail in -[Bazel Query Reference](/reference/query). +[Bazel Query Reference](/query/language). Please refer to that document for reference, for examples, and for query-specific command-line options. @@ -1901,7 +1901,7 @@ For more details, see [Action Graph Query](/docs/aquery). The `help` command provides on-line help. By default, it shows a summary of available commands and help topics, as shown in -[Building with Bazel](/docs/build#quickstart). +[Building with Bazel](/run/build#quickstart). Specifying an argument displays detailed help for a particular topic. Most topics are Bazel commands, such as `build` or `query`, but there are some additional help topics @@ -1920,7 +1920,7 @@ Bazel server processes may be stopped by using the `shutdown` command. This command causes the Bazel server to exit as soon as it becomes idle (for example, after the completion of any builds or other commands that are currently in progress). For more details, see -[Client/server implementation](/docs/client-server). +[Client/server implementation](/run/client-server). Bazel servers stop themselves after an idle timeout, so this command is rarely necessary; however, it can be useful in scripts when it is @@ -2383,7 +2383,7 @@ run Bazel with. #### `--batch` {:#batch} Batch mode causes Bazel to not use the -[standard client/server mode](/docs/client-server), but instead runs a bazel +[standard client/server mode](/run/client-server), but instead runs a bazel java process for a single command, which has been used for more predictable semantics with respect to signal handling, job control, and environment variable inheritance, and is necessary for running bazel in a chroot jail. @@ -2489,7 +2489,7 @@ of the setting of the TERM environment variable. #### `--config={{ "" }}name{{ "" }}` {:#config} Selects additional config section from -[the rc files](/docs/bazelrc#bazelrc-file-locations); for the current `command`, +[the rc files](/run/bazelrc#bazelrc-file-locations); for the current `command`, it also pulls in the options from `command:name` if such a section exists. Can be specified multiple times to add flags from several config sections. Expansions can refer to other definitions (for example, expansions can be chained). diff --git a/site/en/extending/aspects.md b/site/en/extending/aspects.md index 7add9758468a9f..ecd89d2e365dd6 100644 --- a/site/en/extending/aspects.md +++ b/site/en/extending/aspects.md @@ -48,11 +48,11 @@ This `BUILD` file defines a dependency graph shown in the following figure: **Figure 1.** `BUILD` file dependency graph. Bazel analyzes this dependency graph by calling an implementation function of -the corresponding [rule](/rules/rules) (in this case "java_library") for every +the corresponding [rule](/extending/rules) (in this case "java_library") for every target in the above example. Rule implementation functions generate actions that build artifacts, such as `.jar` files, and pass information, such as locations and names of those artifacts, to the reverse dependencies of those targets in -[providers](/rules/rules#providers). +[providers](/extending/rules#providers). Aspects are similar to rules in that they have an implementation function that generates actions and returns providers. However, their power comes from @@ -138,8 +138,8 @@ def _print_aspect_impl(target, ctx): ``` Aspect implementation functions are similar to the rule implementation -functions. They return [providers](/rules/rules#providers), can generate -[actions](/rules/rules#actions), and take two arguments: +functions. They return [providers](/extending/rules#providers), can generate +[actions](/extending/rules#actions), and take two arguments: * `target`: the [target](/rules/lib/Target) the aspect is being applied to. * `ctx`: [`ctx`](/rules/lib/ctx) object that can be used to access attributes @@ -401,4 +401,4 @@ itself, and all of the targets accessible recursively via ``deps``. ## References -* [`aspect` API reference](/rules/lib/globals#aspect) \ No newline at end of file +* [`aspect` API reference](/rules/lib/globals#aspect) diff --git a/site/en/extending/concepts.md b/site/en/extending/concepts.md index 82dfad4dcb73ed..44c0a2b2d7dce3 100644 --- a/site/en/extending/concepts.md +++ b/site/en/extending/concepts.md @@ -18,19 +18,19 @@ Before learning the more advanced concepts, first: * Read about the [Starlark language](/rules/language), used in both the `BUILD` and `.bzl` files. -* Learn how you can [share variables](/rules/tutorial-sharing-variables) +* Learn how you can [share variables](/build/share-variables) between two `BUILD` files. ## Macros and rules -A [macro](/rules/macros) is a function that instantiates rules. It is useful when a +A [macro](/extending/macros) is a function that instantiates rules. It is useful when a `BUILD` file is getting too repetitive or too complex, as it allows you to reuse some code. The function is evaluated as soon as the `BUILD` file is read. After the evaluation of the `BUILD` file, Bazel has little information about macros: if your macro generates a `genrule`, Bazel will behave as if you wrote the `genrule`. As a result, `bazel query` will only list the generated `genrule`. -A [rule](/rules/rules) is more powerful than a macro. It can access Bazel +A [rule](/extending/rules) is more powerful than a macro. It can access Bazel internals and have full control over what is going on. It may for example pass information to other rules. @@ -73,12 +73,12 @@ they will not be executed. ## Creating extensions -* [Create your first macro](/rules/tutorial-creating-a-macro) in order to - reuse some code. Then [learn more about macros](/rules/macros) and - [using them to create "custom verbs"](/rules/tutorial-custom-verbs). +* [Create your first macro](/rules/macro-tutorial) in order to + reuse some code. Then [learn more about macros](/extending/macros) and + [using them to create "custom verbs"](/rules/verbs-tutorial). * [Follow the rules tutorial](/rules/rules-tutorial) to get started with rules. - Next, you can read more about the [rules concepts](/rules/rules). + Next, you can read more about the [rules concepts](/extending/rules). The two links below will be very useful when writing your own extensions. Keep them within reach: @@ -89,8 +89,8 @@ them within reach: ## Going further -In addition to [macros](/rules/macros) and [rules](/rules/rules), you may want to write -[aspects](/rules/aspects) and [repository rules](/rules/repository_rules). +In addition to [macros](/extending/macros) and [rules](/extending/rules), you may want to write +[aspects](/extending/aspects) and [repository rules](/rules/repository_rules). * Use [Buildifier](https://github.com/bazelbuild/buildtools){: .external} consistently to format and lint your code. diff --git a/site/en/extending/config.md b/site/en/extending/config.md index 90c92e2da3abf9..8a57fc0f389e3b 100644 --- a/site/en/extending/config.md +++ b/site/en/extending/config.md @@ -27,7 +27,7 @@ and more, all completely from .bzl files (no Bazel release required). See the ## User-defined build settings {:#user-defined-build-settings} A build setting is a single piece of -[configuration](/rules/rules#configurations) +[configuration](/extending/rules#configurations) information. Think of a configuration as a key/value map. Setting `--cpu=ppc` and `--copt="-DFoo"` produces a configuration that looks like `{cpu: ppc, copt: "-DFoo"}`. Each entry is a build setting. @@ -77,7 +77,7 @@ feature inside other non-test rules. #### Using ctx.build_setting_value {:#ctx-build-setting-value} -Like all rules, build setting rules have [implementation functions](/rules/rules#implementation-function). +Like all rules, build setting rules have [implementation functions](/extending/rules#implementation-function). The basic Starlark-type value of the build settings can be accessed via the `ctx.build_setting_value` method. This method is only available to [`ctx`](/rules/lib/ctx) objects of build setting rules. These implementation @@ -744,7 +744,7 @@ here. Many native flags today, like `--cpu` and `--crosstool_top` are related to toolchain resolution. In the future, explicit transitions on these types of flags will likely be replaced by transitioning on the -[target platform](/docs/platforms). +[target platform](/extending/platforms). ## Memory and performance considerations {:#memory-performance-considerations} @@ -810,5 +810,5 @@ TODO: Add strategies for measurement and mitigation of these issues. For more details on modifying build configurations, see: * [Starlark Build Configuration](https://docs.google.com/document/d/1vc8v-kXjvgZOdQdnxPTaV0rrLxtP2XwnD2tAZlYJOqw/edit?usp=sharing){: .external} - * [Bazel Configurability Roadmap](https://bazel.build/roadmaps/configuration.html){: .external} + * [Bazel Configurability Roadmap](https://bazel.build/community/roadmaps-configurability){: .external} * Full [set](https://github.com/bazelbuild/examples/tree/HEAD/configurations){: .external} of end to end examples diff --git a/site/en/extending/exec-groups.md b/site/en/extending/exec-groups.md index 1d0b3952f06bf0..9abdf1dfd208f1 100644 --- a/site/en/extending/exec-groups.md +++ b/site/en/extending/exec-groups.md @@ -6,8 +6,8 @@ Book: /_book.yaml {% include "_buttons.html" %} Execution groups allow for multiple execution platforms within a single target. -Each execution group has its own [toolchain](/docs/toolchains) dependencies and -performs its own [toolchain resolution](/docs/toolchains#toolchain-resolution). +Each execution group has its own [toolchain](/extending/toolchains) dependencies and +performs its own [toolchain resolution](/extending/toolchains#toolchain-resolution). ## Background {:#background} @@ -122,7 +122,7 @@ def _impl(ctx): ) ``` -Rule authors will also be able to access the [resolved toolchains](/docs/toolchains#toolchain-resolution) +Rule authors will also be able to access the [resolved toolchains](/extending/toolchains#toolchain-resolution) of execution groups, similarly to how you can access the resolved toolchain of a target: diff --git a/site/en/extending/macros.md b/site/en/extending/macros.md index e6ccb5f6af8c36..356383e1b9a871 100644 --- a/site/en/extending/macros.md +++ b/site/en/extending/macros.md @@ -11,7 +11,7 @@ debugging, and conventions. A macro is a function called from the `BUILD` file that can instantiate rules. Macros are mainly used for encapsulation and code reuse of existing rules and other macros. By the end of the -[loading phase](/rules/concepts#evaluation-model), macros don't exist anymore, +[loading phase](/extending/concepts#evaluation-model), macros don't exist anymore, and Bazel sees only the concrete set of instantiated rules. ## Usage {:#usage} diff --git a/site/en/extending/platforms.md b/site/en/extending/platforms.md index 2ae1dcca029bd2..e6b3ff889b7068 100644 --- a/site/en/extending/platforms.md +++ b/site/en/extending/platforms.md @@ -16,7 +16,7 @@ resources that are available in some environment. Modeling the environment as a platform helps Bazel to automatically select the appropriate -[toolchains](/docs/toolchains) +[toolchains](/extending/toolchains) for build actions. Platforms can also be used in combination with the [config_setting](/reference/be/general#config_setting) rule to write [configurable attributes](/docs/configurable-attributes). @@ -229,7 +229,7 @@ cc_library( You can use the [`IncompatiblePlatformProvider`](/rules/lib/IncompatiblePlatformProvider) in `bazel cquery`'s [Starlark output -format](/docs/cquery#output-format-definition) to distinguish +format](/query/cquery#output-format-definition) to distinguish incompatible targets from compatible ones. This can be used to filter out incompatible targets. The example below will diff --git a/site/en/extending/rules.md b/site/en/extending/rules.md index 8f65214dc7db7a..efd903f7d89395 100644 --- a/site/en/extending/rules.md +++ b/site/en/extending/rules.md @@ -24,9 +24,9 @@ inputs to a rule, but also all of the tools and libraries required to execute the actions. Before creating or modifying any rule, ensure you are familiar with Bazel's -[build phases](/rules/concepts). It is important to understand the three +[build phases](/extending/concepts). It is important to understand the three phases of a build (loading, analysis, and execution). It is also useful to -learn about [macros](/rules/macros) to understand the difference between rules and +learn about [macros](/extending/macros) to understand the difference between rules and macros. To get started, first review the [Rules Tutorial](/rules/rules-tutorial). Then, use this page as a reference. @@ -43,7 +43,7 @@ When defining your own rule, you get to decide what attributes it supports and how it generates its outputs. The rule's `implementation` function defines its exact behavior during the -[analysis phase](/rules/concepts#evaluation-model). This function does not run any +[analysis phase](/extending/concepts#evaluation-model). This function does not run any external commands. Rather, it registers [actions](#actions) that will be used later during the execution phase to build the rule's outputs, if they are needed. @@ -65,7 +65,7 @@ example_library = rule( ) ``` -This defines a [kind of rule](/reference/query#kind) named `example_library`. +This defines a [kind of rule](/query/language#kind) named `example_library`. The call to `rule` also must specify if the rule creates an [executable](#executable-rules) output (with `executable=True`), or specifically @@ -91,9 +91,9 @@ a target. This is called *instantiating* the rule. This specifies a name for the new target and values for the target's [attributes](#attributes). Rules can also be called from Starlark functions and loaded in `.bzl` files. -Starlark functions that call rules are called [Starlark macros](/rules/macros). +Starlark functions that call rules are called [Starlark macros](/extending/macros). Starlark macros must ultimately be called from `BUILD` files, and can only be -called during the [loading phase](/rules/concepts#evaluation-model), when `BUILD` +called during the [loading phase](/extending/concepts#evaluation-model), when `BUILD` files are evaluated to instantiate targets. ## Attributes @@ -215,8 +215,8 @@ label. Implicit dependencies are generally used for tools that reside in the same repository as the rule implementation. If the tool comes from the -[execution platform](/docs/platforms) or a different repository instead, the -rule should obtain that tool from a [toolchain](/docs/toolchains). +[execution platform](/extending/platforms) or a different repository instead, the +rule should obtain that tool from a [toolchain](/extending/toolchains). ### Output attributes @@ -240,7 +240,7 @@ can be specifically depended upon or ## Implementation function Every rule requires an `implementation` function. These functions are executed -strictly in the [analysis phase](/rules/concepts#evaluation-model) and transform the +strictly in the [analysis phase](/extending/concepts#evaluation-model) and transform the graph of targets generated in the loading phase into a graph of [actions](#actions) to be performed during the execution phase. As such, implementation functions can not actually read or write files. @@ -400,7 +400,7 @@ def _example_library_impl(ctx): Actions take a list or depset of input files and generate a (non-empty) list of output files. The set of input and output files must be known during the -[analysis phase](/rules/concepts#evaluation-model). It might depend on the value of +[analysis phase](/extending/concepts#evaluation-model). It might depend on the value of attributes, including providers from dependencies, but it cannot depend on the result of the execution. For example, if your action runs the unzip command, you must specify which files you expect to be inflated (before running unzip). @@ -478,7 +478,7 @@ reproduce the failure. #### Runfiles Runfiles are a set of files used by a target at runtime (as opposed to build -time). During the [execution phase](/rules/concepts#evaluation-model), Bazel creates +time). During the [execution phase](/extending/concepts#evaluation-model), Bazel creates a directory tree containing symlinks pointing to the runfiles. This stages the environment for the binary so it can access the runfiles during runtime. @@ -699,7 +699,7 @@ and a attributes implicitly defined, in addition to those added for [all rules](/reference/be/common-definitions#common-attributes). The defaults of implicitly-added attributes cannot be changed, though this can be worked around -by wrapping a private rule in a [Starlark macro](/rules/macros) which alters the +by wrapping a private rule in a [Starlark macro](/extending/macros) which alters the default: ```python @@ -786,7 +786,7 @@ def _example_library_impl(ctx): ``` Also unlike most providers, `OutputGroupInfo` can be returned by both an -[aspect](/rules/aspects) and the rule target to which that aspect is applied, as +[aspect](/extending/aspects) and the rule target to which that aspect is applied, as long as they do not define the same output groups. In that case, the resulting providers are merged. @@ -799,7 +799,7 @@ of files from a target to the actions of its consumers. Define Imagine that you want to build a C++ binary for a different architecture. The build can be complex and involve multiple steps. Some of the intermediate binaries, like compilers and code generators, have to run on -[the execution platform](/docs/platforms#overview) (which could be your host, +[the execution platform](/extending/platforms#overview) (which could be your host, or a remote executor). Some binaries like the final output must be built for the target architecture. diff --git a/site/en/extending/toolchains.md b/site/en/extending/toolchains.md index 1beb4a971c618c..0d86d693ea2104 100644 --- a/site/en/extending/toolchains.md +++ b/site/en/extending/toolchains.md @@ -7,7 +7,7 @@ Book: /_book.yaml This page describes the toolchain framework, which is a way for rule authors to decouple their rule logic from platform-based selection of tools. It is -recommended to read the [rules](/rules/rules) and [platforms](/docs/platforms) +recommended to read the [rules](/extending/rules) and [platforms](/extending/platforms) pages before continuing. This page covers why toolchains are needed, how to define and use them, and how Bazel selects an appropriate toolchain based on platform constraints. @@ -474,7 +474,7 @@ This will end up building `//bar_tools:barc_linux` but not ## Toolchain resolution {:#toolchain-resolution} -Note: [Some Bazel rules](/concepts/platforms-intro#status) do not yet support +Note: [Some Bazel rules](/concepts/platforms#status) do not yet support toolchain resolution. For each target that uses toolchains, Bazel's toolchain resolution procedure @@ -530,7 +530,7 @@ In cases where the same target can be built in multiple configurations (such as for different CPUs) within the same build, the resolution procedure is applied independently to each version of the target. -If the rule uses [execution groups](/reference/exec-groups), each execution +If the rule uses [execution groups](/extending/exec-groups), each execution group performs toolchain resolution separately, and each has its own execution platform and toolchains. @@ -542,8 +542,8 @@ provides verbose output for toolchain types or target names that match the regex can use `.*` to output all information. Bazel will output names of toolchains it checks and skips during the resolution process. -If you'd like to see which [`cquery`](/docs/cquery) dependencies are from toolchain -resolution, use `cquery`'s [`--transitions`](/docs/cquery#transitions) flag: +If you'd like to see which [`cquery`](/query/cquery) dependencies are from toolchain +resolution, use `cquery`'s [`--transitions`](/query/cquery#transitions) flag: ``` # Find all direct dependencies of //cc:my_cc_lib. This includes explicitly diff --git a/site/en/install/windows.md b/site/en/install/windows.md index 587a45a27867bd..4f1c892c9609b9 100644 --- a/site/en/install/windows.md +++ b/site/en/install/windows.md @@ -49,7 +49,7 @@ To make Bazel easily accessible from command prompts or PowerShell by default, y set PATH=%PATH%;{{ '' }}path to the Bazel binary{{ '' }} ``` -You can also change your system `PATH` environment variable to make it permanent. Check out how to [set environment variables](/docs/windows#set-environment-variables). +You can also change your system `PATH` environment variable to make it permanent. Check out how to [set environment variables](/configure/windows#set-environment-variables). ### Done {:#done} @@ -65,8 +65,8 @@ Next, you can check out more tips and guidance here: * [Installing compilers and language runtimes](#install-compilers) * [Troubleshooting](#troubleshooting) -* [Best practices on Windows](/docs/windows#best-practices) -* [Tutorials](/start/getting-started#tutorials) +* [Best practices on Windows](/configure/windows#best-practices) +* [Tutorials](/start/#tutorials) ## Installing compilers and language runtimes {:#install-compilers} diff --git a/site/en/migrate/maven.md b/site/en/migrate/maven.md index e1940013bd829d..1b7f755004ca9f 100644 --- a/site/en/migrate/maven.md +++ b/site/en/migrate/maven.md @@ -24,7 +24,7 @@ directly run by Bazel since there's no Maven compatibility layer. * [Install Bazel](/install) if it's not yet installed. * If you're new to Bazel, go through the tutorial - [Introduction to Bazel: Build Java](/tutorials/java) before you start + [Introduction to Bazel: Build Java](/start/java) before you start migrating. The tutorial explains Bazel's concepts, structure, and label syntax. diff --git a/site/en/migrate/xcode.md b/site/en/migrate/xcode.md index 7009c069e79889..3ae1db77f95685 100644 --- a/site/en/migrate/xcode.md +++ b/site/en/migrate/xcode.md @@ -51,7 +51,7 @@ Before you begin, do the following: 1. [Install Bazel](/install) if you have not already done so. 2. If you're not familiar with Bazel and its concepts, complete the - [iOS app tutorial](/tutorials/ios-app). You should understand the Bazel + [iOS app tutorial](/start/ios-app)). You should understand the Bazel workspace, including the `WORKSPACE` and `BUILD` files, as well as the concepts of targets, build rules, and Bazel packages. diff --git a/site/en/query/aquery.md b/site/en/query/aquery.md index 2899fc86084e9a..f82e1e5874e386 100644 --- a/site/en/query/aquery.md +++ b/site/en/query/aquery.md @@ -44,7 +44,7 @@ The query expression (in quotes) consists of the following: * `aquery_function(...)`: functions specific to `aquery`. More details [below](#using-aquery-functions). -* `function(...)`: the standard [functions](/reference/query#functions) +* `function(...)`: the standard [functions](/query/language#functions) as traditional `query`. * `//target` is the label to the interested target. @@ -159,7 +159,7 @@ This flag is only available with `--output=proto` or `--output=textproto`. [Skyframe](/reference/skyframe) is the evaluation and incrementality model of Bazel. On each instance of Bazel server, Skyframe stores the dependency graph -constructed from the previous runs of the [Analysis phase](/docs/build#analysis). +constructed from the previous runs of the [Analysis phase](/run/build#analysis). In some cases, it is useful to query the Action Graph on Skyframe. An example use case would be: @@ -271,7 +271,7 @@ to be compared. ### Aspect-on-aspect {:#aspect-on-aspect} -It is possible for [Aspects](/rules/aspects) +It is possible for [Aspects](/extending/aspects) to be applied on top of each other. The aquery output of the action generated by these Aspects would then include the _Aspect path_, which is the sequence of Aspects applied to the target which generated the action. @@ -317,7 +317,7 @@ Each `AspectDescriptor` has the following format: `AspectClass` could be the name of the Aspect class (for native Aspects) or `bzl_file%aspect_name` (for Starlark Aspects). `AspectDescriptor` are sorted in topological order of the -[dependency graph](/rules/aspects#aspect_basics). +[dependency graph](/extending/aspects#aspect_basics). ### Linking with the JSON profile {:#linking-with-json-profile} diff --git a/site/en/query/cquery.md b/site/en/query/cquery.md index c7106e4e40716a..3497db581594f7 100644 --- a/site/en/query/cquery.md +++ b/site/en/query/cquery.md @@ -5,12 +5,12 @@ Book: /_book.yaml {% include "_buttons.html" %} -`cquery` is a variant of [`query`](/reference/query) that correctly handles +`cquery` is a variant of [`query`](/query/language) that correctly handles [`select()`](/docs/configurable-attributes) and build options' effects on the build graph. It achieves this by running over the results of Bazel's [analysis -phase](/rules/concepts#evaluation-model), +phase](/extending/concepts#evaluation-model), which integrates these effects. `query`, by constrast, runs over the results of Bazel's loading phase, before options are evaluated. @@ -78,14 +78,14 @@ The query expression `"function(//target)"` consists of the following: * **`function(...)`** is the function to run on the target. `cquery` supports most - of `query`'s [functions](/reference/query#functions), plus a + of `query`'s [functions](/query/language#functions), plus a few new ones. * **`//target`** is the expression fed to the function. In this example, the expression is a simple target. But the query language also allows nesting of functions. See the [Query guide](/query/guide) for examples. -`cquery` requires a target to run through the [loading and analysis](/rules/concepts#evaluation-model) +`cquery` requires a target to run through the [loading and analysis](/extending/concepts#evaluation-model) phases. Unless otherwise specified, `cquery` parses the target(s) listed in the query expression. See [`--universe_scope`](#universe-scope) for querying dependencies of top-level build targets. @@ -127,7 +127,7 @@ configured versions of `//foo`. For `cquery`, a target pattern in the query expression evaluates to every configured target with a label that matches that pattern. Output is deterministic, but `cquery` makes no ordering guarantee beyond the -[core query ordering contract](/reference/query#graph-order). +[core query ordering contract](/query/language#graph-order). This produces subtler results for query expressions than with `query`. For example, the following can produce multiple results: @@ -146,14 +146,14 @@ If you want to precisely declare which instance to query over, use the [`config`](#config) function. See `query`'s [target pattern -documentation](/reference/query#target-patterns) for more information on target patterns. +documentation](/query/language#target-patterns) for more information on target patterns. ## Functions {:#functions} -Of the [set of functions](/reference/query#functions "list of query functions") -supported by `query`, `cquery` supports all but [`visible`](/reference/query#visible), -[`siblings`](/reference/query#siblings), [`buildfiles`](/reference/query#buildfiles), -and [`tests`](/reference/query#tests). +Of the [set of functions](/query/language#functions "list of query functions") +supported by `query`, `cquery` supports all but [`visible`](/query/language#visible), +[`siblings`](/query/language#siblings), [`buildfiles`](/query/language#buildfiles), +and [`tests`](/query/language#tests). `cquery` also introduces the following new functions: @@ -199,7 +199,7 @@ can be found in the specified configuration, the query fails. #### `--universe_scope` (comma-separated list) {:#universe-scope} Often, the dependencies of configured targets go through -[transitions](/rules/rules#configurations), +[transitions](/extending/rules#configurations), which causes their configuration to differ from their dependent. This flag allows you to query a target as if it were built as a dependency or a transitive dependency of another target. For example: @@ -219,7 +219,7 @@ cc_library( Genrules configure their tools in the -[host configuration](/rules/rules#configurations) +[host configuration](/extending/rules#configurations) so the following queries would produce the following outputs:
@@ -270,7 +270,7 @@ toolchains. Setting this flag to false filters out all configured targets for which the path from the queried target to them crosses a transition between the target configuration and the -[non-target configurations](/rules/rules#configurations). +[non-target configurations](/extending/rules#configurations). If the queried target is in the target configuration, setting `--notool_deps` will only return targets that also are in the target configuration. If the queried target is in a non-target configuration, setting `--notool_deps` will only return @@ -279,7 +279,7 @@ of resolved toolchains. #### `--include_aspects` (boolean, default=True) {:#include-aspects} -[Aspects](/rules/aspects) can add +[Aspects](/extending/aspects) can add additional dependencies to a build. By default, `cquery` doesn't follow aspects because they make the queryable graph bigger, which uses more memory. But following them produces more accurate results. @@ -303,7 +303,7 @@ There are other options for exposing the results as well. --transitions=full -Configuration [transitions](/rules/rules#configurations) +Configuration [transitions](/extending/rules#configurations) are used to build targets underneath the top level targets in different configurations than the top level targets. @@ -341,7 +341,7 @@ By default, cquery results return configuration information as part of each configured target. If you'd like to omit this information and get proto output that is formatted exactly like query's proto output, set this flag to false. -See [query's proto output documentation](/reference/query#output-formats) +See [query's proto output documentation](/query/language#output-formats) for more proto output-related options. Note: While selects are resolved both at the top level of returned @@ -355,9 +355,9 @@ included as `rule_input` fields. This option generates output as a Graphviz-compatible .dot file. See `query`'s -[graph output documentation](/reference/query#display-result-graph) for details. `cquery` -also supports [`--graph:node_limit`](/reference/query#graph-nodelimit) and -[`--graph:factored`](/reference/query#graph-factored). +[graph output documentation](/query/language#display-result-graph) for details. `cquery` +also supports [`--graph:node_limit`](/query/language#graph-nodelimit) and +[`--graph:factored`](/query/language#graph-factored). ### Files output {:#files-output} @@ -413,7 +413,7 @@ targets have a null configuration. ##### providers(target) {:#providers} `providers(target)` returns a map whose keys are names of -[providers](/rules/rules#providers) +[providers](/extending/rules#providers) (for example, `"DefaultInfo"`) and whose values are their Starlark values. Providers whose values are not legal Starlark values are omitted from this map. @@ -531,7 +531,7 @@ different niches. Consider the following to decide which is right for you: evaluates _configured targets_ while `query` only evaluates _targets_. This takes more time and uses more memory. * `cquery`'s intepretation of - the [query language](/reference/query) introduces ambiguity + the [query language](/query/language) introduces ambiguity that `query` avoids. For example, if `"//foo"` exists in two configurations, which one should `cquery "deps(//foo)"` use? @@ -571,7 +571,7 @@ configurations is not supported) $ bazel cquery 'somepath(//foo, //bar)' --universe_scope=//foo -**No support for [`--output=xml`](/reference/query#xml).** +**No support for [`--output=xml`](/query/language#xml).** **Non-deterministic output.** @@ -579,7 +579,7 @@ $ bazel cquery 'somepath(//foo, //bar)' --universe_scope=//foo previous commands and is therefore prone to picking up results from past queries. For example, `genquery` exerts a host transition on its `tools` attribute - that is, it configures its tools in the -[host configuration](/rules/rules#configurations). +[host configuration](/extending/rules#configurations). You can see the lingering effects of that transition below. diff --git a/site/en/query/guide.md b/site/en/query/guide.md index 5819baae980c9b..879ebabfc81bd4 100644 --- a/site/en/query/guide.md +++ b/site/en/query/guide.md @@ -9,8 +9,8 @@ This page covers how to get started using Bazel's query language to trace dependencies in your code. For a language details and `--output` flag details, please see the -reference manuals, [Bazel query reference](/reference/query) -and [Bazel cquery reference](/docs/cquery). You can get help by +reference manuals, [Bazel query reference](/query/language) +and [Bazel cquery reference](/query/cquery). You can get help by typing `bazel help query` or `bazel help cquery` on the command line. @@ -112,7 +112,7 @@ if you're going to change some code, you might want to know what other code you're about to break. You can use `rdeps(u, x)` to find the reverse dependencies of the targets in `x` within the transitive closure of `u`. -Bazel's [Sky Query](/reference/query#sky-query) +Bazel's [Sky Query](/query/language#sky-query) supports the `allrdeps` function which allows you to query reverse dependencies in a universe you specify. diff --git a/site/en/query/language.md b/site/en/query/language.md index f91236e07bd0af..b6ab5bd346bd98 100644 --- a/site/en/query/language.md +++ b/site/en/query/language.md @@ -9,7 +9,7 @@ This page is the reference manual for the _Bazel Query Language_ used when you use `bazel query` to analyze build dependencies. It also describes the output formats `bazel query` supports. -For practical use cases, see the [Bazel Query How-To](/docs/query-how-to). +For practical use cases, see the [Bazel Query How-To](//query/guide). ## Additional query reference @@ -35,7 +35,7 @@ and instead returns all possible resolutions of selects. However, the configurable query environment, `cquery`, properly handles configurations but doesn't provide all of the functionality of this original query. -For more details, see the [cquery reference](/docs/cquery). +For more details, see the [cquery reference](/query/cquery). ## Examples {:#examples} diff --git a/site/en/query/quickstart.md b/site/en/query/quickstart.md index 07694b9b9d694a..8bb8582c843141 100644 --- a/site/en/query/quickstart.md +++ b/site/en/query/quickstart.md @@ -5,7 +5,7 @@ Book: /_book.yaml This tutorial covers how to work with Bazel to trace dependencies in your code using a premade Bazel project. -For language and `--output` flag details, see the [Bazel query reference](/reference/query) and [Bazel cquery reference](/docs/cquery) manuals. Get help in your IDE by typing `bazel help query` or `bazel help cquery` on the command line. +For language and `--output` flag details, see the [Bazel query reference](/query/language) and [Bazel cquery reference](/query/cquery) manuals. Get help in your IDE by typing `bazel help query` or `bazel help cquery` on the command line. ## Objective diff --git a/site/en/reference/_index.yaml b/site/en/reference/_index.yaml index 5ebaeb26224fde..22270b066004c7 100644 --- a/site/en/reference/_index.yaml +++ b/site/en/reference/_index.yaml @@ -50,7 +50,7 @@ landing_page: description: > Find options and syntax for working in a command line environment. - heading: Query reference - path: /reference/query + path: /query/language image_path: /images/why_faq.svg description: > Reference the query manual when analyzing build dependencies with one of Bazel's query languages. diff --git a/site/en/reference/glossary.md b/site/en/reference/glossary.md index 01c26cd97b6cb0..c86bef31d8bdca 100644 --- a/site/en/reference/glossary.md +++ b/site/en/reference/glossary.md @@ -12,7 +12,7 @@ A command to run during the build, for example, a call to a compiler that takes Includes metadata like the command line arguments, action key, environment variables, and declared input/output artifacts. -**See also:** [Rules documentation](/rules/rules#actions) +**See also:** [Rules documentation](/extending/rules#actions) ### Action cache {:#action-cache} @@ -72,7 +72,7 @@ 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](/rules/aspects) +**See also:** [Aspects documentation](/extending/aspects) ### Aspect-on-aspect {:#aspect-on-aspect} @@ -187,7 +187,7 @@ 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](/rules/rules#configurations) +**See also:** [Configurations](/extending/rules#configurations) @@ -206,7 +206,7 @@ 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](/docs/cquery) +**See also:** [cquery documentation](/query/cquery) ### Configured target {:#configured-target} @@ -331,7 +331,7 @@ a single [Starlark](#starlark) function. Enables reusing common rule declaration patterns across `BUILD` files. Expanded to the underlying rule target declarations during the [loading phase](#loading-phase). -**See also:** [Macro documentation](/rules/macros) +**See also:** [Macro documentation](/extending/macros) ### Mnemonic {:#mnemonic} @@ -404,7 +404,7 @@ 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](/rules/rules#providers) +**See also:** [Provider documentation](/extending/rules#providers) ### Query (concept) {:#query-concept} @@ -420,7 +420,7 @@ 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](/docs/query-how-to), [Query reference](/reference/query) +**See also:** [Query how-to](//query/guide), [Query reference](/query/language) ### Repository cache {:#repo-cache} @@ -461,7 +461,7 @@ 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](/rules/rules) +**See also:** [Rules documentation](/extending/rules) ### Rule target {:#rule-target} @@ -476,7 +476,7 @@ 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](/rules/rules#runfiles) +**See also:** [Runfiles documentation](/extending/rules#runfiles) ### Sandboxing {:#sandboxing} @@ -498,12 +498,12 @@ On Linux, it's not significant, but on macOS it can make sandboxing unusable. 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](/rules/rules) that +Enable through the `--workspace_status_command` flag and [rules](/extending/rules) that support the stamp attribute. ### Starlark {:#starlark} -The extension language for writing [rules](/rules/rules) and [macros](#macro). A +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 diff --git a/site/en/release/backward-compatibility.md b/site/en/release/backward-compatibility.md index 1fd2f3c5082f02..cb9034d3774da6 100644 --- a/site/en/release/backward-compatibility.md +++ b/site/en/release/backward-compatibility.md @@ -26,7 +26,7 @@ works, see ## How to follow this policy {:#policy} -* [For Bazel users - how to update Bazel](/versions/updating-bazel) +* [For Bazel users - how to update Bazel](/install/bazelisk) * [For contributors - best practices for incompatible changes](/contribute/breaking-changes) * [For release managers - how to update issue labels and release](https://github.com/bazelbuild/continuous-integration/tree/master/docs/release-playbook.%6D%64){: .external} diff --git a/site/en/release/versioning.md b/site/en/release/versioning.md index 3308df4df88b1c..e387ecb90878a7 100644 --- a/site/en/release/versioning.md +++ b/site/en/release/versioning.md @@ -91,6 +91,6 @@ details, see the ## Updating versions {:#updating-versions} * For more information on updating your Bazel version, see - [Updating Bazel](/versions/updating-bazel). + [Updating Bazel](/install/bazelisk). * For more information on contributing updates to new Bazel releases, see [Contributing to Bazel](/contribute). diff --git a/site/en/remote/bep-examples.md b/site/en/remote/bep-examples.md index c3972383b7ee77..93b236c6abf02f 100644 --- a/site/en/remote/bep-examples.md +++ b/site/en/remote/bep-examples.md @@ -104,7 +104,7 @@ built. ## Aspect Results in BEP {:#aspect-results} Ordinary builds evaluate actions associated with `(target, configuration)` -pairs. When building with [aspects](/rules/aspects) enabled, Bazel +pairs. When building with [aspects](/extending/aspects) enabled, Bazel additionally evaluates targets associated with `(target, configuration, aspect)` triples, for each target affected by a given enabled aspect. diff --git a/site/en/remote/bep-glossary.md b/site/en/remote/bep-glossary.md index 405e3841c7ca81..ff0b384f5c7f0d 100644 --- a/site/en/remote/bep-glossary.md +++ b/site/en/remote/bep-glossary.md @@ -401,7 +401,7 @@ differentiate `FLAKY` tests from `FAILED` tests. Unlike [CommandLine](#commandline), this event carries the unparsed commandline flags in string form as encountered by the build tool after expanding all -[`.bazelrc`](/docs/bazelrc) files and +[`.bazelrc`](/run/bazelrc) files and considering the `--config` flag. The `UnstructuredCommandLine` event may be relied upon to precisely reproduce a diff --git a/site/en/remote/bep.md b/site/en/remote/bep.md index a6a999dacedbfd..390373db90f5e4 100644 --- a/site/en/remote/bep.md +++ b/site/en/remote/bep.md @@ -141,7 +141,7 @@ The BEP typically contains many references to log files (test.log, test.xml, etc. ) stored on the machine where Bazel is running. A remote BES server typically can't access these files as they are on different machines. A way to work around this issue is to use Bazel with [remote -caching](/docs/remote-caching). +caching](/remote/caching). Bazel will upload all output files to the remote cache (including files referenced in the BEP) and the BES server can then fetch the referenced files from the cache. diff --git a/site/en/remote/cache-local.md b/site/en/remote/cache-local.md index a7be1e7441e0b5..f4aea843f5aae5 100644 --- a/site/en/remote/cache-local.md +++ b/site/en/remote/cache-local.md @@ -14,7 +14,7 @@ that the remote cache is being effectively utilized. For tips on how to check your cache hit rate and how to compare the execution logs between two Bazel invocations, see -[Debugging Remote Cache Hits for Remote Execution](/docs/remote-execution-caching-debug). +[Debugging Remote Cache Hits for Remote Execution](/remote/cache-remote). Everything presented in that guide also applies to remote caching with local execution. However, local execution presents some additional challenges. @@ -22,7 +22,7 @@ execution. However, local execution presents some additional challenges. Successful remote cache hits will show up in the status line, similar to [Cache Hits rate with Remote -Execution](/docs/remote-execution-caching-debug#check-cache-hits). +Execution](/remote/cache-remote#check-cache-hits). In the standard output of your Bazel run, you will see something like the following: @@ -72,7 +72,7 @@ the steps in this section. `--verbose_failures`. 2. Follow the steps from [Troubleshooting cache hits for remote - execution](/docs/remote-execution-caching-debug#troubleshooting_cache_hits) to + execution](/remote/cache-remote#troubleshooting_cache_hits) to ensure that your cache-writing Bazel invocations are able to get cache hits on the same machine and across machines. @@ -87,6 +87,6 @@ the steps in this section. cache-writing Bazel invocations. c. Follow the same steps as to [ensure caching across - machines](/docs/remote-execution-caching-debug#caching-across-machines), + machines](/remote/cache-remote#caching-across-machines), to ensure caching from your cache-writing Bazel invocation to your cache-reading Bazel invocation. diff --git a/site/en/remote/cache-remote.md b/site/en/remote/cache-remote.md index 4dd7ebbee549ca..6d583a0a6b951d 100644 --- a/site/en/remote/cache-remote.md +++ b/site/en/remote/cache-remote.md @@ -111,7 +111,7 @@ If you are not getting the cache hit rate you are expecting, do the following: d. If `remote_accept_cached` is `false`, determine where it is being set to `false`: either at the command line or in a - [bazelrc](/docs/bazelrc#bazelrc-file-locations) file. + [bazelrc](/run/bazelrc#bazelrc-file-locations) file. ### Ensure caching across machines {:#caching-across-machines} diff --git a/site/en/remote/caching.md b/site/en/remote/caching.md index 206614e0f80580..d34f5e7557b15e 100644 --- a/site/en/remote/caching.md +++ b/site/en/remote/caching.md @@ -348,8 +348,8 @@ and Bazel must rebuild it before using the remote cache. * **Faster Bazel builds with remote caching: a benchmark:** Nicolò Valigi wrote a [blog post](https://nicolovaligi.com/faster-bazel-remote-caching-benchmark.html){: .external} in which he benchmarks remote caching in Bazel. -* [Adapting Rules for Remote Execution](/docs/remote-execution-rules) -* [Troubleshooting Remote Execution](/docs/remote-execution-sandbox) +* [Adapting Rules for Remote Execution](/remote/rules) +* [Troubleshooting Remote Execution](/remote/sandbox) * [WebDAV module](https://nginx.org/en/docs/http/ngx_http_dav_module.html){: .external} * [Docker image](https://hub.docker.com/r/buchgr/bazel-remote-cache/){: .external} * [bazel-remote](https://github.com/buchgr/bazel-remote/){: .external} diff --git a/site/en/remote/ci.md b/site/en/remote/ci.md index b1a88d0b323755..ca9c7098d81e35 100644 --- a/site/en/remote/ci.md +++ b/site/en/remote/ci.md @@ -74,7 +74,7 @@ If your build or tests fail, it's likely due to the following: * **Build or test targets are using rules that are incompatible with remote execution.** See - [Adapting Bazel Rules for Remote Execution](/docs/remote-execution-rules) for + [Adapting Bazel Rules for Remote Execution](/remote/rules) for details about compatibility with remote execution. ## Using a custom container in the rbe_ubuntu1604 CI config {:#custom-container} @@ -196,7 +196,7 @@ Container Registry as follows: ### Specifying the build platform definition {:#platform-definition} -You must include a [Bazel platform](/docs/platforms) configuration in your +You must include a [Bazel platform](/extending/platforms) configuration in your custom toolchain configuration, which allows Bazel to select a toolchain appropriate to the desired hardware/software platform. To generate automatically a valid platform, you can add to your `WORKSPACE` an diff --git a/site/en/remote/creating.md b/site/en/remote/creating.md index 21390e203d1ee9..9469198f490e1e 100644 --- a/site/en/remote/creating.md +++ b/site/en/remote/creating.md @@ -5,7 +5,7 @@ Book: /_book.yaml {% include "_buttons.html" %} -[Persistent workers](/docs/persistent-workers) can make your build faster. If +[Persistent workers](/remote/persistent) can make your build faster. If you have repeated actions in your build that have a high startup cost or would benefit from cross-action caching, you may want to implement your own persistent worker to perform these actions. @@ -65,7 +65,7 @@ Bazel sets the `verbosity` field to 10, but smaller or larger values can be used manually for different amounts of output. The optional `sandbox_dir` field is used only by workers that support -[multiplex sandboxing](/docs/multiplex-worker). +[multiplex sandboxing](/remote/multiplex). ### Work responses {:#work-responses} @@ -237,7 +237,7 @@ ctx.actions.run( ``` For another example, see -[Implementing persistent workers](/docs/persistent-workers#implementation). +[Implementing persistent workers](/remote/persistent#implementation). ## Examples {:#examples} diff --git a/site/en/remote/dynamic.md b/site/en/remote/dynamic.md index 4783ac460a04b6..6b5a4bdfd2821c 100644 --- a/site/en/remote/dynamic.md +++ b/site/en/remote/dynamic.md @@ -17,7 +17,7 @@ This page describes how to enable, tune, and debug dynamic execution. If you have both local and remote execution set up and are trying to adjust Bazel settings for better performance, this page is for you. If you don't already have remote execution set up, go to the Bazel -[Remote Execution Overview](/docs/remote-execution) first. +[Remote Execution Overview](/remote/rbe) first. ## Enabling dynamic execution? {:#enabling-dynamic-execution} @@ -53,9 +53,9 @@ away to add roundtrip latency. You can use the to look at how long typical cache hits take. Dynamic execution can be used with local sandboxed strategy as well as with -[persistent workers](/docs/persistent-workers). Persistent workers will +[persistent workers](/remote/persistent). Persistent workers will automatically run with sandboxing when used with dynamic execution, and cannot -use [multiplex workers](/docs/multiplex-worker). On Darwin and Windows systems, +use [multiplex workers](/remote/multiplex). On Darwin and Windows systems, the sandboxed strategy can be slow; you can pass `--reuse_sandbox_directories` to reduce overhead of creating sandboxes on these systems. @@ -77,13 +77,13 @@ Merino's excellent ## When should I use dynamic execution? {:#when-to-use} Dynamic execution requires some form of -[remote execution system](/docs/remote-execution). It is not currently +[remote execution system](/remote/rbe). It is not currently possible to use a cache-only remote system, as a cache miss would be considered a failed action. Not all types of actions are well suited for remote execution. The best candidates are those that are inherently faster locally, for instance through -the use of [persistent workers](/docs/persistent-workers), or those that run +the use of [persistent workers](/remote/persistent), or those that run fast enough that the overhead of remote execution dominates execution time. Since each locally executed action locks some amount of CPU and memory resources, running actions that don't fall into those categories merely delays diff --git a/site/en/remote/persistent.md b/site/en/remote/persistent.md index 08da2afab61243..6bd76a97dec59e 100644 --- a/site/en/remote/persistent.md +++ b/site/en/remote/persistent.md @@ -160,7 +160,7 @@ For Android builds, see details at the ## Implementing persistent workers {:#implementation} -See the [creating persistent workers](/docs/creating-workers) page for more +See the [creating persistent workers](/remote/creating) page for more information on how to make a worker. This example shows a Starlark configuration for a worker that uses JSON: @@ -224,7 +224,7 @@ be spawned for each value used. This can lead to excessive memory consumption if too many variations are used. Each worker can currently only process one request at a time. The experimental -[multiplex workers](/docs/multiplex-worker) feature allows using multiple +[multiplex workers](/remote/multiplex) feature allows using multiple threads, if the underlying tool is multithreaded and the wrapper is set up to understand this. diff --git a/site/en/remote/rbe.md b/site/en/remote/rbe.md index 4222e4a091675c..b0e116b6ebdc03 100644 --- a/site/en/remote/rbe.md +++ b/site/en/remote/rbe.md @@ -31,4 +31,4 @@ self-service tools, see Remote execution of Bazel builds imposes a set of mandatory configuration constraints on the build. For more information, see -[Adapting Bazel Rules for Remote Execution](/docs/remote-execution-rules). +[Adapting Bazel Rules for Remote Execution](/remote/rules). diff --git a/site/en/remote/rules.md b/site/en/remote/rules.md index c47de9f66b3ebf..15ea01760b0233 100644 --- a/site/en/remote/rules.md +++ b/site/en/remote/rules.md @@ -64,7 +64,7 @@ and [Go](https://github.com/bazelbuild/rules_go/blob/master/go/toolchains.rst){: and new toolchain rules are under way for other languages and tools such as [bash](https://docs.google.com/document/d/e/2PACX-1vRCSB_n3vctL6bKiPkIa_RN_ybzoAccSe0ic8mxdFNZGNBJ3QGhcKjsL7YKf-ngVyjRZwCmhi_5KhcX/pub){: .external}. If a toolchain rule does not exist for the tool your rule uses, consider -[creating a toolchain rule](/docs/toolchains#creating-a-toolchain-rule). +[creating a toolchain rule](/extending/toolchains#creating-a-toolchain-rule). ## Managing implicit dependencies {:#manage-dependencies} @@ -87,7 +87,7 @@ _foo_ will be lost and the build will fail. To help detect and eliminate these dependency problems, Bazel 0.14.1 offers the local Docker sandbox, which has the same restrictions for dependencies as remote execution. Use the sandbox to prepare your build for remote execution by -identifying and resolving dependency-related build errors. See [Troubleshooting Bazel Remote Execution with Docker Sandbox](/docs/remote-execution-sandbox) +identifying and resolving dependency-related build errors. See [Troubleshooting Bazel Remote Execution with Docker Sandbox](/remote/sandbox) for more information. ## Managing platform-dependent binaries {:#manage-binaries} @@ -143,7 +143,7 @@ remote execution: `runfiles` tree, creating environment variables, and similar actions, as they may behave unexpectedly on the remote execution platform. -To help find potential non-hermetic behavior you can use [Workspace rules log](/docs/workspace-log). +To help find potential non-hermetic behavior you can use [Workspace rules log](/remote/workspace). If an external dependency executes specific operations dependent on the host platform, you should split those operations between `WORKSPACE` and build diff --git a/site/en/remote/sandbox.md b/site/en/remote/sandbox.md index b94eb90c07172b..f72cb7941f4b38 100644 --- a/site/en/remote/sandbox.md +++ b/site/en/remote/sandbox.md @@ -7,7 +7,7 @@ Book: /_book.yaml Bazel builds that succeed locally may fail when executed remotely due to restrictions and requirements that do not affect local builds. The most common -causes of such failures are described in [Adapting Bazel Rules for Remote Execution](/docs/remote-execution-rules). +causes of such failures are described in [Adapting Bazel Rules for Remote Execution](/remote/rules). This page describes how to identify and resolve the most common issues that arise with remote execution using the Docker sandbox feature, which imposes @@ -97,7 +97,7 @@ machine and is a reliable way to confirm whether your build will succeed when executed remotely. However, with this method, locally installed tools, binaries, and data may leak -into into your build, especially if it uses [configure-style WORKSPACE rules](/docs/remote-execution-rules#manage-workspace-rules). +into into your build, especially if it uses [configure-style WORKSPACE rules](/remote/rules#manage-workspace-rules). Such leaks will cause problems with remote execution; to detect them, [troubleshoot in a Docker container](#troubleshooting-docker-container) in addition to troubleshooting natively. @@ -132,19 +132,19 @@ The following are the most commonly encountered issues and their workarounds. * **A file, tool, binary, or resource referenced by the Bazel runfiles tree is missing.**. Confirm that all dependencies of the affected targets have been [explicitly declared](/concepts/dependencies). See - [Managing implicit dependencies](/docs/remote-execution-rules#manage-dependencies) + [Managing implicit dependencies](/remote/rules#manage-dependencies) for more information. * **A file, tool, binary, or resource referenced by an absolute path or the `PATH` variable is missing.** Confirm that all required tools are installed within - the toolchain container and use [toolchain rules](/docs/toolchains) to properly + the toolchain container and use [toolchain rules](/extending/toolchains) to properly declare dependencies pointing to the missing resource. See - [Invoking build tools through toolchain rules](/docs/remote-execution-rules#invoking-build-tools-through-toolchain-rules) + [Invoking build tools through toolchain rules](/remote/rules#invoking-build-tools-through-toolchain-rules) for more information. * **A binary execution fails.** One of the build rules is referencing a binary incompatible with the execution environment (the Docker container). See - [Managing platform-dependent binaries](/docs/remote-execution-rules#manage-binaries) + [Managing platform-dependent binaries](/remote/rules#manage-binaries) for more information. If you cannot resolve the issue, contact [bazel-discuss@google.com](mailto:bazel-discuss@google.com) for help. @@ -255,7 +255,7 @@ You can resolve build failures as follows: * If the build fails during the analysis or loading phases, one or more of your build rules declared in the WORKSPACE file are not compatible with - remote execution. See [Adapting Bazel Rules for Remote Execution](/docs/remote-execution-rules) + remote execution. See [Adapting Bazel Rules for Remote Execution](/remote/rules) for possible causes and workarounds. * If the build fails for any other reason, see the troubleshooting steps in [Step 2: Resolve detected issues](#start-container). diff --git a/site/en/remote/workspace.md b/site/en/remote/workspace.md index f4f80ae956852d..aa65553a09dabf 100644 --- a/site/en/remote/workspace.md +++ b/site/en/remote/workspace.md @@ -15,7 +15,7 @@ host machine for use during execution, your build is likely to break due to incompatibilities between the environments. As part of [adapting Bazel rules for remote -execution](/docs/remote-execution-rules), you need to find such workspace rules +execution](/remote/rules), you need to find such workspace rules and fix them. This page describes how to find potentially problematic workspace rules using the workspace log. diff --git a/site/en/rules/bzl-style.md b/site/en/rules/bzl-style.md index 11e07aa08093b0..595b6117947b03 100644 --- a/site/en/rules/bzl-style.md +++ b/site/en/rules/bzl-style.md @@ -169,7 +169,7 @@ goals. As a rule of thumb, the more macros resemble the rules, the better. -See also [macros](/rules/macros#conventions). +See also [macros](/extending/macros#conventions). ## Rules {:#rules} @@ -204,7 +204,7 @@ See also [macros](/rules/macros#conventions). (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](/rules/rules#providers) interface. Declare and document provider + [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 diff --git a/site/en/rules/deploying.md b/site/en/rules/deploying.md index a767bad3e28dea..8bc1c092df4a5b 100644 --- a/site/en/rules/deploying.md +++ b/site/en/rules/deploying.md @@ -129,7 +129,7 @@ For `rules_mockascript` that means there will be a directory named ### Constraints If your rule defines -[toolchain](/docs/toolchains) rules, +[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 `///constraints` package. Your directory structure will look like this: diff --git a/site/en/rules/faq.md b/site/en/rules/faq.md index 4e831cc28be614..85788fa16097cc 100644 --- a/site/en/rules/faq.md +++ b/site/en/rules/faq.md @@ -22,7 +22,7 @@ Bazel only executes the actions needed to produce the *requested* output files. 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](/rules/rules#requesting-output-files) for more information. +See the [Rules page](/extending/rules#requesting-output-files) for more information. ## Why is my implementation function not executed? @@ -42,14 +42,14 @@ that creates the action. The proper path for the file can be obtained using For binaries (the executable outputs run by a `bazel run` or `bazel test` command), you declare inputs by including them in the -[runfiles](/rules/rules#runfiles). Instead of using the `path` field, use +[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](/rules/rules#requesting-output-files). +[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? diff --git a/site/en/rules/index.md b/site/en/rules/index.md index dd3599f9a04be8..a3dbdf3df2cb71 100644 --- a/site/en/rules/index.md +++ b/site/en/rules/index.md @@ -8,7 +8,7 @@ Book: /_book.yaml 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](/rules/concepts) that can be used by others. +[define new rules](/extending/concepts) that can be used by others. This page describes the recommended, native, and non-native Bazel rules. @@ -38,7 +38,7 @@ 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](/contribute/recommended-rules){: .external}. +[requirements for recommended rules](/community/recommended-rules){: .external}. Contact the respective rule set's maintainers regarding issues and feature requests. diff --git a/site/en/rules/macro-tutorial.md b/site/en/rules/macro-tutorial.md index 8f20e152c94723..34c00aa68e7c7c 100644 --- a/site/en/rules/macro-tutorial.md +++ b/site/en/rules/macro-tutorial.md @@ -11,7 +11,7 @@ tutorial, you are going to create a 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](/rules/rules). Rules give you more control and flexibility. +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`: diff --git a/site/en/rules/rules-tutorial.md b/site/en/rules/rules-tutorial.md index f5285d5fee399c..a934deb9421869 100644 --- a/site/en/rules/rules-tutorial.md +++ b/site/en/rules/rules-tutorial.md @@ -17,7 +17,7 @@ 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/getting-started) and [Starlark](/rules/concepts) documentation for +[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. @@ -114,7 +114,7 @@ Make a few observations: * 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`](/docs/cquery) ("configured +To analyze the targets, use the [`cquery`](/query/cquery) ("configured query") or the `build` command: ``` diff --git a/site/en/rules/testing.md b/site/en/rules/testing.md index 1359128a7c6881..b93d50e12295b1 100644 --- a/site/en/rules/testing.md +++ b/site/en/rules/testing.md @@ -26,7 +26,7 @@ Some caveats: * 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](/rules/concepts#evaluation-model) that macros + 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. diff --git a/site/en/rules/verbs-tutorial.md b/site/en/rules/verbs-tutorial.md index a9ed24025d77c8..b324a6f804640e 100644 --- a/site/en/rules/verbs-tutorial.md +++ b/site/en/rules/verbs-tutorial.md @@ -70,7 +70,7 @@ learn to recognize it. ## Adapting your own rules -[Macros](/rules/macros) are the heart of this pattern. Macros are used like +[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 diff --git a/site/en/run/build.md b/site/en/run/build.md index 0b018bdd37ae31..c02d4c1912d055 100644 --- a/site/en/run/build.md +++ b/site/en/run/build.md @@ -27,13 +27,13 @@ Usage: bazel {{ "" }}command{{ "" }} {{ "" }}options{{ "" * [`build`](#bazel-build): Builds the specified targets. * [`canonicalize-flags`](/docs/user-manual#canonicalize-flags): Canonicalize Bazel flags. * [`clean`](/docs/user-manual#clean): Removes output files and optionally stops the server. -* [`cquery`](/docs/cquery): Executes a [post-analysis](#analysis) dependency graph query. +* [`cquery`](/query/cquery): Executes a [post-analysis](#analysis) dependency graph query. * [`dump`](/docs/user-manual#dump): Dumps the internal state of the Bazel server process. * [`help`](/docs/user-manual#help): Prints help for commands, or the index. * [`info`](/docs/user-manual#info): Displays runtime info about the bazel server. * [`fetch`](#fetching-external-dependencies): Fetches all external dependencies of a target. * [`mobile-install`](/docs/user-manual#mobile-install): Installs apps on mobile devices. -* [`query`](/docs/query-how-to): Executes a dependency graph query. +* [`query`](//query/guide): Executes a dependency graph query. * [`run`](/docs/user-manual#running-executables): Runs the specified target. * [`shutdown`](/docs/user-manual#shutdown): Stops the Bazel server. * [`test`](/docs/user-manual#running-tests): Builds and runs the specified test targets. @@ -612,7 +612,7 @@ the host system in unknown ways. To disable this warning you can pass the Note: Hermeticity means that the action only uses its declared input files and no other files in the filesystem, and it only produces its declared -output files. See [Hermeticity](/concepts/hermeticity) for more details. +output files. See [Hermeticity](/basics/hermeticity) for more details. On some platforms such as [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/){: .external} cluster nodes or Debian, @@ -668,7 +668,7 @@ inputs to a rule, and all rule-specific error messages. The loading and analysis phases are fast because Bazel avoids unnecessary file I/O at this stage, reading only BUILD files in order to determine the work to be done. This is by design, and makes Bazel a good foundation for analysis tools, -such as Bazel's [query](/docs/query-how-to) command, which is implemented atop the loading +such as Bazel's [query](//query/guide) command, which is implemented atop the loading phase. #### Execution phase {:#execution} diff --git a/site/en/run/scripts.md b/site/en/run/scripts.md index 622f148af10e50..dc17707074b792 100644 --- a/site/en/run/scripts.md +++ b/site/en/run/scripts.md @@ -31,7 +31,7 @@ commands to complete before it can continue. ### Notes about server mode {:#server-mode} -By default, Bazel uses a long-running [server process](/docs/client-server) as an +By default, Bazel uses a long-running [server process](/run/client-server) as an optimization. When running Bazel in a script, don't forget to call `shutdown` when you're finished with the server, or, specify `--max_idle_secs=5` so that idle servers shut themselves down promptly. @@ -89,7 +89,7 @@ However, all non-zero exit values will always constitute an error. ### Reading the .bazelrc file {:#reading-bazelrc} -By default, Bazel reads the [`.bazelrc` file](/docs/bazelrc) from the base +By default, Bazel reads the [`.bazelrc` file](/run/bazelrc) from the base workspace directory or the user's home directory. Whether or not this is desirable is a choice for your script; if your script needs to be perfectly hermetic (such as when doing release builds), you should disable reading the diff --git a/site/en/start/_index.yaml b/site/en/start/_index.yaml index 491033a54fdb71..6fe071910fb7f1 100644 --- a/site/en/start/_index.yaml +++ b/site/en/start/_index.yaml @@ -149,6 +149,6 @@ landing_page: Defines whether a target can be depended upon by other targets. - heading: Hermeticity classname: fully-clickable - path: /concepts/hermeticity + path: /basics/hermeticity description: > Builds with no external influences for deterministic and correct results. diff --git a/site/en/start/cpp.md b/site/en/start/cpp.md index fd38635bef2b7f..851e4c4974fa47 100644 --- a/site/en/start/cpp.md +++ b/site/en/start/cpp.md @@ -399,8 +399,8 @@ start. Here are some more resources to continue learning with Bazel: * To keep focusing on C++, read about common [C++ build use cases](https://bazel.build/tutorials/cpp-use-cases). * To get started with building other applications with Bazel, see the tutorials -for [Java](https://bazel.build/tutorials/java), [Android application](https://bazel.build/tutorials/android-app), -or [iOS application](https://bazel.build/tutorials/ios-app). +for [Java](https://bazel.build/start/java), [Android application](https://bazel.build/start/android-app ), +or [iOS application](https://bazel.build/start/ios-app)). * To learn more about working with local and remote repositories, read about [external dependencies](https://bazel.build/docs/external). * To learn more about Bazel’s other rules, see this [reference guide](https://bazel.build/rules). diff --git a/site/en/start/ios-app.md b/site/en/start/ios-app.md index 3e96126d49157e..38e1903eb7b543 100644 --- a/site/en/start/ios-app.md +++ b/site/en/start/ios-app.md @@ -3,4 +3,4 @@ Book: /_book.yaml # Bazel Tutorial: Build an iOS App -This tutorial has been moved into the [bazelbuild/rules_apple](https://github.com/bazelbuild/rules_apple/blob/master/doc/tutorials/ios-app.md) repository. +This tutorial has been moved into the [bazelbuild/rules_apple](https://github.com/bazelbuild/rules_apple/blob/master/doc/start/ios-app).md) repository. diff --git a/site/en/start/java.md b/site/en/start/java.md index eb91918e8e4813..56e904a9000d27 100644 --- a/site/en/start/java.md +++ b/site/en/start/java.md @@ -427,11 +427,11 @@ For more details, see: * The [other rules](/rules) to learn more about Bazel. -* The [C++ build tutorial](/tutorials/cpp) to get started with building +* The [C++ build tutorial](/start/cpp) to get started with building C++ projects with Bazel. -* The [Android application tutorial](/tutorials/android-app) and - [iOS application tutorial](/tutorials/ios-app) to get started with +* The [Android application tutorial](/start/android-app ) and + [iOS application tutorial](/start/ios-app)) to get started with building mobile applications for Android and iOS with Bazel. Happy building! diff --git a/site/en/tutorials/cpp-use-cases.md b/site/en/tutorials/cpp-use-cases.md index 5c5acfdcf3e517..45951c8c05d62d 100644 --- a/site/en/tutorials/cpp-use-cases.md +++ b/site/en/tutorials/cpp-use-cases.md @@ -8,7 +8,7 @@ Book: /_book.yaml Here you will find some of the most common use cases for building C++ projects with Bazel. If you have not done so already, get started with building C++ projects with Bazel by completing the tutorial -[Introduction to Bazel: Build a C++ Project](/tutorials/cpp). +[Introduction to Bazel: Build a C++ Project](/start/cpp). For information on cc_library and hdrs header files, see cc_library.