diff --git a/upstream b/upstream index 37654e56..a0bb2eed 160000 --- a/upstream +++ b/upstream @@ -1 +1 @@ -Subproject commit 37654e56598027f1f65bf729d604a600786dd8e9 +Subproject commit a0bb2eedde841cff8b75ae5965de851d2403da69 diff --git a/versions/9.1.0/basics/task-based-builds.mdx b/versions/9.1.0/basics/task-based-builds.mdx index a0fe9fb2..b5a3d46a 100644 --- a/versions/9.1.0/basics/task-based-builds.mdx +++ b/versions/9.1.0/basics/task-based-builds.mdx @@ -23,32 +23,32 @@ Take this example from the simple example build file - + {/* set global properties for this build */} - + {/* Create the time stamp */} - + {/* Create the build directory structure used by compile */} - + {/* Compile the Java code from ${src} into ${build} */} - + {/* Create the distribution directory */} - + {/* Put everything in ${build} into the MyProject-${DSTAMP}.jar file */} - + {/* Delete the ${build} and ${dist} directory trees */} diff --git a/versions/9.1.0/community/images/Bitrise.png b/versions/9.1.0/community/images/Bitrise.png new file mode 100644 index 00000000..07f85f1e Binary files /dev/null and b/versions/9.1.0/community/images/Bitrise.png differ diff --git a/versions/9.1.0/community/images/Gradle.png b/versions/9.1.0/community/images/Gradle.png new file mode 100644 index 00000000..1e5f5eb0 Binary files /dev/null and b/versions/9.1.0/community/images/Gradle.png differ diff --git a/versions/9.1.0/community/images/Linkedin-Logo.png b/versions/9.1.0/community/images/Linkedin-Logo.png new file mode 100644 index 00000000..9dd8715c Binary files /dev/null and b/versions/9.1.0/community/images/Linkedin-Logo.png differ diff --git a/versions/9.1.0/community/images/Lucid_Software-logo.svg b/versions/9.1.0/community/images/Lucid_Software-logo.svg new file mode 100644 index 00000000..6c8591e0 --- /dev/null +++ b/versions/9.1.0/community/images/Lucid_Software-logo.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + diff --git a/versions/9.1.0/community/images/acqio_logo.svg b/versions/9.1.0/community/images/acqio_logo.svg new file mode 100644 index 00000000..8fa11bcd --- /dev/null +++ b/versions/9.1.0/community/images/acqio_logo.svg @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/versions/9.1.0/community/images/aspect-logo-2.png b/versions/9.1.0/community/images/aspect-logo-2.png new file mode 100644 index 00000000..dfebc4cb Binary files /dev/null and b/versions/9.1.0/community/images/aspect-logo-2.png differ diff --git a/versions/9.1.0/community/images/bitrise-logo.png b/versions/9.1.0/community/images/bitrise-logo.png new file mode 100644 index 00000000..27037ce6 Binary files /dev/null and b/versions/9.1.0/community/images/bitrise-logo.png differ diff --git a/versions/9.1.0/community/images/buildbuddy-logo.svg b/versions/9.1.0/community/images/buildbuddy-logo.svg new file mode 100644 index 00000000..bdb72dc6 --- /dev/null +++ b/versions/9.1.0/community/images/buildbuddy-logo.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/versions/9.1.0/community/images/buildkite.svg b/versions/9.1.0/community/images/buildkite.svg new file mode 100644 index 00000000..209a4ab1 --- /dev/null +++ b/versions/9.1.0/community/images/buildkite.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/community/images/codethink-logo.svg b/versions/9.1.0/community/images/codethink-logo.svg new file mode 100644 index 00000000..406005d8 --- /dev/null +++ b/versions/9.1.0/community/images/codethink-logo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/community/images/develocity.png b/versions/9.1.0/community/images/develocity.png new file mode 100644 index 00000000..eb3eb65a Binary files /dev/null and b/versions/9.1.0/community/images/develocity.png differ diff --git a/versions/9.1.0/community/images/dropbox.png b/versions/9.1.0/community/images/dropbox.png new file mode 100644 index 00000000..125476a6 Binary files /dev/null and b/versions/9.1.0/community/images/dropbox.png differ diff --git a/versions/9.1.0/community/images/engflow-logo.svg b/versions/9.1.0/community/images/engflow-logo.svg new file mode 100644 index 00000000..e5f0c343 --- /dev/null +++ b/versions/9.1.0/community/images/engflow-logo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/community/images/epam-logo.png b/versions/9.1.0/community/images/epam-logo.png new file mode 100644 index 00000000..e6a5674c Binary files /dev/null and b/versions/9.1.0/community/images/epam-logo.png differ diff --git a/versions/9.1.0/community/images/flare-logo.png b/versions/9.1.0/community/images/flare-logo.png new file mode 100644 index 00000000..84cb0e5b Binary files /dev/null and b/versions/9.1.0/community/images/flare-logo.png differ diff --git a/versions/9.1.0/community/images/hermetiq-logo.png b/versions/9.1.0/community/images/hermetiq-logo.png new file mode 100644 index 00000000..90765d96 Binary files /dev/null and b/versions/9.1.0/community/images/hermetiq-logo.png differ diff --git a/versions/9.1.0/community/images/jetbrains.svg b/versions/9.1.0/community/images/jetbrains.svg new file mode 100644 index 00000000..cb3a2a0e --- /dev/null +++ b/versions/9.1.0/community/images/jetbrains.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + diff --git a/versions/9.1.0/community/images/liulishuo.png b/versions/9.1.0/community/images/liulishuo.png new file mode 100644 index 00000000..a6758e5c Binary files /dev/null and b/versions/9.1.0/community/images/liulishuo.png differ diff --git a/versions/9.1.0/community/images/nativelink.svg b/versions/9.1.0/community/images/nativelink.svg new file mode 100644 index 00000000..148fcdce --- /dev/null +++ b/versions/9.1.0/community/images/nativelink.svg @@ -0,0 +1,1123 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/versions/9.1.0/community/images/oasis-logo.png b/versions/9.1.0/community/images/oasis-logo.png new file mode 100644 index 00000000..846a9cd5 Binary files /dev/null and b/versions/9.1.0/community/images/oasis-logo.png differ diff --git a/versions/9.1.0/community/images/sumglobal-logo.png b/versions/9.1.0/community/images/sumglobal-logo.png new file mode 100644 index 00000000..6736328d Binary files /dev/null and b/versions/9.1.0/community/images/sumglobal-logo.png differ diff --git a/versions/9.1.0/community/images/trunk-logo-dark.svg b/versions/9.1.0/community/images/trunk-logo-dark.svg new file mode 100644 index 00000000..f25940af --- /dev/null +++ b/versions/9.1.0/community/images/trunk-logo-dark.svg @@ -0,0 +1,22 @@ + + + + + + + + + + + + + + + + + + + + + + diff --git a/versions/9.1.0/community/images/tweag-logo.png b/versions/9.1.0/community/images/tweag-logo.png new file mode 100644 index 00000000..20210ed7 Binary files /dev/null and b/versions/9.1.0/community/images/tweag-logo.png differ diff --git a/versions/9.1.0/community/images/typedb.png b/versions/9.1.0/community/images/typedb.png new file mode 100644 index 00000000..48ce1056 Binary files /dev/null and b/versions/9.1.0/community/images/typedb.png differ diff --git a/versions/9.1.0/community/images/virtuslab.svg b/versions/9.1.0/community/images/virtuslab.svg new file mode 100644 index 00000000..6fba0316 --- /dev/null +++ b/versions/9.1.0/community/images/virtuslab.svg @@ -0,0 +1,20 @@ + + + + + + + + + + + + + + + + + + diff --git a/versions/9.1.0/community/users.mdx b/versions/9.1.0/community/users.mdx index 7c72399d..39851e98 100644 --- a/versions/9.1.0/community/users.mdx +++ b/versions/9.1.0/community/users.mdx @@ -1,5 +1,5 @@ --- -title: 'Who's Using Bazel' +title: "Who's Using Bazel" --- Note: Using Bazel? You can add your company on @@ -9,26 +9,26 @@ contact [product@bazel.build](mailto:product@bazel.build). This page lists companies and OSS projects that are known to use Bazel. This does not constitute an endorsement. -## Companies using Bazel {:#companies-using-bazel} +## Companies using Bazel {#companies-using-bazel} -### [acqio](https://acqio.com.br){: .external} +### [acqio](https://acqio.com.br) - + Acqio is a Fintech that provides payment products and services for small and medium merchants. Acqio has a handful of monorepos and uses Bazel along with Kubernetes to deliver fast and reliable microservices. -### [Adobe](https://www.adobe.com/){: .external} +### [Adobe](https://www.adobe.com/) - + -Adobe has released Bazel [rules](https://github.com/adobe/rules_gitops){: .external} for +Adobe has released Bazel [rules](https://github.com/adobe/rules_gitops) for continuous, GitOps driven Kubernetes deployments. -### [Asana](https://asana.com){: .external} +### [Asana](https://asana.com) - + Asana is a web and mobile application designed to help teams track their work. In their own words: @@ -41,32 +41,32 @@ at Asana. We no longer need to clean because of incorrect caches. Ascend is a Palo Alto startup that offers solutions for large data sets analysis. Their motto is _Big data is hard. We make it easy_. -### [ASML](https://asml.com){: .external} +### [ASML](https://asml.com) - + ASML is an innovation leader in the semiconductor industry. We provide chipmakers with everything they need – hardware, software and services – to mass produce patterns on silicon through lithography. -### [Beeswax](https://www.beeswax.com/){: .external} +### [Beeswax](https://www.beeswax.com/) > Beeswax is a New York based startup that provides real time bidding as service. Bazel powers their Jenkins based continuous integration and deployment framework. Beeswax loves Bazel because it is blazingly fast, correct and well supported across many languages and platforms. -### [Braintree](https://www.braintreepayments.com){: .external} +### [Braintree](https://www.braintreepayments.com) - + Braintree, a PayPal subsidiary, develops payment solutions for websites and applications. They use Bazel for parts of their internal build and Paul Gross even posted a [nice piece about how their switch to Bazel went](https://www.pgrs.net/2015/09/01/migrating-from-gradle-to-bazel/). -### [Canva](https://www.canva.com/){: .external} - +### [Canva](https://www.canva.com/) + Canva leverages Bazel to manage its large polyglot codebase, which includes Java, TypeScript, Scala, Python, and more. Migration to Bazel has delivered @@ -74,21 +74,21 @@ significant developer and compute infrastructure efficiencies, for example 5-6x decreases in average CI build times, and it continues to become the foundation of fast, reproducible, and standardised software builds at the company. -### [CarGurus](https://www.cargurus.com){: .external} - +### [CarGurus](https://www.cargurus.com) + CarGurus is on a mission to build the world's most trusted and transparent automotive marketplace and uses Bazel to build their polyglot monorepo. -### [Compass](https://www.compass.com){: .external} +### [Compass](https://www.compass.com) Compass is a tech-driven real estate platform. With an elite team of real estate, technology and business professionals, we aim to be the best and most trusted source for home seekers. -### [Databricks](https://databricks.com){: .external} +### [Databricks](https://databricks.com) - + Databricks provides cloud-based integrated workspaces based on Apache Spark™. > The Databricks codebase is a Monorepo, containing the Scala code that powers @@ -98,32 +98,32 @@ monorepo contains a million lines of Scala, working with code within is fast and snappy. ([Speedy Scala Builds with Bazel at Databricks](https://databricks.com/blog/2019/02/27/speedy-scala-builds-with-bazel-at-databricks.html)) -### [Dataform](https://dataform.co){: .external} +### [Dataform](https://dataform.co) Dataform provides scalable analytics for data teams. They maintain a handful of NPM packages and a documentation site in one single monorepo and they do it all with Bazel. After the migration to Bazel, they -[reported many benefits](https://github.com/bazelbuild/rules_nodejs#user-testimonials){: .external}, +[reported many benefits](https://github.com/bazelbuild/rules_nodejs#user-testimonials), including: > * Faster CI: we enabled the remote build caching which has reduced our average build time from 30 minutes to 5 (for the entire repository). > * Improvements to local development: no more random bash scripts that you forget to run, incremental builds reduced to seconds from minutes > * Developer setup time: New engineers can build all our code with just 3 dependencies - bazel, docker and the JVM. The last engineer to join our team managed to build all our code in < 30 minutes on a brand new, empty laptop -### [Deep Silver FISHLABS](https://www.dsfishlabs.com){: .external} +### [Deep Silver FISHLABS](https://www.dsfishlabs.com) Deep Silver FISHLABS is a developer of high-end 3D games. They use Bazel with C++/Python/Go/C as a base for their internal build tooling and especially for baking and deploying all their 3D Assets. -### [Dropbox](https://www.dropbox.com/){: .external} - +### [Dropbox](https://www.dropbox.com/) + At Dropbox, Bazel is a key component to our distributed build and test environment. We use Bazel to combine TypeScript/Python/Go/C/Rust into reliable production releases. -### [Engel & Völkers](https://www.engelvoelkers.com){: .external} +### [Engel & Völkers](https://www.engelvoelkers.com) Engel & Völkers AG is a privately owned German company that, via a series of franchised offices, provides services related to real estate transactions. @@ -131,10 +131,10 @@ franchised offices, provides services related to real estate transactions. > One of our internal project has seen a decrease of compilation time from 11 minutes to roughly 1 minute, this was an impressive achievement and we are currently working on bringing Bazel to more projects. -([Experimenting with Google Cloud Build and Bazel](https://www.engelvoelkers.com/en/tech/engineering/software-engineering/experimenting-with-google-cloud-build-and-bazel/)){: .external} +([Experimenting with Google Cloud Build and Bazel](https://www.engelvoelkers.com/en/tech/engineering/software-engineering/experimenting-with-google-cloud-build-and-bazel/)) -### [Etsy](https://www.etsy.com/){: .external} - +### [Etsy](https://www.etsy.com/) + Etsy is an e-commerce website focused on handmade or vintage items and supplies, as well as unique factory-manufactured items. @@ -142,24 +142,24 @@ as well as unique factory-manufactured items. They use Bazel to build and test its Java-based search platform. Bazel produces both packages for bare metal servers and repeatable Docker images. -### [Evertz.io](https://www.evertz.io/){: .external} +### [Evertz.io](https://www.evertz.io/) Evertz.io is a multi-tenant, serverless SaaS platform for offering cost effective, multi-regional services worldwide to the Broadcast Media Industry, created by [Evertz Microsystems](https://en.wikipedia.org/wiki/Evertz_Microsystems). The website is fully built and deployed with an Angular and Bazel workflow -([source](https://twitter.com/MattMackay/status/1113947685508341762){: .external}). +([source](https://twitter.com/MattMackay/status/1113947685508341762)). -### [FINDMINE](http://www.findmine.com){: .external} - +### [FINDMINE](http://www.findmine.com) + FINDMINE is a automation technology for the retail industry that uses machine learning to scale the currently manual and tedious process of product curation. We use Bazel to mechanize our entire python package building, testing, and deployment process. -### [Flexport](https://www.flexport.com/){: .external} +### [Flexport](https://www.flexport.com/) Flexport is a tech-enabled global freight forwarder; our mission is to make global trade easier for everyone. At Flexport, we use Bazel to build/test our @@ -167,8 +167,8 @@ Java/JavaScript services and client libraries and to generate Java and Ruby code from protobuf definitions. [Read about how we run individual JUnit 5 tests in isolation with Bazel.](https://flexport.engineering/connecting-bazel-and-junit5-by-transforming-arguments-46440c6ea068) -### [Foursquare](https://foursquare.com){: .external} - +### [Foursquare](https://foursquare.com) + Foursquare's mission is to create technology that constructs meaningful bridges between digital spaces and physical places. We manage millions of @@ -176,45 +176,45 @@ lines of primarily Scala and Python code powering data-intensive applications, including complex codegen and container build processes, with Bazel. -### [GermanTechJobs](https://germantechjobs.de){: .external} - +### [GermanTechJobs](https://germantechjobs.de) + Bazel has simplified our workflows 10-fold and enabled shipping features at scale. -### [Google](https://google.com){: .external} - +### [Google](https://google.com) + Bazel was designed to be able to scale to Google's needs and meet Google's requirements of reproducibility and platform/language support. All software at Google is built using Bazel. Google uses Bazel and its rules for millions of builds every day. -### [Huawei](http://www.huawei.com/){: .external} +### [Huawei](http://www.huawei.com/) > Huawei Technologies is using Bazel in about 30 projects, they are Java/Scala/Go projects, except for Go projects, others originally were built by Maven. We write a simple tool to translate a Maven-built project into Bazel-built one. More and more projects will use Bazel in recent future. -### [IMC Trading](https://imc.com){: .external} - +### [IMC Trading](https://imc.com) + > IMC is a global proprietary trading firm and market maker headquarted in Amsterdam. We are using Bazel to continuously build and test our Java/C++/Python/SystemVerilog projects. -### [Improbable.io](https://improbable.io/){: .external} +### [Improbable.io](https://improbable.io/) Improbable.io develops SpatialOS, a distributed operating system that enables creating huge simulations inhabited by millions of complex entities. -### [Interaxon](https://www.choosemuse.com/){: .external} +### [Interaxon](https://www.choosemuse.com/) InteraXon is a thought-controlled computing firm that creates hardware and software platforms to convert brainwaves into digital signals. -### [Jupiter](https://jupiter.co/){: .external} +### [Jupiter](https://jupiter.co/) Jupiter is a company that provides delivery of groceries and household essentials every week. @@ -223,7 +223,7 @@ They use Bazel in their backend code, specifically to compile protos and Kotlin to JVM binaries, using remote caching. ([source](https://starship.jupiter.co/jupiter-stack/)) -### [Just](https://gojust.com/){: .external} +### [Just](https://gojust.com/) Just is an enterprise financial technology company, headquartered in Norway, creating software solutions to transform how global corporate treasurers manage @@ -235,29 +235,29 @@ Line provides an app for instant communications, which is the most popular messaging application in Japan. They use Bazel on their codebase consisting of about 60% Swift and 40% C/C++/Objective-C/Objective-C++ -([source](https://twitter.com/thi_dt/status/1253334262020886532){: .external}). +([source](https://twitter.com/thi_dt/status/1253334262020886532)). > After switching to Bazel, we were able to achieve a huge improvement in the build times. This brought a significant improvement in the turn-around time during a QA period. Distributing a new build to our testers no longer means another hour waiting for building and testing. -([Improving Build Performance of LINE for iOS with Bazel](https://engineering.linecorp.com/en/blog/improving-build-performance-line-ios-bazel/){: .external}) +([Improving Build Performance of LINE for iOS with Bazel](https://engineering.linecorp.com/en/blog/improving-build-performance-line-ios-bazel/)) -### [LingoChamp](https://www.liulishuo.com/en){: .external} +### [LingoChamp](https://www.liulishuo.com/en) - + LingoChamp provides professional solutions to English learners. We use Bazel for our go, java and python projects. -### [LinkedIn](https://linkedin.com/){: .external} +### [LinkedIn](https://linkedin.com/) - + LinkedIn, a subsidiary of Microsoft, is the world’s largest professional social network. LinkedIn uses Bazel for building its iOS Apps. -### [Lucid Software](https://lucid.co/){: .external} +### [Lucid Software](https://lucid.co/) - + Lucid Software is a leader in visual collaboration, helping teams see and build the future from idea to reality. With its products—[Lucidchart](https://www.lucidchart.com/), @@ -271,35 +271,35 @@ dependencies on the build environment, and simplified developers' experience with the build system. Bazel has improved developer productivity at Lucid and unlocked further growth. -### [Lyft](https://www.lyft.com/){: .external} +### [Lyft](https://www.lyft.com/) Lyft is using Bazel for their iOS ([source](https://twitter.com/SmileyKeith/status/1116486751806033920)) and Android Apps. -### [Meetup](http://www.meetup.com/){: .external} +### [Meetup](http://www.meetup.com/) Meetup is an online social networking portal that facilitates offline group meetings. The Meetup engineering team contributes to -[rules_scala](https://github.com/bazelbuild/rules_scala){: .external} and is the -maintainer of [rules_avro](https://github.com/meetup/rules_avro){: .external} -and [rules_openapi](https://github.com/meetup/rules_openapi){: .external}. +[rules_scala](https://github.com/bazelbuild/rules_scala) and is the +maintainer of [rules_avro](https://github.com/meetup/rules_avro) +and [rules_openapi](https://github.com/meetup/rules_openapi). -### [Nvidia](https://www.nvidia.com/){: .external} +### [Nvidia](https://www.nvidia.com/) > At Nvidia we have been using dazel(docker bazel) for python to work around some of bazel's python short comings. Everything else runs in normal bazel (Mostly Go / Scala/ C++/ Cuda) -([source](https://twitter.com/rwhitcomb/status/1080887723433447424){: .external}) +([source](https://twitter.com/rwhitcomb/status/1080887723433447424)) -### [Peloton Technology](http://www.peloton-tech.com){: .external} +### [Peloton Technology](http://www.peloton-tech.com) Peloton Technology is an automated vehicle technology company that tackles truck accidents and fuel use. They use Bazel to _enable reliable builds for automotive safety systems_. -### [Pigweed](https://pigweed.dev){: .external} +### [Pigweed](https://pigweed.dev) - + Pigweed is an open-source solution for sustained, robust, and rapid embedded product development for large teams. Pigweed has shipped in millions of @@ -314,9 +314,9 @@ system for embedded projects! [pw-bazel-great]: https://blog.bazel.build/2024/08/08/bazel-for-embedded.html#why-bazel-for-embedded -### [Pinterest](https://www.pinterest.com/){: .external} +### [Pinterest](https://www.pinterest.com/) - + Pinterest is the world’s catalog of ideas. They use Bazel to build various backend services (Java/C++) and the iOS application (Objective-C/C++). @@ -327,19 +327,19 @@ build environments and adopt incrementally. As a result, we’re now shipping al our iOS releases using Bazel. [Developing fast & reliable iOS builds at Pinterest](https://medium.com/@Pinterest_Engineering/developing-fast-reliable-ios-builds-at-pinterest-part-one-cb1810407b92) -### [PubRef](https://github.com/pubref){: .external} +### [PubRef](https://github.com/pubref) PubRef is an emerging scientific publishing platform. They use Bazel with -[rules_closure](https://github.com/bazelbuild/rules_closure){: .external} to build the +[rules_closure](https://github.com/bazelbuild/rules_closure) to build the frontend, native java rules to build the main backend, -[rules_go](https://github.com/bazelbuild/rules_go){: .external}, -[rules_node](https://github.com/pubref/rules_node){: .external}, and -[rules_kotlin](https://github.com/pubref/rules_kotlin){: .external} to build assorted -backend services. [rules_protobuf](https://github.com/pubref/rules_protobuf){: .external} is +[rules_go](https://github.com/bazelbuild/rules_go), +[rules_node](https://github.com/pubref/rules_node), and +[rules_kotlin](https://github.com/pubref/rules_kotlin) to build assorted +backend services. [rules_protobuf](https://github.com/pubref/rules_protobuf) is used to assist with gRPC-based communication between backend services. PubRef.org is based in Boulder, CO. -### [Redfin](https://redfin.com/){: .external} +### [Redfin](https://redfin.com/) Redfin is a next-generation real estate brokerage with full-service local agents. They use Bazel to build and deploy the website and various backend services. @@ -352,32 +352,32 @@ quantify, but the shift from unexplained build failures being something that virtuous cycle of ever-increasing reliability. ([We Switched from Maven to Bazel and Builds Got 10x Faster](https://redfin.engineering/we-switched-from-maven-to-bazel-and-builds-got-10x-faster-b265a7845854)) -### [Ritual](https://ritual.co){: .external} - +### [Ritual](https://ritual.co) + Ritual is a mobile pick up app, connecting restaurants with customers to offer a simple, time-saving tool to get the food and beverages they want, without the wait. Ritual uses Bazel for their backend services. -### [Snap](https://www.snap.com/en-US/){: .external} +### [Snap](https://www.snap.com/en-US/) Snap, the developer of Snapchat messaging app, has migrated from Buck to Bazel -in 2020 ([source](https://twitter.com/wew/status/1326957862816509953){: .external}). For more -details about their process, see their [engineering blog](https://eng.snap.com/blog/){: .external}. +in 2020 ([source](https://twitter.com/wew/status/1326957862816509953)). For more +details about their process, see their [engineering blog](https://eng.snap.com/blog/). -### [Stripe](https://stripe.com){: .external} - +### [Stripe](https://stripe.com) + -Stripe provides mobile payment solutions. They use Bazel in their build and test pipelines, as detailed in their [engineering blog](https://stripe.com/blog/fast-secure-builds-choose-two){: .external}. +Stripe provides mobile payment solutions. They use Bazel in their build and test pipelines, as detailed in their [engineering blog](https://stripe.com/blog/fast-secure-builds-choose-two). -### [Tinder](https://tinder.com){: .external} - +### [Tinder](https://tinder.com) + Tinder migrated its iOS app from CocoaPods to Bazel -in 2021 ([source](https://medium.com/tinder/bazel-hermetic-toolchain-and-tooling-migration-c244dc0d3ae){: .external}). +in 2021 ([source](https://medium.com/tinder/bazel-hermetic-toolchain-and-tooling-migration-c244dc0d3ae)). -### [Tink](https://tink.com/){: .external} - +### [Tink](https://tink.com/) + Tink is a european fintech, building the best way to connect to banks across Europe. @@ -386,7 +386,7 @@ They are using Bazel to build their backend services from a polyglot monorepo. Engineers at Tink are organizing the [bazel build //stockholm/...](https://www.meetup.com/BazelSTHLM/) meetup group. -### [Tokopedia](https://www.tokopedia.com/){: .external} +### [Tokopedia](https://www.tokopedia.com/) Tokopedia is an Indonesian technology company specializing in e-commerce, with over 90 million monthly active users and over 7 million merchants on the @@ -398,27 +398,27 @@ where they explain how Bazel sped up their builds. The build duration went from 55 minutes to 10 minutes by using Bazel, and down to 5 minutes with remote caching. -### [Trunk.io](https://trunk.io/merge/trunk-merge-and-bazel){: .external} - +### [Trunk.io](https://trunk.io/merge/trunk-merge-and-bazel) + Trunk is a San Francisco-based company backed by Andreessen Horowitz and Initialized Capital. Trunk offers a powerful pull request merge service with first-class support for the Bazel build system. By leveraging Bazel's understanding of dependencies within a codebase, Trunk's merge service intelligently creates parallel merge lanes, allowing independent changes to be tested and merged simultaneously. > Trunk’s internal monorepo builds modern C++ 20 and typescript all while leveraging bazel graph knowledge to selectively test and merge code. -### [Twitter](https://twitter.com/){: .external} +### [Twitter](https://twitter.com/) Twitter has made the decision to migrate from Pants to Bazel as their primary build tool ([source](https://groups.google.com/forum/#!msg/pants-devel/PHVIbVDLhx8/LpSKIP5cAwAJ)). -### [Two Sigma](https://www.twosigma.com/){: .external} - +### [Two Sigma](https://www.twosigma.com/) + Two Sigma is a New York-headquartered technology company dedicated to finding value in the world’s data. -### [TypeDB](https://typedb.com){: .external} -TypeDB Logo +### [TypeDB](https://typedb.com) +TypeDB Logo TypeDB is a database technology that can be used to intuitively model interconnected data. Through its type-theoretic and polymorphic query language, @@ -430,32 +430,32 @@ pipeline that manages many repositories in a wide variety of languages, and deploys to numerous platforms seamlessly. The TypeDB team has also released Bazel rules for assembling and deploying software distributions. -### [Uber](https://www.uber.com){: .external} +### [Uber](https://www.uber.com) Uber is a ride-hailing company. With 900 active developers, Uber’s Go monorepo is likely one of the largest Go repositories using Bazel. See the article [Building Uber’s Go Monorepo with Bazel](https://eng.uber.com/go-monorepo-bazel/) to learn more about their experience. -### [Uber Advanced Technologies Group](https://www.uber.com/info/atg/){: .external} - +### [Uber Advanced Technologies Group](https://www.uber.com/info/atg/) + Uber Advanced Technologies Group is focused on autonomous vehicle efforts at Uber, including trucking/freight and autonomous ride sharing. The organization uses Bazel as its primary build system. -### [Vistar Media](http://vistarmedia.com){: .external} +### [Vistar Media](http://vistarmedia.com) Vistar Media is an advertising platform that enables brands to reach consumers based on their behavior in the physical world. Their engineering team is primarily based out of Philadelphia and is using Bazel for builds, deploys, to speed up testing, and to consolidate repositories written with a variety of different technologies. -### [VMware](https://www.vmware.com/){: .external} +### [VMware](https://www.vmware.com/) VMware uses Bazel to produce deterministic, reliable builds while developing innovative products for their customers. -### [Wix](https://www.wix.com/){: .external} +### [Wix](https://www.wix.com/) Wix is a cloud-based web development platform. Their backend uses Java and Scala code. They use remote execution with Google Cloud Build. @@ -465,25 +465,25 @@ execution which utilizes bazel’s great build/test parallelism capabilities whe it dispatches build/test actions to a worker farm. Average build times are more than 10 times faster due to the utilization of bazel’s aggressive caching mechanism. -([Migrating to Bazel from Maven or Gradle? 5 crucial questions you should ask yourself](https://medium.com/wix-engineering/migrating-to-bazel-from-maven-or-gradle-5-crucial-questions-you-should-ask-yourself-f23ac6bca070){: .external}) +([Migrating to Bazel from Maven or Gradle? 5 crucial questions you should ask yourself](https://medium.com/wix-engineering/migrating-to-bazel-from-maven-or-gradle-5-crucial-questions-you-should-ask-yourself-f23ac6bca070)) -### [Zenly](https://zen.ly/){: .external} +### [Zenly](https://zen.ly/) Zenly is a live map of your friends and family. It’s the most fun way to meet up — or just see what’s up! — so you can feel together, even when you're apart. *** -## Open source projects using Bazel {:#open-source-projects-using-Bazel} +## Open source projects using Bazel {#open-source-projects-using-Bazel} -### [Abseil](https://abseil.io/){: .external} +### [Abseil](https://abseil.io/) Abseil is an open-source collection of C++ code (compliant to C++11) designed to augment the C++ standard library. -### [Angular](https://angular.io){: .external} +### [Angular](https://angular.io) - + Angular is a popular web framework. Angular is [built with Bazel](https://github.com/angular/angular/blob/master/docs/BAZEL.md). @@ -493,165 +493,165 @@ Angular is [built with Bazel](https://github.com/angular/angular/blob/master/doc Apollo is a high performance, flexible architecture which accelerates the development, testing, and deployment of Autonomous Vehicles. -### [brpc](https://github.com/brpc/brpc){: .external} +### [brpc](https://github.com/brpc/brpc) An industrial-grade RPC framework used throughout Baidu, with 1,000,000+ instances(not counting clients) and thousands kinds of services, called "baidu-rpc" inside Baidu. -### [cert-manager](https://github.com/jetstack/cert-manager){: .external} +### [cert-manager](https://github.com/jetstack/cert-manager) cert-manager is a Kubernetes add-on to automate the management and issuance of TLS certificates from various issuing sources. It will ensure certificates are valid and up to date periodically, and attempt to renew certificates at an appropriate time before expiry. -### [CallBuilder](https://github.com/google/CallBuilder){: .external} +### [CallBuilder](https://github.com/google/CallBuilder) A Java code generator that allows you to create a builder by writing one function. -### [CPPItertools](https://github.com/ryanhaining/cppitertools){: .external} +### [CPPItertools](https://github.com/ryanhaining/cppitertools) C++ library providing range-based for loop add-ons inspired by the Python builtins and itertools library. Like itertools and the Python3 builtins, this library uses lazy evaluation wherever possible. -### [Copybara](https://github.com/google/copybara){: .external} +### [Copybara](https://github.com/google/copybara) Copybara is a tool for transforming and moving code between repositories. -### [Dagger](https://google.github.io/dagger/){: .external} +### [Dagger](https://google.github.io/dagger/) Dagger is a fully static, compile-time dependency injection framework for both Java and Android. -### [DAML](https://github.com/digital-asset/daml){: .external} +### [DAML](https://github.com/digital-asset/daml) DAML is a smart contract language for building future-proof distributed applications on a safe, privacy-aware runtime. -### [DeepMind Lab](https://github.com/deepmind/lab){: .external} +### [DeepMind Lab](https://github.com/deepmind/lab) A customisable 3D platform for agent-based AI research. -### [Drake](https://github.com/RobotLocomotion/drake){: .external} +### [Drake](https://github.com/RobotLocomotion/drake) Drake is a C++ toolbox started at MIT and now led by the Toyota Research Institute. It is a collection of tools for analyzing the dynamics of our robots and building control systems for them, with a heavy emphasis on optimization-based design/analysis. -### [Envoy](https://github.com/lyft/envoy){: .external} +### [Envoy](https://github.com/lyft/envoy) C++ L7 proxy and communication bus -### [Error Prone](https://github.com/google/error-prone){: .external} +### [Error Prone](https://github.com/google/error-prone) Catches common Java mistakes as compile-time errors. (Migration to Bazel is in progress.) -### [Extensible Service Proxy](https://github.com/cloudendpoints/esp){: .external} +### [Extensible Service Proxy](https://github.com/cloudendpoints/esp) Extensible Service Proxy, a.k.a. ESP is a proxy which enables API management capabilities for JSON/REST or gRPC API services. The current implementation is based on an NGINX HTTP reverse proxy server. -### [FFruit](https://gitlab.com/perezd/ffruit/){: .external} +### [FFruit](https://gitlab.com/perezd/ffruit/) FFruit is a free & open source Android application to the popular service -[Falling Fruit](https://fallingfruit.org){: .external}. +[Falling Fruit](https://fallingfruit.org). -### [Gerrit Code Review](https://gerritcodereview.com){: .external} +### [Gerrit Code Review](https://gerritcodereview.com) Gerrit is a code review and project management tool for Git based projects. -### [Gitiles](https://gerrit.googlesource.com/gitiles/){: .external} +### [Gitiles](https://gerrit.googlesource.com/gitiles/) Gitiles is a simple repository browser for Git repositories, built on JGit. -### [Grakn](https://github.com/graknlabs/grakn){: .external} +### [Grakn](https://github.com/graknlabs/grakn) Grakn (https://grakn.ai/) is the knowledge graph engine to organise complex networks of data and make it queryable. -### [GRPC](http://www.grpc.io){: .external} +### [GRPC](http://www.grpc.io) A language-and-platform-neutral remote procedure call system. (Bazel is a supported, although not primary, build system.) -### [gVisor](https://github.com/google/gvisor){: .external} +### [gVisor](https://github.com/google/gvisor) gVisor is a container runtime sandbox. -### [Guetzli](https://github.com/google/guetzli/){: .external} +### [Guetzli](https://github.com/google/guetzli/) Guetzli is a JPEG encoder that aims for excellent compression density at high visual quality. -### [Gulava](http://www.github.com/google/gulava/){: .external} +### [Gulava](http://www.github.com/google/gulava/) A Java code generator that lets you write Prolog-style predicates and use them seamlessly from normal Java code. -### [Heron](https://github.com/apache/incubator-heron){: .external} +### [Heron](https://github.com/apache/incubator-heron) Heron is a realtime, distributed, fault-tolerant stream processing engine from Twitter. -### [Internet Computer Protocol](https://internetcomputer.org/){: .external} +### [Internet Computer Protocol](https://internetcomputer.org/) - + The Internet Computer Protocol is a publicly available blockchain network that enables replicated execution of general-purpose computation, serving hundreds of thousands of applications and their users. -### [Jazzer](https://github.com/CodeIntelligenceTesting/jazzer){: .external} +### [Jazzer](https://github.com/CodeIntelligenceTesting/jazzer) - + Jazzer is a fuzzer for Java and other JVM-based languages that integrates with JUnit 5. -### [JGit](https://eclipse.org/jgit/){: .external} +### [JGit](https://eclipse.org/jgit/) JGit is a lightweight, pure Java library implementing the Git version control system. -### [Jsonnet](https://jsonnet.org/){: .external} +### [Jsonnet](https://jsonnet.org/) An elegant, formally-specified config generation language for JSON. (Bazel is a supported build system.) -### [Kubernetes](https://github.com/kubernetes/kubernetes){: .external} +### [Kubernetes](https://github.com/kubernetes/kubernetes) - + Kubernetes is an open source system for managing containerized applications across multiple hosts, providing basic mechanisms for deployment, maintenance, and scaling of applications. -### [Kythe](https://github.com/google/kythe){: .external} +### [Kythe](https://github.com/google/kythe) An ecosystem for building tools that work with code. -### [ls-lint](https://github.com/loeffel-io/ls-lint){: .external} +### [ls-lint](https://github.com/loeffel-io/ls-lint) - + An extremely fast directory and filename linter - Bring some structure to your project file system. -### [Nomulus](https://github.com/google/nomulus){: .external} +### [Nomulus](https://github.com/google/nomulus) Top-level domain name registry service on Google App Engine. -### [ONOS : Open Network Operating System](https://github.com/opennetworkinglab/onos){: .external} +### [ONOS : Open Network Operating System](https://github.com/opennetworkinglab/onos) - + ONOS is the only SDN controller platform that supports the transition from legacy “brown field” networks to SDN “green field” networks. This enables exciting new capabilities, and disruptive deployment and operational cost points for network operators. -### [PetitParser for Java](https://github.com/petitparser/java-petitparser){: .external} +### [PetitParser for Java](https://github.com/petitparser/java-petitparser) Grammars for programming languages are traditionally specified statically. They are hard to compose and reuse due to ambiguities that inevitably arise. @@ -659,87 +659,87 @@ PetitParser combines ideas from scannnerless parsing, parser combinators, parsing expression grammars and packrat parsers to model grammars and parsers as objects that can be reconfigured dynamically. -### [PlaidML](https://github.com/plaidml/plaidml){: .external} +### [PlaidML](https://github.com/plaidml/plaidml) PlaidML is a framework for making deep learning work everywhere. -### [Project V](https://www.v2ray.com/){: .external} +### [Project V](https://www.v2ray.com/) - + Project V is a set of tools to help you build your own privacy network over internet. -### [Prysmatic Labs Ethereum 2.0 Implementation](https://github.com/prysmaticlabs/prysm){: .external} +### [Prysmatic Labs Ethereum 2.0 Implementation](https://github.com/prysmaticlabs/prysm) Prysm is a sharding client for Ethereum 2.0, a blockchain-based distributed computing platform. -### [Ray](https://github.com/ray-project/ray){: .external} +### [Ray](https://github.com/ray-project/ray) Ray is a flexible, high-performance distributed execution framework. -### [Resty](https://github.com/go-resty/resty){: .external} +### [Resty](https://github.com/go-resty/resty) Resty is a Simple HTTP and REST client library for Go (inspired by Ruby rest-client). -### [Roughtime](https://roughtime.googlesource.com/roughtime){: .external} +### [Roughtime](https://roughtime.googlesource.com/roughtime) Roughtime is a project that aims to provide secure time synchronisation. -### [Selenium](https://github.com/SeleniumHQ/selenium){: .external} +### [Selenium](https://github.com/SeleniumHQ/selenium) Selenium is a portable framework for testing web applications. -### [Semantic](https://github.com/github/semantic){: .external} +### [Semantic](https://github.com/github/semantic) Semantic is a Haskell library and command line tool for parsing, analyzing, and comparing source code. It is developed by GitHub (and used for example for the code navigation). -### [Served](https://github.com/meltwater/served){: .external} +### [Served](https://github.com/meltwater/served) Served is a C++ library for building high performance RESTful web servers. -### [Sonnet](https://github.com/deepmind/sonnet){: .external} +### [Sonnet](https://github.com/deepmind/sonnet) Sonnet is a library built on top of TensorFlow for building complex neural networks. -### [Sorbet](https://github.com/sorbet/sorbet){: .external} +### [Sorbet](https://github.com/sorbet/sorbet) Sorbet is a fast, powerful type checker for a subset of Ruby. It scales to codebases with millions of lines of code and can be adopted incrementally. -### [Spotify](https://spotify.com){: .external} +### [Spotify](https://spotify.com) Spotify is using Bazel to build their iOS and Android Apps ([source](https://twitter.com/BalestraPatrick/status/1573355078995566594)). -### [Tink](https://github.com/google/tink){: .external} +### [Tink](https://github.com/google/tink) Tink is a multi-language, cross-platform, open source library that provides cryptographic APIs that are secure, easy to use correctly, and hard(er) to misuse. -### [TensorFlow](http://tensorflow.org){: .external} - +### [TensorFlow](http://tensorflow.org) + An open source software library for machine intelligence. -### [Turbo Santa](https://github.com/turbo-santa/turbo-santa-common){: .external} +### [Turbo Santa](https://github.com/turbo-santa/turbo-santa-common) A platform-independent GameBoy emulator. -### [Wycheproof](https://github.com/google/wycheproof){: .external} +### [Wycheproof](https://github.com/google/wycheproof) Project Wycheproof tests crypto libraries against known attacks. -### [XIOSim](https://github.com/s-kanev/XIOSim){: .external} +### [XIOSim](https://github.com/s-kanev/XIOSim) XIOSim is a detailed user-mode microarchitectural simulator for the x86 architecture. -### [ZhihuDailyPurify](https://github.com/izzyleung/ZhihuDailyPurify){: .external} +### [ZhihuDailyPurify](https://github.com/izzyleung/ZhihuDailyPurify) ZhihuDailyPurify is a light weight version of Zhihu Daily, a Chinese question-and-answer webs. \ No newline at end of file diff --git a/versions/9.1.0/concepts/build-files.mdx b/versions/9.1.0/concepts/build-files.mdx index 882107b2..57e853e2 100644 --- a/versions/9.1.0/concepts/build-files.mdx +++ b/versions/9.1.0/concepts/build-files.mdx @@ -15,7 +15,7 @@ For simplicity's sake, the documentation refers to these files simply as `BUILD` files. `BUILD` files are evaluated using an imperative language, -[Starlark](https://github.com/bazelbuild/starlark/){: .external}. +[Starlark](https://github.com/bazelbuild/starlark/). They are interpreted as a sequential list of statements. @@ -48,7 +48,7 @@ team. `BUILD` file authors should comment liberally to document the role of each build target, whether or not it is intended for public use, and to document the role of the package itself. -## Loading an extension {:#load} +## Loading an extension {#load} Bazel extensions are files ending in `.bzl`. Use the `load` statement to import a symbol from an extension. @@ -90,7 +90,7 @@ loaded from another file. You can use [load visibility](/versions/9.1.0/concepts/visibility#load-visibility) to restrict who may load a `.bzl` file. -## Types of build rules {:#types-of-build-rules} +## Types of build rules {#types-of-build-rules} The majority of build rules come in families, grouped together by language. For example, `cc_binary`, `cc_library` @@ -130,19 +130,6 @@ for anyone to create new rules. and binaries and tests can depend on libraries, with the expected separate-compilation behavior. - - - - - -
- Labels - - Dependencies -
- ## File encoding `BUILD` and `.bzl` files should be encoded in UTF-8, of which ASCII is a valid diff --git a/versions/9.1.0/concepts/dependencies.mdx b/versions/9.1.0/concepts/dependencies.mdx index 4cbd73ba..e16b3549 100644 --- a/versions/9.1.0/concepts/dependencies.mdx +++ b/versions/9.1.0/concepts/dependencies.mdx @@ -4,7 +4,7 @@ title: 'Dependencies' A target `A` _depends upon_ a target `B` if `B` is needed by `A` at build or execution time. The _depends upon_ relation induces a -[Directed Acyclic Graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph){: .external} +[Directed Acyclic Graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph) (DAG) over targets, and it is called a _dependency graph_. A target's _direct_ dependencies are those other targets reachable by a path @@ -16,7 +16,7 @@ of _actual dependencies_ and the graph of _declared dependencies_. Most of the time, the two graphs are so similar that this distinction need not be made, but it is useful for the discussion below. -## Actual and declared dependencies {:#actual-and-declared-dependencies} +## Actual and declared dependencies {#actual-and-declared-dependencies} A target `X` is _actually dependent_ on target `Y` if `Y` must be present, built, and up-to-date in order for `X` to be built correctly. _Built_ could @@ -57,7 +57,7 @@ dependencies don't appear in the `BUILD` file. Because the rule doesn't directly depend on the provider, there is no way to track changes, as shown in the following example timeline: -### 1. Declared dependencies match actual dependencies {:#this-is-fine} +### 1. Declared dependencies match actual dependencies {#this-is-fine} At first, everything works. The code in package `a` uses code in package `b`. The code in package `b` uses code in package `c`, and thus `a` transitively @@ -70,21 +70,22 @@ depends on `c`. - 
rule(
+```
+rule(
     name = "a",
     srcs = "a.in",
     deps = "//b:b",
 )
-
+``` - 
+```
 rule(
     name = "b",
     srcs = "b.in",
     deps = "//c:c",
 )
-
+``` @@ -92,25 +93,26 @@ rule( b / b.in - 
+    
+```
 import b;
 b.foo();
-
+``` - 
+```
 import c;
 function foo() {
   c.bar();
 }
-
+```
Declared dependency graph with arrows connecting a, b, and c + alt="Declared dependency graph with arrows connecting a, b, and c" />
Declared dependency graph
@@ -118,7 +120,7 @@ function foo() {
Actual dependency graph that matches the declared dependency - graph with arrows connecting a, b, and c + graph with arrows connecting a, b, and c" />
Actual dependency graph
@@ -127,7 +129,7 @@ function foo() { The declared dependencies overapproximate the actual dependencies. All is well. -### 2. Adding an undeclared dependency {:#undeclared-dependency} +### 2. Adding an undeclared dependency {#undeclared-dependency} A latent hazard is introduced when someone adds code to `a` that creates a direct _actual_ dependency on `c`, but forgets to declare it in the build file @@ -140,12 +142,12 @@ direct _actual_ dependency on `c`, but forgets to declare it in the build file - 
-        import b;
-        import c;
-        b.foo();
-        c.garply();
-
+``` +import b; +import c; +b.foo(); +c.garply(); +```   @@ -153,7 +155,7 @@ direct _actual_ dependency on `c`, but forgets to declare it in the build file
Declared dependency graph with arrows connecting a, b, and c + alt="Declared dependency graph with arrows connecting a, b, and c" />
Declared dependency graph
@@ -162,7 +164,7 @@ direct _actual_ dependency on `c`, but forgets to declare it in the build file Actual dependency graph with arrows connecting a, b, and c. An arrow now connects A to C as well. This does not match the - declared dependency graph + declared dependency graph" />
Actual dependency graph
@@ -173,7 +175,7 @@ The declared dependencies no longer overapproximate the actual dependencies. This may build ok, because the transitive closures of the two graphs are equal, but masks a problem: `a` has an actual but undeclared dependency on `c`. -### 3. Divergence between declared and actual dependency graphs {:#divergence} +### 3. Divergence between declared and actual dependency graphs {#divergence} The hazard is revealed when someone refactors `b` so that it no longer depends on `c`, inadvertently breaking `a` through no @@ -187,12 +189,13 @@ fault of their own.   - 
rule(
+```
+rule(
     name = "b",
     srcs = "b.in",
     deps = "//d:d",
 )
-
+``` @@ -202,12 +205,12 @@ fault of their own.   - 
-      import d;
-      function foo() {
-        d.baz();
-      }
-
+``` +import d; +function foo() { + d.baz(); +} +``` @@ -215,7 +218,7 @@ fault of their own.
Declared dependency graph with arrows connecting a and b. - b no longer connects to c, which breaks a's connection to c + b no longer connects to c, which breaks a's connection to c" />
Declared dependency graph
@@ -223,7 +226,7 @@ fault of their own.
Actual dependency graph that shows a connecting to b and c, - but b no longer connects to c + but b no longer connects to c" />
Actual dependency graph
@@ -236,7 +239,7 @@ dependencies, even when transitively closed; the build is likely to fail. The problem could have been averted by ensuring that the actual dependency from `a` to `c` introduced in Step 2 was properly declared in the `BUILD` file. -## Types of dependencies {:#types-of-dependencies} +## Types of dependencies {#types-of-dependencies} Most build rules have three attributes for specifying different kinds of generic dependencies: `srcs`, `deps` and `data`. These are explained below. For @@ -247,16 +250,16 @@ Many rules also have additional attributes for rule-specific kinds of dependencies, for example, `compiler` or `resources`. These are detailed in the [Build Encyclopedia](/versions/9.1.0/reference/be/). -### `srcs` dependencies {:#srcs-dependencies} +### `srcs` dependencies {#srcs-dependencies} Files consumed directly by the rule or rules that output source files. -### `deps` dependencies {:#deps-dependencies} +### `deps` dependencies {#deps-dependencies} Rule pointing to separately-compiled modules providing header files, symbols, libraries, data, etc. -### `data` dependencies {:#data-dependencies} +### `data` dependencies {#data-dependencies} A build target might need some data files to run correctly. These data files aren't source code: they don't affect how the target is built. For example, a @@ -293,21 +296,24 @@ you can refer to these files by joining the paths of the test's source directory and the workspace-relative path, for example, `${TEST_SRCDIR}/workspace/path/to/data/file`. -## Using labels to reference directories {:#using-labels-reference-directories} +## Using labels to reference directories {#using-labels-reference-directories} As you look over our `BUILD` files, you might notice that some `data` labels refer to directories. These labels end with `/.` or `/` like these examples, which you should not use: -

Not recommended — +

+ Not recommended — data = ["//data/regression:unittest/."]

-

Not recommended — +

+ Not recommended — data = ["testdata/."]

-

Not recommended — +

+ Not recommended — data = ["testdata/"]

@@ -325,7 +331,8 @@ enumerate the set of files contained within them, either explicitly or using the [`glob()`](/versions/9.1.0/reference/be/functions#glob) function. (Use `**` to force the `glob()` to be recursive.) -

Recommended — +

+ Recommended — data = glob(["testdata/**"])

@@ -358,16 +365,3 @@ filegroup( You can then reference the label `my_data` as the data dependency in your test. - - - - - -
- BUILD files - - Visibility -
- diff --git a/versions/9.1.0/concepts/labels.mdx b/versions/9.1.0/concepts/labels.mdx index f0a2ff28..f646d7d3 100644 --- a/versions/9.1.0/concepts/labels.mdx +++ b/versions/9.1.0/concepts/labels.mdx @@ -115,7 +115,7 @@ used from external repositories. For information about the different ways you can refer to targets, see [target patterns](/versions/9.1.0/run/build#specifying-build-targets). -### Lexical specification of a label {:#labels-lexical-specification} +### 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 @@ -124,7 +124,7 @@ construct tools and scripts that manipulate labels, such as the The precise details of allowed target names are below. -### Target names — `{{ "" }}package-name{{ "" }}:target-name` {:#target-names} +### Target names — `package-name:target-name` {#target-names} `target-name` is the name of the target within the package. The name of a rule is the value of the `name` attribute in the rule's declaration in a `BUILD` @@ -143,7 +143,7 @@ current-directory references (`./`) are forbidden.

Wrong — Do not use .. to refer to files in other packages

Correct — Use - //{{ "" }}package-name{{ "" }}:{{ "" }}filename{{ "" }}

+ //package-name:filename

While it is common to use `/` in the name of a file target, avoid the use of `/` in the names of rules. Especially when the shorthand form of a label is @@ -155,7 +155,7 @@ However, there are some situations where use of a slash is convenient, or sometimes even necessary. For example, the name of certain rules must match their principal source file, which may reside in a subdirectory of the package. -### Package names — `//package-name:{{ "" }}target-name{{ "" }}` {:#package-names} +### Package names — `//package-name:target-name` {#package-names} The name of a package is the name of the directory containing its `BUILD` file, relative to the top-level directory of the containing repository. @@ -186,7 +186,7 @@ On a practical level: `//:foo`), it's best to leave that package empty so all meaningful packages have descriptive names. -## Rules {:#rules} +## Rules {#rules} A rule specifies the relationship between inputs and outputs, and the steps to build the outputs. Rules can be of one of many different @@ -239,16 +239,3 @@ 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](/versions/9.1.0/query/guide) operates. - - - - - - -
- Targets - - BUILD files -
diff --git a/versions/9.1.0/concepts/visibility.mdx b/versions/9.1.0/concepts/visibility.mdx index d44ea0f9..b907d506 100644 --- a/versions/9.1.0/concepts/visibility.mdx +++ b/versions/9.1.0/concepts/visibility.mdx @@ -10,7 +10,7 @@ library's public API and its implementation details, and help enforce structure as your workspace grows. You can also use visibility when deprecating a public API to allow current users while denying new ones. -## Target visibility {:#target-visibility} +## Target visibility {#target-visibility} **Target visibility** controls who may depend on your target — that is, who may use your target's label inside an attribute such as `deps`. A target will fail @@ -36,7 +36,7 @@ The following subsections describe the attribute's format, how to apply it to various kinds of targets, and the interaction between the visibility system and symbolic macros. -### Visibility specifications {:#visibility-specifications} +### Visibility specifications {#visibility-specifications} All rule targets have a `visibility` attribute that takes a list of labels. Each label has one of the following forms. With the exception of the last form, these @@ -83,7 +83,7 @@ Note: The `visibility` attribute may not specify non-`package_group` targets. Doing so triggers a "Label does not refer to a package group" or "Cycle in dependency graph" error. -### Rule target visibility {:#rule-target-visibility} +### Rule target visibility {#rule-target-visibility} A rule target's visibility is determined by taking its `visibility` attribute -- or a suitable default if not given -- and appending the location where the @@ -133,7 +133,7 @@ convenient for prototyping or in small codebases, but the risk of inadvertently creating public targets increases as the codebase grows. It's better to be explicit about which targets are part of a package's public interface. -### Generated file target visibility {:#generated-file-target-visibility} +### Generated file target visibility {#generated-file-target-visibility} A generated file target has the same visibility as the rule target that generates it. @@ -164,7 +164,7 @@ some_rule( ) ``` -### Source file target visibility {:#source-file-target-visibility} +### Source file target visibility {#source-file-target-visibility} Source file targets can either be explicitly declared using [`exports_files`](/versions/9.1.0/reference/be/functions#exports_files), or implicitly created @@ -181,7 +181,7 @@ file. For files that do not appear in a call to `exports_files`, the visibility depends on the value of the flag -[`--incompatible_no_implicit_file_export`](https://github.com/bazelbuild/bazel/issues/10225){: .external}: +[`--incompatible_no_implicit_file_export`](https://github.com/bazelbuild/bazel/issues/10225): * If the flag is true, the visibility is private. @@ -197,7 +197,7 @@ source file. For example, instead of calling `exports_files` on a `.java` file, wrap the file in a non-private `java_library` target. Generally, rule targets should only directly reference source files that live in the same package. -#### Example {:#source-file-visibility-example} +#### Example {#source-file-visibility-example} File `//frobber/data/BUILD`: @@ -214,19 +214,19 @@ cc_binary( ) ``` -### Config setting visibility {:#config-setting-visibility} +### Config setting visibility {#config-setting-visibility} Historically, Bazel has not enforced visibility for [`config_setting`](/versions/9.1.0/reference/be/general#config_setting) targets that are referenced in the keys of a [`select()`](/versions/9.1.0/reference/be/functions#select). There are two flags to remove this legacy behavior: -* [`--incompatible_enforce_config_setting_visibility`](https://github.com/bazelbuild/bazel/issues/12932){: .external} +* [`--incompatible_enforce_config_setting_visibility`](https://github.com/bazelbuild/bazel/issues/12932) enables visibility checking for these targets. To assist with migration, it also causes any `config_setting` that does not specify a `visibility` to be considered public (regardless of package-level `default_visibility`). -* [`--incompatible_config_setting_private_default_visibility`](https://github.com/bazelbuild/bazel/issues/12933){: .external} +* [`--incompatible_config_setting_private_default_visibility`](https://github.com/bazelbuild/bazel/issues/12933) causes `config_setting`s that do not specify a `visibility` to respect the package's `default_visibility` and to fallback on private visibility, just like any other rule target. It is a no-op if @@ -236,12 +236,12 @@ Avoid relying on the legacy behavior. Any `config_setting` that is intended to be used outside the current package should have an explicit `visibility`, if the package does not already specify a suitable `default_visibility`. -### Package group target visibility {:#package-group-target-visibility} +### Package group target visibility {#package-group-target-visibility} `package_group` targets do not have a `visibility` attribute. They are always publicly visible. -### Visibility of implicit dependencies {:#visibility-implicit-dependencies} +### Visibility of implicit dependencies {#visibility-implicit-dependencies} Some rules have [implicit dependencies](/versions/9.1.0/extending/rules#private_attributes_and_implicit_dependencies) — dependencies that are not spelled out in a `BUILD` file but are inherent to @@ -259,12 +259,12 @@ respect to the `cc_library` target. If you want to restrict the usage of a rule to certain packages, use [load visibility](#load-visibility) instead. -### Visibility and symbolic macros {:#symbolic-macros} +### Visibility and symbolic macros {#symbolic-macros} This section describes how the visibility system interacts with [symbolic macros](/versions/9.1.0/extending/macros). -#### Locations within symbolic macros {:#locations-within-symbolic-macros} +#### Locations within symbolic macros {#locations-within-symbolic-macros} A key detail of the visibility system is how we determine the location of a declaration. For targets that are not declared in a symbolic macro, the location @@ -301,7 +301,7 @@ composes, in the sense that a chain of nested calls to submacros may each pass the caller at each level, without exposing any of the macros' implementation details. -#### Delegating privileges to a submacro {:#delegating-privileges-to-a-submacro} +#### Delegating privileges to a submacro {#delegating-privileges-to-a-submacro} The visibility model has a special feature to allow a macro to delegate its permissions to a submacro. This is important for factoring and composing macros. @@ -377,7 +377,7 @@ label-typed attributes. Note: Visibility delegation does not work for labels that were not passed into the macro, such as labels derived by string manipulation. -#### Finalizers {:#finalizers} +#### Finalizers {#finalizers} Targets declared in a rule finalizer (a symbolic macro with `finalizer = True`), in addition to seeing targets following the usual symbolic macro visibility @@ -396,7 +396,7 @@ finalizer, the finalizer cannot see such a target. Note, however, that a `native.existing_rules()`-based legacy macro will also be unable to see such a target. -## Load visibility {:#load-visibility} +## Load visibility {#load-visibility} **Load visibility** controls whether a `.bzl` file may be loaded from other `BUILD` or `.bzl` files outside the current package. @@ -421,7 +421,7 @@ not be done for submitted code. Load visibility is available as of Bazel 6.0. -### Declaring load visibility {:#declaring-load-visibility} +### Declaring load visibility {#declaring-load-visibility} To set the load visibility of a `.bzl` file, call the [`visibility()`](/versions/9.1.0/rules/lib/globals/bzl#visibility) function from within the file. @@ -438,7 +438,7 @@ that do not call `visibility()` are always loadable from anywhere in the workspace. It is a good idea to add `visibility("private")` to the top of any new `.bzl` file that is not specifically intended for use outside the package. -### Example {:#load-visibility-example} +### Example {#load-visibility-example} ```starlark # //mylib/internal_defs.bzl @@ -472,11 +472,11 @@ load("//mylib:internal_defs.bzl", "helper") # error ... ``` -### Load visibility practices {:#load-visibility-practices} +### Load visibility practices {#load-visibility-practices} This section describes tips for managing load visibility declarations. -#### Factoring visibilities {:#factoring-visibilities} +#### Factoring visibilities {#factoring-visibilities} When multiple `.bzl` files should have the same visibility, it can be helpful to factor their package specifications into a common list. For example: @@ -514,7 +514,7 @@ visibility(clients) This helps prevent accidental skew between the various `.bzl` files' visibilities. It also is more readable when the `clients` list is large. -#### Composing visibilities {:#composing-visibilities} +#### Composing visibilities {#composing-visibilities} Sometimes a `.bzl` file might need to be visible to an allowlist that is composed of multiple smaller allowlists. This is analogous to how a @@ -534,7 +534,7 @@ load("//some_big_client:defs.bzl", "their_remaining_uses") visibility(our_packages + their_remaining_uses) ``` -#### Deduplicating with package groups {:#deduplicating-with-package-groups} +#### Deduplicating with package groups {#deduplicating-with-package-groups} Unlike target visibility, you cannot define a load visibility in terms of a `package_group`. If you want to reuse the same allowlist for both target @@ -557,7 +557,7 @@ package_group( This only works if the list does not contain any negative package specifications. -#### Protecting individual symbols {:#protecting-individual-symbols} +#### Protecting individual symbols {#protecting-individual-symbols} Any Starlark symbol whose name begins with an underscore cannot be loaded from another file. This makes it easy to create private symbols, but does not allow @@ -599,7 +599,7 @@ visibility("public") public_util = _public_util ``` -#### bzl-visibility Buildifier lint {:#bzl-visibility-buildifier-lint} +#### bzl-visibility Buildifier lint {#bzl-visibility-buildifier-lint} There is a [Buildifier lint](https://github.com/bazelbuild/buildtools/blob/master/WARNINGS.md#bzl-visibility) that provides a warning if users load a file from a directory named `internal` diff --git a/versions/9.1.0/contribute/images/structured-concurrency-3d.svg b/versions/9.1.0/contribute/images/structured-concurrency-3d.svg new file mode 100644 index 00000000..accbb42a --- /dev/null +++ b/versions/9.1.0/contribute/images/structured-concurrency-3d.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/contribute/images/structured-concurrency.svg b/versions/9.1.0/contribute/images/structured-concurrency.svg new file mode 100644 index 00000000..0258d9a9 --- /dev/null +++ b/versions/9.1.0/contribute/images/structured-concurrency.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/contribute/images/suspend-resume.svg b/versions/9.1.0/contribute/images/suspend-resume.svg new file mode 100644 index 00000000..7de1218f --- /dev/null +++ b/versions/9.1.0/contribute/images/suspend-resume.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/contribute/images/unstructured-concurrency.svg b/versions/9.1.0/contribute/images/unstructured-concurrency.svg new file mode 100644 index 00000000..0951639a --- /dev/null +++ b/versions/9.1.0/contribute/images/unstructured-concurrency.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/contribute/search.mdx b/versions/9.1.0/contribute/search.mdx index c5b8cb84..704c230b 100644 --- a/versions/9.1.0/contribute/search.mdx +++ b/versions/9.1.0/contribute/search.mdx @@ -2,14 +2,14 @@ title: 'Searching the codebase' --- -## Product overview {:#product-overview} +## Product overview {#product-overview} Bazel's [code search and source browsing interface](https://source.bazel.build) is a web-based tool for browsing Bazel source code repositories. You can use these features to navigate among different repositories, branches, and files. You can also view history, diffs, and blame information. -## Getting started {:#getting-started} +## Getting started {#getting-started} Note: For the best experience, use the latest version of Chrome, Safari, or Firefox. @@ -29,9 +29,9 @@ commit. At the top of the screen is a search box. You can use this box to search for specific files and code. -## Working with repositories {:#working-with-repositories} +## Working with repositories {#working-with-repositories} -### Opening a repository {:#opening-a-repository} +### Opening a repository {#opening-a-repository} To open a repository, click its name from the main screen. @@ -41,11 +41,11 @@ repository and allows you to move quickly to another location such as another repository, or another location within a repository, such as a file, branch, or commit. -### Switch repositories {:#switch-repositories} +### Switch repositories {#switch-repositories} To switch to a different repository, select the repository from the Breadcrumb toolbar. -### View a repository at a specific commit {:#view-a-repository-at-a-specific-commit} +### View a repository at a specific commit {#view-a-repository-at-a-specific-commit} To view a repository at a specific commit: @@ -56,7 +56,7 @@ To view a repository at a specific commit: The interface now shows the repository as it existed at that commit. -### Open a branch, commit, or tag {:#open-a-branch-commit-or-tag} +### Open a branch, commit, or tag {#open-a-branch-commit-or-tag} By default, the code search and source browsing interface opens a repository to the default branch. To open a different branch, from the Breadcrumb toolbar, @@ -72,7 +72,7 @@ branch using a branch name, a tag name, or through a search box. * To search for a branch, commit, or tag, select the corresponding item and type a search term in the search box. -## Working with files {:#working-with-files} +## Working with files {#working-with-files} When you select a repository from the main screen, the screen changes to display a view of that repository. If a README file exists, its contents appear in the @@ -90,13 +90,13 @@ three components: * A **File path** box, which displays the name of the current file or folder and its corresponding path -### Open a file {:#open-a-file} +### Open a file {#open-a-file} You can open a file by browsing to its directory and selecting it. The view of the repository updates to show the contents of the file in the file pane, and its location in the repository in the tree pane. -### View file changes {:#view-file-changes} +### View file changes {#view-file-changes} To view file changes: @@ -105,7 +105,7 @@ To view file changes: The file pane updates to display who made changes to the file and when. -### View change history {:#view-change-history} +### View change history {#view-change-history} To view the change history of a file: @@ -113,7 +113,7 @@ To view the change history of a file: 1. Click **HISTORY**, located in the upper-right corner. The **Change history** pane appears, showing the commits for this file. -### View code reviews {:#view-code-reviews} +### View code reviews {#view-code-reviews} For Gerrit code reviews, you can open the tool directly from the Change History pane. @@ -128,7 +128,7 @@ To view the code review for a file: The Gerrit Code Review tool opens in a new browser window. -### Open a file at a specific commit {:#open-a-file-at-a-specific-commit} +### Open a file at a specific commit {#open-a-file-at-a-specific-commit} To open a file at a specific commit: @@ -138,7 +138,7 @@ To open a file at a specific commit: 1. Hover over a commit. A **VIEW** button appears. 1. Click the **VIEW** button. -### Compare a file to a different commit {:#compare-a-file-to-a-different-commit} +### Compare a file to a different commit {#compare-a-file-to-a-different-commit} To compare a file at a different commit: @@ -157,7 +157,7 @@ To change either file, hover over the commit in the Change History pane. Then, click either the **Left** or **Right** button to have the open the commit on the left or right side of the diff. -### Browsing cross references {:#browsing-cross-references} +### Browsing cross references {#browsing-cross-references} Another way to browse source repositories is through the use of cross references. These references appear automatically as hyperlinks within a given @@ -188,12 +188,12 @@ You can continue to browse cross references using the Cross Reference pane, just as you can in the File pane. When you do, the pane displays a breadcrumb trail, which you can use to navigate between different cross references. -## Searching for code {:#search} +## Searching for code {#search} You can search for specific files or code snippets using the search box located at the top of the screen. Searches are always against the default branch. -All searches use [RE2 regular expressions](https://github.com/google/re2/wiki/Syntax){: .external} +All searches use [RE2 regular expressions](https://github.com/google/re2/wiki/Syntax) by default. If you do not want to use regular expressions, enclose your search in double quotes ( " ). @@ -225,8 +225,8 @@ You can refine your search using the following filters. file: -filepath:
-path:
+filepath:
+path:
f: @@ -256,10 +256,10 @@ f: hello -world -\ +`\` Escapes special characters, such as ., \, or (. -run\(\) +`run\(\)` "[term]" @@ -270,7 +270,7 @@ f: -## Additional Support {:#additional-support} +## Additional Support {#additional-support} To report an issue, click the **Feedback** button that appears in the top right-hand corner of the screen and enter your feedback in the provided form. diff --git a/versions/9.1.0/docs/android-instrumentation-test.mdx b/versions/9.1.0/docs/android-instrumentation-test.mdx index 70d87610..7ef394b5 100644 --- a/versions/9.1.0/docs/android-instrumentation-test.mdx +++ b/versions/9.1.0/docs/android-instrumentation-test.mdx @@ -54,7 +54,7 @@ bazel info release ``` This results in output similar to the following: -```none {:.devsite-disable-click-to-copy} +``` release 4.1.0 ``` @@ -72,7 +72,7 @@ apt-get install cpu-checker && kvm-ok If it prints the following message, you have the correct configuration: -```none {:.devsite-disable-click-to-copy} +``` INFO: /dev/kvm exists KVM acceleration can be used ``` @@ -93,7 +93,7 @@ which Xvfb ``` The output is the following: -```{:.devsite-disable-click-to-copy} +``` /usr/bin/Xvfb ``` @@ -201,7 +201,7 @@ Here is an example `AndroidTestManifest.xml` for the test app: android:targetSdkVersion="27" /> - + {/* ... */} ``` diff --git a/versions/9.1.0/docs/cc-toolchain-config-reference.mdx b/versions/9.1.0/docs/cc-toolchain-config-reference.mdx index 5c6f3e29..b025aa8c 100644 --- a/versions/9.1.0/docs/cc-toolchain-config-reference.mdx +++ b/versions/9.1.0/docs/cc-toolchain-config-reference.mdx @@ -2,7 +2,7 @@ title: 'C++ Toolchain Configuration' --- -## Overview {:#overview} +## Overview {#overview} To invoke the compiler with the right options, Bazel needs some knowledge about the compiler internals, such as include directories and important flags. @@ -35,7 +35,7 @@ that provides the `CcToolchainConfigInfo` and you need to point the You can create the `CcToolchainConfigInfo` by calling [`cc_common.create_cc_toolchain_config_info()`](/versions/9.1.0/rules/lib/toplevel/cc_common#create_cc_toolchain_config_info). You can find Starlark constructors for all structs you'll need in the process in -[`@rules_cc//cc:cc_toolchain_config_lib.bzl`](https://github.com/bazelbuild/rules_cc/blob/master/cc/cc_toolchain_config_lib.bzl){: .external}. +[`@rules_cc//cc:cc_toolchain_config_lib.bzl`](https://github.com/bazelbuild/rules_cc/blob/master/cc/cc_toolchain_config_lib.bzl). When a C++ target enters the analysis phase, Bazel selects the appropriate `cc_toolchain` target based on the `BUILD` file, and obtains the @@ -59,7 +59,7 @@ The artifacts to be shipped to the sandbox are declared in the `cc_toolchain` target. For example, with the `cc_toolchain.linker_files` attribute you can specify the linker binary and toolchain libraries to ship into the sandbox. -## Toolchain selection {:#toolchain-selection} +## Toolchain selection {#toolchain-selection} The toolchain selection logic operates as follows: @@ -93,7 +93,7 @@ fully fledged C++ features in Bazel without modifying the Bazel binary. C++ rules support multiple unique actions documented in detail [in the Bazel source code](https://source.bazel.build/bazel/+/4f547a7ea86df80e4c76145ffdbb0c8b75ba3afa:tools/build_defs/cc/action_names.bzl). -## Features {:#features} +## Features {#features} A feature is an entity that requires command-line flags, actions, constraints on the execution environment, or dependency alterations. A feature @@ -121,7 +121,7 @@ A feature is enabled in one of the following ways: Features can have interdependencies, depend on command line flags, `BUILD` file settings, and other variables. -### Feature relationships {:#feature-relationships} +### Feature relationships {#feature-relationships} Dependencies are typically managed directly with Bazel, which simply enforces the requirements and manages conflicts intrinsic to the nature of the features @@ -130,60 +130,62 @@ constraints for use directly within the Starlark rule that govern feature support and expansion. These are: - - + + - - + + - - - - + - - + - -
Constraint - Description - ConstraintDescription 
requires = [
-   feature_set (features = [
-       'feature-name-1',
-       'feature-name-2'
-   ]),
-]
+ 		+ 
requires = [
+     feature_set (features = [
+     'feature-name-1',
+     'feature-name-2'
+     ]),
+     ]
Feature-level. The feature is supported only if the specified required - features are enabled. For example, when a feature is only supported in - certain build modes (opt, dbg, or - fastbuild). If `requires` contains multiple `feature_set`s - the feature is supported if any of the `feature_set`s is satisfied - (when all specified features are enabled). + + Feature-level. The feature is supported only if the specified required + features are enabled. For example, when a feature is only supported in + certain build modes (opt, dbg, or + fastbuild). If `requires` contains multiple `feature_set`s + the feature is supported if any of the `feature_set`s is satisfied + (when all specified features are enabled). 
implies = ['feature']
-

Feature-level. This feature implies the specified feature(s). - Enabling a feature also implicitly enables all features implied by it - (that is, it functions recursively).

-

Also provides the ability to factor common subsets of functionality out of - a set of features, such as the common parts of sanitizers. Implied - features cannot be disabled.

+ 
implies = ['feature']
 +

Feature-level. This feature implies the specified feature(s). + Enabling a feature also implicitly enables all features implied by it + (that is, it functions recursively).

+

Also provides the ability to factor common subsets of functionality out of + a set of features, such as the common parts of sanitizers. Implied + features cannot be disabled.

 
provides = ['feature']
-

Feature-level. Indicates that this feature is one of several mutually - exclusive alternate features. For example, all of the sanitizers could - specify provides = ["sanitizer"].

-

This improves error handling by listing the alternatives if the user asks - for two or more mutually exclusive features at once.

+ 
provides = ['feature']
 +

Feature-level. Indicates that this feature is one of several mutually + exclusive alternate features. For example, all of the sanitizers could + specify provides = ["sanitizer"].

+

This improves error handling by listing the alternatives if the user asks + for two or more mutually exclusive features at once.

 
with_features = [
-  with_feature_set(
-    features = ['feature-1'],
-    not_features = ['feature-2'],
-  ),
-]
+ 		+ 
with_features = [
+     with_feature_set(
+     features = ['feature-1'],
+     not_features = ['feature-2'],
+     ),
+     ]
Flag set-level. A feature can specify multiple flag sets with multiple. + + Flag set-level. A feature can specify multiple flag sets with multiple. When with_features is specified, the flag set will only expand to the build command if there is at least one with_feature_set for which all of the features in the specified features set @@ -195,7 +197,7 @@ support and expansion. These are:
-## Actions {:#actions} +## Actions {#actions} Actions provide the flexibility to modify the circumstances under which an action executes without assuming how the action will be run. An @@ -216,149 +218,117 @@ that implements an action (such as `CppCompileAction`). In particular, the "assembler actions" and "compiler actions" in the table below are `CppCompileAction`, while the link actions are `CppLinkAction`. -### Assembler actions {:#assembler-actions} +### Assembler actions {#assembler-actions} - - + + - - + + - - + + - - + +
Action - Description - ActionDescription
preprocess-assemble - Assemble with preprocessing. Typically for .S files. - preprocess-assembleAssemble with preprocessing. Typically for .S files.
assemble - Assemble without preprocessing. Typically for .s files. - assembleAssemble without preprocessing. Typically for .s files.
-### Compiler actions {:#compiler-actions} +### Compiler actions {#compiler-actions} - - + + - - + + - - + + - - + + - - + + - - +
Action - Description - ActionDescription
cc-flags-make-variable - Propagates CC_FLAGS to genrules. - cc-flags-make-variablePropagates CC_FLAGS to genrules.
c-compile - Compile as C. - c-compileCompile as C.
c++-compile - Compile as C++. - c++-compileCompile as C++.
c++-header-parsing - Run the compiler's parser on a header file to ensure that the header is + c++-header-parsing + Run the compiler's parser on a header file to ensure that the header is self-contained, as it will otherwise produce compilation errors. Applies only to toolchains that support modules.
-### Link actions {:#link-actions} +### Link actions {#link-actions} - - + + - - + + - - + + - - + + - - + +
Action - Description - ActionDescription
c++-link-dynamic-library - Link a shared library containing all of its dependencies. - c++-link-dynamic-libraryLink a shared library containing all of its dependencies.
c++-link-nodeps-dynamic-library - Link a shared library only containing cc_library sources. - c++-link-nodeps-dynamic-libraryLink a shared library only containing cc_library sources.
c++-link-executable - Link a final ready-to-run library. - c++-link-executableLink a final ready-to-run library.
-### AR actions {:#ar-actions} +### AR actions {#ar-actions} AR actions assemble object files into archive libraries (`.a` files) via `ar` and encode some semantics into the name. - - + + - - + + - - + +
Action - Description - ActionDescription
c++-link-static-library - Create a static library (archive). - c++-link-static-libraryCreate a static library (archive).
-### LTO actions {:#lto-actions} +### LTO actions {#lto-actions} - - + + - - + + - - + + - - + +
Action - Description - ActionDescription
lto-backend - ThinLTO action compiling bitcodes into native objects. - lto-backendThinLTO action compiling bitcodes into native objects.
lto-index - ThinLTO action generating global index. - lto-indexThinLTO action generating global index.
-## Using action_config {:#using-action-config} +## Using action_config {#using-action-config} The `action_config` is a Starlark struct that describes a Bazel action by specifying the tool (binary) to invoke during the action and sets of @@ -368,42 +338,40 @@ execution. The `action_config()` constructor has the following parameters: - - + + - - + + - - + + - - + - - + - - +
Attribute - Description - AttributeDescription
action_name - The Bazel action to which this action corresponds. - Bazel uses this attribute to discover per-action tool and execution - requirements. - action_name + The Bazel action to which this action corresponds. + Bazel uses this attribute to discover per-action tool and execution + requirements. +
tools - The executable to invoke. The tool applied to the action will be the - first tool in the list with a feature set that matches the feature - configuration. Default value must be provided. + tools + The executable to invoke. The tool applied to the action will be the + first tool in the list with a feature set that matches the feature + configuration. Default value must be provided.
flag_sets - A list of flags that applies to a group of actions. Same as for a - feature. + flag_sets + A list of flags that applies to a group of actions. Same as for a + feature.
env_sets - A list of environment constraints that applies to a group of actions. - Same as for a feature. + env_sets + A list of environment constraints that applies to a group of actions. + Same as for a feature.
@@ -424,31 +392,27 @@ within the same toolchain. This prevents ambiguity in tool paths and enforces the intention behind `action_config` - that an action's properties are clearly described in a single place in the toolchain. -### Using tool constructor {:#using-tool-constructor} +### Using tool constructor {#using-tool-constructor} An`action_config` can specify a set of tools via its `tools` parameter. The `tool()` constructor takes in the following parameters: - - + + - - + + - - + + - - +
Field - Description - FieldDescription
path - Path to the tool in question (relative to the current location). - pathPath to the tool in question (relative to the current location).
with_features - A list of feature sets out of which at least one must be satisfied - for this tool to apply. + with_features + A list of feature sets out of which at least one must be satisfied + for this tool to apply.
@@ -461,7 +425,7 @@ with a `with_feature` set matching the feature configuration is found for more information). You should end your tool lists with a default tool that corresponds to an empty feature configuration. -### Example usage {:#example-usage} +### Example usage {#example-usage} Features and actions can be used together to implement Bazel actions with diverse cross-platform semantics. For example, debug symbol generation on @@ -553,7 +517,7 @@ follows: ), ] -### Flag groups {:#flag-groups} +### Flag groups {#flag-groups} `CcToolchainConfigInfo` allows you to bundle flags into groups that serve a specific purpose. You can specify a flag within using pre-defined variables @@ -599,7 +563,7 @@ A variable can repeat multiple times. For example: expands to: - -iprefix= -isystem= -iprefix= -isystem= + `-iprefix= -isystem= -iprefix= -isystem=` Variables can correspond to structures accessible using dot-notation. For example: @@ -622,7 +586,7 @@ example: ], ) -### Conditional expansion {:#conditional-expansion} +### Conditional expansion {#conditional-expansion} Flag groups support conditional expansion based on the presence of a particular variable or its field using the `expand_if_available`, `expand_if_not_available`, @@ -654,12 +618,12 @@ Note: The `--whole_archive` and `--no_whole_archive` options are added to the build command only when a currently iterated library has an `is_whole_archive` field. -## CcToolchainConfigInfo reference {:#cctoolchainconfiginfo-reference} +## CcToolchainConfigInfo reference {#cctoolchainconfiginfo-reference} This section provides a reference of build variables, features, and other information required to successfully configure C++ rules. -### CcToolchainConfigInfo build variables {:#cctoolchainconfiginfo-build-variables} +### CcToolchainConfigInfo build variables {#cctoolchainconfiginfo-build-variables} The following is a reference of `CcToolchainConfigInfo` build variables. @@ -667,365 +631,314 @@ Note: The **Action** column indicates the relevant action type, if applicable. - - - + + + - + - + - + - + - + - + - + - - + - - + - - + - - + - - + - - + - + - + - + - + - + - + - + - + - + - + - + - + - - + - - + - - + - + - + - - + - - + - + - + - + - + - - + - + - + - - + - + - + - + - + - + - + - + - + - - + - + - + - - + - - + - - + - - + - + - + - + - + - + - + -
Variable - Action - Description - VariableActionDescription
source_file - source_file compileSource file to compile. - Source file to compile.
input_file - input_file stripArtifact to strip. - Artifact to strip.
output_file - output_file compile, stripCompilation output. - Compilation output.
output_assembly_file - output_assembly_file compileEmitted assembly file. Applies only when the - compile action emits assembly text, typically when using the - --save_temps flag. The contents are the same as for - output_file. + + Emitted assembly file. Applies only when the + compile action emits assembly text, typically when using the + --save_temps flag. The contents are the same as for + output_file.
output_preprocess_file - output_preprocess_file compilePreprocessed output. Applies only to compile - actions that only preprocess the source files, typically when using the + + Preprocessed output. Applies only to compile + actions that only preprocess the source files, typically when using the --save_temps flag. The contents are the same as for output_file.
includes - includes compileSequence of files the compiler must - unconditionally include in the compiled source. + + Sequence of files the compiler must + unconditionally include in the compiled source.
include_paths - include_paths compileSequence directories in which the compiler - searches for headers included using #include<foo.h> - and #include "foo.h". + + Sequence directories in which the compiler + searches for headers included using #include<foo.h> + and #include "foo.h".
quote_include_paths - quote_include_paths compileSequence of -iquote includes - - directories in which the compiler searches for headers included using - #include "foo.h". + + Sequence of -iquote includes - + directories in which the compiler searches for headers included using + #include "foo.h".
system_include_paths - system_include_paths compileSequence of -isystem includes - - directories in which the compiler searches for headers included using - #include <foo.h>. + + Sequence of -isystem includes - + directories in which the compiler searches for headers included using + #include <foo.h>.
dependency_file - dependency_file compileThe .d dependency file generated by the compiler. - The .d dependency file generated by the compiler.
preprocessor_defines - preprocessor_defines compileSequence of defines, such as --DDEBUG. - Sequence of defines, such as --DDEBUG.
pic - pic compileCompiles the output as position-independent code. - Compiles the output as position-independent code.
gcov_gcno_file - gcov_gcno_file compileThe gcov coverage file. - The gcov coverage file.
per_object_debug_info_file - per_object_debug_info_file compileThe per-object debug info (.dwp) file. - The per-object debug info (.dwp) file.
stripopts - stripopts stripSequence of stripopts. - Sequence of stripopts.
legacy_compile_flags - legacy_compile_flags compileSequence of flags from legacy - CROSSTOOL fields such as compiler_flag, - optional_compiler_flag, cxx_flag, and - optional_cxx_flag. + + Sequence of flags from legacy + CROSSTOOL fields such as compiler_flag, + optional_compiler_flag, cxx_flag, and + optional_cxx_flag.
user_compile_flags - user_compile_flags compileSequence of flags from either the - copt rule attribute or the --copt, - --cxxopt, and --conlyopt flags. + + Sequence of flags from either the + copt rule attribute or the --copt, + --cxxopt, and --conlyopt flags.
unfiltered_compile_flags - unfiltered_compile_flags compileSequence of flags from the + + Sequence of flags from the unfiltered_cxx_flag legacy CROSSTOOL field or the - unfiltered_compile_flags feature. These are not filtered by - the nocopts rule attribute. + unfiltered_compile_flags feature. These are not filtered by + the nocopts rule attribute.
sysroot - sysroot The sysroot. - The sysroot.
runtime_library_search_directories - runtime_library_search_directories linkEntries in the linker runtime search path (usually - set with the -rpath flag). + + Entries in the linker runtime search path (usually + set with the -rpath flag).
library_search_directories - library_search_directories linkEntries in the linker search path (usually set with - the -L flag). + + Entries in the linker search path (usually set with + the -L flag).
libraries_to_link - libraries_to_link linkFlags providing files to link as inputs in the linker invocation. - Flags providing files to link as inputs in the linker invocation.
def_file_path - def_file_path linkLocation of def file used on Windows with MSVC. - Location of def file used on Windows with MSVC.
linker_param_file - linker_param_file linkLocation of linker param file created by bazel to - overcome command line length limit. + + Location of linker param file created by bazel to + overcome command line length limit.
output_execpath - output_execpath linkExecpath of the output of the linker. - Execpath of the output of the linker.
generate_interface_library - generate_interface_library link"yes" or "no" depending on whether interface library should - be generated. + + "yes" or "no" depending on whether interface library should + be generated.
interface_library_builder_path - interface_library_builder_path linkPath to the interface library builder tool. - Path to the interface library builder tool.
interface_library_input_path - interface_library_input_path linkInput for the interface library ifso builder tool. - Input for the interface library ifso builder tool.
interface_library_output_path - interface_library_output_path linkPath where to generate interface library using the ifso builder tool. - Path where to generate interface library using the ifso builder tool.
legacy_link_flags - legacy_link_flags linkLinker flags coming from the legacy CROSSTOOL fields. - Linker flags coming from the legacy CROSSTOOL fields.
user_link_flags - user_link_flags linkLinker flags coming from the --linkopt - or linkopts attribute. + + Linker flags coming from the --linkopt + or linkopts attribute.
linkstamp_paths - linkstamp_paths linkA build variable giving linkstamp paths. - A build variable giving linkstamp paths.
force_pic - force_pic linkPresence of this variable indicates that PIC/PIE code should + + Presence of this variable indicates that PIC/PIE code should be generated (Bazel option `--force_pic` was passed).
strip_debug_symbols - strip_debug_symbols linkPresence of this variable indicates that the debug - symbols should be stripped. + + Presence of this variable indicates that the debug + symbols should be stripped.
is_cc_test - is_cc_test linkTruthy when current action is a cc_test - linking action, false otherwise. + + Truthy when current action is a cc_test + linking action, false otherwise.
is_using_fission - is_using_fission compile, linkPresence of this variable indicates that fission (per-object debug info) + + Presence of this variable indicates that fission (per-object debug info) is activated. Debug info will be in .dwo files instead - of .o files and the compiler and linker need to know this. + of .o files and the compiler and linker need to know this.
fdo_instrument_path - fdo_instrument_path compile, link Path to the directory that stores FDO instrumentation profile. - Path to the directory that stores FDO instrumentation profile.
fdo_profile_path - fdo_profile_path compile Path to FDO profile. - Path to FDO profile.
fdo_prefetch_hints_path - fdo_prefetch_hints_path compile Path to the cache prefetch profile. - Path to the cache prefetch profile.
cs_fdo_instrument_path - cs_fdo_instrument_path compile, link Path to the directory that stores context sensitive FDO - instrumentation profile. + + Path to the directory that stores context sensitive FDO + instrumentation profile.
-### Well-known features {:#wellknown-features} +### Well-known features {#wellknown-features} The following is a reference of features and their activation conditions. - - + + - - + + - - + + - - + + - - + + - - + - - + - - + - - + - - + - + - + - - + +
Feature - Documentation - FeatureDocumentation
opt | dbg | fastbuild - Enabled by default based on compilation mode. - opt | dbg | fastbuildEnabled by default based on compilation mode.
static_linking_mode | dynamic_linking_mode - Enabled by default based on linking mode. - static_linking_mode | dynamic_linking_modeEnabled by default based on linking mode.
per_object_debug_info - Enabled if the supports_fission feature is specified and - enabled and the current compilation mode is specified in the - --fission flag. - per_object_debug_info + Enabled if the supports_fission feature is specified and + enabled and the current compilation mode is specified in the + --fission flag. +
supports_start_end_lib - If enabled (and the option --start_end_lib is set), Bazel + supports_start_end_lib + If enabled (and the option --start_end_lib is set), Bazel will not link against static libraries but instead use the --start-lib/--end-lib linker options to link against objects directly. This speeds up the build since Bazel doesn't have to build @@ -1033,25 +946,25 @@ conditions.
supports_interface_shared_libraries - If enabled (and the option --interface_shared_objects is + supports_interface_shared_libraries + If enabled (and the option --interface_shared_objects is set), Bazel will link targets that have linkstatic set to False (cc_tests by default) against interface shared libraries. This makes incremental relinking faster.
supports_dynamic_linker - If enabled, C++ rules will know the toolchain can produce shared + supports_dynamic_linker + If enabled, C++ rules will know the toolchain can produce shared libraries.
static_link_cpp_runtimes - If enabled, Bazel will link the C++ runtime statically in static linking + static_link_cpp_runtimes + If enabled, Bazel will link the C++ runtime statically in static linking mode and dynamically in dynamic linking mode. Artifacts specified in the cc_toolchain.static_runtime_lib or cc_toolchain.dynamic_runtime_lib attribute (depending on the @@ -1059,24 +972,21 @@ conditions.
supports_pic - If enabled, toolchain will know to use PIC objects for dynamic libraries. + supports_pic + If enabled, toolchain will know to use PIC objects for dynamic libraries. The `pic` variable is present whenever PIC compilation is needed. If not enabled by default, and `--force_pic` is passed, Bazel will request `supports_pic` and validate that the feature is enabled. If the feature is missing, or couldn't - be enabled, `--force_pic` cannot be used. + be enabled, `--force_pic` cannot be used.
- static_linking_mode | dynamic_linking_mode - static_linking_mode | dynamic_linking_mode Enabled by default based on linking mode.
no_legacy_features - no_legacy_features Prevents Bazel from adding legacy features to the C++ configuration when present. See the complete list of @@ -1084,15 +994,12 @@ conditions.
shorten_virtual_includes - - If enabled, virtual include header files are linked under bin/_virtual_includes/<hash of target path> instead of bin/<target package path>/_virtual_includes/<target name>. Useful on Windows to avoid long path issue with MSVC. - shorten_virtual_includesIf enabled, virtual include header files are linked under bin/_virtual_includes/<hash of target path> instead of bin/<target package path>/_virtual_includes/<target name>. Useful on Windows to avoid long path issue with MSVC.
-#### Legacy features patching logic {:#legacy-features-patching-logic} +#### Legacy features patching logic {#legacy-features-patching-logic}

Bazel applies the following changes to the toolchain's features for backwards @@ -1142,7 +1049,7 @@ conditions.

This is a long list of features. The plan is to get rid of them once -[Crosstool in Starlark](https://github.com/bazelbuild/bazel/issues/5380){: .external} is +[Crosstool in Starlark](https://github.com/bazelbuild/bazel/issues/5380) is done. For the curious reader see the implementation in [CppActionConfigs](https://source.bazel.build/bazel/+/master:src/main/java/com/google/devtools/build/lib/rules/cpp/CppActionConfigs.java?q=cppactionconfigs&ss=bazel), and for production toolchains consider adding `no_legacy_features` to make diff --git a/versions/9.1.0/docs/images/a_b_a_c.svg b/versions/9.1.0/docs/images/a_b_a_c.svg new file mode 100644 index 00000000..d38be075 --- /dev/null +++ b/versions/9.1.0/docs/images/a_b_a_c.svg @@ -0,0 +1,42 @@ + + + + + + +G + + + +a + +a + + + +b + +b + + + +a->b + + + + + +c + +c + + + +a->c + + + + + + diff --git a/versions/9.1.0/docs/images/a_b_c.svg b/versions/9.1.0/docs/images/a_b_c.svg new file mode 100644 index 00000000..acd948ab --- /dev/null +++ b/versions/9.1.0/docs/images/a_b_c.svg @@ -0,0 +1,41 @@ + + + + + + +G + + + +a + +a + + + +b + +b + + + +a->b + + + + + +c + +c + + + +b->c + + + + + diff --git a/versions/9.1.0/docs/images/a_b_c_ac.svg b/versions/9.1.0/docs/images/a_b_c_ac.svg new file mode 100644 index 00000000..b099c53e --- /dev/null +++ b/versions/9.1.0/docs/images/a_b_c_ac.svg @@ -0,0 +1,47 @@ + + + + + + +G + + + +a + +a + + + +b + +b + + + +a->b + + + + + +c + +c + + + +a->c + + + + + +b->c + + + + + diff --git a/versions/9.1.0/docs/images/ab_c.svg b/versions/9.1.0/docs/images/ab_c.svg new file mode 100644 index 00000000..bcc4563f --- /dev/null +++ b/versions/9.1.0/docs/images/ab_c.svg @@ -0,0 +1,36 @@ + + + + + + +G + + + +a + +a + + + +b + +b + + + +a->b + + + + + +c + +c + + + + diff --git a/versions/9.1.0/docs/images/allpaths.svg b/versions/9.1.0/docs/images/allpaths.svg new file mode 100644 index 00000000..47d0ee33 --- /dev/null +++ b/versions/9.1.0/docs/images/allpaths.svg @@ -0,0 +1,141 @@ + + + + + + +allpaths + + + +n1 + + + + +n2 + + + + +n1->n2 + + + + + +n3 + + + + +n2->n3 + + + + + +n10 + + + + +n2->n10 + + + + + +n3->n10 + + + + + +n4 + +E + + + +n5 + + + + +n6 + + + + +n5->n6 + + + + + +n6->n4 + + + + + +n9 + + + + +n6->n9 + + + + + +n7 + +S1 + + + +n7->n2 + + + + + +n7->n5 + + + + + +n8 + +S2 + + + +n8->n6 + + + + + +n10->n4 + + + + + +n11 + + + + +n10->n11 + + + + + diff --git a/versions/9.1.0/docs/images/android_instrumentation_test.png b/versions/9.1.0/docs/images/android_instrumentation_test.png new file mode 100644 index 00000000..e4534fbd Binary files /dev/null and b/versions/9.1.0/docs/images/android_instrumentation_test.png differ diff --git a/versions/9.1.0/docs/images/android_ndk.png b/versions/9.1.0/docs/images/android_ndk.png new file mode 100644 index 00000000..76b63cb3 Binary files /dev/null and b/versions/9.1.0/docs/images/android_ndk.png differ diff --git a/versions/9.1.0/docs/images/android_tutorial_app.png b/versions/9.1.0/docs/images/android_tutorial_app.png new file mode 100644 index 00000000..076be5b9 Binary files /dev/null and b/versions/9.1.0/docs/images/android_tutorial_app.png differ diff --git a/versions/9.1.0/docs/images/android_tutorial_before.png b/versions/9.1.0/docs/images/android_tutorial_before.png new file mode 100644 index 00000000..8e41d419 Binary files /dev/null and b/versions/9.1.0/docs/images/android_tutorial_before.png differ diff --git a/versions/9.1.0/docs/images/bep-graph.png b/versions/9.1.0/docs/images/bep-graph.png new file mode 100644 index 00000000..82da6715 Binary files /dev/null and b/versions/9.1.0/docs/images/bep-graph.png differ diff --git a/versions/9.1.0/docs/images/bep-graph.svg b/versions/9.1.0/docs/images/bep-graph.svg new file mode 100644 index 00000000..62b1480f --- /dev/null +++ b/versions/9.1.0/docs/images/bep-graph.svg @@ -0,0 +1,4 @@ + + + + diff --git a/versions/9.1.0/docs/images/cpp-tutorial-stage1.png b/versions/9.1.0/docs/images/cpp-tutorial-stage1.png new file mode 100644 index 00000000..c85fb303 Binary files /dev/null and b/versions/9.1.0/docs/images/cpp-tutorial-stage1.png differ diff --git a/versions/9.1.0/docs/images/cpp-tutorial-stage2.png b/versions/9.1.0/docs/images/cpp-tutorial-stage2.png new file mode 100644 index 00000000..80e202c9 Binary files /dev/null and b/versions/9.1.0/docs/images/cpp-tutorial-stage2.png differ diff --git a/versions/9.1.0/docs/images/cpp-tutorial-stage3.png b/versions/9.1.0/docs/images/cpp-tutorial-stage3.png new file mode 100644 index 00000000..54d82f31 Binary files /dev/null and b/versions/9.1.0/docs/images/cpp-tutorial-stage3.png differ diff --git a/versions/9.1.0/docs/images/deps.svg b/versions/9.1.0/docs/images/deps.svg new file mode 100644 index 00000000..4354222a --- /dev/null +++ b/versions/9.1.0/docs/images/deps.svg @@ -0,0 +1,101 @@ + + + + + + +G1 + + + +r1 + +rule + + + +s1 + +in + + + +r1->s1 + + + + + +s2 + +in + + + +r1->s2 + + + + + +s3 + +in + + + +r1->s3 + + + + + +r2 + +rule + + + +r2->r1 + + + + + +s4 + +in + + + +r2->s4 + + + + + +o1 + +out + + + +o1->r1 + + + + + +o2 + +out + + + +o2->r2 + + + + + diff --git a/versions/9.1.0/docs/images/dyn-trace-alldynamic.png b/versions/9.1.0/docs/images/dyn-trace-alldynamic.png new file mode 100644 index 00000000..fe36b253 Binary files /dev/null and b/versions/9.1.0/docs/images/dyn-trace-alldynamic.png differ diff --git a/versions/9.1.0/docs/images/dyn-trace-javaconly.png b/versions/9.1.0/docs/images/dyn-trace-javaconly.png new file mode 100644 index 00000000..2ae41e52 Binary files /dev/null and b/versions/9.1.0/docs/images/dyn-trace-javaconly.png differ diff --git a/versions/9.1.0/docs/images/e4b-workflow.png b/versions/9.1.0/docs/images/e4b-workflow.png new file mode 100644 index 00000000..412822da Binary files /dev/null and b/versions/9.1.0/docs/images/e4b-workflow.png differ diff --git a/versions/9.1.0/docs/images/e4b-workflow.svg b/versions/9.1.0/docs/images/e4b-workflow.svg new file mode 100644 index 00000000..1de66e02 --- /dev/null +++ b/versions/9.1.0/docs/images/e4b-workflow.svg @@ -0,0 +1,4 @@ + + + + diff --git a/versions/9.1.0/docs/images/error_example_1.png b/versions/9.1.0/docs/images/error_example_1.png new file mode 100644 index 00000000..07ba1358 Binary files /dev/null and b/versions/9.1.0/docs/images/error_example_1.png differ diff --git a/versions/9.1.0/docs/images/error_example_2.png b/versions/9.1.0/docs/images/error_example_2.png new file mode 100644 index 00000000..861171ee Binary files /dev/null and b/versions/9.1.0/docs/images/error_example_2.png differ diff --git a/versions/9.1.0/docs/images/error_example_3.png b/versions/9.1.0/docs/images/error_example_3.png new file mode 100644 index 00000000..dc16eec4 Binary files /dev/null and b/versions/9.1.0/docs/images/error_example_3.png differ diff --git a/versions/9.1.0/docs/images/error_example_4.png b/versions/9.1.0/docs/images/error_example_4.png new file mode 100644 index 00000000..84383e63 Binary files /dev/null and b/versions/9.1.0/docs/images/error_example_4.png differ diff --git a/versions/9.1.0/docs/images/graph_ex_1.svg b/versions/9.1.0/docs/images/graph_ex_1.svg new file mode 100644 index 00000000..dd7427f4 --- /dev/null +++ b/versions/9.1.0/docs/images/graph_ex_1.svg @@ -0,0 +1,131 @@ + + + + + + +mygraph + + + +//net/proto_compiler:protocol-compiler + +//net/proto_compiler:protocol-compiler + + + +//net/proto_compiler:util + +//net/proto_compiler:util + + + +//net/proto_compiler:protocol-compiler->//net/proto_compiler:util + + + + + +//net/proto_compiler:protocol-compiler-lib + +//net/proto_compiler:protocol-compiler-lib + + + +//net/proto_compiler:protocol-compiler->//net/proto_compiler:protocol-compiler-lib + + + + + +//net/proto2/bridge/public:compiler_upgrader + +//net/proto2/bridge/public:compiler_upgrader + + + +//net/proto_compiler:protocol-compiler->//net/proto2/bridge/public:compiler_upgrader + + + + + +//net/proto_compiler:parser + +//net/proto_compiler:parser + + + +//net/proto_compiler:util->//net/proto_compiler:parser + + + + + +//net/proto_compiler:proto-min-lib + +//net/proto_compiler:proto-min-lib + + + +//net/proto_compiler:protocol-compiler-lib->//net/proto_compiler:proto-min-lib + + + + + +//net/proto_compiler:protocol-compiler-lib->//net/proto_compiler:parser + + + + + +//net/proto2/bridge/internal:compiler_upgrader + +//net/proto2/bridge/internal:compiler_upgrader + + + +//net/proto2/bridge/public:compiler_upgrader->//net/proto2/bridge/internal:compiler_upgrader + + + + + +//net/proto_compiler:proto-min-lib->//net/proto_compiler:parser + + + + + +//util/regexp:regexp + +//util/regexp:regexp + + + +//net/proto_compiler:proto-min-lib->//util/regexp:regexp + + + + + +//net/proto_compiler:parser->//util/regexp:regexp + + + + + +//net/proto2/bridge/internal:compiler_upgrader->//net/proto2/bridge/public:compiler_upgrader + + + + + +//net/proto2/bridge/internal:compiler_upgrader->//net/proto_compiler:parser + + + + + diff --git a/versions/9.1.0/docs/images/graph_hello-world.svg b/versions/9.1.0/docs/images/graph_hello-world.svg new file mode 100644 index 00000000..93b61444 --- /dev/null +++ b/versions/9.1.0/docs/images/graph_hello-world.svg @@ -0,0 +1,70 @@ + + + + + + +mygraph + + +//main:hello-world + +//main:hello-world + + +//main:hello-time + +//main:hello-time + + +//main:hello-world->//main:hello-time + + + + +//main:hello-world.cc + +//main:hello-world.cc + + +//main:hello-world->//main:hello-world.cc + + + + +//lib:hello-greet + +//lib:hello-greet + + +//main:hello-world->//lib:hello-greet + + + + +//main:hello-time.cc\n//main:hello-time.h + +//main:hello-time.cc +//main:hello-time.h + + +//main:hello-time->//main:hello-time.cc\n//main:hello-time.h + + + + +//lib:hello-greet.cc\n//lib:hello-greet.h + +//lib:hello-greet.cc +//lib:hello-greet.h + + +//lib:hello-greet->//lib:hello-greet.cc\n//lib:hello-greet.h + + + + + diff --git a/versions/9.1.0/docs/images/json-trace-profile-network-usage.png b/versions/9.1.0/docs/images/json-trace-profile-network-usage.png new file mode 100644 index 00000000..8a7500a6 Binary files /dev/null and b/versions/9.1.0/docs/images/json-trace-profile-network-usage.png differ diff --git a/versions/9.1.0/docs/images/json-trace-profile-system-load-average.png b/versions/9.1.0/docs/images/json-trace-profile-system-load-average.png new file mode 100644 index 00000000..e71b420c Binary files /dev/null and b/versions/9.1.0/docs/images/json-trace-profile-system-load-average.png differ diff --git a/versions/9.1.0/docs/images/json-trace-profile-workers-memory-usage.png b/versions/9.1.0/docs/images/json-trace-profile-workers-memory-usage.png new file mode 100644 index 00000000..806505f0 Binary files /dev/null and b/versions/9.1.0/docs/images/json-trace-profile-workers-memory-usage.png differ diff --git a/versions/9.1.0/docs/images/json-trace-profile.png b/versions/9.1.0/docs/images/json-trace-profile.png new file mode 100644 index 00000000..538382b2 Binary files /dev/null and b/versions/9.1.0/docs/images/json-trace-profile.png differ diff --git a/versions/9.1.0/docs/images/mobile-install-performance.svg b/versions/9.1.0/docs/images/mobile-install-performance.svg new file mode 100644 index 00000000..b139d658 --- /dev/null +++ b/versions/9.1.0/docs/images/mobile-install-performance.svg @@ -0,0 +1,86 @@ + + + + + + + + + + + Build times + + + + + + + adb install + + + + + + + mobile-install + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Google Maps + + + Google+ + + + YouTube + + + 0 + + + 75 + + + 150 + + + 225 + + + 300 + + + + + + Seconds + + + + diff --git a/versions/9.1.0/docs/images/namedsetoffiles-bep-graph.png b/versions/9.1.0/docs/images/namedsetoffiles-bep-graph.png new file mode 100644 index 00000000..ea1e10cc Binary files /dev/null and b/versions/9.1.0/docs/images/namedsetoffiles-bep-graph.png differ diff --git a/versions/9.1.0/docs/images/out-ranked.svg b/versions/9.1.0/docs/images/out-ranked.svg new file mode 100644 index 00000000..07e96804 --- /dev/null +++ b/versions/9.1.0/docs/images/out-ranked.svg @@ -0,0 +1,71 @@ + + + + + + +mygraph + + + +//a:a + +//a:a + + + +//a:a.cc + +//a:a.cc + + + +//a:a->//a:a.cc + + + + + +//b:b + +//b:b + + + +//b:b->//a:a + + + + + +//b:b.cc + +//b:b.cc + + + +//b:b->//b:b.cc + + + + + +//c:c + +//c:c + + + +//c:c->//a:a + + + + + +//c:c->//b:b + + + + + diff --git a/versions/9.1.0/docs/images/rbe-ci-1.png b/versions/9.1.0/docs/images/rbe-ci-1.png new file mode 100644 index 00000000..fbe76a85 Binary files /dev/null and b/versions/9.1.0/docs/images/rbe-ci-1.png differ diff --git a/versions/9.1.0/docs/images/rbe-ci-2.png b/versions/9.1.0/docs/images/rbe-ci-2.png new file mode 100644 index 00000000..07611889 Binary files /dev/null and b/versions/9.1.0/docs/images/rbe-ci-2.png differ diff --git a/versions/9.1.0/docs/images/somepath1.svg b/versions/9.1.0/docs/images/somepath1.svg new file mode 100644 index 00000000..5e5f8812 --- /dev/null +++ b/versions/9.1.0/docs/images/somepath1.svg @@ -0,0 +1,141 @@ + + + + + + +somepath1 + + + +n1 + + + + +n2 + + + + +n1->n2 + + + + + +n3 + + + + +n2->n3 + + + + + +n10 + + + + +n2->n10 + + + + + +n3->n10 + + + + + +n4 + +E + + + +n5 + + + + +n6 + + + + +n5->n6 + + + + + +n6->n4 + + + + + +n9 + + + + +n6->n9 + + + + + +n7 + +S1 + + + +n7->n2 + + + + + +n7->n5 + + + + + +n8 + +S2 + + + +n8->n6 + + + + + +n10->n4 + + + + + +n11 + + + + +n10->n11 + + + + + diff --git a/versions/9.1.0/docs/images/somepath2.svg b/versions/9.1.0/docs/images/somepath2.svg new file mode 100644 index 00000000..911f2c9b --- /dev/null +++ b/versions/9.1.0/docs/images/somepath2.svg @@ -0,0 +1,141 @@ + + + + + + +somepath2 + + + +n1 + + + + +n2 + + + + +n1->n2 + + + + + +n3 + + + + +n2->n3 + + + + + +n10 + + + + +n2->n10 + + + + + +n3->n10 + + + + + +n4 + +E + + + +n5 + + + + +n6 + + + + +n5->n6 + + + + + +n6->n4 + + + + + +n9 + + + + +n6->n9 + + + + + +n7 + +S1 + + + +n7->n2 + + + + + +n7->n5 + + + + + +n8 + +S2 + + + +n8->n6 + + + + + +n10->n4 + + + + + +n11 + + + + +n10->n11 + + + + + diff --git a/versions/9.1.0/docs/images/targets.svg b/versions/9.1.0/docs/images/targets.svg new file mode 100644 index 00000000..82f47e74 --- /dev/null +++ b/versions/9.1.0/docs/images/targets.svg @@ -0,0 +1,113 @@ + + + + + + +G1 + + + +Target + +Target + + + +Rule + +Rule + + + +Target->Rule + + + + + +File + +File + + + +Target->File + + + + + +Package group + +Package group + + + +Target->Package group + + + + + +cc_library + +cc_library + + + +Rule->cc_library + + + + + +java_test + +java_test + + + +Rule->java_test + + + + + +... + +... + + + +Rule->... + + + + + +Source + +Source + + + +File->Source + + + + + +Generated + +Generated + + + +File->Generated + + + + + diff --git a/versions/9.1.0/docs/images/tutorial_java_01.svg b/versions/9.1.0/docs/images/tutorial_java_01.svg new file mode 100644 index 00000000..2fe72f36 --- /dev/null +++ b/versions/9.1.0/docs/images/tutorial_java_01.svg @@ -0,0 +1,29 @@ + + + + + + +mygraph + + +//:ProjectRunner + +//:ProjectRunner + + +//:src/main/java/com/example/Greeting.java\n//:src/main/java/com/example/ProjectRunner.java + +//:src/main/java/com/example/Greeting.java +//:src/main/java/com/example/ProjectRunner.java + + +//:ProjectRunner->//:src/main/java/com/example/Greeting.java\n//:src/main/java/com/example/ProjectRunner.java + + + + + diff --git a/versions/9.1.0/docs/images/tutorial_java_02.svg b/versions/9.1.0/docs/images/tutorial_java_02.svg new file mode 100644 index 00000000..40cbb218 --- /dev/null +++ b/versions/9.1.0/docs/images/tutorial_java_02.svg @@ -0,0 +1,48 @@ + + + + + + +mygraph + + +//:ProjectRunner + +//:ProjectRunner + + +//:greeter + +//:greeter + + +//:ProjectRunner->//:greeter + + + + +//:src/main/java/com/example/ProjectRunner.java + +//:src/main/java/com/example/ProjectRunner.java + + +//:ProjectRunner->//:src/main/java/com/example/ProjectRunner.java + + + + +//:src/main/java/com/example/Greeting.java + +//:src/main/java/com/example/Greeting.java + + +//:greeter->//:src/main/java/com/example/Greeting.java + + + + + diff --git a/versions/9.1.0/docs/images/tutorial_java_03.svg b/versions/9.1.0/docs/images/tutorial_java_03.svg new file mode 100644 index 00000000..7d79041a --- /dev/null +++ b/versions/9.1.0/docs/images/tutorial_java_03.svg @@ -0,0 +1,48 @@ + + + + + + +mygraph + + +//src/main/java/com/example/cmdline:runner + +//src/main/java/com/example/cmdline:runner + + +//src/main/java/com/example/cmdline:Runner.java + +//src/main/java/com/example/cmdline:Runner.java + + +//src/main/java/com/example/cmdline:runner->//src/main/java/com/example/cmdline:Runner.java + + + + +//:greeter + +//:greeter + + +//src/main/java/com/example/cmdline:runner->//:greeter + + + + +//:src/main/java/com/example/Greeting.java + +//:src/main/java/com/example/Greeting.java + + +//:greeter->//:src/main/java/com/example/Greeting.java + + + + + diff --git a/versions/9.1.0/docs/images/workers-clean-chart.png b/versions/9.1.0/docs/images/workers-clean-chart.png new file mode 100644 index 00000000..63526fc1 Binary files /dev/null and b/versions/9.1.0/docs/images/workers-clean-chart.png differ diff --git a/versions/9.1.0/docs/images/workers-incremental-chart.png b/versions/9.1.0/docs/images/workers-incremental-chart.png new file mode 100644 index 00000000..1c62d25c Binary files /dev/null and b/versions/9.1.0/docs/images/workers-incremental-chart.png differ diff --git a/versions/9.1.0/docs/images/ws-diamond.png b/versions/9.1.0/docs/images/ws-diamond.png new file mode 100644 index 00000000..154a7440 Binary files /dev/null and b/versions/9.1.0/docs/images/ws-diamond.png differ diff --git a/versions/9.1.0/docs/images/ws-line.png b/versions/9.1.0/docs/images/ws-line.png new file mode 100644 index 00000000..e8bfe7a1 Binary files /dev/null and b/versions/9.1.0/docs/images/ws-line.png differ diff --git a/versions/9.1.0/docs/images/ws-multiline.png b/versions/9.1.0/docs/images/ws-multiline.png new file mode 100644 index 00000000..f07b43b1 Binary files /dev/null and b/versions/9.1.0/docs/images/ws-multiline.png differ diff --git a/versions/9.1.0/docs/user-manual.mdx b/versions/9.1.0/docs/user-manual.mdx index 0b60502e..e3639541 100644 --- a/versions/9.1.0/docs/user-manual.mdx +++ b/versions/9.1.0/docs/user-manual.mdx @@ -6,13 +6,13 @@ 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](/versions/9.1.0/run/build). -## Target syntax {:#target-syntax} +## 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](/versions/9.1.0/run/build#specifying-build-targets). -## Options {:#build-options} +## Options {#build-options} The following sections describe the options available during a build. When `--long` is used on a help command, the on-line @@ -23,9 +23,9 @@ Most options can only be specified once. When specified multiple times, the last instance wins. Options that can be specified multiple times are identified in the on-line help with the text 'may be used multiple times'. -### Package location {:#package-location} +### Package location {#package-location} -#### `--package_path` {:#package-path} +#### `--package_path` {#package-path} **WARNING:** The `--package_path` option is deprecated. Bazel prefers packages in the main repository to be under the workspace root. @@ -39,9 +39,9 @@ partial source tree. _To specify a custom package path_ using the `--package_path` option: -
+```
   % bazel build --package_path %workspace%:/some/other/root
-
+``` Package path elements may be specified in three formats: @@ -71,14 +71,14 @@ on the package path. Example: Building from an empty client -
+```
   % mkdir -p foo/bazel
   % cd foo/bazel
   % touch MODULE.bazel
   % bazel build --package_path /some/other/path //foo
-
+``` -#### `--deleted_packages` {:flag--deleted_packages} +#### `--deleted_packages` {#flag--deleted_packages} This option specifies a comma-separated list of packages which Bazel should consider deleted, and not attempt to load from any directory @@ -86,17 +86,17 @@ on the package path. This can be used to simulate the deletion of packages witho actually deleting them. This option can be passed multiple times, in which case the individual lists are concatenated. -### Error checking {:#error-checking} +### Error checking {#error-checking} These options control Bazel's error-checking and/or warnings. -#### `--[no]check_visibility` {:#check-visibility} +#### `--[no]check_visibility` {#check-visibility} If this option is set to false, visibility checks are demoted to warnings. The default value of this option is true, so that by default, visibility checking is done. -#### `--output_filter={{ "" }}regex{{ "" }}` {:#output-filter} +#### `--output_filter=regex` {#output-filter} The `--output_filter` option will only show build and compilation warnings for targets that match the regular expression. If a target does not @@ -116,21 +116,19 @@ Here are some typical values for this option: `--output_filter=` - Show everything. - + Show everything. `--output_filter=DONT_MATCH_ANYTHING` - Show nothing. - + Show nothing. -### Tool flags {:#tool-flags} +### Tool flags {#tool-flags} These options control which options Bazel will pass to other tools. -#### `--copt={{ "" }}cc-option{{ "" }}` {:#copt} +#### `--copt=cc-option` {#copt} This option takes an argument which is to be passed to the compiler. The argument will be passed to the compiler whenever it is invoked @@ -139,9 +137,9 @@ assembler code. It will not be passed when linking. This option can be used multiple times. For example: -
+```
   % bazel build --copt="-g0" --copt="-fpic" //foo
-
+``` will compile the `foo` library without debug tables, generating position-independent code. @@ -159,35 +157,35 @@ Similarly, compiler options that only have an effect at link time (such as `-l`) should be specified in `--linkopt`, not in `--copt`. -#### `--host_copt={{ "" }}cc-option{{ "" }}` {:#host-copt} +#### `--host_copt=cc-option` {#host-copt} This option takes an argument which is to be passed to the compiler for source files that are compiled in the exec configuration. This is analogous to the [`--copt`](#copt) option, but applies only to the exec configuration. -#### `--host_conlyopt={{ "" }}cc-option{{ "" }}` {:#host-conlyopt} +#### `--host_conlyopt=cc-option` {#host-conlyopt} This option takes an argument which is to be passed to the compiler for C source files that are compiled in the exec configuration. This is analogous to the [`--conlyopt`](#cconlyopt) option, but applies only to the exec configuration. -#### `--host_cxxopt={{ "" }}cc-option{{ "" }}` {:#host-cxxopt} +#### `--host_cxxopt=cc-option` {#host-cxxopt} This option takes an argument which is to be passed to the compiler for C++ source files that are compiled in the exec configuration. This is analogous to the [`--cxxopt`](#cxxopt) option, but applies only to the exec configuration. -#### `--host_linkopt={{ "" }}linker-option{{ "" }}` {:#host-linkopt} +#### `--host_linkopt=linker-option` {#host-linkopt} This option takes an argument which is to be passed to the linker for source files that are compiled in the exec configuration. This is analogous to the [`--linkopt`](#linkopt) option, but applies only to the exec configuration. -#### `--conlyopt={{ "" }}cc-option{{ "" }}` {:#cconlyopt} +#### `--conlyopt=cc-option` {#cconlyopt} This option takes an argument which is to be passed to the compiler when compiling C source files. @@ -198,7 +196,7 @@ not to C++ compilation or linking. So you can pass C-specific options Note: copts parameters listed in specific cc_library or cc_binary build rules are placed on the compiler command line _after_ these options. -#### `--cxxopt={{ "" }}cc-option{{ "" }}` {:#cxxopt} +#### `--cxxopt=cc-option` {#cxxopt} This option takes an argument which is to be passed to the compiler when compiling C++ source files. @@ -209,14 +207,14 @@ not to C compilation or linking. So you can pass C++-specific options For example: -
+```
   % bazel build --cxxopt="-fpermissive" --cxxopt="-Wno-error" //foo/cruddy_code
-
+``` Note: copts parameters listed in specific cc_library or cc_binary build rules are placed on the compiler command line _after_ these options. -#### `--linkopt={{ "" }}linker-option{{ "" }}` {:#linkopt} +#### `--linkopt=linker-option` {#linkopt} This option takes an argument which is to be passed to the compiler when linking. @@ -225,15 +223,15 @@ not to compilation. So you can pass compiler options that only make sense at link time (such as `-lssp` or `-Wl,--wrap,abort`) using `--linkopt`. For example: -
+```
   % bazel build --copt="-fmudflap" --linkopt="-lmudflap" //foo/buggy_code
-
+``` Build rules can also specify link options in their attributes. This option's settings always take precedence. Also see [cc_library.linkopts](/versions/9.1.0/reference/be/c-cpp#cc_library.linkopts). -#### `--strip (always|never|sometimes)` {:#strip} +#### `--strip (always|never|sometimes)` {#strip} This option determines whether Bazel will strip debugging information from all binaries and shared libraries, by invoking the linker with the `-Wl,--strip-debug` option. @@ -242,9 +240,9 @@ all binaries and shared libraries, by invoking the linker with the `-Wl,--strip- The default value of `--strip=sometimes` means strip if the `--compilation_mode` is `fastbuild`. -
+```
   % bazel build --strip=always //foo:bar
-
+``` will compile the target while stripping debugging information from all generated binaries. @@ -266,7 +264,7 @@ pass `--stripopt=--strip-all` and explicitly build the `--stripopt`, this applies a strip action after the final binary is linked rather than including stripping in all of the build's link actions. -#### `--stripopt={{ "" }}strip-option{{ "" }}` {:#stripopt} +#### `--stripopt=strip-option` {#stripopt} This is an additional option to pass to the `strip` command when generating a [`*.stripped` binary](/versions/9.1.0/reference/be/c-cpp#cc_binary_implicit_outputs). The default @@ -275,7 +273,7 @@ is `-S -p`. This option can be used multiple times. Note: `--stripopt` does not apply to the stripping of the main binary with `[--strip](#flag--strip)=(always|sometimes)`. -#### `--fdo_instrument={{ "" }}profile-output-dir{{ "" }}` {:#fdo-instrument} +#### `--fdo_instrument=profile-output-dir` {#fdo-instrument} The `--fdo_instrument` option enables the generation of FDO (feedback directed optimization) profile output when the @@ -285,16 +283,16 @@ containing profile information for each .o file. Once the profile data tree has been generated, the profile tree should be zipped up, and provided to the -`--fdo_optimize={{ "" }}profile-zip{{ "" }}` +`--fdo_optimize=profile-zip` Bazel option to enable the FDO-optimized compilation. For the LLVM compiler the argument is also the directory under which the raw LLVM profile data file(s) is dumped. For example: -`--fdo_instrument={{ "" }}/path/to/rawprof/dir/{{ "" }}`. +`--fdo_instrument=/path/to/rawprof/dir/`. The options `--fdo_instrument` and `--fdo_optimize` cannot be used at the same time. -#### `--fdo_optimize={{ "" }}profile-zip{{ "" }}` {:#fdo-optimize} +#### `--fdo_optimize=profile-zip` {#fdo-optimize} The `--fdo_optimize` option enables the use of the per-object file profile information to perform FDO (feedback @@ -315,66 +313,66 @@ extension. The options `--fdo_instrument` and `--fdo_optimize` cannot be used at the same time. -#### `--java_language_version={{ "" }}version{{ "" }}` {:#java-language-version} +#### `--java_language_version=version` {#java-language-version} This option specifies the version of Java sources. For example: -
+```
   % bazel build --java_language_version=8 java/com/example/common/foo:all
-
+``` compiles and allows only constructs compatible with Java 8 specification. -Default value is 11. --> +Default value is 11. Possible values are: 8, 9, 10, 11, 17, and 21 and may be extended by registering custom Java toolchains using `default_java_toolchain`. -#### `--tool_java_language_version={{ "" }}version{{ "" }}` {:#tool-java-language-version} +#### `--tool_java_language_version=version` {#tool-java-language-version} The Java language version used to build tools that are executed during a build. Default value is 11. -#### `--java_runtime_version={{ "" }}version{{ "" }}` {:#java-runtime-version} +#### `--java_runtime_version=version` {#java-runtime-version} This option specifies the version of JVM to use to execute the code and run the tests. For example: -
+```
   % bazel run --java_runtime_version=remotejdk_11 java/com/example/common/foo:java_application
-
+``` downloads JDK 11 from a remote repository and run the Java application using it. Default value is `local_jdk`. -Possible values are: `local_jdk`, `local_jdk_{{ "" }}version{{ "" }}`, +Possible values are: `local_jdk`, `local_jdk_version`, `remotejdk_11`, `remotejdk_17`, and `remotejdk_21`. You can extend the values by registering custom JVM using either `local_java_repository` or `remote_java_repository` repository rules. -#### `--tool_java_runtime_version={{ "" }}version{{ "" }}` {:#tool-java-runtime-version} +#### `--tool_java_runtime_version=version` {#tool-java-runtime-version} The version of JVM used to execute tools that are needed during a build. Default value is `remotejdk_11`. -#### `--jvmopt={{ "" }}jvm-option{{ "" }}` {:#jvmopt} +#### `--jvmopt=jvm-option` {#jvmopt} This option allows option arguments to be passed to the Java VM. It can be used with one big argument, or multiple times with individual arguments. For example: -
+```
   % bazel build --jvmopt="-server -Xms256m" java/com/example/common/foo:all
-
+``` will use the server VM for launching all Java binaries and set the startup heap size for the VM to 256 MB. -#### `--javacopt={{ "" }}javac-option{{ "" }}` {:#javacopt} +#### `--javacopt=javac-option` {#javacopt} This option allows option arguments to be passed to javac. It can be used with one big argument, or multiple times with individual arguments. For example: -
+```
   % bazel build --javacopt="-g:source,lines" //myprojects:prog
-
+``` will rebuild a java_binary with the javac default debug info (instead of the bazel default). @@ -383,16 +381,16 @@ The option is passed to javac after the Bazel built-in default options for javac and before the per-rule options. The last specification of any option to javac wins. The default options for javac are: -
+```
   -source 8 -target 8 -encoding UTF-8
-
+``` Note: Changing `--javacopt` settings will force a recompilation of all affected classes. Also note that javacopts parameters listed in specific java_library or java_binary build rules will be placed on the javac command line _after_ these options. -#### `--strict_java_deps (default|strict|off|warn|error)` {:#strict-java-deps} +#### `--strict_java_deps (default|strict|off|warn|error)` {#strict-java-deps} This option controls whether javac checks for missing direct dependencies. Java targets must explicitly declare all directly used targets as @@ -408,11 +406,11 @@ of a direct dependency of the current target. target to fail to build if any missing direct dependencies are found. This is also the default behavior when the flag is unspecified. -### Build semantics {:#build-semantics} +### Build semantics {#build-semantics} These options affect the build commands and/or the output file contents. -#### `--compilation_mode (fastbuild|opt|dbg)` (-c) {:#compilation-mode} +#### `--compilation_mode (fastbuild|opt|dbg)` (-c) {#compilation-mode} The `--compilation_mode` option (often shortened to `-c`, especially `-c opt`) takes an argument of `fastbuild`, `dbg` @@ -433,7 +431,7 @@ needing to do a full rebuild _every_ time. Debugging information will not be generated in `opt` mode unless you also pass `--copt -g`. -#### `--cpu={{ "" }}cpu{{ "" }}` {:#cpu} +#### `--cpu=cpu` {#cpu} This option specifies the target CPU architecture to be used for the compilation of binaries during the build. @@ -442,7 +440,7 @@ Note: A particular combination of crosstool version, compiler version, and target CPU is allowed only if it has been specified in the currently used CROSSTOOL file. -#### `--action_env={{ "" }}VAR=VALUE{{ "" }}` {:#action-env} +#### `--action_env=VAR=VALUE` {#action-env} Specifies the set of environment variables available during the execution of all actions. Variables can be either specified by name, in which case the value will be taken from the @@ -452,17 +450,17 @@ invocation environment. This `--action_env` flag can be specified multiple times. If a value is assigned to the same variable across multiple `--action_env` flags, the latest assignment wins. -#### `--experimental_action_listener={{ "" }}label{{ "" }}` {:#experimental-action-listener} +#### `--experimental_action_listener=label` {#experimental-action-listener} Warning: Extra actions are deprecated. Use [aspects](/versions/9.1.0/extending/aspects) instead. The `experimental_action_listener` option instructs Bazel to use -details from the [`action_listener`](/versions/9.1.0/reference/be/extra-actions#action_listener) rule specified by {{ "" }}label{{ "" }} to +details from the [`action_listener`](/versions/9.1.0/reference/be/extra-actions#action_listener) rule specified by label to insert [`extra_actions`](/versions/9.1.0/reference/be/extra-actions#extra_action) into the build graph. -#### `--[no]experimental_extra_action_top_level_only` {:experimental-extra-action-top-level-only} +#### `--[no]experimental_extra_action_top_level_only` {#experimental-extra-action-top-level-only} Warning: Extra actions are deprecated. Use [aspects](/versions/9.1.0/extending/aspects) instead. @@ -471,7 +469,7 @@ If this option is set to true, extra actions specified by the [ `--experimental_action_listener`](#experimental-action-listener) command line option will only be scheduled for top level targets. -#### `--experimental_extra_action_filter={{ "" }}regex{{ "" }}` {:#experimental-extra-action-filter} +#### `--experimental_extra_action_filter=regex` {#experimental-extra-action-filter} Warning: Extra actions are deprecated. Use [aspects](/versions/9.1.0/extending/aspects) instead. @@ -491,16 +489,17 @@ regular expression. The following example will limit scheduling of `extra_actions` to only apply to actions of which the owner's label contains '/bar/': -
% bazel build --experimental_action_listener=//test:al //foo/... \
+```
+% bazel build --experimental_action_listener=//test:al //foo/... \
   --experimental_extra_action_filter=.*/bar/.*
-
+``` -#### `--host_cpu={{ "" }}cpu{{ "" }}` {:#host-cpu} +#### `--host_cpu=cpu` {#host-cpu} This option specifies the name of the CPU architecture that should be used to build host tools. -#### `--android_platforms={{ "" }}platform[,platform]*{{ "" }}` {:#android-platforms} +#### `--android_platforms=platform[,platform]*` {#android-platforms} The platforms to build the transitive `deps` of `android_binary` rules (specifically for native dependencies like C++). For @@ -517,7 +516,7 @@ with `--android_platforms`. The `.so` file's name prefixes the name of the `android_binary` rule with "lib". For example, if the name of the `android_binary` is "foo", then the file is `libfoo.so`. -#### `--per_file_copt={{ "" }}[+-]regex[,[+-]regex]...@option[,option]...{{ "" }}` {:#per-file-copt} +#### `--per_file_copt=[+-]regex[,[+-]regex]...@option[,option]...` {#per-file-copt} When present, any C++ file with a label or an execution path matching one of the inclusion regex expressions and not matching any of the exclusion expressions will be built @@ -558,7 +557,7 @@ to the C++ compiler. If an option contains a `,` it has to be quoted like so adds the `-O0` and the `-fprofile-arcs` options to the command line of the C++ compiler for all `.cc` files in `//foo/` except `file.cc`. -#### `--dynamic_mode={{ "" }}mode{{ "" }}` {:#dynamic-mode} +#### `--dynamic_mode=mode` {#dynamic-mode} Determines whether C++ binaries will be linked dynamically, interacting with the [linkstatic attribute](/versions/9.1.0/reference/be/c-cpp#cc_binary.linkstatic) on build rules. @@ -574,9 +573,9 @@ Modes: [mostly static](/versions/9.1.0/reference/be/c-cpp#cc_binary.linkstatic) mode. If `-static` is set in linkopts, targets will change to fully static. -#### `--fission (yes|no|[dbg][,opt][,fastbuild])` {:#fission} +#### `--fission (yes|no|[dbg][,opt][,fastbuild])` {#fission} -Enables [Fission](https://gcc.gnu.org/wiki/DebugFission){: .external}, +Enables [Fission](https://gcc.gnu.org/wiki/DebugFission), which writes C++ debug information to dedicated .dwo files instead of .o files, where it would otherwise go. This substantially reduces the input size to links and can reduce link times. @@ -587,13 +586,13 @@ settings. When set to `yes`, Fission is enabled universally. When set to `no`, Fission is disabled universally. Default is no. -#### `--force_ignore_dash_static` {:#force-ignore-dash-static} +#### `--force_ignore_dash_static` {#force-ignore-dash-static} If this flag is set, any `-static` options in linkopts of `cc_*` rules BUILD files are ignored. This is only intended as a workaround for C++ hardening builds. -#### `--[no]force_pic` {:#force-pic} +#### `--[no]force_pic` {#force-pic} If enabled, all C++ compilations produce position-independent code ("-fPIC"), links prefer PIC pre-built libraries over non-PIC libraries, and links produce @@ -603,38 +602,38 @@ Note: Dynamically linked binaries (for example `--dynamic_mode fully`) generate PIC code regardless of this flag's setting. So this flag is for cases where users want PIC code explicitly generated for static links. -#### `--android_resource_shrinking` {:#flag--android_resource_shrinking} +#### `--android_resource_shrinking` {#flag--android_resource_shrinking} Selects whether to perform resource shrinking for android_binary rules. Sets the default for the [shrink_resources attribute](/versions/9.1.0/reference/be/android#android_binary.shrink_resources) on android_binary rules; see the documentation for that rule for further details. Defaults to off. -#### `--custom_malloc={{ "" }}malloc-library-target{{ "" }}` {:#custom-malloc} +#### `--custom_malloc=malloc-library-target` {#custom-malloc} When specified, always use the given malloc implementation, overriding all `malloc="target"` attributes, including in those targets that use the default (by not specifying any `malloc`). -#### `--crosstool_top={{ "" }}label{{ "" }}` {:#crosstool-top} +#### `--crosstool_top=label` {#crosstool-top} This option specifies the location of the crosstool compiler suite to be used for all C++ compilation during a build. Bazel will look in that location for a CROSSTOOL file and uses that to automatically determine settings for `--compiler`. -#### `--host_crosstool_top={{ "" }}label{{ "" }}` {:#host-crosstool-top} +#### `--host_crosstool_top=label` {#host-crosstool-top} If not specified, Bazel uses the value of `--crosstool_top` to compile code in the exec configuration, such as tools run during the build. The main purpose of this flag is to enable cross-compilation. -#### `--apple_crosstool_top={{ "" }}label{{ "" }}` {:#apple-crosstool-top} +#### `--apple_crosstool_top=label` {#apple-crosstool-top} The crosstool to use for compiling C/C++ rules in the transitive `deps` of objc_*, ios__*, and apple_* rules. For those targets, this flag overwrites `--crosstool_top`. -#### `--compiler={{ "" }}version{{ "" }}` {:#compiler} +#### `--compiler=version` {#compiler} This option specifies the C/C++ compiler version (such as `gcc-4.1.0`) to be used for the compilation of binaries during the build. If you want to @@ -644,7 +643,7 @@ specifying this flag. Note: Only certain combinations of crosstool version, compiler version, and target CPU are allowed. -#### `--android_sdk={{ "" }}label{{ "" }}` {:#android-sdk} +#### `--android_sdk=label` {#android-sdk} Deprecated. This shouldn't be directly specified. @@ -655,30 +654,30 @@ rule. The Android SDK will be automatically selected if an `android_sdk_repository` rule is defined in the WORKSPACE file. -#### `--java_toolchain={{ "" }}label{{ "" }}` {:#java-toolchain} +#### `--java_toolchain=label` {#java-toolchain} No-op. Kept only for backwards compatibility. -#### `--host_java_toolchain={{ "" }}label{{ "" }}` {:#host-java-toolchain} +#### `--host_java_toolchain=label` {#host-java-toolchain} No-op. Kept only for backwards compatibility. -#### `--javabase=({{ "" }}label{{ "" }})` {:#javabase} +#### `--javabase=(label)` {#javabase} No-op. Kept only for backwards compatibility. -#### `--host_javabase={{ "" }}label{{ "" }}` {:#host-javabase} +#### `--host_javabase=label` {#host-javabase} No-op. Kept only for backwards compatibility. -### Execution strategy {:#execution-strategy} +### Execution strategy {#execution-strategy} These options affect how Bazel will execute the build. They should not have any significant effect on the output files generated by the build. Typically their main effect is on the speed of the build. -#### `--spawn_strategy={{ "" }}strategy{{ "" }}` {:#spawn-strategy} +#### `--spawn_strategy=strategy` {#spawn-strategy} This option controls where and how commands are executed. @@ -695,7 +694,7 @@ This option controls where and how commands are executed. * `remote` causes commands to be executed remotely; this is only available if a remote executor has been configured separately. -#### `--strategy {{ "" }}mnemonic{{ "" }}={{ "" }}strategy{{ "" }}` {:#strategy} +#### `--strategy mnemonic=strategy` {#strategy} This option controls where and how commands are executed, overriding the [--spawn_strategy](#spawn-strategy) (and @@ -704,7 +703,7 @@ Genrule) on a per-mnemonic basis. See [--spawn_strategy](#spawn-strategy) for the supported strategies and their effects. -#### `--strategy_regexp={{ "" }}={{ "" }}` {:#strategy-regexp} +#### `--strategy_regexp==` {#strategy-regexp} This option specifies which strategy should be used to execute commands that have descriptions matching a certain `regex_filter`. See @@ -726,11 +725,11 @@ other flags for specifying strategy. 'Compiling //foo/bar/baz' with the `local` strategy and falls back to `sandboxed` if it fails. -#### `--genrule_strategy={{ "" }}strategy{{ "" }}` {:#genrule-strategy} +#### `--genrule_strategy=strategy` {#genrule-strategy} -This is a deprecated short-hand for `--strategy=Genrule={{ "" }}strategy{{ "" }}`. +This is a deprecated short-hand for `--strategy=Genrule=strategy`. -#### `--jobs={{ "" }}n{{ "" }}` (-j) {:#jobs} +#### `--jobs=n` (-j) {#jobs} This option, which takes an integer argument, specifies a limit on the number of jobs that should be executed concurrently during the @@ -744,7 +743,7 @@ based on some (very crude) estimates of the resource consumption of each job. The behavior of the scheduler can be controlled by the `--local_resources` option. -#### `--progress_report_interval={{ "" }}n{{ "" }}` {:progress-report-interval} +#### `--progress_report_interval=n` {#progress-report-interval} Bazel periodically prints a progress report on jobs that are not finished yet (such as long running tests). This option sets the @@ -758,7 +757,7 @@ that progress is reported once every minute. When bazel is using cursor control, as specified by [`--curses`](#curses), progress is reported every second. -#### `--local_resources {{ "" }}resources or resource expression{{ "" }}` {:#local-resources} +#### `--local_resources resources or resource expression` {#local-resources} These options specify the amount of local resources (RAM in MB and number of CPU logical cores) that Bazel can take into consideration when scheduling build and test activities to run locally. They take @@ -768,7 +767,7 @@ an float, or a keyword (HOST_RAM or HOST_CPUS) optionally followed by `[-|*`floa The flags are independent; one or both may be set. By default, Bazel estimates the amount of RAM and number of CPU cores directly from the local system's configuration. -#### `--[no]build_runfile_links` {:#build-runfile-links} +#### `--[no]build_runfile_links` {#build-runfile-links} This option, which is enabled by default, specifies whether the runfiles symlinks for tests and binaries should be built in the output directory. @@ -781,7 +780,7 @@ dependencies are gathered together in one place. Within Bazel's output tree, this "runfiles" tree is typically rooted as a sibling of the corresponding binary or test. During test execution, runfiles may be accessed using paths of the form -`$TEST_SRCDIR/{{ "" }}canonical_repo_name{{ "" }}/{{ "" }}packagename{{ "" }}/{{ "" }}filename{{ "" }}`. +`$TEST_SRCDIR/canonical_repo_name/packagename/filename`. The runfiles tree ensures that tests have access to all the files upon which they have a declared dependence, and nothing more. By default, the runfiles tree is implemented by constructing a set of @@ -790,7 +789,7 @@ does the cost of this operation, and for some large builds it can contribute significantly to overall build time, particularly because each individual test (or application) requires its own runfiles tree. -#### `--[no]build_runfile_manifests` {:#build-runfile-manifests} +#### `--[no]build_runfile_manifests` {#build-runfile-manifests} This option, which is enabled by default, specifies whether runfiles manifests should be written to the output tree. @@ -799,7 +798,7 @@ Disabling it implies `--nobuild_runfile_links`. It can be disabled when executing tests remotely, as runfiles trees will be created remotely from in-memory manifests. -#### `--[no]discard_analysis_cache` {:#discard-analysis-cache} +#### `--[no]discard_analysis_cache` {#discard-analysis-cache} When this option is enabled, Bazel will discard the analysis cache right before execution starts, thus freeing up additional memory @@ -807,7 +806,7 @@ right before execution starts, thus freeing up additional memory The drawback is that further incremental builds will be slower. See also [memory-saving mode](/versions/9.1.0/configure/memory). -#### `--[no]keep_going` (-k) {:#keep-going} +#### `--[no]keep_going` (-k) {#keep-going} As in GNU Make, the execution phase of a build stops when the first error is encountered. Sometimes it is useful to try to build as @@ -824,7 +823,7 @@ unless `--keep_going` is specified, in which case the build will proceed to the execution phase, but only for the targets that were successfully analyzed. -#### `--[no]use_ijars` {:#use-ijars} +#### `--[no]use_ijars` {#use-ijars} This option changes the way `java_library` targets are compiled by Bazel. Instead of using the output of a @@ -843,7 +842,7 @@ is not visible you will get an error that the member does not exist. Changing the `--use_ijars` setting will force a recompilation of all affected classes. -#### `--[no]interface_shared_objects` {:#interface-shared-objects} +#### `--[no]interface_shared_objects` {#interface-shared-objects} This option enables _interface shared objects_, which makes binaries and other shared libraries depend on the _interface_ of a shared object, @@ -851,11 +850,11 @@ rather than its implementation. When only the implementation changes, Bazel can avoid rebuilding targets that depend on the changed shared library unnecessarily. -### Output selection {:#output-selection} +### Output selection {#output-selection} These options determine what to build or test. -#### `--[no]build` {:#build} +#### `--[no]build` {#build} This option causes the execution phase of the build to occur; it is on by default. When it is switched off, the execution phase is @@ -864,7 +863,7 @@ skipped, and only the first two phases, loading and analysis, occur. This option can be useful for validating BUILD files and detecting errors in the inputs, without actually building anything. -#### `--[no]build_tests_only` {:#build-tests-only} +#### `--[no]build_tests_only` {#build-tests-only} If specified, Bazel will build only what is necessary to run the `*_test` and `test_suite` rules that were not filtered due to their @@ -879,7 +878,7 @@ testing. This is useful because running `bazel test --build_tests_only foo/...` may not detect all build breakages in the `foo` tree. -#### `--[no]check_up_to_date` {:#check-up-to-date} +#### `--[no]check_up_to_date` {#check-up-to-date} This option causes Bazel not to perform a build, but merely check whether all specified targets are up-to-date. If so, the build @@ -891,7 +890,7 @@ checks) without incurring the cost of a build. See also [`--check_tests_up_to_date`](#check-tests-up-to-date). -#### `--[no]compile_one_dependency` {:#compile-one-dependency} +#### `--[no]compile_one_dependency` {#compile-one-dependency} Compile a single dependency of the argument files. This is useful for syntax checking source files in IDEs, for example, by rebuilding a single @@ -906,7 +905,7 @@ multiple rules with the same preference, the one that appears first in the BUILD file is chosen. An explicitly named target pattern which does not reference a source file results in an error. -#### `--save_temps` {:#save-temps} +#### `--save_temps` {#save-temps} The `--save_temps` option causes temporary outputs from the compiler to be saved. These include .s files (assembler code), .i (preprocessed C) and .ii @@ -924,10 +923,10 @@ produce the preprocessed files after the compilation fails. The `--save_temps` flag currently works only for cc_* rules. To ensure that Bazel prints the location of the additional output files, check that -your [`--show_result {{ "" }}n{{ "" }}`](#show-result) +your [`--show_result n`](#show-result) setting is high enough. -#### `--build_tag_filters={{ "" }}tag[,tag]*{{ "" }}` {:#build-tag-filters} +#### `--build_tag_filters=tag[,tag]*` {#build-tag-filters} If specified, Bazel will build only targets that have at least one required tag (if any of them are specified) and does not have any excluded tags. Build tag @@ -939,7 +938,7 @@ When running tests, Bazel ignores `--build_tag_filters` for test targets, which are built and run even if they do not match this filter. To avoid building them, filter test targets using `--test_tag_filters` or by explicitly excluding them. -#### `--test_size_filters={{ "" }}size[,size]*{{ "" }}` {:#test-size-filters} +#### `--test_size_filters=size[,size]*` {#test-size-filters} If specified, Bazel will test (or build if `--build_tests_only` is also specified) only test targets with the given size. Test size filter @@ -947,21 +946,21 @@ is specified as comma delimited list of allowed test size values (small, medium, large or enormous), optionally preceded with '-' sign used to denote excluded test sizes. For example, -
+```
   % bazel test --test_size_filters=small,medium //foo:all
-
+``` and -
+```
   % bazel test --test_size_filters=-large,-enormous //foo:all
-
+``` will test only small and medium tests inside //foo. By default, test size filtering is not applied. -#### `--test_timeout_filters={{ "" }}timeout[,timeout]*{{ "" }}` {:#test-timeout-filters} +#### `--test_timeout_filters=timeout[,timeout]*` {#test-timeout-filters} If specified, Bazel will test (or build if `--build_tests_only` is also specified) only test targets with the given timeout. Test timeout filter @@ -972,7 +971,7 @@ for example syntax. By default, test timeout filtering is not applied. -#### `--test_tag_filters={{ "" }}tag[,tag]*{{ "" }}` {:#test-tag-filters} +#### `--test_tag_filters=tag[,tag]*` {#test-tag-filters} If specified, Bazel will test (or build if `--build_tests_only` is also specified) only test targets that have at least one required tag @@ -983,9 +982,9 @@ have a preceding '+' sign. For example, -
+```
   % bazel test --test_tag_filters=performance,stress,-flaky //myproject:all
-
+``` will test targets that are tagged with either `performance` or `stress` tag but are **not** tagged with the `flaky` tag. @@ -994,7 +993,7 @@ By default, test tag filtering is not applied. Note that you can also filter on test's `size` and `local` tags in this manner. -#### `--test_lang_filters={{ "" }}string[,string]*{{ "" }}` {:#test-lang-filters} +#### `--test_lang_filters=string[,string]*` {#test-lang-filters} Specifies a comma-separated list of strings referring to names of test rule classes. To refer to the rule class `foo_test`, use the string "foo". Bazel will @@ -1002,17 +1001,17 @@ test (or build if `--build_tests_only` is also specified) only targets of the referenced rule classes. To instead exclude those targets, use the string "-foo". For example, -

-
+

+```
   % bazel test --test_lang_filters=foo,bar //baz/...
-
+```

will test only targets that are instances of `foo_test` or `bar_test` in `//baz/...`, while

-
+```
   % bazel test --test_lang_filters=-foo,-bar //baz/...
-
+```

will test all the targets in `//baz/...` except for the `foo_test` and `bar_test` instances. @@ -1028,25 +1027,25 @@ Warning: The option name "--test_lang_filter" is vestigal and is therefore unfortunately misleading; don't make assumptions about the semantics based on the name. -#### `--test_filter={{ "" }}filter-expression{{ "" }}` {:#test-filter} +#### `--test_filter=filter-expression` {#test-filter} Specifies a filter that the test runner may use to pick a subset of tests for running. All targets specified in the invocation are built, but depending on the expression only some of them may be executed; in some cases, only certain test methods are run. -The particular interpretation of {{ "" }}filter-expression{{ "" }} is up to +The particular interpretation of filter-expression is up to the test framework responsible for running the test. It may be a glob, substring, or regexp. `--test_filter` is a convenience over passing different `--test_arg` filter arguments, but not all frameworks support it. -### Verbosity {:#verbosity} +### Verbosity {#verbosity} These options control the verbosity of Bazel's output, either to the terminal, or to additional log files. -#### `--explain={{ "" }}logfile{{ "" }}` {:#explain} +#### `--explain=logfile` {#explain} This option, which requires a filename argument, causes the dependency checker in `bazel build`'s execution phase to @@ -1061,7 +1060,7 @@ when you see an execution step executed unexpectedly. This option may carry a small performance penalty, so you might want to remove it when it is no longer needed. -#### `--verbose_explanations` {:#verbose-explanations} +#### `--verbose_explanations` {#verbose-explanations} This option increases the verbosity of the explanations generated when the [--explain](#explain) option is enabled. @@ -1079,31 +1078,31 @@ generated explanation file and the performance penalty of using If `--explain` is not enabled, then `--verbose_explanations` has no effect. -#### `--profile={{ "" }}file{{ "" }}` {:#profile} +#### `--profile=file` {#profile} This option, which takes a filename argument, causes Bazel to write profiling data into a file. The data then can be analyzed or parsed using the `bazel analyze-profile` command. The Build profile can be useful in understanding where Bazel's `build` command is spending its time. -#### `--[no]show_loading_progress` {:#show-loading-progress} +#### `--[no]show_loading_progress` {#show-loading-progress} This option causes Bazel to output package-loading progress messages. If it is disabled, the messages won't be shown. -#### `--[no]show_progress` {:#show-progress} +#### `--[no]show_progress` {#show-progress} This option causes progress messages to be displayed; it is on by default. When disabled, progress messages are suppressed. -#### `--show_progress_rate_limit={{ "" }}n{{ "" }}` {:#show-progress-rate} +#### `--show_progress_rate_limit=n` {#show-progress-rate} This option causes bazel to display at most one progress message per `n` seconds, -where {{ "" }}n{{ "" }} is a real number. +where n is a real number. The default value for this option is 0.02, meaning bazel will limit the progress messages to one per every 0.02 seconds. -#### `--show_result={{ "" }}n{{ "" }}` {:#show-result} +#### `--show_result=n` {#show-result} This option controls the printing of result information at the end of a `bazel build` command. By default, if a single @@ -1137,23 +1136,23 @@ filename to the shell, to run built executables. The "up-to-date" or "failed" messages for each target can be easily parsed by scripts which drive a build. -#### `--sandbox_debug` {:#sandbox-debug} +#### `--sandbox_debug` {#sandbox-debug} This option causes Bazel to print extra debugging information when using sandboxing for action execution. This option also preserves sandbox directories, so that the files visible to actions during execution can be examined. -#### `--subcommands` (`-s`) {:#subcommands} +#### `--subcommands` (`-s`) {#subcommands} This option causes Bazel's execution phase to print the full command line for each command prior to executing it. -

-  >>>>> # //examples/cpp:hello-world [action 'Linking examples/cpp/hello-world']
+```
+  >>>>> # //examples/cpp:hello-world [action 'Linking examples/cpp/hello-world']
   (cd /home/johndoe/.cache/bazel/_bazel_johndoe/4c084335afceb392cfbe7c31afee3a9f/bazel && \
     exec env - \
     /usr/bin/gcc -o bazel-out/local-fastbuild/bin/examples/cpp/hello-world -B/usr/bin/ -Wl,-z,relro,-z,now -no-canonical-prefixes -pass-exit-codes -Wl,-S -Wl,@bazel-out/local_linux-fastbuild/bin/examples/cpp/hello-world-2.params)
-
+``` Where possible, commands are printed in a Bourne shell compatible syntax, so that they can be easily copied and pasted to a shell command prompt. @@ -1173,7 +1172,7 @@ For logging subcommands to a file in a tool-friendly format, see and [--execution_log_binary_file](/versions/9.1.0/reference/command-line-reference#flag--execution_log_binary_file). -#### `--verbose_failures` {:#verbose-failures} +#### `--verbose_failures` {#verbose-failures} This option causes Bazel's execution phase to print the full command line for commands that failed. This can be invaluable for debugging a @@ -1182,14 +1181,14 @@ failing build. Failing commands are printed in a Bourne shell compatible syntax, suitable for copying and pasting to a shell prompt. -### Workspace status {:#workspace-status} +### Workspace status {#workspace-status} Use these options to "stamp" Bazel-built binaries: to embed additional information into the binaries, such as the source control revision or other workspace-related information. You can use this mechanism with rules that support the `stamp` attribute, such as `genrule`, `cc_binary`, and more. -#### `--workspace_status_command={{ "" }}program{{ "" }}` {:#workspace-status-command} +#### `--workspace_status_command=program` {#workspace-status-command} This flag lets you specify a binary that Bazel runs before each build. The program can report information about the status of the workspace, such as the current source control revision. @@ -1251,18 +1250,18 @@ If the workspace status command fails (exits non-zero) for any reason, the build Example program on Linux using Git: -
+```
 #!/bin/bash
 echo "CURRENT_TIME $(date +%s)"
 echo "RANDOM_HASH $(cat /proc/sys/kernel/random/uuid)"
 echo "STABLE_GIT_COMMIT $(git rev-parse HEAD)"
 echo "STABLE_USER_NAME $USER"
-
+``` Pass this program's path with `--workspace_status_command`, and the stable status file will include the STABLE lines and the volatile status file will include the rest of the lines. -#### `--[no]stamp` {:#stamp} +#### `--[no]stamp` {#stamp} This option, in conjunction with the `stamp` rule attribute, controls whether to embed build information in binaries. @@ -1281,23 +1280,23 @@ their dependencies have not changed. Setting `--nostamp` is generally desireable for build performance, as it reduces input volatility and maximizes build caching. -### Platform {:#platform} +### Platform {#platform} 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](/versions/9.1.0/extending/platforms) and [Toolchains](/versions/9.1.0/extending/toolchains). -#### `--platforms={{ "" }}labels{{ "" }}` {:#platforms} +#### `--platforms=labels` {#platforms} The labels of the platform rules describing the target platforms for the current command. -#### `--host_platform={{ "" }}label{{ "" }}` {:#host-platform} +#### `--host_platform=label` {#host-platform} The label of a platform rule that describes the host system. -#### `--extra_execution_platforms={{ "" }}labels{{ "" }}` {:#extra-execution-platforms} +#### `--extra_execution_platforms=labels` {#extra-execution-platforms} The platforms that are available as execution platforms to run actions. Platforms can be specified by exact target, or as a target pattern. These @@ -1306,29 +1305,29 @@ platforms will be considered before those declared in MODULE.bazel files by This option accepts a comma-separated list of platforms in order of priority. If the flag is passed multiple times, the most recent overrides. -#### `--extra_toolchains={{ "" }}labels{{ "" }}` {:#extra-toolchains} +#### `--extra_toolchains=labels` {#extra-toolchains} The toolchain rules to be considered during toolchain resolution. Toolchains can be specified by exact target, or as a target pattern. These toolchains will be considered before those declared in MODULE.bazel files by [register_toolchains()](/versions/9.1.0/rules/lib/globals/module#register_toolchains). -#### `--toolchain_resolution_debug={{ "" }}regex{{ "" }}` {:#toolchain-resolution-debug} +#### `--toolchain_resolution_debug=regex` {#toolchain-resolution-debug} Print debug information while finding toolchains if the toolchain type matches the regex. Multiple regexes can be separated by commas. The regex can be negated by using a `-` at the beginning. This might help developers of Bazel or Starlark rules with debugging failures due to missing toolchains. -### Miscellaneous {:#miscellaneous} +### Miscellaneous {#miscellaneous} -#### `--flag_alias={{ "" }}alias_name=target_path{{ "" }}` {:#flag-alias} +#### `--flag_alias=alias_name=target_path` {#flag-alias} A convenience flag used to bind longer Starlark build settings to a shorter name. For more details, see the [Starlark Configurations](/versions/9.1.0/extending/config#using-build-setting-aliases). -#### `--symlink_prefix={{ "" }}string{{ "" }}` {:#symlink-prefix} +#### `--symlink_prefix=string` {#symlink-prefix} Changes the prefix of the generated convenience symlinks. The default value for the symlink prefix is `bazel-` which @@ -1356,7 +1355,7 @@ Some common values of this option: `--symlink_prefix=.bazel/` will cause Bazel to create symlinks called `bin` (etc) inside a hidden directory `.bazel`. -#### `--platform_suffix={{ "" }}string{{ "" }}` {:#platform-suffix} +#### `--platform_suffix=string` {#platform-suffix} Adds a suffix to the configuration short name, which is used to determine the output directory. Setting this option to different values puts the files into @@ -1364,22 +1363,22 @@ different directories, for example to improve cache hit rates for builds that otherwise clobber each others output files, or to keep the output files around for comparisons. -#### `--default_visibility={{ "" }}(private|public){{ "" }}` {:#default-visibility} +#### `--default_visibility=(private|public)` {#default-visibility} Temporary flag for testing bazel default visibility changes. Not intended for general use but documented for completeness' sake. -#### `--starlark_cpu_profile=_file_` {:#starlark-cpu-profile} +#### `--starlark_cpu_profile=_file_` {#starlark-cpu-profile} This flag, whose value is the name of a file, causes Bazel to gather statistics about CPU usage by all Starlark threads, -and write the profile, in [pprof](https://github.com/google/pprof){: .external} format, +and write the profile, in [pprof](https://github.com/google/pprof) format, to the named file. Use this option to help identify Starlark functions that make loading and analysis slow due to excessive computation. For example: -
+```
 $ bazel build --nobuild --starlark_cpu_profile=/tmp/pprof.gz my/project/...
 $ pprof /tmp/pprof.gz
 (pprof) top
@@ -1395,19 +1394,19 @@ Showing nodes accounting for 3.34s, 100% of 3.34s total
          0     0%   100%      1.38s 41.32%  my/project/main/BUILD
          0     0%   100%      1.96s 58.68%  my/project/library.bzl
          0     0%   100%      3.34s   100%  main
-
+``` For different views of the same data, try the `pprof` commands `svg`, `web`, and `list`. -## Using Bazel for releases {:#bazel-for-releases} +## Using Bazel for releases {#bazel-for-releases} Bazel is used both by software engineers during the development cycle, and by release engineers when preparing binaries for deployment to production. This section provides a list of tips for release engineers using Bazel. -### Significant options {:#significant-options} +### Significant options {#significant-options} When using Bazel for release builds, the same issues arise as for other scripts that perform a build. For more details, see @@ -1426,7 +1425,7 @@ These options are also important: with a distinct identifier, such as "64bit" vs. "32bit". This option differentiates the `bazel-bin` (etc.) symlinks. -## Running tests {:#running-tests} +## Running tests {#running-tests} To build and run tests with bazel, type `bazel test` followed by the name of the test targets. @@ -1439,9 +1438,9 @@ their prerequisites are built, meaning that test execution is interleaved with building. Doing so usually results in significant speed gains. -### Options for `bazel test` {:#bazel-test-options} +### Options for `bazel test` {#bazel-test-options} -#### `--cache_test_results=(yes|no|auto)` (`-t`) {:#cache-test-results} +#### `--cache_test_results=(yes|no|auto)` (`-t`) {#cache-test-results} If this option is set to 'auto' (the default) then Bazel will only rerun a test if any of the following conditions applies: @@ -1469,7 +1468,7 @@ their `.bazelrc` file may find the abbreviations `-t` (on) or `-t-` (off) convenient for overriding the default on a particular run. -#### `--check_tests_up_to_date` {:#check-tests-up-to-date} +#### `--check_tests_up_to_date` {#check-tests-up-to-date} This option tells Bazel not to run the tests, but to merely check and report the cached test results. If there are any tests which have not been @@ -1484,7 +1483,7 @@ This option also implies This option may be useful for pre-submit checks. -#### `--test_verbose_timeout_warnings` {:#test-verbose-timeout-warnings} +#### `--test_verbose_timeout_warnings` {#test-verbose-timeout-warnings} This option tells Bazel to explicitly warn the user if a test's timeout is significantly longer than the test's actual execution time. While a test's @@ -1501,14 +1500,14 @@ Note: Each test shard is allotted the timeout of the entire `XX_test` target. Using this option does not affect a test's timeout value, merely warns if Bazel thinks the timeout could be restricted further. -#### `--[no]test_keep_going` {:#test-keep-going} +#### `--[no]test_keep_going` {#test-keep-going} By default, all tests are run to completion. If this flag is disabled, however, the build is aborted on any non-passing test. Subsequent build steps and test invocations are not run, and in-flight invocations are canceled. Do not specify both `--notest_keep_going` and `--keep_going`. -#### `--flaky_test_attempts={{ "" }}attempts{{ "" }}` {:#flaky-test-attempts} +#### `--flaky_test_attempts=attempts` {#flaky-test-attempts} This option specifies the maximum number of times a test should be attempted if it fails for any reason. A test that initially fails but eventually @@ -1523,7 +1522,7 @@ default), only a single attempt is allowed for regular tests, and an integer value to override the maximum limit of test attempts. Bazel allows a maximum of 10 test attempts in order to prevent abuse of the system. -#### `--runs_per_test={{ "" }}[regex@]number{{ "" }}` {:#runs-per-test} +#### `--runs_per_test=[regex@]number` {#runs-per-test} This option specifies the number of times each test should be executed. All test executions are treated as separate tests (fallback functionality @@ -1544,7 +1543,7 @@ which match the regex (`--runs_per_test=^//pizza:.*@4` runs all tests under `//pizza/` 4 times). This form of `--runs_per_test` may be specified more than once. -#### `--[no]runs_per_test_detects_flakes` {:#run-per-test-detects-flakes} +#### `--[no]runs_per_test_detects_flakes` {#run-per-test-detects-flakes} If this option is specified (by default it is not), Bazel will detect flaky test shards through `--runs_per_test`. If one or more runs for a single shard @@ -1552,7 +1551,7 @@ fail and one or more runs for the same shard pass, the target will be considered flaky with the flag. If unspecified, the target will report a failing status. -#### `--test_summary={{ "" }}output_style{{ "" }}` {:#test-summary} +#### `--test_summary=output_style` {#test-summary} Specifies how the test result summary should be displayed. @@ -1565,7 +1564,7 @@ Specifies how the test result summary should be displayed. only each test. The names of test output files are omitted. * `none` does not print test summary. -#### `--test_output={{ "" }}output_style{{ "" }}` {:#test-output} +#### `--test_output=output_style` {#test-output} Specifies how test output should be displayed: @@ -1583,12 +1582,12 @@ Specifies how test output should be displayed: * `streamed` streams stdout/stderr output from each test in real-time. -#### `--java_debug` {:#java-debug} +#### `--java_debug` {#java-debug} This option causes the Java virtual machine of a java test to wait for a connection from a JDWP-compliant debugger before starting the test. This option implies `--test_output=streamed`. -#### `--[no]verbose_test_summary` {:#verbose-test-summary} +#### `--[no]verbose_test_summary` {#verbose-test-summary} By default this option is enabled, causing test times and other additional information (such as test attempts) to be printed to the test summary. If @@ -1596,7 +1595,7 @@ information (such as test attempts) to be printed to the test summary. If include only test name, test status and cached test indicator and will be formatted to stay within 80 characters when possible. -#### `--test_tmpdir={{ "" }}path{{ "" }}` {:#test-tmpdir} +#### `--test_tmpdir=path` {#test-tmpdir} Specifies temporary directory for tests executed locally. Each test will be executed in a separate subdirectory inside this directory. The directory will @@ -1606,7 +1605,7 @@ By default, bazel will place this directory under Bazel output base directory. Note: This is a directory for running tests, not storing test results (those are always stored under the `bazel-out` directory). -#### `--test_timeout={{ "" }}seconds{{ "" }}` OR `--test_timeout={{ "" }}seconds{{ "" }},{{ "" }}seconds{{ "" }},{{ "" }}seconds{{ "" }},{{ "" }}seconds{{ "" }}` {:#test-timeout} +#### `--test_timeout=seconds` OR `--test_timeout=seconds,seconds,seconds,seconds` {#test-timeout} Overrides the timeout value for all tests by using specified number of seconds as a new timeout value. If only one value is provided, then it will @@ -1628,7 +1627,7 @@ the size tag. So a test of size 'small' which declares a 'long' timeout will have the same effective timeout that a 'large' tests has with no explicit timeout. -#### `--test_arg={{ "" }}arg{{ "" }}` {:#test-arg} +#### `--test_arg=arg` {#test-arg} Passes command-line options/flags/arguments to each test process. This option can be used multiple times to pass several arguments. For example, @@ -1646,21 +1645,21 @@ target being run is a test target. (As with any other flag, if it's passed in a `bazel run` command after a `--` token, it's not processed by Bazel but forwarded verbatim to the executed target.) -#### `--test_env={{ "" }}variable{{ "" }}=_value_` OR `--test_env={{ "" }}variable{{ "" }}` {:#test-env} +#### `--test_env=variable=_value_` OR `--test_env=variable` {#test-env} Specifies additional variables that must be injected into the test -environment for each test. If {{ "" }}value{{ "" }} is not specified it will be +environment for each test. If value is not specified it will be inherited from the shell environment used to start the `bazel test` command. The environment can be accessed from within a test by using `System.getenv("var")` (Java), `getenv("var")` (C or C++), -#### `--run_under={{ "" }}command-prefix{{ "" }}` {:#test-run-under} +#### `--run_under=command-prefix` {#test-run-under} This specifies a prefix that the test runner will insert in front of the test command before running it. The -{{ "" }}command-prefix{{ "" }} is split into words using Bourne shell +command-prefix is split into words using Bourne shell tokenization rules, and then the list of words is prepended to the command that will be executed. @@ -1673,20 +1672,20 @@ Some caveats apply: * The PATH used for running tests may be different than the PATH in your environment, so you may need to use an **absolute path** for the `--run_under` - command (the first word in {{ "" }}command-prefix{{ "" }}). + command (the first word in command-prefix). * **`stdin` is not connected**, so `--run_under` can't be used for interactive commands. Examples: -
+```
         --run_under=/usr/bin/strace
         --run_under='/usr/bin/strace -c'
         --run_under=/usr/bin/valgrind
         --run_under='/usr/bin/valgrind --quiet --num-callers=20'
-
+``` -#### Test selection {:#test-selection} +#### Test selection {#test-selection} As documented under [Output selection options](#output-selection), you can filter tests by [size](#test-size-filters), @@ -1696,18 +1695,18 @@ you can filter tests by [size](#test-size-filters), [general name filter](#test-filter) can forward particular filter args to the test runner. -#### Other options for `bazel test` {:#bazel-test-other-options} +#### Other options for `bazel test` {#bazel-test-other-options} The syntax and the remaining options are exactly like [`bazel build`](/versions/9.1.0/run/build). -## Running executables {:#running-executables} +## Running executables {#running-executables} The `bazel run` command is similar to `bazel build`, except it is used to build _and run_ a single target. Here is a typical session (`//java/myapp:myapp` says hello and prints out its args): -
+```
   % bazel run java/myapp:myapp -- --arg1 --arg2
   INFO: Analyzed target //java/myapp:myapp (13 packages loaded, 27 targets configured).
   INFO: Found 1 target...
@@ -1720,7 +1719,7 @@ it is used to build _and run_ a single target. Here is a typical session
   $EXEC_ROOT/java/myapp/myapp
   --arg1
   --arg2
-
+``` Note: `--` is needed so that Bazel does not interpret `--arg1` and `--arg2` as @@ -1756,9 +1755,9 @@ The following extra environment variables are also available to the binary: These can be used, for example, to interpret file names on the command line in a user-friendly way. -### Options for `bazel run` {:#bazel-run-options} +### Options for `bazel run` {#bazel-run-options} -#### `--run_under={{ "" }}command-prefix{{ "" }}` {:#run-run-under} +#### `--run_under=command-prefix` {#run-run-under} This has the same effect as the `--run_under` option for `bazel test` ([see above](#test-run-under)), @@ -1776,7 +1775,7 @@ suppress the outputs from Bazel itself with the `--ui_event_filters` and For example: `bazel run --ui_event_filters=-info,-stdout,-stderr --noshow_progress //java/myapp:myapp` -### Executing tests {:#executing-tests} +### Executing tests {#executing-tests} `bazel run` can also execute test binaries, which has the effect of running the test in a close approximation of the environment described at @@ -1784,9 +1783,9 @@ running the test in a close approximation of the environment described at `--test_*` arguments have an effect when running a test in this manner except `--test_arg` . -## Cleaning build outputs {:#cleaning-build-outputs} +## Cleaning build outputs {#cleaning-build-outputs} -### The `clean` command {:#clean} +### The `clean` command {#clean} Bazel has a `clean` command, analogous to that of Make. It deletes the output directories for all build configurations performed @@ -1808,9 +1807,9 @@ stops the Bazel server after the clean, equivalent to the [`shutdown`](#shutdown clean up all disk and memory traces of a Bazel instance, you could specify: -
+```
   % bazel clean --expunge
-
+``` Alternatively, you can expunge in the background by using `--expunge_async`. It is safe to invoke a Bazel command @@ -1829,7 +1828,7 @@ these bugs are a high priority to be fixed. If you ever find an incorrect incremental build, file a bug report, and report bugs in the tools rather than using `clean`. -## Querying the dependency graph {:#querying-dependency-graph} +## Querying the dependency graph {#querying-dependency-graph} Bazel includes a query language for asking questions about the dependency graph used during the build. The query language is used @@ -1863,11 +1862,11 @@ but added by bazel. Example: "Show the locations of the definitions (in BUILD files) of all genrules required to build all the tests in the PEBL tree." -
+```
   bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))'
-
+``` -## Querying the action graph {:#aquery} +## Querying the action graph {#aquery} Caution: The aquery command is still experimental and its API will change. @@ -1888,9 +1887,9 @@ It supports the same set of functions that is also available to traditional For more details, see [Action Graph Query](/versions/9.1.0/query/aquery). -## Miscellaneous commands and options {:#misc-commands-options} +## Miscellaneous commands and options {#misc-commands-options} -### `help` {:#help} +### `help` {#help} The `help` command provides on-line help. By default, it shows a summary of available commands and help topics, as shown in @@ -1900,14 +1899,14 @@ topic. Most topics are Bazel commands, such as `build` or `query`, but there are some additional help topics that do not correspond to commands. -#### `--[no]long` (`-l`) {:#long} +#### `--[no]long` (`-l`) {#long} -By default, `bazel help [{{ "" }}topic{{ "" }}]` prints only a +By default, `bazel help [topic]` prints only a summary of the relevant options for a topic. If the `--long` option is specified, the type, default value and full description of each option is also printed. -### `shutdown` {:#shutdown} +### `shutdown` {#shutdown} Bazel server processes may be stopped by using the `shutdown` command. This command causes the Bazel server to exit as soon as it @@ -1927,7 +1926,7 @@ useful for scripts that initiate a lot of builds, as any memory leaks in the Bazel server could cause it to crash spuriously on occasion; performing a conditional restart preempts this condition. -### `info` {:#info} +### `info` {#info} The `info` command prints various values associated with the Bazel server instance, or with a specific build configuration. @@ -1935,12 +1934,12 @@ the Bazel server instance, or with a specific build configuration. The `info` command also permits a single (optional) argument, which is the name of one of the keys in the list below. -In this case, `bazel info {{ "" }}key{{ "" }}` will print only +In this case, `bazel info key` will print only the value for that one key. (This is especially convenient when scripting Bazel, as it avoids the need to pipe the result through `sed -ne /key:/s/key://p`: -#### Configuration-independent data {:#configuration-independent-data} +#### Configuration-independent data {#configuration-independent-data} * `release`: the release label for this Bazel instance, or "development version" if this is not a released @@ -1994,11 +1993,12 @@ through `sed -ne /key:/s/key://p`: Example: the process ID of the Bazel server. -
% bazel info server_pid
+```
+% bazel info server_pid
 1285
-
+``` -#### Configuration-specific data {:#configuration-specific-data} +#### Configuration-specific data {#configuration-specific-data} These data may be affected by the configuration options passed to `bazel info`, for @@ -2028,23 +2028,24 @@ Example: the C++ compiler for the current configuration. This is the `$(CC)` variable in the "Make" environment, so the `--show_make_env` flag is needed. -
+```
   % bazel info --show_make_env -c opt COMPILATION_MODE
   opt
-
+``` Example: the `bazel-bin` output directory for the current configuration. This is guaranteed to be correct even in cases where the `bazel-bin` symlink cannot be created for some reason (such as if you are building from a read-only directory). -
% bazel info --cpu=piii bazel-bin
+```
+% bazel info --cpu=piii bazel-bin
 /var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/piii-opt/bin
 % bazel info --cpu=k8 bazel-bin
 /var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/k8-opt/bin
-
+``` -### `version` and `--version` {:#version} +### `version` and `--version` {#version} The version command prints version details about the built Bazel binary, including the changelist at which it was built and the date. @@ -2063,7 +2064,7 @@ are: a Bazel server or unpacking the server archive. `bazel --version` can be run from anywhere - it does not require a workspace directory. -### `mobile-install` {:#mobile-install} +### `mobile-install` {#mobile-install} The `mobile-install` command installs apps to mobile devices. Currently only Android devices running ART are supported. @@ -2077,7 +2078,7 @@ transparent to the app. The following options are supported: -#### `--incremental` {:#incremental} +#### `--incremental` {#incremental} If set, Bazel tries to install the app incrementally, that is, only those parts that have changed since the last build. This cannot update resources @@ -2091,23 +2092,23 @@ when a full install is needed. If you are using a device with Marshmallow or later, consider the [`--split_apks`](#split-apks) flag. -#### `--split_apks` {:#split-apks} +#### `--split_apks` {#split-apks} Whether to use split apks to install and update the application on the device. Works only with devices with Marshmallow or later. Note that the [`--incremental`](#incremental) flag is not necessary when using `--split_apks`. -#### `--start_app` {:#start-app} +#### `--start_app` {#start-app} Starts the app in a clean state after installing. Equivalent to `--start=COLD`. -#### `--debug_app` {:#debug-app} +#### `--debug_app` {#debug-app} Waits for debugger to be attached before starting the app in a clean state after installing. Equivalent to `--start=DEBUG`. -#### `--start=_start_type_` {:#start} +#### `--start=_start_type_` {#start} How the app should be started after installing it. Supported _start_type_s are: @@ -2120,34 +2121,35 @@ How the app should be started after installing it. Supported _start_type_s are: Note: If more than one of `--start=_start_type_`, `--start_app` or `--debug_app` is set, the last value is used. -#### `--adb={{ "" }}path{{ "" }}` {:#adb} +#### `--adb=path` {#adb} Indicates the `adb` binary to be used. The default is to use the adb in the Android SDK specified by [`--android_sdk`](#android-sdk). -#### `--adb_arg={{ "" }}serial{{ "" }}` {:#adb-arg} +#### `--adb_arg=serial` {#adb-arg} Extra arguments to `adb`. These come before the subcommand in the command line and are typically used to specify which device to install to. For example, to select the Android device or emulator to use: -
% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef
-
+``` +% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef +``` invokes `adb` as -
+```
 adb -s deadbeef install ...
-
+``` -#### `--incremental_install_verbosity={{ "" }}number{{ "" }}` {:#incremental-install-verbosity} +#### `--incremental_install_verbosity=number` {#incremental-install-verbosity} The verbosity for incremental install. Set to 1 for debug logging to be printed to the console. -### `dump` {:#dump} +### `dump` {#dump} The `dump` command prints to stdout a dump of the internal state of the Bazel server. This command is intended @@ -2170,7 +2172,7 @@ Following options are supported: [pprof](https://github.com/google/pprof) compatible .gz file to the specified path. You must enable memory tracking for this to work. -#### Memory tracking {:#memory-tracking} +#### Memory tracking {#memory-tracking} Some `dump` commands require memory tracking. To turn this on, you have to pass startup flags to Bazel: @@ -2187,7 +2189,7 @@ restart. Example: -
+```
     % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.4.jar \
     --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
     build --nobuild <targets>
@@ -2202,15 +2204,15 @@ Example:
     --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
     dump --skylark_memory=$HOME/prof.gz
     % pprof -flame $HOME/prof.gz
-
+``` -### `analyze-profile` {:#analyze-profile} +### `analyze-profile` {#analyze-profile} The `analyze-profile` command analyzes a [JSON trace profile](/versions/9.1.0/advanced/performance/json-trace-profile) previously gathered during a Bazel invocation. -### `canonicalize-flags` {:#canonicalize-flags} +### `canonicalize-flags` {#canonicalize-flags} The [`canonicalize-flags`](/versions/9.1.0/reference/command-line-reference#canonicalize-flags-options) command, which takes a list of options for a Bazel command and returns a list of @@ -2227,13 +2229,13 @@ _does not_ expand flags from `--config`. As an example: -
+```
   % bazel canonicalize-flags -- --config=any_name --test_tag_filters="-lint"
   --config=any_name
   --test_tag_filters=-lint
-
+``` -### Startup options {:#startup-options} +### Startup options {#startup-options} The options described in this section affect the startup of the Java virtual machine used by Bazel server process, and they apply to all @@ -2246,7 +2248,7 @@ All of the options described in this section must be specified using the syntax. Also, these options must appear _before_ the name of the Bazel command. Use `startup --key=value` to list these in a `.bazelrc` file. -#### `--output_base={{ "" }}dir{{ "" }}` {:#output-base} +#### `--output_base=dir` {#output-base} This option requires a path argument, which must specify a writable directory. Bazel will use this location to write all its @@ -2267,10 +2269,10 @@ workspace directory by varying the output base. For example: -
+```
  OUTPUT_BASE=/var/tmp/google/_bazel_johndoe/custom_output_base
 % bazel --output_base ${OUTPUT_BASE}1 build //foo  &  bazel --output_base ${OUTPUT_BASE}2 build //bar
-
+``` In this command, the two Bazel commands run concurrently (because of the shell `&` operator), each using a different Bazel @@ -2283,13 +2285,13 @@ by an incremental build of `//bar`. Note: We recommend you do not use an NFS or similar networked file system for the root directory, as the higher access latency will cause noticeably slower builds. -#### `--output_user_root={{ "" }}dir{{ "" }}` {:#output-user-root} +#### `--output_user_root=dir` {#output-user-root} Points to the root directory where output and install bases are created. The directory must either not exist or be owned by the calling user. In the past, this was allowed to point to a directory shared among various users but it's not allowed any longer. This may be allowed once -[issue #11100](https://github.com/bazelbuild/bazel/issues/11100){: .external} is addressed. +[issue #11100](https://github.com/bazelbuild/bazel/issues/11100) is addressed. If the `--output_base` option is specified, it overrides using `--output_user_root` to calculate the output base. @@ -2305,15 +2307,15 @@ base) if there is a better location in your filesystem layout. Note: We recommend you do not use an NFS or similar networked file system for the root directory, as the higher access latency will cause noticeably slower builds. -#### `--server_javabase={{ "" }}dir{{ "" }}` {:#server-javabase} +#### `--server_javabase=dir` {#server-javabase} Specifies the Java virtual machine in which _Bazel itself_ runs. The value must be a path to the directory containing a JDK or JRE. It should not be a label. This option should appear before any Bazel command, for example: -
+```
   % bazel --server_javabase=/usr/local/buildtools/java/jdk build //foo
-
+``` This flag does _not_ affect the JVMs used by Bazel subprocesses such as applications, tests, tools, and so on. Use build options [--javabase](#javabase) or @@ -2324,14 +2326,14 @@ This flag was previously named `--host_javabase` (sometimes referred to as the build flag [--host_javabase](#host-javabase) (sometimes referred to as the 'right-hand side' `--host_javabase`). -#### `--host_jvm_args={{ "" }}string{{ "" }}` {:#host-jvm-args} +#### `--host_jvm_args=string` {#host-jvm-args} Specifies a startup option to be passed to the Java virtual machine in which _Bazel itself_ runs. This can be used to set the stack size, for example: -
+```
   % bazel --host_jvm_args="-Xss256K" build //foo
-
+``` This option can be used multiple times with individual arguments. Note that setting this flag should rarely be needed. You can also pass a space-separated list of strings, @@ -2346,7 +2348,7 @@ the `--jvm_flags` argument which all `java_binary` and `java_test` programs support. Alternatively for tests, use `bazel test --test_arg=--jvm_flags=foo ...`. -#### `--host_jvm_debug` {:#host-java-debug} +#### `--host_jvm_debug` {#host-java-debug} This option causes the Java virtual machine to wait for a connection from a JDWP-compliant debugger before @@ -2356,14 +2358,14 @@ intended for use by Bazel developers. Note: This does _not_ affect any JVMs used by subprocesses of Bazel: applications, tests, tools, etc. -#### `--autodetect_server_javabase` {:#autodetect-server-javabase} +#### `--autodetect_server_javabase` {#autodetect-server-javabase} This option causes Bazel to automatically search for an installed JDK on startup, and to fall back to the installed JRE if the embedded JRE isn't available. `--explicit_server_javabase` can be used to pick an explicit JRE to run Bazel with. -#### `--batch` {:#batch} +#### `--batch` {#batch} Batch mode causes Bazel to not use the [standard client/server mode](/versions/9.1.0/run/client-server), but instead runs a bazel @@ -2390,7 +2392,7 @@ for the purpose of build isolation, you should use the command option in-memory state is kept between builds. In order to restart the Bazel server and JVM after a build, please explicitly do so using the "shutdown" command. -#### `--max_idle_secs={{ "" }}n{{ "" }}` {:#max-idle-secs} +#### `--max_idle_secs=n` {#max-idle-secs} This option specifies how long, in seconds, the Bazel server process should wait after the last client request, before it exits. The @@ -2418,7 +2420,7 @@ there was already a server running, that server will continue to run until it has been idle for the usual time. Of course, the existing server's idle timer will be reset. -#### `--[no]shutdown_on_low_sys_mem` {:#shutdown-on-low-sys-mem} +#### `--[no]shutdown_on_low_sys_mem` {#shutdown-on-low-sys-mem} If enabled and `--max_idle_secs` is set to a positive duration, after the build server has been idle for a while, shut down the server when the system is @@ -2428,7 +2430,7 @@ In addition to running an idle check corresponding to max_idle_secs, the build s starts monitoring available system memory after the server has been idle for some time. If the available system memory becomes critically low, the server will exit. -#### `--[no]block_for_lock` {:#block-for-lock} +#### `--[no]block_for_lock` {#block-for-lock} If enabled, Bazel will wait for other Bazel commands holding the server lock to complete before progressing. If disabled, Bazel will @@ -2438,27 +2440,27 @@ proceed. Developers might use this in presubmit checks to avoid long waits caused by another Bazel command in the same client. -#### `--io_nice_level={{ "" }}n{{ "" }}` {:#io-nice-level} +#### `--io_nice_level=n` {#io-nice-level} Sets a level from 0-7 for best-effort IO scheduling. 0 is highest priority, 7 is lowest. The anticipatory scheduler may only honor up to priority 4. Negative values are ignored. -#### `--batch_cpu_scheduling` {:#batch-cpu-scheduling} +#### `--batch_cpu_scheduling` {#batch-cpu-scheduling} Use `batch` CPU scheduling for Bazel. This policy is useful for workloads that are non-interactive, but do not want to lower their nice value. See 'man 2 sched_setscheduler'. This policy may provide for better system interactivity at the expense of Bazel throughput. -### Miscellaneous options {:#misc-options} +### Miscellaneous options {#misc-options} -#### `--[no]announce_rc` {:#announce-rc} +#### `--[no]announce_rc` {#announce-rc} Controls whether Bazel announces startup options and command options read from the bazelrc files when starting up. -#### `--color (yes|no|auto)` {:#color} +#### `--color (yes|no|auto)` {#color} This option determines whether Bazel will use colors to highlight its output on the screen. @@ -2471,7 +2473,7 @@ If this option is set to `no`, color output is disabled, regardless of whether the output is going to a terminal and regardless of the setting of the TERM environment variable. -#### `--config={{ "" }}name{{ "" }}` {:#config} +#### `--config=name` {#config} Selects additional config section from [the rc files](/versions/9.1.0/run/bazelrc#bazelrc-file-locations); for the current `command`, @@ -2479,7 +2481,7 @@ it also pulls in the options from `command:name` if such a section exists. Can b specified multiple times to add flags from several config sections. Expansions can refer to other definitions (for example, expansions can be chained). -#### `--curses (yes|no|auto)` {:#curses} +#### `--curses (yes|no|auto)` {#curses} This option determines whether Bazel will use cursor controls in its screen output. This results in less scrolling data, and a more @@ -2491,7 +2493,7 @@ If this option is set to `no`, use of cursor controls is disabled. If this option is set to `auto`, use of cursor controls will be enabled under the same conditions as for `--color=auto`. -#### `--[no]show_timestamps` {:#show-timestamps} +#### `--[no]show_timestamps` {#show-timestamps} If specified, a timestamp is added to each message generated by Bazel specifying the time at which the message was displayed. diff --git a/versions/9.1.0/extending/config.mdx b/versions/9.1.0/extending/config.mdx index d9dd6927..86aa680e 100644 --- a/versions/9.1.0/extending/config.mdx +++ b/versions/9.1.0/extending/config.mdx @@ -21,9 +21,9 @@ This makes it possible to: and more, all completely from .bzl files (no Bazel release required). See the `bazelbuild/examples` repo for -[examples](https://github.com/bazelbuild/examples/tree/HEAD/configurations){: .external}. +[examples](https://github.com/bazelbuild/examples/tree/HEAD/configurations). -## User-defined build settings {:#user-defined-build-settings} +## User-defined build settings {#user-defined-build-settings} A build setting is a single piece of [configuration](/versions/9.1.0/extending/rules#configurations) @@ -41,11 +41,11 @@ register changes). They also can be set via the command line (if they're designated as `flags`, see more below), but can also be set via [user-defined transitions](#user-defined-transitions). -### Defining build settings {:#defining-build-settings} +### Defining build settings {#defining-build-settings} -[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/basic_build_setting){: .external} +[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/basic_build_setting) -#### The `build_setting` `rule()` parameter {:#rule-parameter} +#### The `build_setting` `rule()` parameter {#rule-parameter} Build settings are rules like any other rule and are differentiated using the Starlark `rule()` function's `build_setting` @@ -74,7 +74,7 @@ writer have some debug mode that you'd like to turn on inside test rules, you don't want to give users the ability to indiscriminately turn on that feature inside other non-test rules. -#### Using ctx.build_setting_value {:#ctx-build-setting-value} +#### Using ctx.build_setting_value {#ctx-build-setting-value} Like all rules, build setting rules have [implementation functions](/versions/9.1.0/extending/rules#implementation-function). The basic Starlark-type value of the build settings can be accessed via the @@ -110,7 +110,7 @@ But all other references to the value of the build setting (such as in transitio will see its basic Starlark-typed value, not this post implementation function value. -#### Defining multi-set string flags {:#multi-set-string-flags} +#### Defining multi-set string flags {#multi-set-string-flags} String settings have an additional `allow_multiple` parameter which allows the flag to be set multiple times on the command line or in bazelrcs. Their default @@ -143,7 +143,7 @@ $ bazel build //my/target --//example:roasts=blonde \ The above is parsed to `{"//example:roasts": ["blonde", "medium,dark"]}` and `ctx.build_setting_value` returns the list `["blonde", "medium,dark"]`. -#### Instantiating build settings {:#instantiating-build-settings} +#### Instantiating build settings {#instantiating-build-settings} Rules defined with the `build_setting` parameter have an implicit mandatory `build_setting_default` attribute. This attribute takes on the same type as @@ -171,12 +171,12 @@ flavor( ) ``` -### Predefined settings {:#predefined-settings} +### Predefined settings {#predefined-settings} -[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/use_skylib_build_setting){: .external} +[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/use_skylib_build_setting) The -[Skylib](https://github.com/bazelbuild/bazel-skylib){: .external} +[Skylib](https://github.com/bazelbuild/bazel-skylib) library includes a set of predefined settings you can instantiate without having to write custom Starlark. @@ -193,11 +193,11 @@ string_flag( ``` For a complete list, see -[Common build setting rules](https://github.com/bazelbuild/bazel-skylib/blob/main/rules/common_settings.bzl){: .external}. +[Common build setting rules](https://github.com/bazelbuild/bazel-skylib/blob/main/rules/common_settings.bzl). -### Using build settings {:#using-build-settings} +### Using build settings {#using-build-settings} -#### Depending on build settings {:#depending-on-build-settings} +#### Depending on build settings {#depending-on-build-settings} If a target would like to read a piece of configuration information, it can directly depend on the build setting via a regular attribute dependency. @@ -262,7 +262,7 @@ kotlin_binary = rule( ``` -#### Using build settings on the command line {:#build-settings-command-line} +#### Using build settings on the command line {#build-settings-command-line} Similar to most native flags, you can use the command line to set build settings [that are marked as flags](#rule-parameter). The build @@ -280,7 +280,7 @@ $ bazel build //my/target --//example:boolean_flag $ bazel build //my/target --no//example:boolean_flag ``` -#### Using build setting aliases {:#using-build-setting-aliases} +#### Using build setting aliases {#using-build-setting-aliases} You can set an alias for your build setting target path to make it easier to read on the command line. Aliases function similarly to native flags and also make use @@ -312,9 +312,9 @@ $ bazel build //my/target --//experimental/user/starlark_configurations/basic_bu Best Practice: While it possible to set aliases on the command line, leaving them in a `.bazelrc` reduces command line clutter. -### Label-typed build settings {:#label-typed-build-settings} +### Label-typed build settings {#label-typed-build-settings} -[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/label_typed_build_setting){: .external} +[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/label_typed_build_setting) Unlike other build settings, label-typed settings cannot be defined using the `build_setting` rule parameter. Instead, bazel has two built-in rules: @@ -366,9 +366,9 @@ label_flag( ) ``` -### Build settings and select() {:#build-settings-and-select} +### Build settings and select() {#build-settings-and-select} -[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/select_on_build_setting){: .external} +[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/select_on_build_setting) Users can configure attributes on build settings by using [`select()`](/versions/9.1.0/reference/be/functions#select). Build setting targets can be passed to the `flag_values` attribute of @@ -384,7 +384,7 @@ config_setting( ) ``` -## User-defined transitions {:#user-defined-transitions} +## User-defined transitions {#user-defined-transitions} A configuration [transition](/versions/9.1.0/rules/lib/builtins/transition#transition) @@ -393,7 +393,7 @@ build graph. Important: Transitions have [memory and performance impact](#memory-performance-considerations). -### Defining {:#defining} +### Defining {#defining} Transitions define configuration changes between rules. For example, a request like "compile my dependency for a different CPU than its parent" is handled by a @@ -424,7 +424,7 @@ hot_chocolate_transition = transition( The `transition()` function takes in an implementation function, a set of build settings to read(`inputs`), and a set of build settings to write (`outputs`). The implementation function has two parameters, `settings` and -`attr`. `settings` is a dictionary {`String`:`Object`} of all settings declared +`attr`. `settings` is a dictionary `{String:Object}` of all settings declared in the `inputs` parameter to `transition()`. `attr` is a dictionary of attributes and values of the rule to which the @@ -452,9 +452,9 @@ parameter of the transition function. This is true even if a build setting is not actually changed over the course of the transition - its original value must be explicitly passed through in the returned dictionary. -### Defining 1:2+ transitions {:#defining-1-2-transitions} +### Defining 1:2+ transitions {#defining-1-2-transitions} -[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/multi_arch_binary){: .external} +[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/multi_arch_binary) [Outgoing edge transition](#outgoing-edge-transitions) can map a single input configuration to two or more output configurations. This is useful for defining @@ -497,9 +497,9 @@ multi_arch_transition = transition( ) ``` -### Attaching transitions {:#attaching-transitions} +### Attaching transitions {#attaching-transitions} -[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/attaching_transitions_to_rules){: .external} +[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/attaching_transitions_to_rules) Transitions can be attached in two places: incoming edges and outgoing edges. Effectively this means rules can transition their own configuration (incoming @@ -511,7 +511,7 @@ If you need to do this, contact bazel-discuss@googlegroups.com for help with figuring out workarounds. -### Incoming edge transitions {:#incoming-edge-transitions} +### Incoming edge transitions {#incoming-edge-transitions} Incoming edge transitions are activated by attaching a `transition` object (created by `transition()`) to `rule()`'s `cfg` parameter: @@ -527,7 +527,7 @@ drink_rule = rule( Incoming edge transitions must be 1:1 transitions. -### Outgoing edge transitions {:#outgoing-edge-transitions} +### Outgoing edge transitions {#outgoing-edge-transitions} Outgoing edge transitions are activated by attaching a `transition` object (created by `transition()`) to an attribute's `cfg` parameter: @@ -545,9 +545,9 @@ Outgoing edge transitions can be 1:1 or 1:2+. See [Accessing attributes with transitions](#accessing-attributes-with-transitions) for how to read these keys. -### Transitions on native options {:#transitions-native-options} +### Transitions on native options {#transitions-native-options} -[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/transition_on_native_flag){: .external} +[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/transition_on_native_flag) Starlark transitions can also declare reads and writes on native build configuration options via a special prefix to the option name. @@ -564,7 +564,7 @@ cpu_transition = transition( outputs = ["//command_line_option:cpu"] ``` -#### Unsupported native options {:#unsupported-native-options} +#### Unsupported native options {#unsupported-native-options} Bazel doesn't support transitioning on `--define` with `"//command_line_option:define"`. Instead, use a custom @@ -584,7 +584,7 @@ As a workaround, you can explicitly itemize the flags that *are* part of the configuration in your transition. This requires maintaining the `--config`'s expansion in two places, which is a known UI blemish. -### Transitions on allow multiple build settings {:#transitions-multiple-build-settings} +### Transitions on allow multiple build settings {#transitions-multiple-build-settings} When setting build settings that [allow multiple values](#defining-multi-set-string-flags), the value of the @@ -617,7 +617,7 @@ coffee_transition = transition( ) ``` -### No-op transitions {:#no-op-transitions} +### No-op transitions {#no-op-transitions} If a transition returns `{}`, `[]`, or `None`, this is shorthand for keeping all settings at their original values. This can be more convenient than explicitly @@ -646,9 +646,9 @@ hot_chocolate_transition = transition( ) ``` -### Accessing attributes with transitions {:#accessing-attributes-with-transitions} +### Accessing attributes with transitions {#accessing-attributes-with-transitions} -[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/read_attr_in_transition){: .external} +[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/configurations/read_attr_in_transition) When [attaching a transition to an outgoing edge](#outgoing-edge-transitions) (regardless of whether the transition is a 1:1 or 1:2+ transition), `ctx.attr` is forced to be a list @@ -715,14 +715,14 @@ multi_arch_rule = rule( See [complete example](https://github.com/bazelbuild/examples/tree/main/configurations/multi_arch_binary) here. -## Integration with platforms and toolchains {:#integration-platforms-toolchains} +## Integration with platforms and toolchains {#integration-platforms-toolchains} 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](/versions/9.1.0/extending/platforms). -## Memory and performance considerations {:#memory-performance-considerations} +## Memory and performance considerations {#memory-performance-considerations} Adding transitions, and therefore new configurations, to your build comes at a cost: larger build graphs, less comprehensible build graphs, and slower @@ -730,7 +730,7 @@ builds. It's worth considering these costs when considering using transitions in your build rules. Below is an example of how a transition might create exponential growth of your build graph. -### Badly behaved builds: a case study {:#badly-behaved-builds} +### Badly behaved builds: a case study {#badly-behaved-builds} ![Scalability graph](/versions/9.1.0/rules/scalability-graph.png "Scalability graph") @@ -781,9 +781,9 @@ corresponding memory and performance consequences. TODO: Add strategies for measurement and mitigation of these issues. -## Further reading {:#further-reading} +## Further reading {#further-reading} For more details on modifying build configurations, see: - * [Starlark Build Configuration](https://docs.google.com/document/d/1vc8v-kXjvgZOdQdnxPTaV0rrLxtP2XwnD2tAZlYJOqw/edit?usp=sharing){: .external} - * Full [set](https://github.com/bazelbuild/examples/tree/HEAD/configurations){: .external} of end to end examples + * [Starlark Build Configuration](https://docs.google.com/document/d/1vc8v-kXjvgZOdQdnxPTaV0rrLxtP2XwnD2tAZlYJOqw/edit?usp=sharing) + * Full [set](https://github.com/bazelbuild/examples/tree/HEAD/configurations) of end to end examples diff --git a/versions/9.1.0/extending/platforms.mdx b/versions/9.1.0/extending/platforms.mdx index 0b07c52e..f6749058 100644 --- a/versions/9.1.0/extending/platforms.mdx +++ b/versions/9.1.0/extending/platforms.mdx @@ -70,18 +70,18 @@ builds target the same machine Bazel runs on. Build rules can [@platforms/cpu](https://github.com/bazelbuild/platforms/blob/main/cpu/BUILD) constraints. -## Generally useful constraints and platforms {:#useful-constraints-platforms} +## Generally useful constraints and platforms {#useful-constraints-platforms} To keep the ecosystem consistent, Bazel team maintains a repository with constraint definitions for the most popular CPU architectures and operating systems. These are all defined in -[https://github.com/bazelbuild/platforms](https://github.com/bazelbuild/platforms){: .external}. +[https://github.com/bazelbuild/platforms](https://github.com/bazelbuild/platforms). Bazel ships with the following special platform definition: `@platforms//host` (aliased as `@bazel_tools//tools:host_platform`). This auto-detects the OS and CPU properties of the machine Bazel runs on. -## Defining constraints {:#constraints} +## Defining constraints {#constraints} Constraints are modeled with the [`constraint_setting`][constraint_setting] and [`constraint_value`][constraint_value] build rules. @@ -111,7 +111,7 @@ the `x86` constraint as `//cpus:x86`. If visibility allows, you can extend an existing `constraint_setting` by defining your own value for it. -## Defining platforms {:#platforms} +## Defining platforms {#platforms} The [`platform`](/versions/9.1.0/reference/be/platforms-and-toolchains#platform) build rule defines a platform as a collection of `constraint_value`s: @@ -133,7 +133,7 @@ Platforms may only have one `constraint_value` for a given `constraint_setting`. This means, for example, a platform can't have two CPUs unless you create another `constraint_setting` type to model the second value. -## Skipping incompatible targets {:#skipping-incompatible-targets} +## Skipping incompatible targets {#skipping-incompatible-targets} When building for a specific target platform it is often desirable to skip targets that will never work on that platform. For example, your Windows device @@ -163,7 +163,7 @@ incompatible with all else. Incompatibility is transitive. Any targets that transitively depend on an incompatible target are themselves considered incompatible. -### When are targets skipped? {:#when-targets-skipped} +### When are targets skipped? {#when-targets-skipped} Targets are skipped when they are considered incompatible and included in the build as part of a target pattern expansion. For example, the following two @@ -198,7 +198,7 @@ FAILED: Build did NOT complete successfully Incompatible explicit targets are silently skipped if `--skip_incompatible_explicit_targets` is enabled. -### More expressive constraints {:#expressive-constraints} +### More expressive constraints {#expressive-constraints} For more flexibility in expressing constraints, use the `@platforms//:incompatible` @@ -233,8 +233,8 @@ The above can be interpreted as follows: deemed incompatible. To make your constraints more readable, use -[skylib](https://github.com/bazelbuild/bazel-skylib){: .external}'s -[`selects.with_or()`](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/selects_doc.md#selectswith_or){: .external}. +[skylib](https://github.com/bazelbuild/bazel-skylib)'s +[`selects.with_or()`](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/selects_doc.md#selectswith_or). You can express inverse compatibility in a similar way. The following example describes a library that is compatible with everything _except_ for ARM. @@ -250,7 +250,7 @@ cc_library( ) ``` -### Detecting incompatible targets using `bazel cquery` {:#cquery-incompatible-target-detection} +### Detecting incompatible targets using `bazel cquery` {#cquery-incompatible-target-detection} You can use the [`IncompatiblePlatformProvider`](/versions/9.1.0/rules/lib/providers/IncompatiblePlatformProvider) diff --git a/versions/9.1.0/external/images/mod_exampleBefore.svg b/versions/9.1.0/external/images/mod_exampleBefore.svg new file mode 100644 index 00000000..66f01303 --- /dev/null +++ b/versions/9.1.0/external/images/mod_exampleBefore.svg @@ -0,0 +1,175 @@ + + + + + + +mygraph + + + +<root> + +<root> (my_project@1.0) + + + +bazel_skylib@1.1.1 + +bazel_skylib@1.1.1 + + + +<root>->bazel_skylib@1.1.1 + + + + + +bazel_skylib@1.2.0 + +bazel_skylib@1.2.0 + + + +<root>->bazel_skylib@1.2.0 + + + + + +rules_java@5.0.0 + +rules_java@5.0.0 + + + +<root>->rules_java@5.0.0 + + + + + +stardoc@0.5.0 + +stardoc@0.5.0 + + + +<root>->stardoc@0.5.0 + + + + + +platforms@0.0.4 + +platforms@0.0.4 + + + +bazel_skylib@1.1.1->platforms@0.0.4 + + + + + +bazel_skylib@1.2.0->platforms@0.0.4 + + + + + +rules_java@5.0.0->platforms@0.0.4 + + + + + +rules_cc@0.0.1 + +rules_cc@0.0.1 + + + +rules_java@5.0.0->rules_cc@0.0.1 + + + + + +rules_proto@4.0.0 + +rules_proto@4.0.0 + + + +rules_java@5.0.0->rules_proto@4.0.0 + + + + + +bazel_skylib@1.0.3 + +bazel_skylib@1.0.3 + + + +stardoc@0.5.0->bazel_skylib@1.0.3 + + + + + +rules_java@4.0.0 + +rules_java@4.0.0 + + + +stardoc@0.5.0->rules_java@4.0.0 + + + + + +rules_cc@0.0.1->platforms@0.0.4 + + + + + +rules_cc@0.0.1->bazel_skylib@1.0.3 + + + + + +rules_proto@4.0.0->rules_cc@0.0.1 + + + + + +rules_proto@4.0.0->bazel_skylib@1.0.3 + + + + + +bazel_skylib@1.0.3->platforms@0.0.4 + + + + + +rules_java@4.0.0->bazel_skylib@1.0.3 + + + + + \ No newline at end of file diff --git a/versions/9.1.0/external/images/mod_exampleResolved.svg b/versions/9.1.0/external/images/mod_exampleResolved.svg new file mode 100644 index 00000000..224b694c --- /dev/null +++ b/versions/9.1.0/external/images/mod_exampleResolved.svg @@ -0,0 +1,151 @@ + + + + + + +mygraph + + + +<root> + +<root> (my_project@1.0) + + + +bazel_skylib@1.1.1 + +bazel_skylib@1.1.1 + + + +<root>->bazel_skylib@1.1.1 + + + + + +bazel_skylib@1.2.0 + +bazel_skylib@1.2.0 + + + +<root>->bazel_skylib@1.2.0 + + + + + +rules_java@5.0.0 + +rules_java@5.0.0 + + + +<root>->rules_java@5.0.0 + + + + + +stardoc@0.5.0 + +stardoc@0.5.0 + + + +<root>->stardoc@0.5.0 + + + + + +platforms@0.0.4 + +platforms@0.0.4 + + + +bazel_skylib@1.1.1->platforms@0.0.4 + + + + + +bazel_skylib@1.2.0->platforms@0.0.4 + + + + + +rules_java@5.0.0->platforms@0.0.4 + + + + + +rules_cc@0.0.1 + +rules_cc@0.0.1 + + + +rules_java@5.0.0->rules_cc@0.0.1 + + + + + +rules_proto@4.0.0 + +rules_proto@4.0.0 + + + +rules_java@5.0.0->rules_proto@4.0.0 + + + + + +stardoc@0.5.0->bazel_skylib@1.1.1 + + + + + +stardoc@0.5.0->rules_java@5.0.0 + + + + + +rules_cc@0.0.1->bazel_skylib@1.1.1 + + + + + +rules_cc@0.0.1->platforms@0.0.4 + + + + + +rules_proto@4.0.0->bazel_skylib@1.1.1 + + + + + +rules_proto@4.0.0->rules_cc@0.0.1 + + + + + \ No newline at end of file diff --git a/versions/9.1.0/external/lockfile.mdx b/versions/9.1.0/external/lockfile.mdx index c975a62a..c110ecb4 100644 --- a/versions/9.1.0/external/lockfile.mdx +++ b/versions/9.1.0/external/lockfile.mdx @@ -1,5 +1,3 @@ -keywords: product:Bazel,lockfile,Bzlmod - --- title: 'Bazel Lockfile' --- diff --git a/versions/9.1.0/external/migration_tool.mdx b/versions/9.1.0/external/migration_tool.mdx index 4203cc36..ed2250c9 100644 --- a/versions/9.1.0/external/migration_tool.mdx +++ b/versions/9.1.0/external/migration_tool.mdx @@ -1,10 +1,3 @@ -keywords: bzlmod - -{# disableFinding(LINE_OVER_80_LINK) #} -{# disableFinding(SNIPPET_NO_LANG) #} -{# disableFinding(LINK_MISSING_ID) #} -{# disableFinding("repo") #} - --- title: 'Bzlmod Migration Tool' --- @@ -19,7 +12,7 @@ management system. **Note**: If you want to try out the AI driven Bzlmod migration, check [Bzlmod Migration Agent Setup][gemini_cli_setup]. -## Core Functionality {:#migration-tool-core-functionality} +## Core Functionality {#migration-tool-core-functionality} The script's primary functions are: @@ -57,7 +50,7 @@ The migration tool supports: recommendations for correctness. * Use the migration tool with Bazel 7 (not supported with Bazel 8). -## How to Use the Migration Tool {:#migration-tool-how-to-use} +## How to Use the Migration Tool {#migration-tool-how-to-use} Before you begin: @@ -70,7 +63,7 @@ Before you begin: bazel build --nobuild --enable_workspace --noenable_bzlmod ``` -### Command for running the script {:#migration-script-command} +### Command for running the script {#migration-script-command} Once the prerequisites are met, run the following commands to use the migration tool: @@ -91,7 +84,7 @@ cd <your project root> migrate2bzlmod -t <targets> -### Files generated by this script {:#migration-script-files} +### Files generated by this script {#migration-script-files} * `MODULE.bazel` - The central manifest file for Bzlmod, which declares the project's metadata and its direct dependencies on other Bazel modules. @@ -110,7 +103,7 @@ migrate2bzlmod -t <targets> are not standard Bazel modules but can be managed using Bzlmod's [module extensions](/versions/9.1.0/external/extension). -### Flags {:#migration-script-flags} +### Flags {#migration-script-flags} Flags available in this migration scripts are: @@ -121,13 +114,13 @@ Flags available in this migration scripts are: dependencies, introduce them in MODULE.bazel and rerun generation of resolved dependencies. -### Post-migration cleanup {:#post-migration-cleanup} +### Post-migration cleanup {#post-migration-cleanup} * Delete `migration_info.md`, `resolved_deps.py` and `query_direct_deps`. * Clean up comments from `MODULE.bazel` file which were used for the migration, such as `# -- bazel_dep definitions -- #`. -## Migration Example {:#migration-tool-example} +## Migration Example {#migration-tool-example} To see the migration script in action, consider the following scenario when Python, Maven and Go dependencies are declared in `WORKSPACE` file. @@ -348,7 +341,7 @@ which gives the following important information: * `migration_info.md` file contains details about the migration. Check details [at this section](#migration-tool-report-generation). -### Transformations {:#migration-tool-transformations} +### Transformations {#migration-tool-transformations} This section illustrates the migration of code from the `WORKSPACE` file to `MODULE.bazel`. @@ -373,7 +366,7 @@ bazel_dep(name = "rules_shell", version = "0.6.1") -
+
@@ -434,7 +427,7 @@ go_deps.gazelle_override(
-
+
@@ -484,7 +477,7 @@ python.toolchain(python_version = "3.11")
-
+
@@ -536,7 +529,7 @@ maven.artifact(
-
+
@@ -567,7 +560,7 @@ http_archive(
-
+
@@ -600,14 +593,14 @@ extension_for_my_custom_macro = module_extension(implementation = _extension_for
-
+
-## Tips with debugging {:#migration-tool-tips} +## Tips with debugging {#migration-tool-tips} This section provides useful commands and information to help debug issues that may arise during the Bzlmod migration. -### Useful tips {:#debugging-useful-tips} +### Useful tips {#debugging-useful-tips} * Override version - Not rarely it happens that upgrading the version of a dependency causes troubles. Bzlmod could change the version of the @@ -636,7 +629,7 @@ may arise during the Bzlmod migration. `bazel vendor --enable_bzlmod --vendor_dir=vendor_src --repo=@protobuf` -### Migration Report Generation {:#migration-tool-report-generation} +### Migration Report Generation {#migration-tool-report-generation} This file is updated with each run of the migration script or it's generated from scratch if it's the first run or if the [`--i` @@ -711,7 +704,7 @@ flag](#migration-script-flags) is used. The report contains: to the `MODULE.bazel` file. * `gazelle_override` is used for adding specific directives. -## Useful links {:#useful-links} +## Useful links {#useful-links} * Official pages for the external extensions * [rules_jvm_external](https://github.com/bazelbuild/rules_jvm_external/blob/master/docs/bzlmod.md) @@ -722,7 +715,7 @@ flag](#migration-script-flags) is used. The report contains: * [Moving to Bzlmod](https://www.youtube.com/watch?v=W9uXRYLVHUk). * [How Uber Manages Go Dependencies with Bzlmod](https://www.youtube.com/watch?v=hIqzkUE_pSY). -## Feedback {:#feedback} +## Feedback {#feedback} If you would like to contribute, do so by creating an Issue or PR at [bazel-central-registry](https://github.com/bazelbuild/bazel-central-registry). diff --git a/versions/9.1.0/external/mod-command.mdx b/versions/9.1.0/external/mod-command.mdx index 7af0dacc..244507e2 100644 --- a/versions/9.1.0/external/mod-command.mdx +++ b/versions/9.1.0/external/mod-command.mdx @@ -1,5 +1,3 @@ -keywords: Bzlmod - --- title: '`mod` Command' --- @@ -10,7 +8,7 @@ why a certain module or a version of a module is present in the graph, view the repo definitions backing modules, inspect usages of module extensions and repos they generate, among other functions. -## Syntax {:#syntax} +## Syntax {#syntax} ```sh bazel mod [] [ [...]] @@ -140,7 +138,7 @@ The following options only affect the subcommands that print graphs (`graph`, legacy platforms which cannot use Unicode. * `--output `: Include information about the module extension usages as - part of the output graph. `' can be one of: + part of the output graph. `` can be one of: * `text` *(default)*: A human-readable representation of the output graph (flattened as a tree). @@ -183,7 +181,7 @@ Other options include: * `--extension_usages [,[,...]]`: Filters `show_extension` to only display extension usages from the specified modules. -## Examples {:#examples} +## Examples {#examples} Some possible usages of the `mod` command on a real Bazel project are showcased below to give you a general idea on how you can use it to inspect your project's @@ -212,10 +210,10 @@ use_repo(toolchains, my_jdk="remotejdk17_linux")
- Graph Before Resolution + Graph Before Resolution
Graph Before Resolution
- +} */}
- Graph After Resolution + Graph After Resolution
Graph After Resolution
- +} */} diff --git a/versions/9.1.0/external/registry.mdx b/versions/9.1.0/external/registry.mdx index ae16a32c..2b62adbe 100644 --- a/versions/9.1.0/external/registry.mdx +++ b/versions/9.1.0/external/registry.mdx @@ -39,7 +39,7 @@ An index registry must have the following format: * `overlay/`: An optional directory containing overlay files, only used when `source.json` has "archive" type -### `bazel_registry.json` {:#bazel-registry-json} +### `bazel_registry.json` {#bazel-registry-json} `bazel_registry.json` is an optional file that specifies metadata applying to the entire registry. It can contain the following fields: @@ -57,7 +57,7 @@ the entire registry. It can contain the following fields: * `module_base_path`: a string, specifying the base path for modules with `local_path` type in the `source.json` file -### `metadata.json` {:#metadata-json} +### `metadata.json` {#metadata-json} `metadata.json` is an optional JSON file containing information about the module, with the following fields: @@ -73,7 +73,7 @@ module, with the following fields: Note that the BCR requires more information in the `metadata.json` file. -### `source.json` {:#source-json} +### `source.json` {#source-json} `source.json` is a required JSON file containing information about how to fetch a specific version of a module. The schema of this file depends on its `type` @@ -132,16 +132,15 @@ field, which defaults to `archive`. `--registry=file://`. Otherwise, Bazel will throw an error -## Bazel Central Registry {:#bazel-central-registry} +## Bazel Central Registry {#bazel-central-registry} -The Bazel Central Registry (BCR) at is an index +The Bazel Central Registry (BCR) at https://bcr.bazel.build/ is an index registry with contents backed by the GitHub repo [`bazelbuild/bazel-central-registry`][bcr-repo]. You can browse its contents -using the web frontend at . +using the web frontend at https://registry.bazel.build/. The Bazel community maintains the BCR, and contributors are welcome to submit -pull requests. See the [BCR contribution -guidelines][bcr-contribution-guidelines]. +pull requests. See the [BCR contribution guidelines][bcr-contribution-guidelines]. In addition to following the format of a normal index registry, the BCR requires a `presubmit.yml` file for each module version diff --git a/versions/9.1.0/images/about.svg b/versions/9.1.0/images/about.svg new file mode 100644 index 00000000..f927298f --- /dev/null +++ b/versions/9.1.0/images/about.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/images/basics.svg b/versions/9.1.0/images/basics.svg new file mode 100644 index 00000000..013ec519 --- /dev/null +++ b/versions/9.1.0/images/basics.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/images/bazel_hero.svg b/versions/9.1.0/images/bazel_hero.svg new file mode 100644 index 00000000..c48714d0 --- /dev/null +++ b/versions/9.1.0/images/bazel_hero.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/images/community.svg b/versions/9.1.0/images/community.svg new file mode 100644 index 00000000..29f87a76 --- /dev/null +++ b/versions/9.1.0/images/community.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/images/distributed-build-remote-cache.png b/versions/9.1.0/images/distributed-build-remote-cache.png new file mode 100644 index 00000000..99d8a915 Binary files /dev/null and b/versions/9.1.0/images/distributed-build-remote-cache.png differ diff --git a/versions/9.1.0/images/essential_guide.svg b/versions/9.1.0/images/essential_guide.svg new file mode 100644 index 00000000..4ee63ae9 --- /dev/null +++ b/versions/9.1.0/images/essential_guide.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/images/essential_reference.svg b/versions/9.1.0/images/essential_reference.svg new file mode 100644 index 00000000..4d29a8d5 --- /dev/null +++ b/versions/9.1.0/images/essential_reference.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/images/essential_start.svg b/versions/9.1.0/images/essential_start.svg new file mode 100644 index 00000000..c8f48f84 --- /dev/null +++ b/versions/9.1.0/images/essential_start.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/images/extend.svg b/versions/9.1.0/images/extend.svg new file mode 100644 index 00000000..77b2dd97 --- /dev/null +++ b/versions/9.1.0/images/extend.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/images/guide.svg b/versions/9.1.0/images/guide.svg new file mode 100644 index 00000000..23a5d35a --- /dev/null +++ b/versions/9.1.0/images/guide.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/images/high-level-build-system.png b/versions/9.1.0/images/high-level-build-system.png new file mode 100644 index 00000000..462717fa Binary files /dev/null and b/versions/9.1.0/images/high-level-build-system.png differ diff --git a/versions/9.1.0/images/new_1.svg b/versions/9.1.0/images/new_1.svg new file mode 100644 index 00000000..c4cd9dfd --- /dev/null +++ b/versions/9.1.0/images/new_1.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/images/new_2.svg b/versions/9.1.0/images/new_2.svg new file mode 100644 index 00000000..c6b7021b --- /dev/null +++ b/versions/9.1.0/images/new_2.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/images/new_3.svg b/versions/9.1.0/images/new_3.svg new file mode 100644 index 00000000..c2afb4ac --- /dev/null +++ b/versions/9.1.0/images/new_3.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/images/placeholder.png b/versions/9.1.0/images/placeholder.png new file mode 100644 index 00000000..54f1fa0e Binary files /dev/null and b/versions/9.1.0/images/placeholder.png differ diff --git a/versions/9.1.0/images/reference.svg b/versions/9.1.0/images/reference.svg new file mode 100644 index 00000000..7bbc9bea --- /dev/null +++ b/versions/9.1.0/images/reference.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/images/release_notes.svg b/versions/9.1.0/images/release_notes.svg new file mode 100644 index 00000000..8a2e8b56 --- /dev/null +++ b/versions/9.1.0/images/release_notes.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/images/remote-execution-system.png b/versions/9.1.0/images/remote-execution-system.png new file mode 100644 index 00000000..8152fc0c Binary files /dev/null and b/versions/9.1.0/images/remote-execution-system.png differ diff --git a/versions/9.1.0/images/start.svg b/versions/9.1.0/images/start.svg new file mode 100644 index 00000000..3bcebd7b --- /dev/null +++ b/versions/9.1.0/images/start.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/images/task-dependencies.png b/versions/9.1.0/images/task-dependencies.png new file mode 100644 index 00000000..ae1f9c51 Binary files /dev/null and b/versions/9.1.0/images/task-dependencies.png differ diff --git a/versions/9.1.0/images/test.png b/versions/9.1.0/images/test.png new file mode 100644 index 00000000..243939da Binary files /dev/null and b/versions/9.1.0/images/test.png differ diff --git a/versions/9.1.0/images/transitive-dependencies.png b/versions/9.1.0/images/transitive-dependencies.png new file mode 100644 index 00000000..ec641a08 Binary files /dev/null and b/versions/9.1.0/images/transitive-dependencies.png differ diff --git a/versions/9.1.0/images/trunk-logo-dark.svg b/versions/9.1.0/images/trunk-logo-dark.svg new file mode 100644 index 00000000..f25940af --- /dev/null +++ b/versions/9.1.0/images/trunk-logo-dark.svg @@ -0,0 +1,22 @@ + + + + + + + + + + + + + + + + + + + + + + diff --git a/versions/9.1.0/images/why_faq.svg b/versions/9.1.0/images/why_faq.svg new file mode 100644 index 00000000..afec3f8f --- /dev/null +++ b/versions/9.1.0/images/why_faq.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/images/why_overview.svg b/versions/9.1.0/images/why_overview.svg new file mode 100644 index 00000000..c10c363c --- /dev/null +++ b/versions/9.1.0/images/why_overview.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/images/why_vision.svg b/versions/9.1.0/images/why_vision.svg new file mode 100644 index 00000000..739e415f --- /dev/null +++ b/versions/9.1.0/images/why_vision.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/install/images/bazelisk.svg b/versions/9.1.0/install/images/bazelisk.svg new file mode 100644 index 00000000..c0ae9f54 --- /dev/null +++ b/versions/9.1.0/install/images/bazelisk.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/install/images/cli.svg b/versions/9.1.0/install/images/cli.svg new file mode 100644 index 00000000..01119280 --- /dev/null +++ b/versions/9.1.0/install/images/cli.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/install/images/docker.svg b/versions/9.1.0/install/images/docker.svg new file mode 100644 index 00000000..21190ce0 --- /dev/null +++ b/versions/9.1.0/install/images/docker.svg @@ -0,0 +1,6 @@ + \ No newline at end of file diff --git a/versions/9.1.0/install/images/github.svg b/versions/9.1.0/install/images/github.svg new file mode 100644 index 00000000..aa05db9c --- /dev/null +++ b/versions/9.1.0/install/images/github.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/install/images/install.svg b/versions/9.1.0/install/images/install.svg new file mode 100644 index 00000000..ae080865 --- /dev/null +++ b/versions/9.1.0/install/images/install.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/install/images/mac.svg b/versions/9.1.0/install/images/mac.svg new file mode 100644 index 00000000..3ee4fe28 --- /dev/null +++ b/versions/9.1.0/install/images/mac.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/install/images/redhat.svg b/versions/9.1.0/install/images/redhat.svg new file mode 100644 index 00000000..078b3387 --- /dev/null +++ b/versions/9.1.0/install/images/redhat.svg @@ -0,0 +1,69 @@ + + + + + + image/svg+xml + + + + + + + + + + + + diff --git a/versions/9.1.0/install/images/suse.png b/versions/9.1.0/install/images/suse.png new file mode 100644 index 00000000..6435b689 Binary files /dev/null and b/versions/9.1.0/install/images/suse.png differ diff --git a/versions/9.1.0/install/images/tune.svg b/versions/9.1.0/install/images/tune.svg new file mode 100644 index 00000000..8d7d63cb --- /dev/null +++ b/versions/9.1.0/install/images/tune.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/versions/9.1.0/install/images/ubuntu.svg b/versions/9.1.0/install/images/ubuntu.svg new file mode 100644 index 00000000..f217bc8d --- /dev/null +++ b/versions/9.1.0/install/images/ubuntu.svg @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/versions/9.1.0/install/images/windows.svg b/versions/9.1.0/install/images/windows.svg new file mode 100644 index 00000000..120b0190 --- /dev/null +++ b/versions/9.1.0/install/images/windows.svg @@ -0,0 +1,5 @@ + + + + + \ No newline at end of file diff --git a/versions/9.1.0/migrate/maven.mdx b/versions/9.1.0/migrate/maven.mdx index cec426c9..fddfee23 100644 --- a/versions/9.1.0/migrate/maven.mdx +++ b/versions/9.1.0/migrate/maven.mdx @@ -12,18 +12,18 @@ system, and any other relevant systems. You can run Maven and Bazel in the same repository. Note: While Bazel supports downloading and publishing Maven artifacts with -[rules_jvm_external](https://github.com/bazelbuild/rules_jvm_external){: .external} +[rules_jvm_external](https://github.com/bazelbuild/rules_jvm_external) , it does not directly support Maven-based plugins. Maven plugins can't be directly run by Bazel since there's no Maven compatibility layer. -## Before you begin {:#before-you-begin} +## Before you begin {#before-you-begin} * [Install Bazel](/versions/9.1.0/install) if it's not yet installed. * If you're new to Bazel, go through the tutorial [Introduction to Bazel: Build Java](/versions/9.1.0/start/java) before you start migrating. The tutorial explains Bazel's concepts, structure, and label syntax. -## Differences between Maven and Bazel {:#dif-maven-bazel} +## Differences between Maven and Bazel {#dif-maven-bazel} * Maven uses top-level `pom.xml` file(s). Bazel supports multiple build files and multiple targets per `BUILD` file, allowing for builds that are more @@ -35,7 +35,7 @@ directly run by Bazel since there's no Maven compatibility layer. `BUILD` files. Best practice is to add a `BUILD` file to each new Java package. -## Migrate from Maven to Bazel {:#migrate-maven-bazel} +## Migrate from Maven to Bazel {#migrate-maven-bazel} The steps below describe how to migrate your project to Bazel: @@ -45,7 +45,7 @@ The steps below describe how to migrate your project to Bazel: 4. [Build using Bazel](#4-build) Examples below come from a migration of the [Guava -project](https://github.com/google/guava){: .external} from Maven to Bazel. The +project](https://github.com/google/guava) from Maven to Bazel. The Guava project used is release `v31.1`. The examples using Guava do not walk through each step in the migration, but they do show the files and contents that are generated or added manually for the migration. @@ -55,7 +55,7 @@ $ git clone https://github.com/google/guava.git && cd guava $ git checkout v31.1 ``` -### 1. Create the MODULE.bazel file {:#1-build} +### 1. Create the MODULE.bazel file {#1-build} Create a file named `MODULE.bazel` at the root of your project. If your project has no external dependencies, this file can be empty. @@ -64,14 +64,14 @@ If your project depends on files or packages that are not in one of the project's directories, specify these external dependencies in the MODULE.bazel file. You can use `rules_jvm_external` to manage dependencies from Maven. For instructions about using this ruleset, see [the -README](https://github.com/bazelbuild/rules_jvm_external/#rules_jvm_external){: .external} +README](https://github.com/bazelbuild/rules_jvm_external/#rules_jvm_external) . -#### Guava project example: external dependencies {:#guava-1} +#### Guava project example: external dependencies {#guava-1} You can list the external dependencies of the [Guava -project](https://github.com/google/guava){: .external} with the -[`rules_jvm_external`](https://github.com/bazelbuild/rules_jvm_external){: .external} +project](https://github.com/google/guava) with the +[`rules_jvm_external`](https://github.com/bazelbuild/rules_jvm_external) ruleset. Add the following snippet to the `MODULE.bazel` file: @@ -94,7 +94,7 @@ maven.install( use_repo(maven, "maven") ``` -### 2. Create one BUILD file {:#2-build} +### 2. Create one BUILD file {#2-build} Now that you have your workspace defined and external dependencies (if applicable) listed, you need to create `BUILD` files to describe how your @@ -174,7 +174,7 @@ your build by adding more `BUILD` files with more granular targets. The project has now been successfully built with Bazel. You will need to add more `BUILD` files to allow incremental builds of the project. -#### Guava project example: start with one BUILD file {:#guava-2} +#### Guava project example: start with one BUILD file {#guava-2} When migrating the Guava project to Bazel, initially one `BUILD` file is used to build the entire project. Here are the contents of this initial `BUILD` file in @@ -198,7 +198,7 @@ java_library( ) ``` -### 3. Create more BUILD files (optional) {:#3-build} +### 3. Create more BUILD files (optional) {#3-build} Bazel does work with just one `BUILD file`, as you saw after completing your first build. You should still consider breaking the build into smaller chunks by @@ -230,7 +230,7 @@ Tips for adding more `BUILD` files: that the project continues to build with Bazel as you add each build file. Run `bazel build //...` to ensure all of your targets still build. -### 4. Build using Bazel {:#4-build} +### 4. Build using Bazel {#4-build} You've been building using Bazel as you add `BUILD` files to validate the setup of the build. diff --git a/versions/9.1.0/migrate/xcode.mdx b/versions/9.1.0/migrate/xcode.mdx index 4538fe87..d9c2a1b8 100644 --- a/versions/9.1.0/migrate/xcode.mdx +++ b/versions/9.1.0/migrate/xcode.mdx @@ -7,7 +7,7 @@ describes the differences between Xcode and Bazel, and provides the steps for converting an Xcode project to a Bazel project. It also provides troubleshooting solutions to address common errors. -## Differences between Xcode and Bazel {:#dif-xcode-bazel} +## Differences between Xcode and Bazel {#dif-xcode-bazel} * Bazel requires you to explicitly specify every build target and its dependencies, plus the corresponding build settings via build rules. @@ -19,14 +19,14 @@ solutions to address common errors. * When building Xcode projects with Bazel, the `BUILD` file(s) become the source of truth. If you work on the project in Xcode, you must generate a new version of the Xcode project that matches the `BUILD` files using - [rules_xcodeproj](https://github.com/buildbuddy-io/rules_xcodeproj/){: .external} + [rules_xcodeproj](https://github.com/buildbuddy-io/rules_xcodeproj/) whenever you update the `BUILD` files. Certain changes to the `BUILD` files such as adding dependencies to a target don't require regenerating the project which can speed up development. If you're not using Xcode, the `bazel build` and `bazel test` commands provide build and test capabilities with certain limitations described later in this guide. -## Before you begin {:#before-you-begin} +## Before you begin {#before-you-begin} Before you begin, do the following: @@ -39,7 +39,7 @@ Before you begin, do the following: 3. Analyze and understand the project's dependencies. -### Analyze project dependencies {:#analyze-project-dependencies} +### Analyze project dependencies {#analyze-project-dependencies} Unlike Xcode, Bazel requires you to explicitly declare all dependencies for every target in the `BUILD` file. @@ -47,7 +47,7 @@ every target in the `BUILD` file. For more information on external dependencies, see [Working with external dependencies](/versions/9.1.0/docs/external). -## Build or test an Xcode project with Bazel {:#build-xcode-project} +## Build or test an Xcode project with Bazel {#build-xcode-project} To build or test an Xcode project with Bazel, do the following: @@ -69,7 +69,7 @@ To build or test an Xcode project with Bazel, do the following: 6. [Generate the Xcode project with rules_xcodeproj](#generate-the-xcode-project-with-rules_xcodeproj) -### Step 1: Create the `MODULE.bazel` file {:#create-workspace} +### Step 1: Create the `MODULE.bazel` file {#create-workspace} Create a `MODULE.bazel` file in a new directory. This directory becomes the Bazel workspace root. If the project uses no external dependencies, this file @@ -80,19 +80,19 @@ the project's directories, specify these external dependencies in the Note: Place the project source code within the directory tree containing the `MODULE.bazel` file. -### Step 2: (Experimental) Integrate SwiftPM dependencies {:#integrate-swiftpm} +### Step 2: (Experimental) Integrate SwiftPM dependencies {#integrate-swiftpm} To integrate SwiftPM dependencies into the Bazel workspace with -[swift_bazel](https://github.com/cgrindel/swift_bazel){: .external}, you must +[swift_bazel](https://github.com/cgrindel/swift_bazel), you must convert them into Bazel packages as described in the [following -tutorial](https://chuckgrindel.com/swift-packages-in-bazel-using-swift_bazel/){: .external} +tutorial](https://chuckgrindel.com/swift-packages-in-bazel-using-swift_bazel/) . Note: SwiftPM support is a manual process with many variables. SwiftPM integration with Bazel has not been fully verified and is not officially supported. -### Step 3: Create a `BUILD` file {:#create-build-file} +### Step 3: Create a `BUILD` file {#create-build-file} Once you have defined the workspace and external dependencies, you need to create a `BUILD` file that tells Bazel how the project is structured. Create the @@ -106,12 +106,12 @@ initial build of the project as follows: **Tip:** To learn more about packages and other Bazel concepts, see [Workspaces, packages, and targets](/versions/9.1.0/concepts/build-ref). -#### Step 3a: Add the application target {:#add-app-target} +#### Step 3a: Add the application target {#add-app-target} Add a -[`macos_application`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-macos.md#macos_application){: .external} +[`macos_application`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-macos.md#macos_application) or an -[`ios_application`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-ios.md#ios_application){: .external} +[`ios_application`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-ios.md#ios_application) rule target. This target builds a macOS or iOS application bundle, respectively. In the target, specify the following at the minimum: @@ -130,26 +130,26 @@ In the target, specify the following at the minimum: application supports. This ensures Bazel builds the application with the correct API levels. -#### Step 3b: (Optional) Add the test target(s) {:#add-test-target} +#### Step 3b: (Optional) Add the test target(s) {#add-test-target} Bazel's [Apple build -rules](https://github.com/bazelbuild/rules_apple){: .external} support running +rules](https://github.com/bazelbuild/rules_apple) support running unit and UI tests on all Apple platforms. Add test targets as follows: -* [`macos_unit_test`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-macos.md#macos_unit_test){: .external} +* [`macos_unit_test`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-macos.md#macos_unit_test) to run library-based and application-based unit tests on a macOS. -* [`ios_unit_test`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-ios.md#ios_unit_test){: .external} +* [`ios_unit_test`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-ios.md#ios_unit_test) to build and run library-based unit tests on iOS. -* [`ios_ui_test`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-ios.md#ios_ui_test){: .external} +* [`ios_ui_test`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-ios.md#ios_ui_test) to build and run user interface tests in the iOS simulator. * Similar test rules exist for - [tvOS](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-tvos.md){: .external}, - [watchOS](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-watchos.md){: .external} + [tvOS](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-tvos.md), + [watchOS](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-watchos.md) and - [visionOS](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-visionos.md){: .external}. + [visionOS](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-visionos.md). At the minimum, specify a value for the `minimum_os_version` attribute. While other packaging attributes, such as `bundle_identifier` and `infoplists`, @@ -158,11 +158,11 @@ with the project and adjust them as necessary. For tests that require the iOS simulator, also specify the `ios_application` target name as the value of the `test_host` attribute. -#### Step 3c: Add the library target(s) {:#add-library-target} +#### Step 3c: Add the library target(s) {#add-library-target} Add an [`objc_library`](/versions/9.1.0/reference/be/objective-c#objc_library) target for each Objective-C library and a -[`swift_library`](https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_library){: .external} +[`swift_library`](https://github.com/bazelbuild/rules_swift/blob/master/doc/rules.md#swift_library) target for each Swift library on which the application and/or tests depend. Add the library targets as follows: @@ -185,20 +185,20 @@ the [rules_apple examples directory](https://github.com/bazelbuild/rules_apple/tree/master/examples/). For example: -* [macOS application targets](https://github.com/bazelbuild/rules_apple/tree/master/examples/macos){: .external} +* [macOS application targets](https://github.com/bazelbuild/rules_apple/tree/master/examples/macos) -* [iOS applications targets](https://github.com/bazelbuild/rules_apple/tree/master/examples/ios){: .external} +* [iOS applications targets](https://github.com/bazelbuild/rules_apple/tree/master/examples/ios) -* [Multi platform applications (macOS, iOS, watchOS, tvOS)](https://github.com/bazelbuild/rules_apple/tree/master/examples/multi_platform){: .external} +* [Multi platform applications (macOS, iOS, watchOS, tvOS)](https://github.com/bazelbuild/rules_apple/tree/master/examples/multi_platform) For more information on build rules, see [Apple Rules for -Bazel](https://github.com/bazelbuild/rules_apple){: .external}. +Bazel](https://github.com/bazelbuild/rules_apple). At this point, it is a good idea to test the build: `bazel build //:` -### Step 4: (Optional) Granularize the build {:#granularize-build} +### Step 4: (Optional) Granularize the build {#granularize-build} If the project is large, or as it grows, consider chunking it into multiple Bazel packages. This increased granularity provides: @@ -232,7 +232,7 @@ Tips for granularizing the project: * Build the project after each major change to the `BUILD` files and fix build errors as you encounter them. -### Step 5: Run the build {:#run-build} +### Step 5: Run the build {#run-build} Run the fully migrated build to ensure it completes with no errors or warnings. Run every application and test target individually to more easily find sources @@ -244,15 +244,15 @@ For example: bazel build //:my-target ``` -### Step 6: Generate the Xcode project with rules_xcodeproj {:#generate-the-xcode-project-with-rules_xcodeproj} +### Step 6: Generate the Xcode project with rules_xcodeproj {#generate-the-xcode-project-with-rules_xcodeproj} When building with Bazel, the `MODULE.bazel` and `BUILD` files become the source of truth about the build. To make Xcode aware of this, you must generate a Bazel-compatible Xcode project using -[rules_xcodeproj](https://github.com/buildbuddy-io/rules_xcodeproj#features){: .external} +[rules_xcodeproj](https://github.com/buildbuddy-io/rules_xcodeproj#features) . -### Troubleshooting {:#troubleshooting} +### Troubleshooting {#troubleshooting} Bazel errors can arise when it gets out of sync with the selected Xcode version, like when you apply an update. Here are some things to try if you're diff --git a/versions/9.1.0/query/images/query_graph1.png b/versions/9.1.0/query/images/query_graph1.png new file mode 100644 index 00000000..7bc9a61a Binary files /dev/null and b/versions/9.1.0/query/images/query_graph1.png differ diff --git a/versions/9.1.0/query/images/query_graph2.png b/versions/9.1.0/query/images/query_graph2.png new file mode 100644 index 00000000..a0da22ff Binary files /dev/null and b/versions/9.1.0/query/images/query_graph2.png differ diff --git a/versions/9.1.0/query/images/query_graph3.png b/versions/9.1.0/query/images/query_graph3.png new file mode 100644 index 00000000..4418f193 Binary files /dev/null and b/versions/9.1.0/query/images/query_graph3.png differ diff --git a/versions/9.1.0/query/language.mdx b/versions/9.1.0/query/language.mdx index 6ca6b05e..e984021d 100644 --- a/versions/9.1.0/query/language.mdx +++ b/versions/9.1.0/query/language.mdx @@ -13,7 +13,7 @@ For practical use cases, see the [Bazel Query How-To](/versions/9.1.0/query/guid In addition to `query`, which runs on the post-loading phase target graph, Bazel includes *action graph query* and *configurable query*. -### Action graph query {:#aquery} +### Action graph query {#aquery} The action graph query (`aquery`) operates on the post-analysis Configured Target Graph and exposes information about **Actions**, **Artifacts**, and @@ -23,7 +23,7 @@ For example, the actual commands run and their inputs, outputs, and mnemonics. For more details, see the [aquery reference](/versions/9.1.0/query/aquery). -### Configurable query {:#cquery} +### Configurable query {#cquery} Traditional Bazel query runs on the post-loading phase target graph and therefore has no concept of configurations and their related concepts. Notably, @@ -34,7 +34,7 @@ doesn't provide all of the functionality of this original query. For more details, see the [cquery reference](/versions/9.1.0/query/cquery). -## Examples {:#examples} +## Examples {#examples} How do people use `bazel query`? Here are typical examples: @@ -52,7 +52,7 @@ the `foo_bin` target does not? kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo:foo_bin)) ``` -## Tokens: The lexical syntax {:#tokens} +## Tokens: The lexical syntax {#tokens} Expressions in the query language are composed of the following tokens: @@ -103,7 +103,7 @@ tokens: Note that this quoting is in addition to any quoting that may be required by your shell, such as: - ```posix-terminal + ``` bazel query ' "//foo:bar=wiz" ' # single-quotes for shell, double-quotes for Bazel. ``` @@ -136,7 +136,7 @@ tokens: Whitespace characters outside of a quoted word are ignored. -## Bazel query language concepts {:#language-concepts} +## Bazel query language concepts {#language-concepts} The Bazel query language is a language of expressions. Every expression evaluates to a **partially-ordered set** of targets, @@ -149,7 +149,7 @@ aspects of it, for example: * **Set:** The partial order of the targets is not interesting. * **Graph:** The partial order of targets is significant. -### Cycles in the dependency graph {:#dependency-graph-cycles} +### Cycles in the dependency graph {#dependency-graph-cycles} Build dependency graphs should be acyclic. @@ -161,7 +161,7 @@ operates over may contain cycles that do not exist in the configured target graph. Cycles in the configured target graph are detected and reported as errors by [`bazel cquery`](/versions/9.1.0/query/cquery) and [`bazel aquery`](/versions/9.1.0/query/aquery). -### Implicit dependencies {:#implicit-dependencies} +### Implicit dependencies {#implicit-dependencies} In addition to build dependencies that are defined explicitly in `BUILD` files, Bazel adds additional _implicit_ dependencies to rules. Implicit dependencies @@ -179,7 +179,7 @@ Note that, as query does not consider configurations, potential toolchain required toolchain types. See [toolchain documentation](/versions/9.1.0/extending/toolchains#writing-rules-toolchains). -### Soundness {:#soundness} +### Soundness {#soundness} Bazel query language expressions operate over the build dependency graph, which is the graph implicitly defined by all @@ -199,7 +199,7 @@ because, for example, the query tool will include all the files needed to support message translation, even though you don't intend to use that feature in your build. -### On the preservation of graph order {:#graph-order} +### On the preservation of graph order {#graph-order} Operations preserve any ordering constraints inherited from their subexpressions. You can think of @@ -235,7 +235,7 @@ Operators that introduce ordering constraints include: `allpaths`, `deps`, `rdeps`, `somepath`, and the target pattern wildcards `package:*`, `dir/...`, etc. -### Sky query {:#sky-query} +### Sky query {#sky-query} _Sky Query_ is a mode of query that operates over a specified _universe scope_. @@ -259,14 +259,14 @@ the [`allrdeps`](#allrdeps) and from the query expression. This inferred value is the list of unique target patterns in the query expression, but this might not be what you want. For example: -```posix-terminal +``` bazel query --infer_universe_scope --order_output=no "allrdeps(//my:target)" ``` The list of unique target patterns in this query expression is `["//my:target"]`, so Bazel treats this the same as the invocation: -```posix-terminal +``` bazel query --universe_scope=//my:target --order_output=no "allrdeps(//my:target)" ``` @@ -274,7 +274,7 @@ But the result of that query with `--universe_scope` is only `//my:target`; none of the reverse dependencies of `//my:target` are in the universe, by construction! On the other hand, consider: -```posix-terminal +``` bazel query --infer_universe_scope --order_output=no "tests(//a/... + b/...) intersect allrdeps(siblings(rbuildfiles(my/starlark/file.bzl)))" ``` @@ -299,30 +299,30 @@ As well, Sky Query does its work by introspecting the graph, which is what the default implementation does. Thus, there are some circumstances in which it is faster and uses less memory. -## Expressions: Syntax and semantics of the grammar {:#expressions} +## Expressions: Syntax and semantics of the grammar {#expressions} This is the grammar of the Bazel query language, expressed in EBNF notation: -```none {:.devsite-disable-click-to-copy} -expr ::= {{ '' }}word{{ '' }} - | let {{ '' }}name{{ '' }} = {{ '' }}expr{{ '' }} in {{ '' }}expr{{ '' }} - | ({{ '' }}expr{{ '' }}) - | {{ '' }}expr{{ '' }} intersect {{ '' }}expr{{ '' }} - | {{ '' }}expr{{ '' }} ^ {{ '' }}expr{{ '' }} - | {{ '' }}expr{{ '' }} union {{ '' }}expr{{ '' }} - | {{ '' }}expr{{ '' }} + {{ '' }}expr{{ '' }} - | {{ '' }}expr{{ '' }} except {{ '' }}expr{{ '' }} - | {{ '' }}expr{{ '' }} - {{ '' }}expr{{ '' }} - | set({{ '' }}word{{ '' }} *) - | {{ '' }}word{{ '' }} '(' {{ '' }}int{{ '' }} | {{ '' }}word{{ '' }} | {{ '' }}expr{{ '' }} ... ')' +``` +expr ::= word + | let name = expr in expr + | (expr) + | expr intersect expr + | expr ^ expr + | expr union expr + | expr + expr + | expr except expr + | expr - expr + | set(word *) + | word '(' int | word | expr ... ')' ``` The following sections describe each of the productions of this grammar in order. -### Target patterns {:#target-patterns} +### Target patterns {#target-patterns} ``` -expr ::= {{ '' }}word{{ '' }} +expr ::= word ``` Syntactically, a _target pattern_ is just a word. It's interpreted as an @@ -362,24 +362,24 @@ _graph_ over those targets. (No guarantees are made about the relative ordering of the result nodes against other nodes.) For more details, see the [graph order](#graph-order) section. -### Variables {:#variables} +### Variables {#variables} -```none {:.devsite-disable-click-to-copy} -expr ::= let {{ '' }}name{{ '' }} = {{ '' }}expr{{ '' }}{{ '' }}1{{ '' }} in {{ '' }}expr{{ '' }}{{ '' }}2{{ '' }} - | {{ '' }}$name{{ '' }} +``` +expr ::= let name = expr1 in expr2 + | $name ``` The Bazel query language allows definitions of and references to variables. The result of evaluation of a `let` expression is the same as -that of {{ '' }}expr{{ '' }}2, with all free occurrences -of variable {{ '' }}name{{ '' }} replaced by the value of -{{ '' }}expr{{ '' }}1. +that of expr2, with all free occurrences +of variable name replaced by the value of +expr1. For example, `let v = foo/... in allpaths($v, //common) intersect $v` is equivalent to the `allpaths(foo/...,//common) intersect foo/...`. An occurrence of a variable reference `name` other than in -an enclosing `let {{ '' }}name{{ '' }} = ...` expression is an +an enclosing `let name = ...` expression is an error. In other words, top-level query expressions cannot have free variables. @@ -400,24 +400,24 @@ the language can also be expressed without them. However, they improve the conciseness of many queries, and may also lead to more efficient query evaluation. -### Parenthesized expressions {:#parenthesized-expressions} +### Parenthesized expressions {#parenthesized-expressions} -```none {:.devsite-disable-click-to-copy} -expr ::= ({{ '' }}expr{{ '' }}) +``` +expr ::= (expr) ``` Parentheses associate subexpressions to force an order of evaluation. A parenthesized expression evaluates to the value of its argument. -### Algebraic set operations: intersection, union, set difference {:#algebraic-set-operations} +### Algebraic set operations: intersection, union, set difference {#algebraic-set-operations} -```none {:.devsite-disable-click-to-copy} -expr ::= {{ '' }}expr{{ '' }} intersect {{ '' }}expr{{ '' }} - | {{ '' }}expr{{ '' }} ^ {{ '' }}expr{{ '' }} - | {{ '' }}expr{{ '' }} union {{ '' }}expr{{ '' }} - | {{ '' }}expr{{ '' }} + {{ '' }}expr{{ '' }} - | {{ '' }}expr{{ '' }} except {{ '' }}expr{{ '' }} - | {{ '' }}expr{{ '' }} - {{ '' }}expr{{ '' }} +``` +expr ::= expr intersect expr + | expr ^ expr + | expr union expr + | expr + expr + | expr except expr + | expr - expr ``` These three operators compute the usual set operations over their arguments. @@ -453,13 +453,13 @@ x intersect (y union z) Important: Use parentheses where there is any danger of ambiguity in reading a query expression. -### Read targets from an external source: set {:#set} +### Read targets from an external source: set {#set} -```none {:.devsite-disable-click-to-copy} -expr ::= set({{ '' }}word{{ '' }} *) +``` +expr ::= set(word *) ``` -The `set({{ '' }}a{{ '' }} {{ '' }}b{{ '' }} {{ '' }}c{{ '' }} ...)` +The `set(a b c ...)` operator computes the union of a set of zero or more [target patterns](#target-patterns), separated by whitespace (no commas). @@ -469,7 +469,7 @@ that text file using other programs (such as standard UNIX shell tools), and the introducing the result back into the query tool as a value for further processing. For example: -```posix-terminal +``` bazel query deps(//my:target) --output=label | grep ... | sed ... | awk ... > foo bazel query "kind(cc_binary, set($( foo bazel query "kind(cc_library, set($(' }}word{{ '' }} '(' {{ '' }}int{{ '' }} | {{ '' }}word{{ '' }} | {{ '' }}expr{{ '' }} ... ')' +``` +expr ::= word '(' int | word | expr ... ')' ``` The query language defines several functions. The name of the function @@ -520,16 +520,16 @@ functions are available: * [`visible`](#visible) -### Transitive closure of dependencies: deps {:#deps} +### Transitive closure of dependencies: deps {#deps} -```none {:.devsite-disable-click-to-copy} -expr ::= deps({{ '' }}expr{{ '' }}) - | deps({{ '' }}expr{{ '' }}, {{ '' }}depth{{ '' }}) +``` +expr ::= deps(expr) + | deps(expr, depth) ``` -The `deps({{ '' }}x{{ '' }})` operator evaluates to the graph formed +The `deps(x)` operator evaluates to the graph formed by the transitive closure of dependencies of its argument set -{{ '' }}x{{ '' }}. For example, the value of `deps(//foo)` is the +x. For example, the value of `deps(//foo)` is the dependency graph rooted at the single node `foo`, including all its dependencies. The value of `deps(foo/...)` is the dependency graphs whose roots are all rules in every package beneath the `foo` directory. In this context, @@ -547,20 +547,20 @@ literal specifying an upper bound on the depth of the search. So `foo` package, and `deps(foo:*, 2)` further includes the nodes directly reachable from the nodes in `deps(foo:*, 1)`, and so on. (These numbers correspond to the ranks shown in the [`minrank`](#output-ranked) output format.) -If the {{ '' }}depth{{ '' }} parameter is omitted, the search is +If the depth parameter is omitted, the search is unbounded: it computes the reflexive transitive closure of prerequisites. -### Transitive closure of reverse dependencies: rdeps {:#rdeps} +### Transitive closure of reverse dependencies: rdeps {#rdeps} -```none {:.devsite-disable-click-to-copy} -expr ::= rdeps({{ '' }}expr{{ '' }}, {{ '' }}expr{{ '' }}) - | rdeps({{ '' }}expr{{ '' }}, {{ '' }}expr{{ '' }}, {{ '' }}depth{{ '' }}) +``` +expr ::= rdeps(expr, expr) + | rdeps(expr, expr, depth) ``` -The `rdeps({{ '' }}u{{ '' }}, {{ '' }}x{{ '' }})` +The `rdeps(u, x)` operator evaluates to the reverse dependencies of the argument set -{{ '' }}x{{ '' }} within the transitive closure of the universe set -{{ '' }}u{{ '' }}. +x within the transitive closure of the universe set +u. The resulting graph is ordered according to the dependency relation. See the section on [graph order](#graph-order) for more details. @@ -571,14 +571,14 @@ graph only includes nodes within a distance of the specified depth from any node in the argument set. So `rdeps(//foo, //common, 1)` evaluates to all nodes in the transitive closure of `//foo` that directly depend on `//common`. (These numbers correspond to the ranks shown in the [`minrank`](#output-ranked) output -format.) If the {{ '' }}depth{{ '' }} parameter is omitted, the +format.) If the depth parameter is omitted, the search is unbounded. -### Transitive closure of all reverse dependencies: allrdeps {:#allrdeps} +### Transitive closure of all reverse dependencies: allrdeps {#allrdeps} ``` -expr ::= allrdeps({{ '' }}expr{{ '' }}) - | allrdeps({{ '' }}expr{{ '' }}, {{ '' }}depth{{ '' }}) +expr ::= allrdeps(expr) + | allrdeps(expr, depth) ``` Note: Only available with [Sky Query](#sky-query) @@ -589,39 +589,39 @@ evaluated to, instead of being separately specified. Thus, if `--universe_scope=//foo/...` was passed, then `allrdeps(//bar)` is equivalent to `rdeps(//foo/..., //bar)`. -### Direct reverse dependencies in the same package: same_pkg_direct_rdeps {:#same_pkg_direct_rdeps} +### Direct reverse dependencies in the same package: same_pkg_direct_rdeps {#same_pkg_direct_rdeps} ``` -expr ::= same_pkg_direct_rdeps({{ '' }}expr{{ '' }}) +expr ::= same_pkg_direct_rdeps(expr) ``` -The `same_pkg_direct_rdeps({{ '' }}x{{ '' }})` operator evaluates to the full set of targets +The `same_pkg_direct_rdeps(x)` operator evaluates to the full set of targets that are in the same package as a target in the argument set, and which directly depend on it. -### Dealing with a target's package: siblings {:#siblings} +### Dealing with a target's package: siblings {#siblings} ``` -expr ::= siblings({{ '' }}expr{{ '' }}) +expr ::= siblings(expr) ``` -The `siblings({{ '' }}x{{ '' }})` operator evaluates to the full set of targets that are in +The `siblings(x)` operator evaluates to the full set of targets that are in the same package as a target in the argument set. -### Arbitrary choice: some {:#some} +### Arbitrary choice: some {#some} ``` -expr ::= some({{ '' }}expr{{ '' }}) - | some({{ '' }}expr{{ '' }}, {{ '' }}count{{ ' '}}) +expr ::= some(expr) + | some(expr, count) ``` -The `some({{ '' }}x{{ '' }}, {{ '' }}k{{ '' }})` operator -selects at most {{ '' }}k{{ '' }} targets arbitrarily from its -argument set {{ '' }}x{{ '' }}, and evaluates to a set containing -only those targets. Parameter {{ '' }}k{{ '' }} is optional; if +The `some(x, k)` operator +selects at most k targets arbitrarily from its +argument set x, and evaluates to a set containing +only those targets. Parameter k is optional; if missing, the result will be a singleton set containing only one target -arbitrarily selected. If the size of argument set {{ '' }}x{{ '' }} is -smaller than {{ '' }}k{{ '' }}, the whole argument set -{{ '' }}x{{ '' }} will be returned. +arbitrarily selected. If the size of argument set x is +smaller than k, the whole argument set +x will be returned. For example, the expression `some(//foo:main union //bar:baz)` evaluates to a singleton set containing either `//foo:main` or `//bar:baz`—though which @@ -636,22 +636,22 @@ equivalent to `//foo:main`. It is an error if the specified argument set is empty, as in the expression `some(//foo:main intersect //bar:baz)`. -### Path operators: somepath, allpaths {:#somepath-allpaths} +### Path operators: somepath, allpaths {#somepath-allpaths} ``` -expr ::= somepath({{ '' }}expr{{ '' }}, {{ '' }}expr{{ '' }}) - | allpaths({{ '' }}expr{{ '' }}, {{ '' }}expr{{ '' }}) +expr ::= somepath(expr, expr) + | allpaths(expr, expr) ``` -The `somepath({{ '' }}S{{ '' }}, {{ '' }}E{{ '' }})` and -`allpaths({{ '' }}S{{ '' }}, {{ '' }}E{{ '' }})` operators compute +The `somepath(S, E)` and +`allpaths(S, E)` operators compute paths between two sets of targets. Both queries accept two -arguments, a set {{ '' }}S{{ '' }} of starting points and a set -{{ '' }}E{{ '' }} of ending points. `somepath` returns the +arguments, a set S of starting points and a set +E of ending points. `somepath` returns the graph of nodes on _some_ arbitrary path from a target in -{{ '' }}S{{ '' }} to a target in {{ '' }}E{{ '' }}; `allpaths` +S to a target in E; `allpaths` returns the graph of nodes on _all_ paths from any target in -{{ '' }}S{{ '' }} to any target in {{ '' }}E{{ '' }}. +S to any target in E. The resulting graphs are ordered according to the dependency relation. See the section on [graph order](#graph-order) for more details. @@ -660,10 +660,10 @@ See the section on [graph order](#graph-order) for more details.
- Somepath + Somepath
somepath(S1 + S2, E), one possible result.
- +} */}
- Somepath + Somepath
somepath(S1 + S2, E), another possible result.
- +} */}
- Allpaths + Allpaths
allpaths(S1 + S2, E)
- +} */} -### Target kind filtering: kind {:#kind} +### Target kind filtering: kind {#kind} ``` -expr ::= kind({{ '' }}word{{ '' }}, {{ '' }}expr{{ '' }}) +expr ::= kind(word, expr) ``` -The `kind({{ '' }}pattern{{ '' }}, {{ '' }}input{{ '' }})` +The `kind(pattern, input)` operator applies a filter to a set of targets, and discards those targets -that are not of the expected kind. The {{ '' }}pattern{{ '' }} +that are not of the expected kind. The pattern parameter specifies what kind of target to match. For example, the kinds for the four targets defined by the `BUILD` file @@ -807,31 +807,31 @@ rule targets beneath `foo`, and `kind("source file", deps(//foo))` evaluates to the set of all source files in the transitive closure of dependencies of the `//foo` target. -Quotation of the {{ '' }}pattern{{ '' }} argument is often required +Quotation of the pattern argument is often required because without it, many [regular expressions](#regex), such as `source file` and `.*_test`, are not considered words by the parser. When matching for `package group`, targets ending in `:all` may not yield any results. Use `:all-targets` instead. -### Target name filtering: filter {:#filter} +### Target name filtering: filter {#filter} ``` -expr ::= filter({{ '' }}word{{ '' }}, {{ '' }}expr{{ '' }}) +expr ::= filter(word, expr) ``` -The `filter({{ '' }}pattern{{ '' }}, {{ '' }}input{{ '' }})` +The `filter(pattern, input)` operator applies a filter to a set of targets, and discards targets whose labels (in absolute form) do not match the pattern; it evaluates to a subset of its input. -The first argument, {{ '' }}pattern{{ '' }} is a word containing a +The first argument, pattern is a word containing a [regular expression](#regex) over target names. A `filter` expression -evaluates to the set containing all targets {{ '' }}x{{ '' }} such that -{{ '' }}x{{ '' }} is a member of the set {{ '' }}input{{ '' }} and the +evaluates to the set containing all targets x such that +x is a member of the set input and the label (in absolute form, such as `//foo:bar`) -of {{ '' }}x{{ '' }} contains an (unanchored) match -for the regular expression {{ '' }}pattern{{ '' }}. Since all +of x contains an (unanchored) match +for the regular expression pattern. Since all target names start with `//`, it may be used as an alternative to the `^` regular expression anchor. @@ -856,8 +856,8 @@ which would first calculate the set of `//foo` dependencies and then would filter only targets matching the provided pattern—in other words, targets with names containing `//bar` as a substring. -Another common use of the `filter({{ '' }}pattern{{ '' }}, -{{ '' }}expr{{ '' }})` operator is to filter specific files by their +Another common use of the `filter(pattern, +expr)` operator is to filter specific files by their name or extension. For example, ``` @@ -866,30 +866,30 @@ filter("\.cc$", deps(//foo)) will provide a list of all `.cc` files used to build `//foo`. -### Rule attribute filtering: attr {:#attr} +### Rule attribute filtering: attr {#attr} ``` -expr ::= attr({{ '' }}word{{ '' }}, {{ '' }}word{{ '' }}, {{ '' }}expr{{ '' }}) +expr ::= attr(word, word, expr) ``` The -`attr({{ '' }}name{{ '' }}, {{ '' }}pattern{{ '' }}, {{ '' }}input{{ '' }})` +`attr(name, pattern, input)` operator applies a filter to a set of targets, and discards targets that aren't -rules, rule targets that do not have attribute {{ '' }}name{{ '' }} +rules, rule targets that do not have attribute name defined or rule targets where the attribute value does not match the provided -[regular expression](#regex) {{ '' }}pattern{{ '' }}; it evaluates +[regular expression](#regex) pattern; it evaluates to a subset of its input. -The first argument, {{ '' }}name{{ '' }} is the name of the rule +The first argument, name is the name of the rule attribute that should be matched against the provided [regular expression](#regex) pattern. The second argument, -{{ '' }}pattern{{ '' }} is a regular expression over the attribute +pattern is a regular expression over the attribute values. An `attr` expression evaluates to the set containing all targets -{{ '' }}x{{ '' }} such that {{ '' }}x{{ '' }} is a -member of the set {{ '' }}input{{ '' }}, is a rule with the defined -attribute {{ '' }}name{{ '' }} and the attribute value contains an +x such that x is a +member of the set input, is a rule with the defined +attribute name and the attribute value contains an (unanchored) match for the regular expression -{{ '' }}pattern{{ '' }}. If {{ '' }}name{{ '' }} is an +pattern. If name is an optional attribute and rule does not specify it explicitly then default attribute value will be used for comparison. For example, @@ -959,21 +959,21 @@ some_rule( This works because the character before `key=value` will be `{` or a space and the character after `key=value` will be a comma or `}`. -### Rule visibility filtering: visible {:#visible} +### Rule visibility filtering: visible {#visible} ``` -expr ::= visible({{ '' }}expr{{ '' }}, {{ '' }}expr{{ '' }}) +expr ::= visible(expr, expr) ``` -The `visible({{ '' }}predicate{{ '' }}, {{ '' }}input{{ '' }})` operator +The `visible(predicate, input)` operator applies a filter to a set of targets, and discards targets without the required visibility. -The first argument, {{ '' }}predicate{{ '' }}, is a set of targets that all targets -in the output must be visible to. A {{ '' }}visible{{ '' }} expression -evaluates to the set containing all targets {{ '' }}x{{ '' }} such that {{ '' }}x{{ '' }} -is a member of the set {{ '' }}input{{ '' }}, and for all targets {{ '' }}y{{ '' }} in -{{ '' }}predicate{{ '' }} {{ '' }}x{{ '' }} is visible to {{ '' }}y{{ '' }}. For example: +The first argument, predicate, is a set of targets that all targets +in the output must be visible to. A visible expression +evaluates to the set containing all targets x such that x +is a member of the set input, and for all targets y in +predicate x is visible to y. For example: ``` visible(//foo, //bar:*) @@ -982,31 +982,31 @@ visible(//foo, //bar:*) will select all targets in the package `//bar` that `//foo` can depend on without violating visibility restrictions. -### Evaluation of rule attributes of type label: labels {:#labels} +### Evaluation of rule attributes of type label: labels {#labels} ``` -expr ::= labels({{ '' }}word{{ '' }}, {{ '' }}expr{{ '' }}) +expr ::= labels(word, expr) ``` -The `labels({{ '' }}attr_name{{ '' }}, {{ '' }}inputs{{ '' }})` +The `labels(attr_name, inputs)` operator returns the set of targets specified in the -attribute {{ '' }}attr_name{{ '' }} of type "label" or "list of label" in -some rule in set {{ '' }}inputs{{ '' }}. +attribute attr_name of type "label" or "list of label" in +some rule in set inputs. For example, `labels(srcs, //foo)` returns the set of targets appearing in the `srcs` attribute of the `//foo` rule. If there are multiple rules -with `srcs` attributes in the {{ '' }}inputs{{ '' }} set, the +with `srcs` attributes in the inputs set, the union of their `srcs` is returned. -### Expand and filter test_suites: tests {:#tests} +### Expand and filter test_suites: tests {#tests} ``` -expr ::= tests({{ '' }}expr{{ '' }}) +expr ::= tests(expr) ``` -The `tests({{ '' }}x{{ '' }})` operator returns the set of all test -rules in set {{ '' }}x{{ '' }}, expanding any `test_suite` rules into +The `tests(x)` operator returns the set of all test +rules in set x, expanding any `test_suite` rules into the set of individual tests that they refer to, and applying filtering by `tag` and `size`. @@ -1024,15 +1024,15 @@ foo:*`: this may include tests belonging to other packages, that are referenced directly or indirectly via `test_suite` rules. -### Package definition files: buildfiles {:#buildfiles} +### Package definition files: buildfiles {#buildfiles} ``` -expr ::= buildfiles({{ '' }}expr{{ '' }}) +expr ::= buildfiles(expr) ``` -The `buildfiles({{ '' }}x{{ '' }})` operator returns the set +The `buildfiles(x)` operator returns the set of files that define the packages of each target in -set {{ '' }}x{{ '' }}; in other words, for each package, its `BUILD` file, +set x; in other words, for each package, its `BUILD` file, plus any .bzl files it references via `load`. Note that this also returns the `BUILD` files of the packages containing these `load`ed files. @@ -1041,7 +1041,7 @@ This operator is typically used when determining what files or packages are required to build a specified target, often in conjunction with the [`--output package`](#output-package) option, below). For example, -```posix-terminal +``` bazel query 'buildfiles(deps(//foo))' --output package ``` @@ -1060,10 +1060,10 @@ target `//a:b.bzl`), but this isn't necessarily the case. Therefore, misleading when formatted in a structured way, such as [`--output=xml`](#xml). -### Package definition files: rbuildfiles {:#rbuildfiles} +### Package definition files: rbuildfiles {#rbuildfiles} ``` -expr ::= rbuildfiles({{ '' }}word{{ '' }}, ...) +expr ::= rbuildfiles(word, ...) ``` Note: Only available with [Sky Query](#sky-query). @@ -1092,15 +1092,15 @@ outputs of the `buildfiles` operator are targets corresponding to all packages a files needed by a given input. However, the inputs of the `rbuildfiles` operator are not those targets, but rather the path fragments that correspond to those targets. -### Package definition files: loadfiles {:#loadfiles} +### Package definition files: loadfiles {#loadfiles} ``` -expr ::= loadfiles({{ '' }}expr{{ '' }}) +expr ::= loadfiles(expr) ``` -The `loadfiles({{ '' }}x{{ '' }})` operator returns the set of +The `loadfiles(x)` operator returns the set of Starlark files that are needed to load the packages of each target in -set {{ '' }}x{{ '' }}. In other words, for each package, it returns the +set x. In other words, for each package, it returns the .bzl files that are referenced from its `BUILD` files. Warning: Bazel pretends each of these .bzl files has a corresponding target @@ -1109,7 +1109,7 @@ necessarily the case. Therefore, `loadfiles` doesn't compose well with other que operators and its results can be misleading when formatted in a structured way, such as [`--output=xml`](#xml). -## Output formats {:#output-formats} +## Output formats {#output-formats} `bazel query` generates a graph. You specify the content, format, and ordering by which @@ -1128,7 +1128,7 @@ an output format other than `graph` is used. Similarly, `--xml:line_numbers` applies only when `--output=xml` is being used. -### On the ordering of results {:#results-ordering} +### On the ordering of results {#results-ordering} Although query expressions always follow the "[law of conservation of graph order](#graph-order)", _presenting_ the results may be done @@ -1166,7 +1166,7 @@ in which they were visited. Printing nodes in this order may be slower, so it should be used only when determinism is important. -### Print the source form of targets as they would appear in BUILD {:#target-source-form} +### Print the source form of targets as they would appear in BUILD {#target-source-form} ``` --output build @@ -1182,7 +1182,7 @@ giving the name of the macro that was evaluated to produce the effective rule. Although the output uses the same syntax as `BUILD` files, it is not guaranteed to produce a valid `BUILD` file. -### Print the label of each target {:#print-label-target} +### Print the label of each target {#print-label-target} ``` --output label @@ -1210,7 +1210,7 @@ below) format, the distinction becomes clear: the two targets have the same name, but one has kind `sh_binary rule` and the other kind `source file`. -### Print the label and kind of each target {:#print-target-label} +### Print the label and kind of each target {#print-target-label} ``` --output label_kind @@ -1220,7 +1220,7 @@ Like `label`, this output format prints the labels of each target in the resulting graph, in topological order, but it additionally precedes the label by the [_kind_](#kind) of the target. -### Print targets in protocol buffer format {:#print-target-proto} +### Print targets in protocol buffer format {#print-target-proto} ``` --output proto @@ -1230,7 +1230,7 @@ Prints the query output as a [`QueryResult`](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/build.proto) protocol buffer. -### Print targets in length-delimited protocol buffer format {:#print-target-length-delimited-proto} +### Print targets in length-delimited protocol buffer format {#print-target-length-delimited-proto} ``` --output streamed_proto @@ -1245,7 +1245,7 @@ protocol buffers. This is useful to _(i)_ get around of protocol buffers when there are too many targets to fit in a single `QueryResult` or _(ii)_ to start processing while Bazel is still outputting. -### Print targets in text proto format {:#print-target-textproto} +### Print targets in text proto format {#print-target-textproto} ``` --output textproto @@ -1256,7 +1256,7 @@ Similar to `--output proto`, prints the protocol buffer but in [text format](https://protobuf.dev/reference/protobuf/textformat-spec/). -### Print targets in ndjson format {:#print-target-streamed-jsonproto} +### Print targets in ndjson format {#print-target-streamed-jsonproto} ``` --output streamed_jsonproto @@ -1266,7 +1266,7 @@ Similar to `--output streamed_proto`, prints a stream of [`Target`](https://github.com/bazelbuild/bazel/blob/master/src/main/protobuf/build.proto) protocol buffers but in [ndjson](https://github.com/ndjson/ndjson-spec) format. -### Print the label of each target, in rank order {:#print-target-label-rank-order} +### Print the label of each target, in rank order {#print-target-label-rank-order} ``` --output minrank --output maxrank @@ -1277,8 +1277,7 @@ and `maxrank` output formats print the labels of each target in the resulting graph, but instead of appearing in topological order, they appear in rank order, preceded by their rank number. These are unaffected by the result ordering -`--[no]order_results` flag (see [notes on -the ordering of results](#result-order)). +`--[no]order_results` flag (see [notes on the ordering of results](#result-order)). There are two variants of this format: `minrank` ranks each node by the length of the shortest path from a root node to it. @@ -1315,7 +1314,7 @@ are specified, respectively. -
Out ranked + Out ranked 
@@ -1342,7 +1341,7 @@ are specified, respectively.
-### Print the location of each target {:#print-target-location} +### Print the location of each target {#print-target-location} ``` --output location @@ -1365,9 +1364,11 @@ generates it is printed. (The query tool does not have sufficient information to find the actual location of the generated file, and in any case, it might not exist if a build has not yet been performed.) -### Print the set of packages {:#print-package-set} +### Print the set of packages {#print-package-set} -```--output package``` +``` +--output package +``` This option prints the name of all packages to which some target in the result set belongs. The names are printed in @@ -1383,9 +1384,11 @@ In conjunction with the `deps(...)` query, this output option can be used to find the set of packages that must be checked out in order to build a given set of targets. -### Display a graph of the result {:#display-result-graph} +### Display a graph of the result {#display-result-graph} -```--output graph``` +``` +--output graph +``` This option causes the query result to be printed as a directed graph in the popular AT&T GraphViz format. Typically the @@ -1409,7 +1412,7 @@ same `genrule`; in the factored graph, all these files are represented by a single node. This behavior may be disabled with the `--nograph:factored` option. -#### `--graph:node_limit {{ '' }}n{{ '' }}` {:#graph-nodelimit} +#### `--graph:node_limit n` {#graph-nodelimit} The option specifies the maximum length of the label string for a graph node in the output. Longer labels will be truncated; -1 @@ -1419,7 +1422,7 @@ handle labels exceeding 1024 characters, which is the default value of this option. This option has no effect unless `--output=graph` is being used. -#### `--[no]graph:factored` {:#graph-factored} +#### `--[no]graph:factored` {#graph-factored} By default, graphs are displayed in factored form, as explained [above](#output-graph). @@ -1429,9 +1432,11 @@ impractical, but the simpler format may ease processing by other tools (such as grep). This option has no effect unless `--output=graph` is being used. -### XML {:#xml} +### XML {#xml} -```--output xml``` +``` +--output xml +``` This option causes the resulting targets to be printed in an XML form. The output starts with an XML header such as this @@ -1441,8 +1446,8 @@ form. The output starts with an XML header such as this ``` - +{/* The docs should continue to document version 2 into perpetuity, + even if we add new formats, to handle clients synced to old CLs. */} and then continues with an XML element for each target in the result graph, in topological order (unless @@ -1508,12 +1513,12 @@ attribute, whose value is the target's label, and a `location` attribute, whose value is the target's location as printed by the [`--output location`](#print-target-location). -#### `--[no]xml:line_numbers` {:#xml-linenumbers} +#### `--[no]xml:line_numbers` {#xml-linenumbers} By default, the locations displayed in the XML output contain line numbers. When `--noxml:line_numbers` is specified, line numbers are not printed. -#### `--[no]xml:default_values` {:#xml-defaultvalues} +#### `--[no]xml:default_values` {#xml-defaultvalues} By default, XML output does not include rule attribute whose value is the default value for that kind of attribute (for example, if it @@ -1521,13 +1526,13 @@ were not specified in the `BUILD` file, or the default value was provided explicitly). This option causes such attribute values to be included in the XML output. -### Regular expressions {:#regular-expressions} +### Regular expressions {#regular-expressions} Regular expressions in the query language use the Java regex library, so you can use the full syntax for -[`java.util.regex.Pattern`](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html){: .external}. +[`java.util.regex.Pattern`](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html). -### Querying with external repositories {:#querying-external-repositories} +### Querying with external repositories {#querying-external-repositories} If the build depends on rules from [external repositories](/versions/9.1.0/external/overview) then query results will include these dependencies. For diff --git a/versions/9.1.0/reference/flag-cheatsheet.mdx b/versions/9.1.0/reference/flag-cheatsheet.mdx index 8d88b7b4..6abfef35 100644 --- a/versions/9.1.0/reference/flag-cheatsheet.mdx +++ b/versions/9.1.0/reference/flag-cheatsheet.mdx @@ -1,10 +1,3 @@ - - - - - - - --- title: 'Bazel flag cheat sheet' --- @@ -12,28 +5,12 @@ title: 'Bazel flag cheat sheet' Navigating Bazel's extensive list of command line flags can be a challenge. This page focuses on the most crucial flags you'll need to know. - - -## Useful general options {:#useful-command} +## Useful general options {#useful-command} The following flags are meant to be set explicitly on the command line. @@ -107,7 +84,7 @@ Adds build info (user, timestamp) to binaries. -## Uncover Build & Test Issues {:#uncover-build} +## Uncover Build & Test Issues {#uncover-build} The following flags can help you better understand Bazel build or test errors. @@ -181,7 +158,7 @@ regardless of whether it succeeds or fails -## Startup {:#startup} +## Startup {#startup} Caution: Startup flags need to be passed before the command and cause a server restart. Toggle these flags with caution. @@ -270,7 +247,7 @@ see -## Bazel tests {:#bazel-tests} +## Bazel tests {#bazel-tests} The following flags are related to Bazel test @@ -339,7 +316,7 @@ real time. -## Bazel run {:#bazel-run} +## Bazel run {#bazel-run} The following flags are related to Bazel run. @@ -364,7 +341,7 @@ commonly used for debugging. -## User-specific bazelrc options {:#user-specific-bazelrc} +## User-specific bazelrc options {#user-specific-bazelrc} The following flags are related to user-specific **.bazelrc** options. @@ -444,7 +421,7 @@ build. -## Project-specific bazelrc options {:#project-specific-bazelrc} +## Project-specific bazelrc options {#project-specific-bazelrc} The following flags are related to project-specific .bazelrc options. @@ -558,5 +535,3 @@ to your build command. - - \ No newline at end of file diff --git a/versions/9.1.0/reference/test-encyclopedia.mdx b/versions/9.1.0/reference/test-encyclopedia.mdx index b8adc814..c3ebe311 100644 --- a/versions/9.1.0/reference/test-encyclopedia.mdx +++ b/versions/9.1.0/reference/test-encyclopedia.mdx @@ -4,7 +4,7 @@ title: 'Test encyclopedia' An exhaustive specification of the test execution environment. -## Background {:#background} +## Background {#background} The Bazel BUILD language includes rules which can be used to define automated test programs in many languages. @@ -22,7 +22,7 @@ release engineering auditability, and resource isolation of tests (automated testing frameworks ought not DDOS a server because some tests happen to talk to it). -## Objective {:#objective} +## Objective {#objective} The goal of this page is to formally establish the runtime environment for and expected behavior of Bazel tests. It will also impose requirements on the test @@ -38,13 +38,13 @@ This page is intended to be both normative and authoritative. If this specification and the implemented behavior of test runner disagree, the specification takes precedence. -## Proposed Specification {:#proposed-specification} +## Proposed Specification {#proposed-specification} The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in IETF RFC 2119. -## Purpose of tests {:#purpose-of-tests} +## Purpose of tests {#purpose-of-tests} The purpose of Bazel tests is to confirm some property of the source files checked into the repository. (On this page, "source files" includes test data, @@ -64,7 +64,7 @@ Therefore the outcome of a test must depend only on: Currently, such behavior is not enforced. However, test runners reserve the right to add such enforcement in the future. -## Role of the build system {:#role-build-system} +## Role of the build system {#role-build-system} Test rules are analogous to binary rules in that each must yield an executable program. For some languages, this is a stub program which combines a @@ -81,7 +81,7 @@ should ensure that the generated executable loads these files via the runfiles image provided by the test runner, rather than hardcoded references to absolute locations in the source or output tree. -## Role of the test runner {:#role-test-runner} +## Role of the test runner {#role-test-runner} From the point of view of the test runner, each test is a program which can be invoked with `execve()`. There may be other ways to execute tests; for example, @@ -210,7 +210,7 @@ the test runner should consider the run complete and count it as a success or failure based on the exit code observed from the main process. The test runner may kill any stray processes. Tests should not leak processes in this fashion. -## Test sharding {:#test-sharding} +## Test sharding {#test-sharding} Tests can be parallelized via test sharding. See [`--test_sharding_strategy`](/versions/9.1.0/reference/command-line-reference#flag--test_sharding_strategy) @@ -226,7 +226,7 @@ modified date of the file specified by [`--incompatible_check_sharding_support`](/versions/9.1.0/reference/command-line-reference#flag--incompatible_check_sharding_support) is enabled, Bazel will fail the test if it is sharded. -## Initial conditions {:#initial-conditions} +## Initial conditions {#initial-conditions} When executing a test, the test runner must establish certain initial conditions. @@ -564,13 +564,13 @@ The initial process times (as returned by `times()`) and resource utilization The initial scheduling policy and priority are unspecified. -## Role of the host system {:#role-host-system} +## Role of the host system {#role-host-system} In addition to the aspects of user context under direct control of the test runner, the operating system on which tests execute must satisfy certain properties for a test run to be valid. -#### Filesystem {:#filesystem} +#### Filesystem {#filesystem} The root directory observed by a test may or may not be the real root directory. @@ -589,7 +589,7 @@ use. Tests must not assume that atimes are enabled for any mounted filesystem. -#### Users and groups {:#users-groups} +#### Users and groups {#users-groups} The users root, nobody, and unittest must exist. The groups root, nobody, and eng must exist. @@ -606,13 +606,13 @@ supplementary group ids. The current user must have a home directory. It may not be writable. Tests must not attempt to write to it. -#### Networking {:#networking} +#### Networking {#networking} The hostname is unspecified. It may or may not contain a dot. Resolving the hostname must give an IP address of the current host. Resolving the hostname cut after the first dot must also work. The hostname localhost must resolve. -#### Other resources {:#other-resources} +#### Other resources {#other-resources} Tests are granted at least one CPU core. Others may be available but this is not guaranteed. Other performance aspects of this core are not specified. You can @@ -627,14 +627,14 @@ Tests may create subprocesses, but not process groups or sessions. There is a limit on the number of input files a test may consume. This limit is subject to change, but is currently in the range of tens of thousands of inputs. -#### Time and date {:#time-and-date} +#### Time and date {#time-and-date} The current time and date are unspecified. The system timezone is unspecified. X Windows may or may not be available. Tests that need an X server should start Xvfb. -## Test interaction with the filesystem {:#test-interaction-filesystem} +## Test interaction with the filesystem {#test-interaction-filesystem} All file paths specified in test environment variables point to somewhere on the local filesystem, unless otherwise specified. @@ -654,15 +654,15 @@ Tests may also write .part files to the `$TEST_UNDECLARED_OUTPUTS_ANNOTATIONS_DIR` to annotate undeclared output files. In rare cases, a test may be forced to create files in `/tmp`. For example, -[path length limits for Unix domain sockets](https://serverfault.com/questions/641347){: .external} +[path length limits for Unix domain sockets](https://serverfault.com/questions/641347) typically require creating the socket under `/tmp`. Bazel will be unable to track such files; the test itself must take care to be hermetic, to use unique paths to avoid colliding with other, simultaneously running tests and non-test processes, and to clean up the files it creates in `/tmp`. Some popular testing frameworks, such as -[JUnit4 `TemporaryFolder`](https://junit.org/junit4/javadoc/latest/org/junit/rules/TemporaryFolder.html){: .external} -or [Go `TempDir`](https://golang.org/pkg/testing/#T.TempDir){: .external}, have +[JUnit4 `TemporaryFolder`](https://junit.org/junit4/javadoc/latest/org/junit/rules/TemporaryFolder.html) +or [Go `TempDir`](https://golang.org/pkg/testing/#T.TempDir), have their own ways to create a temporary directory under `/tmp`. These testing frameworks include functionality that cleans up files in `/tmp`, so you may use them even though they create files outside of `TEST_TMPDIR`. @@ -695,7 +695,7 @@ In order to catch early exit, a test may create a file at the path specified by file when the test finishes, it will assume that the test exited prematurely and mark it as having failed. -## Execution platform {:#execution-platform} +## Execution platform {#execution-platform} The [execution platform](/versions/9.1.0/extending/platforms) for a test action is determined via [toolchain resolution](/versions/9.1.0/extending/toolchains#toolchain-resolution), just @@ -737,7 +737,7 @@ behavior and their toolchains will take precedence over the default ones. Test rule authors can define their own test toolchain type and also register a default toolchain for it. -## Tag conventions {:#tag-conventions} +## Tag conventions {#tag-conventions} Some tags in the test rules have a special meaning. See also the @@ -762,7 +762,7 @@ See also the test_suite convention; suite of large tests - manual * + ```manual *``` don't include test target in wildcard target patterns like :..., :*, or :all @@ -783,19 +783,19 @@ See also the Note: bazel `query` does not respect the manual tag. -## Runfiles {:#runfiles} +## Runfiles {#runfiles} In the following, assume there is a *_binary() rule labeled `//foo/bar:unittest`, with a run-time dependency on the rule labeled `//deps/server:server`. -#### Location {:#runfiles-location} +#### Location {#runfiles-location} The runfiles directory for a target `//foo/bar:unittest` is the directory `$(WORKSPACE)/$(BINDIR)/foo/bar/unittest.runfiles`. This path is referred to as the `runfiles_dir`. -#### Dependencies {:#runfiles-dependencies} +#### Dependencies {#runfiles-dependencies} The runfiles directory is declared as a compile-time dependency of the `*_binary()` rule. The runfiles directory itself depends on the set of BUILD @@ -803,7 +803,7 @@ files that affect the `*_binary()` rule or any of its compile-time or run-time dependencies. Modifying source files does not affect the structure of the runfiles directory, and thus does not trigger any rebuilding. -#### Contents {:#runfiles-contents} +#### Contents {#runfiles-contents} The runfiles directory contains the following: diff --git a/versions/9.1.0/remote/cache-local.mdx b/versions/9.1.0/remote/cache-local.mdx index 3548679d..a4b73c74 100644 --- a/versions/9.1.0/remote/cache-local.mdx +++ b/versions/9.1.0/remote/cache-local.mdx @@ -24,7 +24,7 @@ Execution](/versions/9.1.0/remote/cache-remote#check-cache-hits). In the standard output of your Bazel run, you will see something like the following: -```none {:.devsite-disable-click-to-copy} +``` INFO: 7 processes: 3 remote cache hit, 4 linux-sandbox. ``` @@ -50,13 +50,13 @@ the steps in this section. cannot cache. Check the output of your Bazel invocation for warnings, such as: - ```none {:.devsite-disable-click-to-copy} + ``` WARNING: Error reading from the remote cache: ``` or - ```none {:.devsite-disable-click-to-copy} + ``` WARNING: Error writing to the remote cache: ``` diff --git a/versions/9.1.0/remote/cache-remote.mdx b/versions/9.1.0/remote/cache-remote.mdx index d2447a80..691644d9 100644 --- a/versions/9.1.0/remote/cache-remote.mdx +++ b/versions/9.1.0/remote/cache-remote.mdx @@ -20,7 +20,7 @@ from a remote cache is displayed as `remote cache hit`. For example: -```none {:.devsite-disable-click-to-copy} +``` INFO: 11 processes: 6 remote cache hit, 3 internal, 2 remote. ``` @@ -62,7 +62,7 @@ If you are not getting the cache hit rate you are expecting, do the following: ```posix-terminal bazel clean - bazel {{ '' }}--optional-flags{{ '' }} build //{{ '' }}your:target{{ '' }} --execution_log_compact_file=/tmp/exec1.log + bazel --optional-flags build //your:target --execution_log_compact_file=/tmp/exec1.log ``` b. [Compare the execution logs](#compare-logs) between the diff --git a/versions/9.1.0/remote/caching.mdx b/versions/9.1.0/remote/caching.mdx index cac28114..a49d9238 100644 --- a/versions/9.1.0/remote/caching.mdx +++ b/versions/9.1.0/remote/caching.mdx @@ -231,7 +231,7 @@ only your CI system to be able to write to the remote cache. Use the following flag to read from and write to the remote cache: ```posix-terminal -build --remote_cache=http://{{ '' }}your.host:port{{ '' }} +build --remote_cache=http://your.host:port ``` Besides `HTTP`, the following protocols are also supported: `HTTPS`, `grpc`, `grpcs`. @@ -278,8 +278,8 @@ is similar to curl's `--unix-socket` flag. Use the following to configure unix domain socket: ```posix-terminal - build --remote_cache=http://{{ '' }}your.host:port{{ '' }} - build --remote_proxy=unix:/{{ '' }}path/to/socket{{ '' }} + build --remote_cache=http://your.host:port + build --remote_proxy=unix:/path/to/socket ``` This feature is unsupported on Windows. @@ -292,7 +292,7 @@ on multiple workspaces of the same project, such as multiple checkouts. Enable the disk cache as follows: ```posix-terminal -build --disk_cache={{ '' }}path/to/build/cache{{ '' }} +build --disk_cache=path/to/build/cache ``` You can pass a user-specific path to the `--disk_cache` flag using the `~` alias diff --git a/versions/9.1.0/remote/dynamic.mdx b/versions/9.1.0/remote/dynamic.mdx index 822d5bcd..d6d1ea3a 100644 --- a/versions/9.1.0/remote/dynamic.mdx +++ b/versions/9.1.0/remote/dynamic.mdx @@ -15,7 +15,7 @@ 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](/versions/9.1.0/remote/rbe) first. -## Enabling dynamic execution? {:#enabling-dynamic-execution} +## Enabling dynamic execution? {#enabling-dynamic-execution} The dynamic execution module is part of Bazel, but to make use of dynamic execution, you must already be able to compile both locally and remotely from @@ -68,9 +68,9 @@ between local and remote execution from going unnoticed. For more background on how dynamic execution and its locking works, see Julio Merino's excellent [blog -posts](https://jmmv.dev/series/bazel-dynamic-execution/){: .external} +posts](https://jmmv.dev/series/bazel-dynamic-execution/) -## When should I use dynamic execution? {:#when-to-use} +## When should I use dynamic execution? {#when-to-use} Dynamic execution requires some form of [remote execution system](/versions/9.1.0/remote/rbe). It is not currently possible to use a cache-only remote system, as a cache miss @@ -85,7 +85,7 @@ running actions that don't fall into those categories merely delays execution for those that do. As of release -[5.0.0-pre.20210708.4](https://github.com/bazelbuild/bazel/releases/tag/5.0.0-pre.20210708.4){: .external}, +[5.0.0-pre.20210708.4](https://github.com/bazelbuild/bazel/releases/tag/5.0.0-pre.20210708.4), [performance profiling](/versions/9.1.0/rules/performance#performance-profiling) contains data about worker execution, including time spent finishing a work request after losing a dynamic execution race. If you see dynamic execution worker threads @@ -95,7 +95,7 @@ threads.

Profiling data with poor dynamic execution performance + src="/versions/9.1.0/docs/images/dyn-trace-alldynamic.png" />

In the profile above, which uses 8 Javac workers, we see many Javac workers @@ -105,7 +105,7 @@ delay the workers.

Profiling data with better dynamic execution performance + src="/versions/9.1.0/docs/images/dyn-trace-javaconly.png" />

When only Javac is run with dynamic execution, only about half of the started @@ -115,7 +115,7 @@ The previously recommended `--experimental_spawn_scheduler` flag is deprecated. It turns on dynamic execution and sets `dynamic` as the default strategy for all mnemonics, which would often lead to these kinds of problems. -## Performance {:#performance} +## Performance {#performance} The dynamic execution approach assumes there are enough resources available locally and remotely that it's worth spending some extra resources to improve @@ -163,7 +163,7 @@ The [JSON trace profile](/versions/9.1.0/advanced/performance/json-trace-profile number of performance-related graphs that can help identify ways to improve the trade-off of performance and resource usage. -## Troubleshooting {:#troubleshooting} +## Troubleshooting {#troubleshooting} Problems with dynamic execution can be subtle and hard to debug, as they can manifest only under some specific combinations of local and remote execution. diff --git a/versions/9.1.0/remote/persistent.mdx b/versions/9.1.0/remote/persistent.mdx index 24ea9f8e..d2e8dba9 100644 --- a/versions/9.1.0/remote/persistent.mdx +++ b/versions/9.1.0/remote/persistent.mdx @@ -43,7 +43,7 @@ mnemonics. As a best practice, this example includes specifying `local` as a fallback to the `worker` strategy: ```posix-terminal -bazel build //{{ '' }}my:target{{ '' }} --strategy=Javac=worker,local +bazel build //my:target --strategy=Javac=worker,local ``` Using the workers strategy instead of the local strategy can boost compilation diff --git a/versions/9.1.0/remote/sandbox.mdx b/versions/9.1.0/remote/sandbox.mdx index 3e466915..5a54275c 100644 --- a/versions/9.1.0/remote/sandbox.mdx +++ b/versions/9.1.0/remote/sandbox.mdx @@ -102,7 +102,7 @@ in addition to troubleshooting natively. your build. For example: ```posix-terminal - bazel --bazelrc=.bazelrc build --config=docker-sandbox {{ '' }}target{{ '' }} + bazel --bazelrc=.bazelrc build --config=docker-sandbox target ``` 2. Run the build and wait for it to complete. The build will run up to four @@ -110,7 +110,7 @@ in addition to troubleshooting natively. You may encounter the following error: -```none {:.devsite-disable-click-to-copy} +``` ERROR: 'docker' is an invalid value for docker spawn strategy. ``` @@ -201,7 +201,7 @@ substitute the path to the source code on your host that you want to build. docker run -it \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /tmp:/tmp \ - -v {{ '' }}your source code directory{{ '' }}:/src \ + -v your source code directory:/src \ -w /src \ bazel_container \ /bin/bash @@ -236,7 +236,7 @@ sandbox feature in which Bazel's build actions are running, and from the local machine on which the host and action containers run. ```posix-terminal -bazel --output_user_root=/tmp/bazel_docker_root --bazelrc=.bazelrc \ build --config=docker-sandbox {{ '' }}target{{ '' }} +bazel --output_user_root=/tmp/bazel_docker_root --bazelrc=.bazelrc \ build --config=docker-sandbox target ``` ### Step 5: Resolve detected issues {#resolve-build-failures} diff --git a/versions/9.1.0/rules/lib/repo/http.mdx b/versions/9.1.0/rules/lib/repo/http.mdx index d9e7df71..376f2219 100644 --- a/versions/9.1.0/rules/lib/repo/http.mdx +++ b/versions/9.1.0/rules/lib/repo/http.mdx @@ -148,11 +148,11 @@ as the value for the Authorization field of the HTTP request. Example attribute and netrc for a http download to an oauth2 enabled API using a bearer token: -
+```
 auth_patterns = {
-    "storage.cloudprovider.com": "Bearer <password>"
+    "storage.cloudprovider.com": "Bearer "
 }
-
+``` netrc: @@ -637,11 +637,11 @@ as the value for the Authorization field of the HTTP request. Example attribute and netrc for a http download to an oauth2 enabled API using a bearer token: -
+```
 auth_patterns = {
-    "storage.cloudprovider.com": "Bearer <password>"
+    "storage.cloudprovider.com": "Bearer "
 }
-
+``` netrc: @@ -885,11 +885,11 @@ as the value for the Authorization field of the HTTP request. Example attribute and netrc for a http download to an oauth2 enabled API using a bearer token: -
+```
 auth_patterns = {
-    "storage.cloudprovider.com": "Bearer <password>"
+    "storage.cloudprovider.com": "Bearer "
 }
-
+``` netrc: diff --git a/versions/9.1.0/run/build.mdx b/versions/9.1.0/run/build.mdx index d463481a..282166df 100644 --- a/versions/9.1.0/run/build.mdx +++ b/versions/9.1.0/run/build.mdx @@ -5,7 +5,7 @@ title: 'Build programs with Bazel' This page covers how to build a program with Bazel, build command syntax, and target pattern syntax. -## Quickstart {:#quickstart} +## Quickstart {#quickstart} To run Bazel, go to your base [workspace](/versions/9.1.0/concepts/build-ref#workspace) directory or any of its subdirectories and type `bazel`. See [build](#bazel-build) if you @@ -13,11 +13,11 @@ need to make a new workspace. ```posix-terminal bazel help - [Bazel release bazel {{ "" }}version{{ "" }}] -Usage: bazel {{ "" }}command{{ "" }} {{ "" }}options{{ "" }} ... + [Bazel release bazel version] +Usage: bazel command options ... ``` -### Available commands {:#available-commands} +### Available commands {#available-commands} * [`analyze-profile`](/versions/9.1.0/docs/user-manual#analyze-profile): Analyzes build profile data. * [`aquery`](/versions/9.1.0/docs/user-manual#aquery): Executes a query on the [post-analysis](#analysis) action graph. @@ -36,10 +36,10 @@ Usage: bazel {{ "" }}command{{ "" }} {{ "" }}options{{ "" * [`test`](/versions/9.1.0/docs/user-manual#running-tests): Builds and runs the specified test targets. * [`version`](/versions/9.1.0/docs/user-manual#version): Prints version information for Bazel. -### Getting help {:#getting-help} +### Getting help {#getting-help} -* `bazel help {{ '' }}command{{ '' }}`: Prints help and options for - `{{ '' }}command{{ '' }}`. +* `bazel help command`: Prints help and options for + `command`. * `bazel help `[`startup_options`](/versions/9.1.0/docs/user-manual#startup-options): Options for the JVM hosting Bazel. * `bazel help `[`target-syntax`](#specifying-build-targets): Explains the syntax for specifying targets. * `bazel help info-keys`: Displays a list of keys used by the info command. @@ -48,7 +48,7 @@ The `bazel` tool performs many functions, called commands. The most commonly used ones are `bazel build` and `bazel test`. You can browse the online help messages using `bazel help`. -### Building one target {:#bazel-build} +### Building one target {#bazel-build} Before you can start a build, you need a _workspace_. A workspace is a directory tree that contains all the source files needed to build your @@ -108,7 +108,7 @@ and no build steps to execute. If something changed in 'foo' or its dependencies, Bazel would re-execute some build actions, or complete an _incremental build_. -### Building multiple targets {:#specifying-build-targets} +### Building multiple targets {#specifying-build-targets} Bazel allows a number of ways to specify the targets to be built. Collectively, these are known as _target patterns_. This syntax is used in commands like @@ -179,7 +179,8 @@ current _working directory_. These examples assume a working directory of `foo`: bar/wiz - Equivalent to: + + Equivalent to:
  • //foo/bar/wiz:wiz if foo/bar/wiz is a package
  • //foo/bar:wiz if foo/bar is a package
    • @@ -270,7 +271,7 @@ you want Bazel to build/test them. In contrast, `bazel query` doesn't perform any such filtering automatically (that would defeat the purpose of `bazel query`). -### Fetching external dependencies {:#fetching-external-dependencies} +### Fetching external dependencies {#fetching-external-dependencies} By default, Bazel will download and symlink external dependencies during the build. However, this can be undesirable, either because you'd like to know @@ -322,7 +323,7 @@ However, if you're using anything outside of the workspace directory then Bazel will automatically run `bazel fetch` before running `bazel build`. -#### The repository cache {:#repository-cache} +#### The repository cache {#repository-cache} Bazel tries to avoid fetching the same file several times, even if the same file is needed in different workspaces, or if the definition of an external @@ -344,7 +345,7 @@ be determined, for example to manually clean up the cache. The cache is never cleaned up automatically, as it might contain a copy of a file that is no longer available upstream. -#### [Deprecated] Distribution files directories {:#distribution-directory} +#### [Deprecated] Distribution files directories {#distribution-directory} **Deprecated**: *Using repository cache is preferred to achieve offline build.* @@ -366,7 +367,7 @@ reduces the number of candidate files to one per specified directory. In this way, specifying distribution files directories remains efficient, even if the number of files in such a directory grows large. -#### Running Bazel in an airgapped environment {:#running-bazel-airgapped} +#### Running Bazel in an airgapped environment {#running-bazel-airgapped} To keep Bazel's binary size small, Bazel's implicit dependencies are fetched over the network while running for the first time. These implicit dependencies @@ -466,10 +467,10 @@ flag pointing to the directory. For convenience, you can add it as an `.bazelrc` entry: ```posix-terminal -build --distdir={{ '' }}path{{ '' }}/to/{{ '' }}directory{{ '' }} +build --distdir=path/to/directory ``` -### Build configurations and cross-compilation {:#build-config-cross-compilation} +### Build configurations and cross-compilation {#build-config-cross-compilation} All the inputs that specify the behavior and result of a given build can be divided into two distinct categories. The first kind is the intrinsic @@ -536,7 +537,7 @@ avoid very expensive rebuilds that would result from minor changes to the request configuration (such as changing a linker options does), as described earlier. -### Correct incremental rebuilds {:#correct-incremental-rebuilds} +### Correct incremental rebuilds {#correct-incremental-rebuilds} One of the primary goals of the Bazel project is to ensure correct incremental rebuilds. Previous build tools, especially those based on Make, make several @@ -571,7 +572,7 @@ The benefit to users of correct incremental builds is: less time wasted due to confusion. (Also, less time spent waiting for rebuilds caused by use of `make clean`, whether necessary or pre-emptive.) -#### Build consistency and incremental builds {:#build-consistency} +#### Build consistency and incremental builds {#build-consistency} Formally, we define the state of a build as _consistent_ when all the expected output files exist, and their contents are correct, as specified by the steps or @@ -613,7 +614,7 @@ build tool. If you ever detect a stable inconsistent state with Bazel, please report a bug. -#### Sandboxed execution {:#sandboxed-execution} +#### Sandboxed execution {#sandboxed-execution} Note: Sandboxing is enabled by default for local execution. @@ -633,7 +634,7 @@ files and no other files in the filesystem, and it only produces its declared output files. See [Hermeticity](/versions/9.1.0/basics/hermeticity) for more details. On some platforms such as [Google Kubernetes -Engine](https://cloud.google.com/kubernetes-engine/){: .external} cluster nodes or Debian, +Engine](https://cloud.google.com/kubernetes-engine/) cluster nodes or Debian, user namespaces are deactivated by default due to security concerns. This can be checked by looking at the file `/proc/sys/kernel/unprivileged_userns_clone`: if it exists and contains a 0, @@ -649,13 +650,13 @@ In that case, try to deactivate the sandbox for genrules with issue tracker and mention which Linux distribution you're using so that we can investigate and provide a fix in a subsequent release. -### Phases of a build {:#build-phases} +### Phases of a build {#build-phases} In Bazel, a build occurs in three distinct phases; as a user, understanding the difference between them provides insight into the options which control a build (see below). -#### Loading phase {:#loading} +#### Loading phase {#loading} The first is **loading** during which all the necessary BUILD files for the initial targets, and their transitive closure of dependencies, are loaded, @@ -669,7 +670,7 @@ very quickly. Errors reported during this phase include: package not found, target not found, lexical and grammatical errors in a BUILD file, and evaluation errors. -#### Analysis phase {:#analysis} +#### Analysis phase {#analysis} The second phase, **analysis**, involves the semantic analysis and validation of each build rule, the construction of a build dependency graph, and the @@ -689,7 +690,7 @@ done. This is by design, and makes Bazel a good foundation for analysis tools, such as Bazel's [query](/versions/9.1.0/query/guide) command, which is implemented atop the loading phase. -#### Execution phase {:#execution} +#### Execution phase {#execution} The third and final phase of the build is **execution**. This phase ensures that the outputs of each step in the build are consistent with its inputs, re-running