diff options
| author |  dzc <dzc@google.com> | 2017-05-31 20:37:50 +0200 |
|---|---|---|
| committer |  László Csomor <laszlocsomor@google.com> | 2017-06-01 14:07:52 +0200 |
| commit | 22b85a2a3c79c6f3aef1e0a61e485bb135be4551 (patch) | |
| tree | 8235e8237b171ced2fa9f39f054f9a7d808c0771 /site/versions | |
| parent | 40d64293b57f0d62bb15599c730f38484b91d3f0 (diff) | |
Restructure site/ directory into docs/ which only contains Bazel documentation.
The new docs/ directory in the bazel source tree will only contain the Bazel
docs site, which is hosted at docs.bazel.build. This change deletes the
marketing site and blog, which have been migrated to the bazel-website and
bazel-blog GitHub repositories respectively.
This change also updates the serve-docs.sh and ci/build.sh under scripts/ in
preparation for publishing the docs site.
Note that to help make reviews more manageable, this change is limited to
moving files to their new locations. Here are the follow-up changes:
* Update all links in docs to remove versions/master in paths and to add
correct bazel.build subdomain when linking to pages on the marketing site
or the blog.
* Set up versioned directories on GCS bucket and add tooling for versioning
docs
This change is also coordinated with
https://bazel-review.googlesource.com/c/11568/ to have the PublishSite job
publish to docs.bazel.build rather than www.bazel.build.
Issue #2397
RELNOTES: None
PiperOrigin-RevId: 157612651
Diffstat (limited to 'site/versions')
46 files changed, 0 insertions, 14461 deletions
diff --git a/site/versions/master/docs/bazel-overview.md b/site/versions/master/docs/bazel-overview.md deleted file mode 100644 index 76c07c965d..0000000000 --- a/site/versions/master/docs/bazel-overview.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -layout: documentation -title: Bazel Overview ---- - -# Bazel Overview - -Bazel is a build tool which coordinates builds and run tests. It works with -source files written in any language, with native support for Java, C, C++ and -Python. Bazel produces builds and runs tests for multiple platforms. - -## BUILD files use a simple declarative language - -Bazel’s BUILD files describe how Bazel should build your project. They have a -declarative structure and use a build language similar to Python. BUILD files -allow you to work at a high level of the system by listing rules and their -attributes. The complexity of the build process is handled by these pre-existing -rules. You can modify rules to tweak the build process, or write new rules to -extend Bazel to work with any language or platform. - -Below is the content of one of the BUILD files from a Hello World program. The -two rules used here are `cc_library` and `cc_binary`. - -``` -cc_library( - name = "hello-time", - srcs = ["hello-time.cc"], - hdrs = ["hello-time.h"], -) - -cc_binary( - name = "hello-world", - srcs = ["hello-world.cc"], - deps = [ - ":hello-time", - "//lib:hello-greet", - ], -) -``` - -## The dependency graph describes the entire system - -Build dependencies are declared explicitly in the BUILD files, allowing Bazel -to create an accurate dependency graph of the entire source code. The graph is -maintained in memory, and incremental builds and parallel execution are possible -because of this accurate dependency graph. - -Here’s the graph of the target ‘hello-world’ from the BUILD file above: - - - - -Bazel’s query language allows you to produce images of the graph like the one -above. You can also use the query language to access information about build -dependencies and their relationships. - -## Build and tests are fast, correct, and reproducible - -Hermetic rules and sandboxing allows Bazel to produce correct, reproducible -artifacts and test results. Caching allows reuse of build artifacts and test -results. - -Bazel’s builds are fast. Incremental builds allow Bazel to do the minimum -required work for a rebuild or retest. Correct and reproducible builds allow -Bazel to reuse cached artifacts for whatever is not changed. If you change a -library, Bazel will not rebuild your entire source. - -Confidence in these correct results also means that you will never need to run -`bazel clean`. If you ever need to run `bazel clean`, there’s a bug in Bazel. diff --git a/site/versions/master/docs/best-practices.md b/site/versions/master/docs/best-practices.md deleted file mode 100644 index ca360954b9..0000000000 --- a/site/versions/master/docs/best-practices.md +++ /dev/null @@ -1,321 +0,0 @@ ---- -layout: documentation -title: Best practices ---- - -# Best practices for Bazel - -This document assumes that you are familiar with Bazel and provides advice on structuring your -projects to take full advantage of Bazel's features. - -The overall goals are: - -- To use fine-grained dependencies to allow parallelism and incrementality. -- To keep dependencies well-encapsulated. -- To make code well-structured and testable. -- To create a build configuration that is easy to understand and maintain. - -These guidelines are not requirements: few projects will be able to adhere to all of them. As the -man page for lint says, "A special reward will be presented to the first person to produce a real -program that produces no errors with strict checking." However, incorporating as many of these -principles as possible should make a project more readable, less error-prone, and faster to build. - -This document uses the requirement levels described in -[this RFC](https://www.ietf.org/rfc/rfc2119.txt). - -## Contents - -- [General structure](#general-structure) - - [Running builds and tests](#running-builds-and-tests) - - [Third party dependencies](#third-party-dependencies) - - [Depending on binaries](#depending-on-binaries) - - [Versioning](#versioning) - - [.bazelrc](#bazelrc) - - [Packages](#packages) -- [BUILD files](#build-files) - - [BUILD file style guide](#build-file-style-guide) - - [Formatting](#formatting) - - [References to targets in the current package](#references-to-targets-in-the-current-package) - - [Target naming](#target-naming) - - [Visibility](#visibility) - - [Dependencies](#dependencies) - - [Globs](#globs) -- [Skylark](#skylark) - - [Skylark style guide](#skylark-style-guide) - - [Packaging rules](#packaging-rules) - - [Rule choice](#rule-choice) -- [WORKSPACE files](#workspace-files) - - [Repository rules](#repository-rules) - - [Custom BUILD files](#custom-build-files) - - [Skylark repository rules](#skylark-repository-rules) -- [Java](#java) - - [Directory structure](#directory-structure) - - [BUILD files](#build-files) -- [C++](#c) - - [BUILD files](#build-files) - - [Include paths](#include-paths) -- [Protos](#protos) - - [Recommended Code Organization](#recommended-code-organization) - -# General structure - -## Running builds and tests - -A project should always be able to run `bazel build //...` and `bazel test //...` successfully on -its stable branch. Targets that are necessary but do not build under certain circumstances (e.g., -require specific build flags, do not build on a certain platform, require license agreements) -should be tagged as specifically as possible (e.g., "`requires-osx`"). This tagging allows -targets to be filtered at a more fine-grained level than the "manual" tag and allows someone -inspecting the BUILD file to understand what a target's restrictions are. - -## Third party dependencies - -Prefer declaring third party dependencies as remote repositories in the WORKSPACE file. If it's -necessary to check third party dependencies into your repository, put them in a directory called -`third_party/` under your workspace directory. Note that all BUILD files in `third_party/` must -include [license](https://bazel.build/versions/master/docs/be/functions.html#licenses) -declarations. - -## Depending on binaries - -Everything should be built from source whenever possible. Generally this means that, instead of -depending on a library `some-library.so`, you'd create a BUILD file and build `some-library.so` -from its sources, then depend on that target. - -Building from source prevents a build from using a library that was built with incompatible flags -or a different architecture. There are also some features like coverage, static analysis, or -dynamic analysis that will only work on the source. - -## Versioning - -Prefer building all code from head whenever possible. When versions must be used, avoid including -the version in the target name (e.g., `//guava`, not `//guava-20.0`). This naming makes the library -easier to update (only one target needs to be updated). It is also more resilient to diamond -dependency issues: if one library depends on `guava-19.0` and one depends on `guava-20.0`, you -could end up with a library that tries to depend on two different versions. If you created a -misleading alias to point both targets to one guava library, then the BUILD files are misleading. - -## `.bazelrc` - -For project-specific options, use the configuration file `_your-workspace_/tools/bazel.rc`. - -For options that you **do not** want to check into source control, create the configuration file -`_your-workspace_/.bazelrc` and add `.bazelrc` to your `.gitignore`. Note that this file has a -different name than the file above (`bazel.rc` vs `.bazelrc`). - -## Packages - -Every directory that contains buildable files should be a package. If a BUILD file refers to files -in subdirectories (e.g., `srcs = ["a/b/C.java"]`) it is a sign that a BUILD file should be added to -that subdirectory. The longer this structure exists, the more likely circular dependencies will be -inadvertently created, a target's scope will creep, and an increasing number of reverse -dependencies will have to be updated. - -# BUILD files - -## BUILD file style guide - -See the [BUILD file style -guide](https://bazel.build/versions/master/docs/skylark/build-style.html). - -## Formatting - -[Buildifier](https://github.com/bazelbuild/buildifier) should be used to achieve the correct -formatting for BUILD files. Editors should be configured to automatically format BUILD files on -save. Humans should not try to format BUILD files themselves. - -If there is a question as to what the correct formatting is, the answer is "how buildifier formats -it." - -## References to targets in the current package - -Files should be referred to by their paths relative to the package directory (without ever using -up-references, such as `..`). Generated files should be prefixed with "`:`" to indicate that they -are not sources. Source files should not be prefixed with `:`. Rules should be prefixed with `:`. -For example, assuming `x.cc` is a source file: - -```python -cc_library( - name = "lib", - srcs = ["x.cc"], - hdrs = [":gen-header"], -) - -genrule( - name = "gen-header", - srcs = [], - outs = ["x.h"], - cmd = "echo 'int x();' > $@", -) -``` - -## Target naming - -Target names should be descriptive. If a target contains one source file, the target should -generally be named after that source (e.g., a `cc_library` for `chat.cc` should be named "`chat`"). - -The eponymous target for a package (the target with the same name as the containing directory) -should provide the functionality described by the directory name. If there is no such target, do -not create an eponymous target. - -Prefer using the short name when referring to an eponymous target (`//x` instead of `//x:x`). If -you are in the same package, prefer the local reference (`:x` instead of `//x`). - -## Visibility - -Do not set the default visibility of a package to `//visibility:public`. `//visibility:public` -should be individually set for targets in the project's public API. These could be libraries which -are designed to be depended on by external projects or binaries that could be used by an external -project's build process. - -Otherwise, visibility should be scoped as tightly as possible, while still allowing access by tests -and reverse dependencies. Prefer using `__pkg__` to `__subpackages__`. - -## Dependencies - -Dependencies should be restricted to direct dependencies (dependencies needed by the sources listed -in the rule). Do not list transitive dependencies. - -Package-local dependencies should be listed first and referred to in a way compatible with the -[References to targets in the current package](#references-to-targets-in-the-current-package) -section above (not by their absolute package name). - -## Globs - -Do not use recursive globs (e.g., `glob(["**/*.java"])`). Recursive globs make BUILD files -difficult to read, as they skip subdirectories containing BUILD files. Non-recursive globs are -generally acceptable, see language-specific advice below for details. - -Indicate "no targets" with `[]`. Do not use a glob that matches nothing: it is more error-prone and -less obvious than an empty list. - -# Skylark - -## Skylark style guide - -See the [Style guide for .bzl -files](https://bazel.build/versions/master/docs/skylark/bzl-style.html) for Skylark rule guidelines. - -## Packaging rules - -See [Packaging rules](https://bazel.build/versions/master/docs/skylark/deploying.html) for advice -on how to structure and where to put new Skylark rules. - -## Rule choice - -When using a language for which Bazel has built-in rules (e.g., C++), prefer using these rules to -writing your own in Skylark. These rules are documented in the [build -encyclopedia](https://bazel.build/versions/master/docs/be/overview.html). - -# WORKSPACE files - -## Repository rules - -Prefer `http_archive` and `new_http_archive` to `git_repository`, `new_git_repository`, and -`maven_jar`. - -`git_repository` depends on jGit, which has several unpleasant bugs, and `maven_jar` uses Maven's -internal API, which generally works but is less optimized for Bazel than `http_archive`'s -downloader logic. Track the following issues filed to remediate these problems: - -- [Use `http_archive` as `git_repository`'s - backend.](https://github.com/bazelbuild/bazel/issues/2147) -- [Improve `maven_jar`'s backend.](https://github.com/bazelbuild/bazel/issues/1752) - -Do not use `bind()`. See "[Consider removing -bind](https://github.com/bazelbuild/bazel/issues/1952)" for a long discussion of its issues and -alternatives. - -## Custom BUILD files - -When using a `new_` repository rule, prefer to specify `build_file_content`, not `build_file`. - -## Skylark repository rules - -A Skylark repository rule should generally be responsible for: - -- Detecting system settings and writing them to files. -- Finding resources elsewhere on the system. -- Downloading resources from URLs. -- Generating or symlinking BUILD files into the external repository directory. - -Avoid using `repository_ctx.execute` when possible. For example, when using a non-Bazel C++ -library that has a build using Make, it is preferable to use `respository_ctx.download()` and then -write a BUILD file that builds it, instead of running `ctx.execute(["make"])`. - -# Java - -## Directory structure - -Prefer Maven's standard directory layout (sources under `src/main/java`, tests under -`src/test/java`). - -## BUILD files - -Use one BUILD file per package containing Java sources. Every BUILD file should contain one -`java_library` rule that looks like this: - -```python -java_library( - name = "directory-name", - srcs = glob(["*.java"]), - deps = [...], -) -``` - -The name of the library should be the name of the directory containing the BUILD file. The sources -should be a non-recursive glob of all Java files in the directory. - -Tests should be in a matching directory under `src/test` and depend on this library. - -# C++ - -## BUILD files - -Each BUILD file should contain one `cc_library` rule target per compilation unit in the directory. -C++ libraries should be as fine-grained as possible to provide as much incrementality as possible. - -If there is a single source file in `srcs`, the library should be named based on that C++ file's -name. This library should contain a C++ file(s), any matching header file(s), and the library's -direct dependencies. For example, - -```python -cc_library( - name = "mylib", - srcs = ["mylib.cc"], - hdrs = ["mylib.h"], - deps = [":lower-level-lib"] -) -``` - -There should be one `cc_test` rule target per `cc_library` target in the file. The `cc_test`'s -source should be a file named `[libname]_test.cc`. For example, a test for the target above might -look like: - -``` -cc_test( - name = "mylib_test", - srcs = ["mylib_test.cc"], - deps = [":mylib"] -) -``` - -## Include paths - -All include paths should be relative to the workspace directory. Use `includes` only if a public -header needs to be widely used at a non-workspace-relative path (for legacy or `third_party` code). -Otherwise, prefer to use the `copts` attribute, not the `includes` attribute. - -Using `cc_inc_library` is discouraged, prefer `copts` or `includes`. -See [the design document](https://docs.google.com/document/d/18qUWh0uUiJBv6ZOySvp6DEV0NjVnBoEy-r-ZHa9cmhU/edit#heading=h.kmep1cl5ym9k) -on C++ include directories for reasoning. - -# Protos - -## Recommended Code Organization - -- One `proto_library` rule per `.proto` file. -- A file named `foo.proto` will be in a rule named `foo_proto`, which is located in the same - package. -- A `[language]_proto_library` that wraps a `proto_library` named `foo_proto` should be called - `foo_[language]_proto`, and be located in the same package. diff --git a/site/versions/master/docs/blaze-query-v2.html b/site/versions/master/docs/blaze-query-v2.html deleted file mode 100644 index dbe80e4846..0000000000 --- a/site/versions/master/docs/blaze-query-v2.html +++ /dev/null @@ -1,1419 +0,0 @@ ---- -layout: documentation -title: Query Language ---- -<h1>The Bazel Query Reference</h1> - -<p> - When you use <code>bazel query</code> to analyze build - dependencies, you use a little language, the <em>Bazel Query - Language</em>. This document is the reference manual for that - language. This document also describes the output - formats <code>bazel query</code> supports. -</p> - -<h2>Examples</h2> - -<p> - How do people use <code>bazel query</code>? Here are typical examples: -</p> - -<p> - Why does the <code>//foo</code> tree depend on <code>//bar/baz</code>? - Show a path:</p> - <pre>somepath(foo/..., //bar/baz:all)</pre> - - -<p> - What C++ libraries do all the <code>foo</code> tests depend on that - the <code>foo_bin</code> target does not?</p> - <pre>kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo:foo_bin))</pre> - - -<h2>Tokens: the lexical syntax</h2> - -<p> - Expressions in the query language are composed of the following - tokens:</p> - <ul> - <li> - <p> - <b>Keywords</b>, such as <code>somepath</code> or - <code>let</code>. Keywords are the reserved words of the - language, and each of them is described below. The complete set - of keywords is: - </p> - -<code><!-- keep this alphabetically sorted --> -<a href="#path-operators">allpaths</a><br/> -<a href="#attr">attr</a><br/> - -<a href="#buildfiles">buildfiles</a><br/> - -<a href="#deps">deps</a><br/> -<a href="#set-operations">except</a><br/> -<a href="#filter">filter</a><br/> -<a href="#variables">in</a><br/> -<a href="#set-operations">intersect</a><br/> -<a href="#kind">kind</a><br/> -<a href="#labels">labels</a><br/> -<a href="#variables">let</a><br/> -<a href="#loadfiles">loadfiles</a><br/> -<a href="#rdeps">rdeps</a><br/> -<a href="#set">set</a><br/> -<a href="#some">some</a><br/> -<a href="#path-operators">somepath</a><br/> -<a href="#tests">tests</a><br/> -<a href="#set-operations">union</a><br/> -</code> - </li> - - <li> - <p> - <b>Words</b>, such as <code>foo/...</code> or - <code>".*test rule"</code> or - <code>//bar/baz:all</code>. - If a character sequence is "quoted" (begins and ends with a - single-quote <code>'</code>, or begins and ends with a - double-quote <code>"</code>), it is a word. - If a character sequence is not quoted, it may still be parsed as a word. - Unquoted words are sequences of characters drawn from - the set of alphabet characters, numerals, slash <code>/</code>, - hyphen <code>-</code>, underscore <code>_</code>, star <code>*</code>, and - period <code>.</code>. Unquoted words may not start with a - hyphen or period. - </p> - - <p>We chose this syntax so that quote marks aren't needed in most cases. - The (unusual) <code>".*test rule"</code> example needs quotes: it - starts with a period and contains a space. - Quoting <code>"cc_library"</code> is unnecessary but harmless. - </p> - - <p> - Quoting <em>is</em> necessary when writing scripts that - construct Bazel query expressions from user-supplied values. - - </p> - <pre> - //foo:bar+wiz # WRONG: scanned as //foo:bar + wiz. - //foo:bar=wiz # WRONG: scanned as //foo:bar = wiz. - "//foo:bar+wiz" # ok. - "//foo:bar=wiz" # ok. - </pre> - <p> - Note that this quoting is in addition to any quoting that may - be required by your shell. e.g. - </p> - <pre>bazel query ' "//foo:bar=wiz" ' # single-quotes for shell, double-quotes for Bazel.</pre> - - <p> - Keywords, when quoted, are treated as ordinary words, thus - <code>some</code> is a keyword but <code>"some"</code> is a word. - Both <code>foo</code> and <code>"foo"</code> are words. - </p> - - <li><b>Punctuation</b>, such as parens <code>()</code>, period - <code>.</code> and comma <code>,</code>, etc. Words containing - punctuation (other than the exceptions listed above) must be quoted. - </ul> - -<p> - Whitespace characters outside of a quoted word are ignored. -</p> - -<h2 id='concepts'>Bazel Query Language Concepts</h2> -<p> - The Bazel query language is a language of expressions. Every - expression evaluates to a <b>partially-ordered set</b> of targets, - or equivalently, a <b>graph</b> (DAG) of targets. This is the only - datatype. -</p> -<p> - In some expressions, the partial order of the graph is - not interesting; In this case, we call the values - "sets". In cases where the partial order of elements - is significant, we call values "graphs". Note - that both terms refer to the same datatype, but merely emphasize - different aspects of it. -</p> - -<h3>Cycles in the dependency graph</h3> -<p> - Build dependency graphs should be acyclic. - - The algorithms used by the query language are intended for use in - acyclic graphs, but are robust against cycles. The details of how - cycles are treated are not specified and should not be relied upon. -</p> - -<h3 id='implicit_deps'>Implicit dependencies</h3> - -<p> - In addition to build dependencies that are defined explicitly in BUILD files, - Bazel adds additional <em>implicit</em> dependencies to rules. For example - every Java rule implicitly depends on the JavaBuilder. Implicit dependencies - are established using attributes that start with <code>$</code> and they - cannot be overridden in BUILD files. - -</p> - -<p> - Per default <code>bazel query</code> takes implicit dependencies into account - when computing the query result. This behavior can be changed with - the <code>--[no]implicit_deps</code> option. -</p> - -<h3 id='soundness'>Soundness</h3> - -<p> - Bazel query language expressions operate over the build - dependency graph, which is the graph implicitly defined by all - rule declarations in all BUILD files. It is important to understand - that this graph is somewhat abstract, and does not constitute a - complete description of how to perform all the steps of a build. In - order to perform a build, a <em>configuration</em> is required too; - see the <a href='bazel-user-manual.html#configurations'>configurations</a> - section of the User's Guide for more detail. -</p> - -<p> - The result of evaluating an expression in the Bazel query language - is true <em>for all configurations</em>, which means that it may be - a conservative over-approximation, and not exactly precise. If you - use the query tool to compute the set of all source files needed - during a build, it may report more than are actually necessary - 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. -</p> - -<h3 id='graph-order'>On the preservation of graph order</h3> - -<p> - Operations preserve any ordering - constraints inherited from their subexpressions. You can think of - this as "the law of conservation of partial order". Consider an - example: if you issue a query to determine the transitive closure of - dependencies of a particular target, the resulting set is ordered - according to the dependency graph. If you filter that set to - include only the targets of <code>file</code> kind, the same - <em>transitive</em> partial ordering relation holds between every - pair of targets in the resulting subset—even though none of - these pairs is actually directly connected in the original graph. - (There are no file–file edges in the build dependency graph). -</p> - -<p> - However, while all operators <em>preserve</em> order, some - operations, such as the <a href='#set-operations'>set operations</a> - don't <em>introduce</em> any ordering constraints of their own. - Consider this expression: -</p> - -<pre>deps(x) union y</pre> - -<p> - The order of the final result set is guaranteed to preserve all the - ordering constraints of its subexpressions, namely, that all the - transitive dependencies of <code>x</code> are correctly ordered with - respect to each other. However, the query guarantees nothing about - the ordering of the targets in <code>y</code>, nor about the - ordering of the targets in <code>deps(x)</code> relative to those in - <code>y</code> (except for those targets in - <code>y</code> that also happen to be in <code>deps(x)</code>). -</p> - -<p> - Operators that introduce ordering constraints include: - <code>allpaths</code>, - <code>deps</code>, - <code>rdeps</code>, - <code>somepath</code>, - and the target pattern wildcards - <code>package:*</code>, - <code>dir/...</code>, etc. -</p> - -<h2>Expressions: syntax and semantics of the grammar</h2> - -<p> - This is the grammar of the Bazel query language, expressed in EBNF - notation: -</p> - - -<pre>expr ::= <var>word</var> - | let <var>name</var> = <var>expr</var> in <var>expr</var> - | (<var>expr</var>) - | <var>expr</var> intersect <var>expr</var> - | <var>expr</var> ^ <var>expr</var> - | <var>expr</var> union <var>expr</var> - | <var>expr</var> + <var>expr</var> - | <var>expr</var> except <var>expr</var> - | <var>expr</var> - <var>expr</var> - | deps(<var>expr</var>) - | deps(<var>expr</var>, <var>depth</var>) - | rdeps(<var>expr</var>, <var>expr</var>) - | rdeps(<var>expr</var>, <var>expr</var>, <var>depth</var>) - | some(<var>expr</var>) - | somepath(<var>expr</var>, <var>expr</var>) - | allpaths(<var>expr</var>, <var>expr</var>) - | kind(<var>word</var>, <var>expr</var>) - | labels(<var>word</var>, <var>expr</var>) - | filter(<var>word</var>, <var>expr</var>) - | set(<var>word</var> *) - | attr(<var>word</var>, <var>word</var>, <var>expr</var>) -</pre> - -<p> - We will examine each of the productions of this grammar in order. -</p> - -<h3 id="target-patterns">Target patterns</h3> -<pre>expr ::= <var>word</var></pre> -<p> - Syntactically, a <em>target pattern</em> is just a word. It - is interpreted as an (unordered) set of targets. The simplest - target pattern is a label, - which identifies a single target (file or rule). For example, the - target pattern <code>//foo:bar</code> evaluates to a set - containing one element, the target, the <code>bar</code> - rule. -</p> - -<p> - Target patterns generalize labels to include wildcards over packages - and targets. For example, <code>foo/...:all</code> (or - just <code>foo/...</code>) is a target pattern that evaluates to a - set containing all <em>rules</em> in every package recursively - beneath the <code>foo</code> directory; - <code>bar/baz:all</code> is a target pattern that - evaluates to a set containing all the rules in the - <code>bar/baz</code> package, but not its subpackages. -</p> - -<p> - Similarly, <code>foo/...:*</code> is a target pattern that evaluates - to a set containing all <em>targets</em> (rules <em>and</em> files) in - every package recursively beneath the <code>foo</code> directory; - <code>bar/baz:*</code> evaluates to a set containing - all the targets in the - <code>bar/baz</code> package, but not its subpackages. -</p> - -<p> - Because the <code>:*</code> wildcard matches files as well as rules, - it is often more useful than <code>:all</code> for queries. - Conversely, the <code>:all</code> wildcard (implicit in target - patterns like <code>foo/...</code>) is typically more useful for - builds. -</p> - -<p> - <code>bazel query</code> target patterns work the same as - <code>bazel build</code> build targets do; - refer to <a href='bazel-user-manual.html#target-patterns'>Target Patterns</a> - in the Bazel User Manual for further details, or type <code>bazel - help target-syntax</code>. - -</p> - -<p> - Target patterns may evaluate to a singleton set (in the case of a - label), to a set containing many elements (as in the case of - <code>foo/...</code>, which has thousands of elements) or to the - empty set, if the target pattern matches no targets. -</p> - -<p> - All nodes in the result of a target pattern expression are correctly - ordered relative to each other according to the dependency relation. - So, the result of <code>foo:*</code> is not just the set of targets - in package <code>foo</code>, it is also the <em>graph</em> over - those targets. (No guarantees are made about the relative ordering - of the result nodes against other nodes.) See the section - on <a href='#graph-order'>graph order</a> for more details. -</p> - -<h3 id="variables">Variables</h3> -<pre>expr ::= let <var>name</var> = <var>expr</var><sub>1</sub> in <var>expr</var><sub>2</sub> - | <var>$name</var></pre> -<p> - The Bazel query language allows definitions of and references to - variables. The - result of evaluation of a <code>let</code> expression is the same as - that of <var>expr</var><sub>2</sub>, with all free occurrences of - variable <var>name</var> replaced by the value of - <var>expr</var><sub>1</sub>. -</p> - -<p> - For example, <code>let v = foo/... in allpaths($v, //common) - intersect $v</code> is equivalent to the <code>allpaths(foo/..., - //common) intersect foo/...</code>. -</p> - -<p> - An occurrence of a variable reference <code>name</code> other than in - an enclosing <code>let <var>name</var> = ...</code> expression is an - error. In other words, toplevel query expressions cannot have free - variables. -</p> - -<p> - In the above grammar productions, <code>name</code> is like - <em>word</em>, but with the additional constraint that it be a legal - identifier in the C programming language. References to the variable - must be prepended with the "$" character. -</p> - -<p> - Each <code>let</code> expression defines only a single variable, - but you can nest them. -</p> - -<p> - (Both <a - href='#target-patterns'>target patterns</a> and variable references - consist of just a single token, a word, creating a syntactic - ambiguity. However, there is no semantic ambiguity, because the - subset of words that are legal variable names is disjoint from the - subset of words that are legal target patterns.) -</p> - -<p> - (Technically speaking, <code>let</code> expressions do not increase - the expressiveness of the query language: any query expressible in - 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.) -</p> - -<h3 id="parentheses">Parenthesized expressions</h3> -<pre>expr ::= (<var>expr</var>)</pre> - -<p> - Parentheses associate subexpressions to force an - order of evaluation. - A parenthesized expression evaluates - to the value of its argument. -</p> - -<h3 id="set-operations">Algebraic set operations: - intersection, union, set difference</h3> - -<pre>expr ::= <var>expr</var> intersect <var>expr</var> - | <var>expr</var> ^ <var>expr</var> - | <var>expr</var> union <var>expr</var> - | <var>expr</var> + <var>expr</var> - | <var>expr</var> except <var>expr</var> - | <var>expr</var> - <var>expr</var> -</pre> - -<p> - These three operators compute the usual set operations over their - arguments. Each operator has two forms, a nominal form such - as <code>intersect</code> and a symbolic form such - as <code>^</code>. Both forms are equivalent; - the symbolic forms are quicker to type. (For clarity, the rest of - this manual uses the nominal forms.) For example, -</p> - -<pre>foo/... except foo/bar/...</pre> - - evaluates to the set of targets that match - <code>foo/...</code> but not - <code>foo/bar/...</code> . Equivalently: - -<pre>foo/... - foo/bar/...</pre> - - The <code>intersect</code> (<code>^</code>) - and <code>union</code> (<code>+</code>) operations are commutative - (symmetric); <code>except</code> (<code>-</code>) is - asymmetric. The parser treats all three operators as - left-associative and of equal precedence, so you might want parentheses. - For example, the first two of these expressions are - equivalent, but the third is not: - -<pre>x intersect y union z -(x intersect y) union z -x intersect (y union z)</pre> - -<p> - (We strongly recommend that you use parentheses where there is - any danger of ambiguity in reading a query expression.) -</p> - -<h3 id="set">Read targets from an external source: set</h3> -<pre>expr ::= set(<var>word</var> *) </pre> -<p> - The <code>set(<var>a</var> <var>b</var> <var>c</var> ...)</code> - operator computes the union of a set of zero or - more <a href='#target-patterns'>target patterns</a>, separated by - whitespace (no commas). -</p> - -<p> - In conjunction with the Bourne shell's <code>$(...)</code> - feature, <code>set()</code> provides a means of saving the results - of one query in a regular text file, manipulating that text file - using other programs (e.g. standard UNIX shell tools), and then - introducing the result back into the query tool as a value for - further processing. For example: -</p> -<pre> - bazel query deps(//my:target) --output=label | grep ... | sed ... | awk ... > foo - bazel query "kind(cc_binary, set($(<foo)))" -</pre> -<p> - In the next example, <code>kind(cc_library, - deps(//some_dir/foo:main, 5))</code> is effectively computed - by filtering on the <code>maxrank</code> values using - an <code>awk</code> program. -</p> -<pre> - bazel query 'deps(//some_dir/foo:main)' --output maxrank | - awk '($1 < 5) { print $2;} ' > foo - bazel query "kind(cc_library, set($(<foo)))" -</pre> -<p> - In these examples, <code>$(<foo)</code> is a shorthand - for <code>$(cat foo)</code>, but shell commands other - than <code>cat</code> may be used too—such as - the previous <code>awk</code> command. -</p> - -<p> - Note, <code>set()</code> introduces no graph ordering constraints, - so path information may be lost when saving and reloading sets of - nodes using it. See the <a href='#graph-order'>graph order</a> - section below for more detail. -</p> - -<h3 id="deps">Transitive closure of dependencies: deps</h3> -<pre>expr ::= deps(<var>expr</var>) - | deps(<var>expr</var>, <var>depth</var>)</pre> -<p> - The <code>deps(<var>x</var>)</code> operator evaluates to the graph - formed by the transitive closure of dependencies of its argument set - <var>x</var>. For example, the value of <code>deps(//foo)</code> is - the dependency graph rooted at the single node <code>foo</code>, - including all its dependencies. The value of - <code>deps(foo/...)</code> is the dependency graphs whose roots are - all rules in every package beneath the <code>foo</code> directory. - Please note that 'dependencies' means only rule and file targets - in this context, therefore the BUILD, - - and Skylark files needed to - create these targets are not included here. For that you should use the - <a href="#buildfiles"><code>buildfiles</code></a> operator. -</p> - -<p> - The resulting graph is ordered according to the dependency relation. - See the section on <a href='#graph-order'>graph order</a> for more - details. -</p> - -<p> - The <code>deps</code> operator accepts an optional second argument, - which is an integer literal specifying an upper bound on the depth - of the search. So <code>deps(foo:*, 1)</code> evaluates to all the - direct prerequisites of any target in the <code>foo</code> package, - and <code>deps(foo:*, 2)</code> further includes the nodes directly - reachable from the nodes in <code>deps(foo:*, 1)</code>, and so on. - (These numbers correspond to the ranks shown in - the <a href='#output-ranked'><code>minrank</code></a> output - format.) If the <var>depth</var> parameter is omitted, the search - is unbounded, i.e. it computes the reflexive transitive closure of - prerequsites. -</p> - -<h3 id="rdeps">Transitive closure of reverse dependencies: rdeps</h3> -<pre>expr ::= rdeps(<var>expr</var>, <var>expr</var>) - | rdeps(<var>expr</var>, <var>expr</var>, <var>depth</var>)</pre> -<p> - The <code>rdeps(<var>u</var>, <var>x</var>)</code> operator evaluates - to the reverse dependencies of the argument set <var>x</var> within the - transitive closure of the universe set <var>u</var>. -</p> - -<p> - The resulting graph is ordered according to the dependency relation. See the - section on <a href='#graph-order'>graph order</a> for more details. -</p> - -<p> - The <code>rdeps</code> operator accepts an optional third argument, - which is an integer literal specifying an upper bound on the depth of the - search. The resulting graph will only include nodes within a distance of the - specified depth from any node in the argument set. So - <code>rdeps(//foo, //common, 1)</code> evaluates to all nodes in the - transitive closure of <code>//foo</code> that directly depend on - <code>//common</code>. (These numbers correspond to the ranks shown in the - <a href='#output-ranked'><code>minrank</code></a> output format.) If the - <var>depth</var> parameter is omitted, the search is unbounded. -</p> - -<h3 id="some">Arbitrary choice: some</h3> -<pre>expr ::= some(<var>expr</var>)</pre> -<p> - The <code>some(<var>x</var>)</code> operator selects one target - arbitrarily from its argument set <var>x</var>, and evaluates to a - singleton set containing only that target. For example, the - expression <code>some(//foo:main union //bar:baz)</code> - evaluates to a set containing either <code>//foo:main</code> or - <code>//bar:baz</code>—though which one is not defined. -</p> - -<p> - If the argument is a singleton, then <code>some</code> - computes the identity function: <code>some(//foo:main)</code> is - equivalent to <code>//foo:main</code>. - - It is an error if the specified argument set is empty, as in the - expression <code>some(//foo:main intersect //bar:baz)</code>. -</p> - -<h3 id="path-operators">Path operators: somepath, allpaths</h3> -<pre>expr ::= somepath(<var>expr</var>, <var>expr</var>) - | allpaths(<var>expr</var>, <var>expr</var>)</pre> -<p> - The <code>somepath(<var>S</var>, <var>E</var>)</code> and - <code>allpaths(<var>S</var>, <var>E</var>)</code> operators compute - paths between two sets of targets. Both queries accept two - arguments, a set <var>S</var> of starting points and a set - <var>E</var> of ending points. <code>somepath</code> returns the - graph of nodes on <em>some</em> arbitrary path from a target in - <var>S</var> to a target in <var>E</var>; <code>allpaths</code> - returns the graph of nodes on <em>all</em> paths from any target in - <var>S</var> to any target in <var>E</var>. -</p> - -<p> - The resulting graphs are ordered according to the dependency relation. - See the section on <a href='#graph-order'>graph order</a> for more - details. -</p> - -<table style='margin: auto'><tr> -<td style='text-align: center'> -<div class='graphviz dot'><!-- -digraph somepath1 { - graph [size="4,4"] - node [label="",shape=circle]; - n1; - n2 [fillcolor="pink",style=filled]; - n3 [fillcolor="pink",style=filled]; - n4 [fillcolor="pink",style=filled,label="E"]; - n5; n6; - n7 [fillcolor="pink",style=filled,label="S1"]; - n8 [label="S2"]; - n9; - n10 [fillcolor="pink",style=filled]; - - n1 -> n2; - n2 -> n3; - n7 -> n5; - n7 -> n2; - n5 -> n6; - n6 -> n4; - n8 -> n6; - n6 -> n9; - n2 -> n10; - n3 -> n10; - n10 -> n4; - n10 -> n11; -} ---></div> -<p><code>somepath(S1 + S2, E)</code>,<br/>one possible result.</p> -</td> -<td style='padding: 40px; text-align: center'> -<div class='graphviz dot'><!-- -digraph somepath2 { - graph [size="4,4"] - node [label="",shape=circle]; - - n1; n2; n3; - n4 [fillcolor="pink",style=filled,label="E"]; - n5; - n6 [fillcolor="pink",style=filled]; - n7 [label="S1"]; - n8 [fillcolor="pink",style=filled,label="S2"]; - n9; n10; - - n1 -> n2; - n2 -> n3; - n7 -> n5; - n7 -> n2; - n5 -> n6; - n6 -> n4; - n8 -> n6; - n6 -> n9; - n2 -> n10; - n3 -> n10; - n10 -> n4; - n10 -> n11; -} ---></div> -<p><code>somepath(S1 + S2, E)</code>,<br/>another possible result.</p> -</td> -<td style='text-align: center'> -<div class='graphviz dot'><!-- -digraph allpaths { - graph [size="4,4"] - node [label="",shape=circle]; - n1; - n2 [fillcolor="pink",style=filled]; - n3 [fillcolor="pink",style=filled]; - n4 [fillcolor="pink",style=filled,label="E"]; - n5 [fillcolor="pink",style=filled]; - n6 [fillcolor="pink",style=filled]; - n7 [fillcolor="pink",style=filled, label="S1"]; - n8 [fillcolor="pink",style=filled, label="S2"]; - n9; - n10 [fillcolor="pink",style=filled]; - - n1 -> n2; - n2 -> n3; - n7 -> n5; - n7 -> n2; - n5 -> n6; - n6 -> n4; - n8 -> n6; - n6 -> n9; - n2 -> n10; - n3 -> n10; - n10 -> n4; - n10 -> n11; -} ---></div> -<p><code>allpaths(S1 + S2, E)</code>.</p> -</td> -</tr></table> - -<h3 id="kind">Target kind filtering: kind</h3> -<pre>expr ::= kind(<var>word</var>, <var>expr</var>) </pre> -<p> - The <code>kind(<var>pattern</var>, <var>input</var>)</code> operator - applies a filter to a set of targets, and discards those targets - that are not of the expected kind. The <var>pattern</var> parameter specifies - what kind of target to match. -</p> -<ul> -<li><b>file</b> patterns can be one of: - <ul> - <li><code>source file</code> - <li><code>generated file</code> - </ul> -<li><b>rule</b> patterns can be one of: - <ul> - <li><code><var>ruletype</var> rule</code> - <li><code><var>ruletype</var></code><br> - Where <var>ruletype</var> is a build rule. The difference between these - forms is that including "rule" causes the regular expression match for - <var>ruletype</var> to be anchored. - </ul> -<li><b>package group</b> patterns should simply be: - <ul> - <li><code>package group</code> - </ul> -</ul> -<p> - For example, the kinds for the four targets defined by the BUILD file - (for package <code>p</code>) shown below are illustrated in the - table: -</p> - -<table style='margin: auto'><tr><td style='padding-right:10px'> -<pre style='margin-left: 0em;'> -genrule( - name = "a", - srcs = ["a.in"], - outs = ["a.out"], - cmd = "...", -) -</pre> -</td><td> - <table class="grid"> - <tr><th>Target</th><th>Kind</th></tr> - <tr class='tt'><td>//p:a</td><td>genrule rule</td></tr> - <tr class='tt'><td>//p:a.in</td><td>source file</td></tr> - <tr class='tt'><td>//p:a.out</td><td>generated file</td></tr> - <tr class='tt'><td>//p:BUILD</td><td>source file</td></tr> - </table> -</td></tr></table> - -<p> - Thus, <code>kind("cc_.* rule", foo/...)</code> evaluates to the set - of all <code>cc_library</code>, <code>cc_binary</code>, etc, - rule targets beneath - <code>foo</code>, and <code>kind("source file", deps(//foo))</code> - evaluates to the set of all source files in the transitive closure - of dependencies of the <code>//foo</code> target. -</p> - -<p> - Quotation of the <var>pattern</var> argument is often required - because without it, many regular expressions, such as <code>source - file</code> and <code>.*_test</code>, are not considered words by - the parser. -</p> - -<p> - When matching for <code>package group</code>, targets ending in - <code>:all</code> may not yield any results. - Use <code>:all-targets</code> instead. -</p> - -<h3 id="filter">Target name filtering: filter</h3> -<pre>expr ::= filter(<var>word</var>, <var>expr</var>) </pre> -<p> - The <code>filter(<var>pattern</var>, <var>input</var>)</code> 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. -</p> - -<p> - The first argument, <var>pattern</var> is a word containing a - regular expression over target names. A <code>filter</code> expression - evaluates to the set containing all targets <var>x</var> such that - <var>x</var> is a member of the set <var>input</var> and the - label (in absolute form, e.g. <code>//foo:bar</code>) - of <var>x</var> contains an (unanchored) match - for the regular expression <var>pattern</var>. Since all - target names start with <code>//</code>, it may be used as an alternative - to the <code>^</code> regular expression anchor. -</p> - -<p> - This operator often provides a much faster and more robust alternative to the - <code>intersect</code> operator. For example, in order to see all - <code>bar</code> dependencies of the <code>//foo:foo</code> target, one could - evaluate -</p> -<pre>deps(//foo) intersect //bar/...</pre> -<p> - This statement, however, will require parsing of all BUILD files in the - <code>bar</code> tree, which will be slow and prone to errors in - irrelevant BUILD files. An alternative would be: -</p> -<pre>filter(//bar, deps(//foo))</pre> -<p> - which would first calculate the set of <code>//foo</code> dependencies and - then would filter only targets matching the provided pattern—in other - words, targets with names containing <code>//bar</code> as a - substring. -</p> - -<p> - Another common use of the <code>filter(<var>pattern</var>, - <var>expr</var>)</code> operator is to filter specific files by their - name or extension. For example, -</p> -<pre>filter("\.cc$", deps(//foo))</pre> -<p> - will provide a list of all <code>.cc</code> files used to build - <code>//foo</code>. -</p> - -<h3 id="attr">Rule attribute filtering: attr</h3> -<pre>expr ::= attr(<var>word</var>, <var>word</var>, <var>expr</var>) </pre> -<p> - The <code>attr(<var>name</var>, <var>pattern</var>, <var>input</var>)</code> - operator applies a filter to a set of targets, and discards targets that - are not rules, rule targets that do not have attribute <var>name</var> - defined or rule targets where the attribute value does not match the provided - regular expression <var>pattern</var>; it evaluates to a subset of its input. -</p> - -<p> - The first argument, <var>name</var> is the name of the rule attribute that - should be matched against the provided regular expression pattern. The second - argument, <var>pattern</var> is a regular expression over the attribute - values. An <code>attr</code> expression evaluates to the set containing all - targets <var>x</var> such that <var>x</var> is a member of the set - <var>input</var>, is a rule with the defined attribute <var>name</var> and - the attribute value contains an (unanchored) match for the regular expression - <var>pattern</var>. Please note, that if <var>name</var> is an optional - attribute and rule does not specify it explicitly then default attribute - value will be used for comparison. For example, -</p> -<pre>attr(linkshared, 0, deps(//foo))</pre> -<p> - will select all <code>//foo</code> dependencies that are allowed to have a - linkshared attribute (e.g., <code>cc_binary</code> rule) and have it either - explicitly set to 0 or do not set it at all but default value is 0 (e.g. for - <code>cc_binary</code> rules). -</p> - -<p> - List-type attributes (such as <code>srcs</code>, <code>data</code>, etc) are - converted to strings of the form <code>[value<sub>1</sub>, ..., value<sub>n</sub>]</code>, - starting with a <code>[</code> bracket, ending with a <code>]</code> bracket - and using "<code>, </code>" (comma, space) to delimit multiple values. - Labels are converted to strings by using the absolute form of the - label. For example, an attribute <code>deps=[":foo", - "//otherpkg:bar", "wiz"]</code> would be converted to the - string <code>[//thispkg:foo, //otherpkg:bar, //thispkg:wiz]</code>. - Brackets - are always present, so the empty list would use string value <code>[]</code> - for matching purposes. For example, -</p> -<pre>attr("srcs", "\[\]", deps(//foo))</pre> -<p> - will select all rules among <code>//foo</code> dependencies that have an - empty <code>srcs</code> attribute, while -</p> -<pre>attr("data", ".{3,}", deps(//foo))</pre> -<p> - will select all rules among <code>//foo</code> dependencies that specify at - least one value in the <code>data</code> attribute (every label is at least - 3 characters long due to the <code>//</code> and <code>:</code>). -</p> - -<h3 id="visible">Rule visibility filtering: visible</h3> -<pre>expr ::= visible(<var>expr</var>, <var>expr</var>) </pre> -<p> - The <code>visible(<var>predicate</var>, <var>input</var>)</code> operator - applies a filter to a set of targets, and discards targets without the - required visibility. -</p> - -<p> - The first argument, <var>predicate</var>, is a set of targets that all targets - in the output must be visible to. A <var>visible</var> expression - evaluates to the set containing all targets <var>x</var> such that <var>x</var> - is a member of the set <var>input</var>, and for all targets <var>y</var> in - <var>predicate</var> <var>x</var> is visible to <var>y</var>. For example: -</p> -<pre>visible(//foo, //bar:*)</pre> -<p> - will select all targets in the package <code>//bar</code> that <code>//foo</code> - can depend on without violating visibility restrictions. -</p> - -<h3 id="labels">Evaluation of rule attributes of type label: labels</h3> -<pre>expr ::= labels(<var>word</var>, <var>expr</var>) </pre> -<p> - The <code>labels(<var>attr_name</var>, <var>inputs</var>)</code> - operator returns the set of targets specified in the - attribute <var>attr_name</var> of type "label" or "list of label" in - some rule in set <var>inputs</var>. -</p> - -<p> - For example, <code>labels(srcs, //foo)</code> returns the set of - targets appearing in the <code>srcs</code> attribute of - the <code>//foo</code> rule. If there are multiple rules - with <code>srcs</code> attributes in the <var>inputs</var> set, the - union of their <code>srcs</code> is returned. -</p> - -<p> - Please note, <code>deps</code> is a reserved word in the query - language, so you must quote it if you wish to query the rule - attribute of that name in a <code>labels</code> expression: - <code>labels("deps", //foo)</code>. -</p> - -<h3 id="tests">Expand and filter test_suites: tests</h3> -<pre>expr ::= tests(<var>expr</var>)</pre> -<p> - The <code>tests(<var>x</var>)</code> operator returns the set of all test - rules in set <var>x</var>, expanding any <code>test_suite</code> rules into - the set of individual tests that they refer to, and applying filtering by - <code>tag</code> and <code>size</code>. - - By default, query evaluation - ignores any non-test targets in all <code>test_suite</code> rules. This can be - changed to errors with the <code>--strict_test_suite</code> option. -</p> - -<p> - For example, the query <code>kind(test, foo:*)</code> lists all - the <code>*_test</code> and <code>test_suite</code> rules - in the <code>foo</code> package. All the results are (by - definition) members of the <code>foo</code> package. In contrast, - the query <code>tests(foo:*)</code> will return all of the - individual tests that would be executed by <code>bazel test - foo:*</code>: this may include tests belonging to other packages, - that are referenced directly or indirectly - via <code>test_suite</code> rules. -</p> - - -<h3 id="buildfiles">Package definition files: buildfiles</h3> -<pre>expr ::= buildfiles(<var>expr</var>)</pre> -<p> - The <code>buildfiles(<var>x</var>)</code> operator returns the set - of files that define the packages of each target in - set <var>x</var>; in other words, for each package, its BUILD file, - plus any files it references - - via <code>load</code>. Note that this also returns the BUILD files of the - packages containing these <code>load</code>ed files. -</p> - -<p> - This operator is typically used when determining what files or - packages are required to build a specified target, often in conjunction with - the <a href='#output-package'><code>--output package</code></a> - option, below). For example, -</p> -<pre>bazel query 'buildfiles(deps(//foo))' --output package</pre> -<p> - returns the set of all packages on which <code>//foo</code> transitively - depends. -</p> - -<p> - (Note: a naive attempt at the above query would omit - the <code>buildfiles</code> operator and use only <code>deps</code>, - but this yields an incorrect result: while the result contains the - majority of needed packages, those packages that contain only files - that are <code>load()</code>'ed - - will be missing. -</p> - -<h3 id="loadfiles">Package definition files: loadfiles</h3> -<pre>expr ::= loadfiles(<var>expr</var>)</pre> -<p> - The <code>loadfiles(<var>x</var>)</code> operator returns the set of - Skylark files that are needed to load the packages of each target in - set <var>x</var>. In other words, for each package, it returns the - .bzl files that are referenced from its BUILD files. -</p> - -<h2>Output formats</h2> - -<p> - <code>bazel query</code> generates a graph. - You specify the content, format, and ordering by which - <code>bazel query</code> presents this graph - by means of the <code>--output</code> - command-line option. - </p> - -<p> - Some of the output formats accept additional options. The name of - each output option is prefixed with the output format to which it - applies, so <code>--graph:factored</code> applies only - when <code>--output=graph</code> is being used; it has no effect if - an output format other than <code>graph</code> is used. Similarly, - <code>--xml:line_numbers</code> applies only when <code>--output=xml</code> - is being used. -</p> - -<h3 id='result-order'>On the ordering of results</h3> - -<p> - Although query expressions always follow the "<a href='#graph-order'>law of - conservation of graph order</a>", <i>presenting</i> the results may be done - in either a dependency-ordered or unordered manner. This does <b>not</b> - influence the targets in the result set or how the query is computed. It only - affects how the results are printed to stdout. Moreover, nodes that are - equivalent in the dependency order may or may not be ordered alphabetically. - The <code>--order_output</code> flag can be used to control this behavior. - (The <code>--[no]order_results</code> flag has a subset of the functionality - of the <code>--order_output</code> flag and is deprecated.) -</p> -<p> - The default value of this flag is <code>auto</code>, which is equivalent to - <code>full</code> for every output format except for <code>proto</code>, - <code>graph</code>, <code>minrank</code>, and <code>maxrank</code>, for which - it is equivalent to <code>deps</code>. -</p> -<p> - When this flag is <code>no</code> and <code>--output</code> is one of - <code>build</code>, <code>label</code>, <code>label_kind</code>, - <code>location</code>, <code>package</code>, <code>proto</code>, - <code>record</code> or <code>xml</code>, the outputs will be printed in - arbitrary order. <b>This is generally the fastest option</b>. It is not - supported though when <code>--output</code> is one of <code>graph</code>, - <code>min_rank</code> or <code>max_rank</code>: with these formats, bazel will - always print results ordered by the dependency order or rank. -</p> -<p> - When this flag is <code>deps</code>, bazel will print results ordered by the - dependency order. However, nodes that are unordered by the dependency order - (because there is no path from either one to the other) may be printed in any - order. -</p> -<p> - When this flag is <code>full</code>, bazel will print results ordered by the - dependency order, with unordered nodes ordered alphabetically or reverse - alphabetically, depending on the output format. This may be slower than the - other options, and so should only be used when deterministic results are - important — it is guaranteed with this option that running the same query - multiple times will always produce the same output. -</p> - -<h3 id="output-build">Print the source form of targets as they would appear in BUILD</h3> -<pre>--output build</pre> -<p> - With this option, the representation of each target is as if it were - hand-written in the BUILD language. All variables and function calls - (e.g. glob, macros) are expanded, which is useful for seeing the effect - of Skylark macros. Additionally, each effective rule is annotated with - the name of the macro (if any, see <code>generator_name</code> and - <code>generator_function</code>) that produced it. -</p> -<p> - Although the output uses the same syntax as BUILD files, it is not - guaranteed to produce a valid BUILD file. -</p> - -<h3 id="output-label">Print the label of each target</h3> -<pre>--output label</pre> -<p> - With this option, the set of names (or <em>labels</em>) of each target - in the resulting graph is printed, one label per line, in - topological order (unless <code>--noorder_results</code> is specified, see - <a href='#result-order'>notes on the ordering of results</a>). - (A topological ordering is one in which a graph - node appears earlier than all of its successors.) Of course there - are many possible topological orderings of a graph (<em>reverse - postorder</em> is just one); which one is chosen is not specified. - - When printing the output of a <code>somepath</code> query, the order - in which the nodes are printed is the order of the path. -</p> - -<p> - Caveat: in some corner cases, there may be two distinct targets with - the same label; for example, a <code>sh_binary</code> rule and its - sole (implicit) <code>srcs</code> file may both be called - <code>foo.sh</code>. If the result of a query contains both of - these targets, the output (in <code>label</code> format) will appear - to contain a duplicate. When using the <code>label_kind</code> (see - below) format, the distinction becomes clear: the two targets have - the same name, but one has kind <code>sh_binary rule</code> and the - other kind <code>source file</code>. -</p> - -<h3 id="output-label_kind">Print the label and kind of each target</h3> -<pre>--output label_kind</pre> -<p> - Like <code>label</code>, this output format prints the labels of - each target in the resulting graph, in topological order, but it - additionally precedes the label by - the <a href='#kind'><em>kind</em></a> of the target. -</p> - -<h3 id="output-ranked">Print the label of each target, in rank order</h3> -<pre>--output minrank ---output maxrank</pre> -<p> - Like <code>label</code>, the <code>minrank</code> - and <code>maxrank</code> 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 - <code>--[no]order_results</code> flag (see <a href='#result-order'>notes on - the ordering of results</a>). -</p> - -<p> - There are two variants of this format: <code>minrank</code> ranks - each node by the length of the shortest path from a root node to it. - "Root" nodes (those which have no incoming edges) are of rank 0, - their successors are of rank 1, etc. (As always, edges point from a - target to its prerequisites: the targets it depends upon.) -</p> - -<p> - <code>maxrank</code> ranks each node by the length of the longest - path from a root node to it. Again, "roots" have rank 0, all other - nodes have a rank which is one greater than the maximum rank of all - their predecessors. -</p> - -<p> - All nodes in a cycle are considered of equal rank. (Most graphs are - acyclic, but cycles do occur - simply because BUILD files contain erroneous cycles.) -</p> - -<p> - These output formats are useful for discovering how deep a graph is. - If used for the result of a <code>deps(x)</code>, <code>rdeps(x)</code>, - or <code>allpaths</code> query, then the rank number is equal to the - length of the shortest (with <code>minrank</code>) or longest - (with <code>maxrank</code>) path from <code>x</code> to a node in - that rank. <code>maxrank</code> can be used to determine the - longest sequence of build steps required to build a target. -</p> - -<p> - Please note, the ranked output of a <code>somepath</code> query is - basically meaningless because <code>somepath</code> doesn't - guarantee to return either a shortest or a longest path, and it may - include "transitive" edges from one path node to another that are - not direct edges in original graph. -</p> - -<p> - For example, the graph on the left yields the outputs on the right - when <code>--output minrank</code> and <code>--output maxrank</code> - are specified, respectively. -</p> - -<table style='margin: auto'><tr><td> -<div class='graphviz dot'><!-- -digraph mygraph { - node [shape=box]; -"//a:a" -> "//a:a.cc" -"//b:b" -> "//a:a" -"//b:b" -> "//b:b.cc" -"//c:c" -> "//b:b" -"//c:c" -> "//a:a" -} ---></div> -</td><td> -<pre> -minrank - -0 //c:c -1 //b:b -1 //a:a -2 //b:b.cc -2 //a:a.cc -</pre> -</td><td> -<pre> -maxrank - -0 //c:c -1 //b:b -2 //a:a -2 //b:b.cc -3 //a:a.cc -</pre> -</td></tr></table> - -<h3 id="output-location">Print the location of each target</h3> -<pre>--output location</pre> -<p> - Like <code>label_kind</code>, this option prints out, for each - target in the result, the target's kind and label, but it is - prefixed by a string describing the location of that target, as a - filename and line number. The format resembles the output of - <code>grep</code>. Thus, tools that can parse the latter (such as Emacs - or vi) can also use the query output to step through a series of - matches, allowing the Bazel query tool to be used as a - dependency-graph-aware "grep for BUILD files". -</p> - -<p> - The location information varies by target kind (see the <a - href='#kind'>kind</a> operator). For rules, the - location of the rule's declaration within the BUILD file is printed. - For source files, the location of line 1 of the actual file is - printed. For a generated file, the location of the rule that - 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.) -</p> - -<h3 id="output-package">Print the set of packages</h3> -<pre>--output package</pre> -<p> - This option prints the name of all packages to which - some target in the result set belongs. The names are printed in - lexicographical order; duplicates are excluded. Formally, this - is a <em>projection</em> from the set of labels (package, target) onto - packages. -</p> - -<p> - In conjunction with the <code>deps(...)</code> 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. -</p> - -<h3 id="output-graph">Display a graph of the result</h3> -<pre>--output graph</pre> -<p> - This option causes the query result to be printed as a directed - graph in the popular AT&T GraphViz format. Typically the - result is saved to a file, such as <code>.png</code> or <code>.svg</code>. - (If the <code>dot</code> program is not installed on your workstation, you - can install it using the command <code>sudo apt-get install graphviz</code>.) - See the example section below for a sample invocation. -</p> - -<p> - This output format is particularly useful for <code>allpath</code>, - <code>deps</code>, or <code>rdeps</code> queries, where the result - includes a <em>set of paths</em> that cannot be easily visualized when - rendered in a linear form, such as with <code>--output label</code>. -</p> - -<p> - By default, the graph is rendered in a <em>factored</em> form. That is, - topologically-equivalent nodes are merged together into a single - node with multiple labels. This makes the graph more compact - and readable, because typical result graphs contain highly - repetitive patterns. For example, a <code>java_library</code> rule - may depend on hundreds of Java source files all generated by the - same <code>genrule</code>; in the factored graph, all these files - are represented by a single node. This behavior may be disabled - with the <code>--nograph:factored</code> option. -</p> - -<h4><code>--graph:node_limit <var>n</var></code></h4> -<p> - The option specifies the maximum length of the label string for a - graph node in the output. Longer labels will be truncated; -1 - disables truncation. Due to the factored form in which graphs are - usually printed, the node labels may be very long. GraphViz cannot - handle labels exceeding 1024 characters, which is the default value - of this option. This option has no effect unless - <code>--output=graph</code> is being used. -</p> - -<h4><code>--[no]graph:factored</code></h4> -<p> - By default, graphs are displayed in factored form, as explained - <a href='#output-graph'>above</a>. - When <code>--nograph:factored</code> is specified, graphs are - printed without factoring. This makes visualization using GraphViz - impractical, but the simpler format may ease processing by other - tools (e.g. grep). This option has no effect - unless <code>--output=graph</code> is being used. -</p> - -<h3 id="output-xml">XML</h3> -<pre>--output xml</pre> -<p> - This option causes the resulting targets to be printed in an XML - form. The output starts with an XML header such as this -</p> -<pre> - <?xml version="1.0" encoding="UTF-8"?> - <query version="2"> -</pre> -<!-- The docs should continue to document version 2 into perpetuity, - even if we add new formats, to handle clients synced to old CLs. --> -<p> - and then continues with an XML element for each target - in the result graph, in topological order (unless - <a href='#result-order'>unordered results</a> are requested), - and then finishes with a terminating -</p> -<pre> -</query> -</pre> -<p> - Simple entries are emitted for targets of <code>file</code> - kind: -</p> -<pre> - <source-file name='//foo:foo_main.cc' .../> - <generated-file name='//foo:libfoo.so' .../> -</pre> -<p> - But for rules, the XML is structured and contains definitions of all - the attributes of the rule, including those whose value was not - explicitly specified in the rule's BUILD file. -</p> -<p> - Additionally, the result includes <code>rule-input</code> and - <code>rule-output</code> elements so that the topology of the - dependency graph can be reconstructed without having to know that, - for example, the elements of the <code>srcs</code> attribute are - forward dependencies (prerequisites) and the contents of the - <code>outs</code> attribute are backward dependencies (consumers). - - <code>rule-input</code> elements for <a - href='#implicit_deps'>implicit dependencies</a> are suppressed if - <code>--noimplicit_deps</code> is specified. -</p> -<pre> - <rule class='cc_binary rule' name='//foo:foo' ...> - <list name='srcs'> - <label value='//foo:foo_main.cc'/> - <label value='//foo:bar.cc'/> - ... - </list> - <list name='deps'> - <label value='//common:common'/> - <label value='//collections:collections'/> - ... - </list> - <list name='data'> - ... - </list> - <int name='linkstatic' value='0'/> - <int name='linkshared' value='0'/> - <list name='licenses'/> - <list name='distribs'> - <distribution value="INTERNAL" /> - </list> - <rule-input name="//common:common" /> - <rule-input name="//collections:collections" /> - <rule-input name="//foo:foo_main.cc" /> - <rule-input name="//foo:bar.cc" /> - ... - </rule> -</pre> - -<p> - Every XML element for a target contains a <code>name</code> - attribute, whose value is the target's label, and - a <code>location</code> attribute, whose value is the target's - location as printed by the <a href='output-location'><code>--output - location</code></a>. -</p> - -<h4><code>--[no]xml:line_numbers</code></h4> -<p> - By default, the locations displayed in the XML output contain line numbers. - When <code>--noxml:line_numbers</code> is specified, line numbers are not - printed. -</p> - -<h4><code>--[no]xml:default_values</code></h4> -<p> - By default, XML output does not include rule attribute whose value - is the default value for that kind of attribute (e.g. because it - 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. -</p> - - -<h3 id="external-repos">Querying with external repositories</h3> - -<p> - If the build depends on rules from external repositories (defined in the - WORKSPACE file) then query results will include these dependencies. For - example, if <code>//foo:bar</code> depends on <code>//external:some-lib</code> - and <code>//external:some-lib</code> is bound to - <code>@other-repo//baz:lib</code>, then - <code>bazel query 'deps(//foo:bar)'</code> - will list both <code>@other-repo//baz:lib</code> and - <code>//external:some-lib</code> as dependencies. -</p> - -<p> - External repositories themselves are not dependencies of a build. That is, in - the example above, <code>//external:other-repo</code> is not a dependency. It - can be queried for as a member of the <code>//external</code> package, though, - for example: -<p> - -<pre> - # Querying over all members of //external returns the repository. - bazel query 'kind(maven_jar, //external:*)' - //external:other-repo - - # ...but the repository is not a dependency. - bazel query 'kind(maven_jar, deps(//foo:bar))' - INFO: Empty results -</pre> diff --git a/site/versions/master/docs/blaze-user-manual.html b/site/versions/master/docs/blaze-user-manual.html deleted file mode 100644 index 782f5ef7b9..0000000000 --- a/site/versions/master/docs/blaze-user-manual.html +++ /dev/null @@ -1,3847 +0,0 @@ ---- -layout: documentation -title: User Manual ---- -<h1>A User's Guide to Bazel</h1> - -<h2 id='overview'>Bazel overview</h2> - -<p> - To run Bazel, go to - - your base <a href="/docs/build-ref.html#workspaces">workspace</a> directory - or any of its subdirectories and type <code>bazel</code>. -</p> - -<pre> - % bazel help - [Bazel release bazel-<<i>version</i>>] - Usage: bazel <command> <options> ... - - Available commands: - <a href='#analyze-profile'>analyze-profile</a> Analyzes build profile data. - <a href='#build'>build</a> Builds the specified targets. - - <a href='#canonicalize'>canonicalize-flags</a> Canonicalize Bazel flags. - <a href='#clean'>clean</a> Removes output files and optionally stops the server. - - <a href='#help'>help</a> Prints help for commands, or the index. - - <a href='#info'>info</a> Displays runtime info about the bazel server. - - <a href='#fetch'>fetch</a> Fetches all external dependencies of a target. - <a href='#mobile-install'>mobile-install</a> Installs apps on mobile devices. - - <a href='#query'>query</a> Executes a dependency graph query. - - <a href='#run'>run</a> Runs the specified target. - <a href='#shutdown'>shutdown</a> Stops the Bazel server. - <a href='#test'>test</a> Builds and runs the specified test targets. - <a href='#version'>version</a> Prints version information for Bazel. - - Getting more help: - bazel help <command> - Prints help and options for <command>. - bazel help <a href='#startup_options'>startup_options</a> - Options for the JVM hosting Bazel. - bazel help <a href='#target-patterns'>target-syntax</a> - Explains the syntax for specifying targets. - bazel help info-keys - Displays a list of keys used by the info command. - -</pre> -<p> - The <code>bazel</code> tool performs many functions, called - commands; users of CVS and Subversion will be familiar - with this "Swiss army knife" arrangement. The most commonly used one is of - course <code>bazel build</code>. You can browse the online help - messages using <code>bazel help</code>. -</p> - -<h3 id='client/server'>Client/server implementation</h3> - -<p> - The Bazel system is implemented as a long-lived server process. - This allows it to perform many optimizations not possible with a - batch-oriented implementation, such as caching of BUILD files, - dependency graphs, and other metadata from one build to the - next. This improves the speed of incremental builds, and allows - different commands, such as <code>build</code> - and <code>query</code> to share the same cache of loaded packages, - making queries very fast. -</p> -<p> - When you run <code>bazel</code>, you're running the client. The - client finds the server based on the output base, which by default is - determined by the path of the base workspace directory and your - userid, so if you build in multiple workspaces, you'll have multiple - output bases and thus multiple Bazel server processes. Multiple - users on the same workstation can build concurrently in the same - workspace because their output bases will differ (different userids). - If the client cannot find a running server instance, it starts a new - one. The server process will stop after a period of inactivity (3 hours, - by default). -</p> -<p> - For the most part, the fact that there is a server running is - invisible to the user, but sometimes it helps to bear this in mind. - For example, if you're running scripts that perform a lot of - automated builds in different directories, it's important to ensure - that you don't accumulate a lot of idle servers; you can do this by - explicitly shutting them down when you're finished with them, or by - specifying a short timeout period. -</p> -<p> - The name of a Bazel server process appears in the output of <code>ps - x</code> or <code>ps -e f</code> as - <code>bazel(<i>dirname</i>)</code>, where <i>dirname</i> is the - basename of the directory enclosing the root your workspace directory. - For example: -</p> -<pre> - % ps -e f - 16143 ? Sl 3:00 bazel(src-jrluser2) -server -Djava.library.path=... -</pre> -<p> - This makes it easier to find out which server process belongs to a - given workspace. (Beware that with certain other options - to <code>ps</code>, Bazel server processes may be named just - <code>java</code>.) Bazel servers can be stopped using - the <a href='#shutdown'>shutdown</a> command. -</p> -<p> - You can also run Bazel in batch mode using the <code>--batch</code> - startup flag. This will immediately shut down the process after the - command (build, test, etc.) has finished and not keep a server process - around. -</p> - -<p> - When running <code>bazel</code>, the client first checks that the - server is the appropriate version; if not, the server is stopped and - a new one started. This ensures that the use of a long-running - server process doesn't interfere with proper versioning. -</p> - -<h3 id='bazelrc'><code>.bazelrc</code>, the Bazel configuration file, -the <code class='flag'>--bazelrc=<var>file</var></code> option, and the -<code class='flag'>--config=<var>value</var></code> option</h3> - -<p> - Bazel accepts many options. Typically, some of these are varied - frequently (e.g. <code class='flag'>--subcommands</code>) while others stay the - same across several builds (e.g. <code class='flag'>--package_path</code>). - To avoid having to specify these constant options every time you do - a build or run some other Bazel command, Bazel allows you to - specify options in a configuration file. -</p> -<p> - Bazel looks for an optional configuration file in the location - specified by the <code class='flag'>--bazelrc=<var>file</var></code> option. If - this option is not specified then, by default, Bazel looks for the - file called <code>.bazelrc</code> in one of two directories: first, - in your base workspace directory, then in your home directory. If - it finds a file in the first (workspace-specific) location, it will - not look at the second (global) location. -</p> -<p> - The <code class='flag'>--bazelrc=<var>file</var></code> option must - appear <em>before</em> the command name (e.g. <code>build</code>). -</p> -<p> - The option <code class='flag'>--bazelrc=/dev/null</code> effectively disables the - use of a configuration file. We strongly recommend that you use - this option when performing release builds, or automated tests that - invoke Bazel. -</p> - -<p> - Aside from the configuration file described above, Bazel also looks - for a master configuration file next to the binary, in the workspace - at <code>tools/bazel.rc</code> or system-wide at - <code>/etc/bazel.bazelrc</code>. These files are here to support - installation-wide options or options shared between users. -</p> -<p> - Like all UNIX "rc" files, the <code>.bazelrc</code> file is a text - file with a line-based grammar. Lines starting <code>#</code> are - considered comments and are ignored, as are blank lines. Each line - contains a sequence of words, which are tokenized according to the - same rules as the Bourne shell. - The first word on each line is the name of a Bazel command, such - as <code>build</code> or <code>query</code>. The remaining words - are the default options that apply to that command. - More than one line may be used for a command; the options are combined - as if they had appeared on a single line. - (Users of CVS, another tool with a "Swiss army knife" command-line - interface, will find the syntax familiar to that of <code>.cvsrc</code>.) -</p> -<p> - Startup options may be specified in the - <code>.bazelrc</code> file using the command <code>startup</code>. - These options are described in the interactive help - at <code>bazel help startup_options</code>. -</p> -<p> - Options specified in the command line always take precedence over - those from a configuration file. In configuration files, lines for a more specific command take - precedence over lines for a less specific command (e.g. the 'test' command inherits all the - options from the 'build' command, so a 'test --foo=bar' line takes precedence over a - 'build --foo=baz' line, regardless of which configuration files these two lines are in) and lines - equally specific for which command they apply have precedence based on the configuration file they - are in, with the user-specific configuration file taking precedence over the master one. -</p> -<p> - Options may include words other than flags, such as the names of - build targets, etc; these are always prepended to the explicit - argument list provided on the command-line, if any. -</p> -<p> - Common command options may be specified in the - <code>.bazelrc</code> file using the command <code>common</code>. -</p> -<p> - In addition, commands may have <code>:name</code> suffixes. These - options are ignored by default, but can be pulled in through the - <code>--config=<var>name</var></code> option, either on the command line or in - a <code>.bazelrc</code> file. The intention is that these bundle command line - options that are commonly used together, for example - <code>--config=memcheck</code>. -</p> -<p> - Note that some config sections are defined in the master bazelrc file. - To avoid conflicts, user-defined sections - should start with the '_' (underscore) character. -</p> -<p> - The command named <code>import</code> is special: if Bazel encounters such - a line in a <code>.bazelrc</code> file, it parses the contents of the file - referenced by the import statement, too. Options specified in an imported file - take precedence over ones specified before the import statement, options - specified after the import statement take precedence over the ones in the - imported file, and options in files imported later take precedence over files - imported earlier. -</p> -<p> - Here's an example <code>~/.bazelrc</code> file: -</p> -<pre> - # Bob's Bazel option defaults - - startup --batch --host_jvm_args=-XX:-UseParallelGC - import /home/bobs_project/bazelrc - build --show_timestamps --keep_going --jobs 600 - build --color=yes - query --keep_going - - build:memcheck --strip=never --test_timeout=3600 -</pre> - -<h2 id='build'>Building programs with Bazel</h2> -<h3>The <code>build</code> command</h3> - -<p> - The most important function of Bazel is, of course, building code. Type - <code>bazel build</code> followed by the name of the - <a href="#target-patterns">target</a> you wish to build. Here's a typical - session: -</p> -<pre> - % bazel build //foo - ____Loading package: foo - ____Loading package: bar - ____Loading package: baz - ____Loading complete. Analyzing... - ____Building 1 target... - ____[0 / 3] Executing Genrule //bar:helper_rule - ____[1 / 3] Executing Genrule //baz:another_helper_rule - ____[2 / 3] Building foo/foo.bin - Target //foo:foo up-to-date: - bazel-bin/foo/foo.bin - bazel-bin/foo/foo - ____Elapsed time: 9.905s -</pre> -<p> - Bazel prints the progress messages as it loads all the - packages in the transitive closure of dependencies of the requested - target, then analyzes them for correctness and to create the build actions, - finally executing the compilers and other tools of the build. -</p> -<p> - Bazel prints progress messages during - the <a href='#execution-phase'>execution phase</a> of the build, showing the - current build step (compiler, linker, etc.) that is being started, - and the number of completed over total number of build actions. As the - build starts the number of total actions will often increase as Bazel - discovers the entire action graph, but the number will usually stabilize - within a few seconds. -</p> -<p> - At the end of the build Bazel - prints which targets were requested, whether or not they were - successfully built, and if so, where the output files can be found. - Scripts that run builds can reliably parse this output; see <a - href='#flag--show_result'><code class='flag'>--show_result</code></a> for more - details. -</p> -<p> - Typing the same command again: -</p> -<pre> - % bazel build //foo - ____Loading... - ____Found 1 target... - ____Building complete. - Target //foo:foo up-to-date: - bazel-bin/foo/foo.bin - bazel-bin/foo/foo - ____Elapsed time: 0.280s -</pre> -<p> - we see a "null" build: in this case, there are no packages to - re-load, since nothing has changed, and no build steps to execute. - (If something had changed in "foo" or some of its dependencies, resulting in the - reexecution of some build actions, we would call it an "incremental" build, not a - "null" build.) -</p> - -<p> - Before you can start a build, you will need a Bazel workspace. This is - simply a directory tree that contains all the source files needed to build - your application. - Bazel allows you to perform a build from a completely read-only volume. -</p> - -<h4 id='flag--package_path'>Setting up a <code class='flag'>--package_path</code></h4> -<p> - Bazel finds its packages by searching the package path. This is a colon - separated ordered list of bazel directories, each being the root of a - partial source tree. -</p> - -<p> - <i>To specify a custom package path</i> using the - <code class='flag'>--package_path</code> option: -</p> -<pre> - % bazel build --package_path %workspace%:/some/other/root -</pre> -<p> -Package path elements may be specified in three formats: -</p> -<ol> - <li> - If the first character is <code>/</code>, the path is absolute. - </li> - <li> - If the path starts with <code>%workspace%</code>, the path is taken relative - to the nearest enclosing bazel directory.<br> - For instance, if your working directory - is <code>/home/bob/clients/bob_client/bazel/foo</code>, then the - string <code>%workspace%</code> in the package-path is expanded - to <code>/home/bob/clients/bob_client/bazel</code>. - </li> - <li> - Anything else is taken relative to the working directory.<br> This is usually not what you mean to do, - and may behave unexpectedly if you use Bazel from directories below the bazel workspace. - For instance, if you use the package-path element <code>.</code>, - and then cd into the directory - <code>/home/bob/clients/bob_client/bazel/foo</code>, packages - will be resolved from the - <code>/home/bob/clients/bob_client/bazel/foo</code> directory. - </li> -</ol> -<p> - If you use a non-default package path, we recommend that you specify - it in your <a href='#bazelrc'>Bazel configuration file</a> for - convenience. -</p> -<p> - <i>Bazel doesn't require any packages to be in the - current directory</i>, so you can do a build from an empty bazel - workspace if all the necessary packages can be found somewhere else - on the package path. -</p> -<p> - <i>Example</i>: Building from an empty client -</p> -<pre> - % mkdir -p foo/bazel - % cd foo/bazel - % bazel build --package_path /some/other/path //foo -</pre> -<h3 id='target-patterns'>Specifying targets to build</h3> -<p> - Bazel allows a number of ways to specify the targets to be built. - Collectively, these are known as <i>target patterns</i>. - The on-line help displays a summary of supported patterns: -</p> -<pre> -% bazel help target-syntax - -Target pattern syntax -===================== - -The BUILD file label syntax is used to specify a single target. Target -patterns generalize this syntax to sets of targets, and also support -working-directory-relative forms, recursion, subtraction and filtering. -Examples: - -Specifying a single target: - - //foo/bar:wiz The single target '//foo/bar:wiz'. - foo/bar/wiz Equivalent to: - '//foo/bar/wiz:wiz' if foo/bar/wiz is a package, - '//foo/bar:wiz' if foo/bar is a package, - '//foo:bar/wiz' otherwise. - //foo/bar Equivalent to '//foo/bar:bar'. - -Specifying all rules in a package: - - //foo/bar:all Matches all rules in package 'foo/bar'. - -Specifying all rules recursively beneath a package: - - //foo/...:all Matches all rules in all packages beneath directory 'foo'. - //foo/... (ditto) - - By default, directory symlinks are followed when performing this recursive traversal, except - those that point to under the output base (for example, the convenience symlinks that are created - in the root directory of the workspace) But we understand that your workspace may intentionally - contain directories with unusual symlink structures that you don't want consumed. As such, if a - directory has a file named - 'DONT_FOLLOW_SYMLINKS_WHEN_TRAVERSING_THIS_DIRECTORY_VIA_A_RECURSIVE_TARGET_PATTERN' then symlinks - in that directory won't be followed when evaluating recursive target patterns. - -Working-directory relative forms: (assume cwd = 'workspace/foo') - - Target patterns which do not begin with '//' are taken relative to - the working directory. Patterns which begin with '//' are always - absolute. - - ...:all Equivalent to '//foo/...:all'. - ... (ditto) - - bar/...:all Equivalent to '//foo/bar/...:all'. - bar/... (ditto) - - bar:wiz Equivalent to '//foo/bar:wiz'. - :foo Equivalent to '//foo:foo'. - - bar Equivalent to '//foo/bar:bar'. - foo/bar Equivalent to '//foo/foo/bar:bar'. - - bar:all Equivalent to '//foo/bar:all'. - :all Equivalent to '//foo:all'. - -Summary of target wildcards: - - :all, Match all rules in the specified packages. - :*, :all-targets Match all targets (rules and files) in the specified - packages, including ones not built by default, such - as _deploy.jar files. - -Subtractive patterns: - - Target patterns may be preceded by '-', meaning they should be - subtracted from the set of targets accumulated by preceding - patterns. (Note that this means order matters.) For example: - - % bazel build -- foo/... -foo/contrib/... - - builds everything in 'foo', except 'contrib'. In case a target not - under 'contrib' depends on something under 'contrib' though, in order to - build the former bazel has to build the latter too. As usual, the '--' is - required to prevent '-f' from being interpreted as an option. -</pre> -<p> - Whereas <a href="build-ref.html#labels">labels</a> are used - to specify individual targets, e.g. for declaring dependencies in - BUILD files, Bazel's target patterns are a syntax for specifying - multiple targets: they are a generalization of the label syntax - for <i>sets</i> of targets, using wildcards. In the simplest case, - any valid label is also a valid target pattern, identifying a set of - exactly one target. -</p> -<p> - <code>foo/...</code> is a wildcard over <em>packages</em>, - indicating all packages recursively beneath - directory <code>foo</code> (for all roots of the package - path). <code>:all</code> is a wildcard - over <em>targets</em>, matching all rules within a package. These two may be - combined, as in <code>foo/...:all</code>, and when both wildcards - are used, this may be abbreviated to <code>foo/...</code>. -</p> -<p> - In addition, <code>:*</code> (or <code>:all-targets</code>) is a - wildcard that matches <em>every target</em> in the matched packages, - including files that aren't normally built by any rule, such - as <code>_deploy.jar</code> files associated - with <code>java_binary</code> rules. -</p> -<p> - This implies that <code>:*</code> denotes a <em>superset</em> - of <code>:all</code>; while potentially confusing, this syntax does - allow the familiar <code>:all</code> wildcard to be used for - typical builds, where building targets like the <code>_deploy.jar</code> - is not desired. -</p> -<p> - In addition, Bazel allows a slash to be used instead of the colon - required by the label syntax; this is often convenient when using - Bash filename expansion. For example, <code>foo/bar/wiz</code> is - equivalent to <code>//foo/bar:wiz</code> (if there is a - package <code>foo/bar</code>) or to <code>//foo:bar/wiz</code> (if - there is a package <code>foo</code>). -</p> -<p> - Many Bazel commands accept a list of target patterns as arguments, - and they all honor the prefix negation operator `<code>-</code>'. - This can be used to subtract a set of targets from the set specified - by the preceding arguments. (Note that this means order matters.) - For example, -</p> -<pre> - bazel build foo/... bar/... -</pre> -<p> - means "build all - targets beneath <code>foo</code> <i>and</i> all targets - beneath <code>bar</code>", whereas -</p> -<pre> - bazel build -- foo/... -foo/bar/... -</pre> -<p> - means "build all targets beneath <code>foo</code> <i>except</i> - those beneath <code>foo/bar</code>". - - (The <code>--</code> argument is required to prevent the subsequent - arguments starting with <code>-</code> from being interpreted as - additional options.) -</p> -<p> - It's important to point out though that subtracting targets this way will not - guarantee that they are not built, since they may be dependencies of targets - that weren't subtracted. For example, if there were a target - <code>//foo:all-apis</code> that among others depended on - <code>//foo/bar:api</code>, then the latter would be built as part of - building the former. -</p> -<p> - Targets with <code>tags=["manual"]</code> will not be included in wildcard target patterns (..., - :*, :all, etc). You should specify such test targets with explicit target patterns on the command - line if you want Bazel to build/test them. -</p> - -<h3 id='fetch'>Fetching external dependencies</h3> - -<p> - By default, Bazel will download and symlink external dependencies during the - build. However, this can be undesirable, either because you'd like to know - when new external dependendencies are added or because you'd like to - "prefetch" dependencies (say, before a flight where you'll be offline). If you - would like to prevent new dependencies from being added during builds, you - can specify the <code>--fetch=false</code> flag. Note that this flag only - applies to repository rules that do not point to a directory in the local - file system. Changes, for example, to <code>local_repository</code>, - <code>new_local_repository</code> and Android SDK and NDK repository rules - will always take effect regardless of the value <code>--fetch</code> . -</p> - -<p> - If you disallow fetching during builds and Bazel finds new external - dependencies, your build will fail. -</p> - -<p> - You can manually fetch dependencies by running <code>bazel fetch</code>. If - you disallow during-build fetching, you'll need to run <code>bazel - fetch</code>: - <ol> - <li>Before you build for the first time. - <li>After you add a new external dependency. - </ol> - Once it has been run, you should not need to run it again until the WORKSPACE - file changes. -</p> - -<p> - <code>fetch</code> takes a list of targets to fetch dependencies for. For - example, this would fetch dependencies needed to build <code>//foo:bar</code> - and <code>//bar:baz</code>: -<pre> -$ bazel fetch //foo:bar //bar:baz -</pre> -</p> - -<p> - To fetch all external dependencies for a workspace, run: -<pre> -$ bazel fetch //... -</pre> -</p> - -<p> - You do not need to run bazel fetch at all if you have all of the tools you are - using (from library jars to the JDK itself) under your workspace root. - However, if you're using anything outside of the workspace directory then you - will need to run <code>bazel fetch</code> before running - <code>bazel build</code>. -</p> - -<h3 id='configurations'>Build configurations and cross-compilation</h3> - -<p> - 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 information stored in the BUILD - files of your project: the build rule, the values of its attributes, - and the complete set of its transitive dependencies. - The second kind is the external or environmental data, supplied by - the user or by the build tool: the choice of target architecture, - compilation and linking options, and other toolchain configuration - options. We refer to a complete set of environmental data as - a <b>configuration</b>. -</p> -<p> - In any given build, there may be more than one configuration. - Consider a cross-compile, in which you build - a <code>//foo:bin</code> executable for a 64-bit architecture, - but your workstation is a 32-bit machine. Clearly, the build - will require building <code>//foo:bin</code> using a toolchain - capable of creating 64-bit executables, but the build system must - also build various tools used during the build itself—for example - tools that are built from source, then subsequently used in, say, a - genrule—and these must be built to run on your workstation. - Thus we can identify two configurations: the <b>host - configuration</b>, which is used for building tools that run during - the build, and the <b>target configuration</b> (or <i>request - configuration</i>, but we say "target configuration" more often even - though that word already has many meanings), which is - used for building the binary you ultimately requested. -</p> -<p> - Typically, there are many libraries that are prerequisites of both - the requested build target (<code>//foo:bin</code>) and one or more of - the host tools, for example some base libraries. Such libraries must be built - twice, once for the host configuration, and once for the target - configuration.<br/> - Bazel takes care of ensuring that both variants are built, and that - the derived files are kept separate to avoid interference; usually - such targets can be built concurrently, since they are independent - of each other. If you see progress messages indicating that a given - target is being built twice, this is most likely the explanation. -</p> -<p> - Bazel uses one of two ways to select the host configuration, based - on the <code class='flag'>--distinct_host_configuration</code> option. This - boolean option is somewhat subtle, and the setting may improve (or - worsen) the speed of your builds. -</p> - -<h4><code class='flag'>--distinct_host_configuration=false</code></h4> -<p> - When this option is false, the host and - request configurations are identical: all tools required during the - build will be built in exactly the same way as target programs. - This setting means that no libraries need to be built twice during a - single build, so it keeps builds short. - However, it does mean that any change to your request configuration - also affects your host configuration, causing all the tools to be - rebuilt, and then anything that depends on the tool output to be - rebuilt too. Thus, for example, simply changing a linker option - between builds might cause all tools to be re-linked, and then all - actions using them reexecuted, and so on, resulting in a very large rebuild. - Also, please note: if your host architecture is not capable of - running your target binaries, your build will not work. -</p> -<p> - If you frequently make changes to your request configuration, such - as alternating between <code>-c opt</code> and <code>-c dbg</code> - builds, or between simple- and cross-compilation, we do not - recommend this option, as you will typically rebuild the majority of - your codebase each time you switch. -</p> - -<h4><code class='flag'>--distinct_host_configuration=true</code> <i>(default)</i></h4> -<p> - If this option is true, then instead of using the same configuration - for the host and request, a completely distinct host configuration - is used. The host configuration is derived from the target - configuration as follows: -</p> -<ul> - <li>Use the same version of Crosstool - (<code class='flag'>--crosstool_top</code>) as specified in the request - configuration, unless <code class='flag'>--host_crosstool_top</code> is - specified. - </li> - <li> - Use the value of <code class="flag">--host_cpu</code> for - <code class='flag'>--cpu</code> - - (default: <code>k8</code>). - </li> - <li>Use the same values of these options as specified in the request - configuration: - <code class='flag'>--compiler</code>, - <code class='flag'>--use_ijars</code>, - <code class='flag'>--java_toolchain</code>, - If <code class='flag'>--host_crosstool_top</code> is used, then the value of - <code class='flag'>--host_cpu</code> is used to look up a - <code>default_toolchain</code> in the Crosstool - (ignoring <code class='flag'>--compiler</code>) for the host configuration. - </li> - <li>Use optimized builds for C++ code (<code>-c opt</code>). - </li> - <li>Generate no debugging information (<code class='flag'>--copt=-g0</code>). - </li> - <li>Strip debug information from executables and shared libraries - (<code class='flag'>--strip=always</code>). - </li> - <li>Place all derived files in a special location, distinct from - that used by any possible request configuration. - </li> - <li>Suppress stamping of binaries with build data - (see <code class='flag'>--embed_*</code> options). - </li> - <li>All other values remain at their defaults. - </li> -</ul> -<p> - There are many reasons why it might be preferable to select a - distinct host configuration from the request configuration. - Some are too esoteric to mention here, but two of them are worth - pointing out. -</p> -<p> - Firstly, by using stripped, optimized binaries, you reduce the time - spent linking and executing the tools, the disk space occupied by - the tools, and the network I/O time in distributed builds. -</p> -<p> - Secondly, by decoupling the host and request configurations in all - builds, you avoid very expensive rebuilds that would result from - minor changes to the request configuration (such as changing a linker options - does), as described earlier. -</p> -<p> - That said, for certain builds, this option may be a hindrance. In - particular, builds in which changes of configuration are infrequent - (especially certain Java builds), and builds where the amount of code that - must be built in both host and target configurations is large, may - not benefit. -</p> - -<h3 id='correctness'>Correct incremental rebuilds</h3> - -<p> - 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 unsound assumptions in their implementation of - incremental builds. -</p> -<p> - Firstly, that timestamps of files increase monotonically. While - this is the typical case, it is very easy to fall afoul of this - assumption; syncing to an earlier revision of a file causes that file's - modification time to decrease; Make-based systems will not rebuild. -</p> -<p> - More generally, while Make detects changes to files, it does - not detect changes to commands. If you alter the options passed to - the compiler in a given build step, Make will not re-run the - compiler, and it is necessary to manually discard the invalid - outputs of the previous build using <code>make clean</code>. -</p> -<p> - Also, Make is not robust against the unsuccessful termination of one - of its subprocesses after that subprocess has started writing to - its output file. While the current execution of Make will fail, the - subsequent invocation of Make will blindly assume that the truncated - output file is valid (because it is newer than its inputs), and it - will not be rebuilt. Similarly, if the Make process is killed, a - similar situation can occur. -</p> -<p> - Bazel avoids these assumptions, and others. Bazel maintains a database - of all work previously done, and will only omit a build step if it - finds that the set of input files (and their timestamps) to that - build step, and the compilation command for that build step, exactly - match one in the database, and, that the set of output files (and - their timestamps) for the database entry exactly match the - timestamps of the files on disk. Any change to the input files or - output files, or to the command itself, will cause re-execution of - the build step. -</p> -<p> - 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 <code>make clean</code>, whether necessary - or pre-emptive.) -</p> - -<h4>Build consistency and incremental builds</h4> -<p> - Formally, we define the state of a build as <i>consistent</i> when - all the expected output files exist, and their contents are correct, - as specified by the steps or rules required to create them. When - you edit a source file, the state of the build is said to - be <i>inconsistent</i>, and remains inconsistent until you next run - the build tool to successful completion. We describe this situation - as <i>unstable inconsistency</i>, because it is only temporary, and - consistency is restored by running the build tool. -</p> -<p> - There is another kind of inconsistency that is pernicious: <i>stable - inconsistency</i>. If the build reaches a stable inconsistent - state, then repeated successful invocation of the build tool does - not restore consistency: the build has gotten "stuck", and the - outputs remain incorrect. Stable inconsistent states are the main - reason why users of Make (and other build tools) type <code>make - clean</code>. Discovering that the build tool has failed in this - manner (and then recovering from it) can be time consuming and very - frustrating. -</p> -<p> - Conceptually, the simplest way to achieve a consistent build is to - throw away all the previous build outputs and start again: make - every build a clean build. This approach is obviously too - time-consuming to be practical (except perhaps for release - engineers), and therefore to be useful, the build tool must be able - to perform incremental builds without compromising consistency. -</p> -<p> - Correct incremental dependency analysis is hard, and as described - above, many other build tools do a poor job of avoiding stable - inconsistent states during incremental builds. In contrast, Bazel - offers the following guarantee: after a successful invocation of the - build tool during which you made no edits, the build will be in a - consistent state. (If you edit your source files during a build, - Bazel makes no guarantee about the consistency of the result of the - current build. But it does guarantee that the results of - the <i>next</i> build will restore consistency.) -</p> -<p> - As with all guarantees, there comes some fine print: there are some - known ways of getting into a stable inconsistent state with Bazel. - We won't guarantee to investigate such problems arising from deliberate - attempts to find bugs in the incremental dependency analysis, but we - will investigate and do our best to fix all stable inconsistent - states arising from normal or "reasonable" use of the build tool. -</p> -<p> - If you ever detect a stable inconsistent state with Bazel, please report a bug. - -</p> - -<h4 id='sandboxing'>Sandboxed execution</h4> -<p> - Bazel uses sandboxes to guarantee that actions run hermetically<sup>1</sup> and correctly. - Bazel runs <i>Spawn</i>s (loosely speaking: actions) in sandboxes that only contain the minimal - set of files the tool requires to do its job. Currently sandboxing works on Linux 3.12 or newer - with the <code>CONFIG_USER_NS</code> option enabled, and also on Mac OS 10.11 for newer. -</p> -<p> - Bazel will print a warning if your system does not support sandboxing to alert you to the fact - that builds are not guaranteed to be hermetic and might affect the host system in unknown ways. - To disable this warning you can pass the <code>--ignore_unsupported_sandboxing</code> flag to - Bazel. -</p> - -<p> - On some platforms such as <a href="https://cloud.google.com/container-engine/">Google Container - Engine</a> cluster nodes or Debian, user namespaces are deactivated by default due to security - concerns. This can be checked by looking at the file - <code>/proc/sys/kernel/unprivileged_userns_clone</code>: if it exists and contains a 0, then - user namespaces can be activated with <code>sudo sysctl kernel.unprivileged_userns_clone=1</code>. -</p> -<p> - In some cases, the Bazel sandbox fails to execute rules because of the system setup. The symptom - is generally a failure that output a message similar to - <code>namespace-sandbox.c:633: execvp(argv[0], argv): No such file or directory</code>. In that - case, try to deactivate the sandbox for genrules with <code>--genrule_strategy=standalone</code> - and for other rules with <code>--spawn_strategy=standalone</code>. Also please report a bug on our - issue tracker and mention which Linux distribution you're using so that we can investigate and - provide a fix in a subsequent release. -</p> - -<p> - <sup>1</sup>: Hermeticity means that the action only uses its declared input files and no other - files in the filesystem, and it only produces its declared output files. -</p> - -<h3 id='clean'>Deleting the outputs of a build</h3> - -<h4>The <code>clean</code> command</h4> - -<p> - Bazel has a <code>clean</code> command, analogous to that of Make. - It deletes the output directories for all build configurations performed - by this Bazel instance, or the entire working tree created by this - Bazel instance, and resets internal caches. If executed without any - command-line options, then the output directory for all configurations - will be cleaned. -</p> - -<p>Recall that each Bazel instance is associated with a single workspace, thus the - <code>clean</code> command will delete all outputs from all builds you've done - with that Bazel instance in that workspace. -</p> -<p> - To completely remove the entire working tree created by a Bazel - instance, you can specify the <code class='flag'>--expunge</code> option. When - executed with <code class='flag'>--expunge</code>, the clean command simply - removes the entire output base tree which, in addition to the build - output, contains all temp files created by Bazel. It also - stops the Bazel server after the clean, equivalent to the <a - href='#shutdown'><code>shutdown</code></a> command. For example, to - clean up all disk and memory traces of a Bazel instance, you could - specify: -</p> -<pre> - % bazel clean --expunge -</pre> -<p> - Alternatively, you can expunge in the background by using - <code class='flag'>--expunge_async</code>. It is safe to invoke a Bazel command - in the same client while the asynchronous expunge continues to run. - Note, however, that this may introduce IO contention. -</p> - -<p> - The <code>clean</code> command is provided primarily as a means of - reclaiming disk space for workspaces that are no longer needed. - However, we recognize that Bazel's incremental rebuilds might not be - perfect; <code>clean</code> may be used to recover a consistent - state when problems arise. -</p> -<p> - Bazel's design is such that these problems are fixable; we consider - such bugs a high priority, and will do our best fix them. If you - ever find an incorrect incremental build, please file a bug report. - We encourage developers to get out of the habit of - using <code>clean</code> and into that of reporting bugs in the - tools. -</p> - -<h3 id='phases'>Phases of a build</h3> - -<p> - 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). -</p> - -<h4 id='loading-phase'>Loading phase</h4> -<p> - The first is <b>loading</b> during which all the necessary BUILD - files for the initial targets, and their transitive closure of - dependencies, are loaded, parsed, evaluated and cached. -</p> -<p> - For the first build after a Bazel server is started, the loading - phase typically takes many seconds as many BUILD files are loaded - from the file system. In subsequent builds, especially if no BUILD - files have changed, loading occurs very quickly. -</p> -<p> - Errors reported during this phase include: package not found, target - not found, lexical and grammatical errors in a BUILD file, - and evaluation errors. -</p> - -<h4 id='analysis-phase'>Analysis phase</h4> -<p> - The second phase, <b>analysis</b>, involves the semantic analysis - and validation of each build rule, the construction of a build - dependency graph, and the determination of exactly what work is to - be done in each step of the build. -</p> -<p> - Like loading, analysis also takes several seconds when computed in - its entirety. However, Bazel caches the dependency graph from - one build to the next and only reanalyzes what it has to, which can - make incremental builds extremely fast in the case where the - packages haven't changed since the previous build. -</p> -<p> - Errors reported at this stage include: inappropriate dependencies, - invalid inputs to a rule, and all rule-specific error messages. -</p> -<p> - The loading and analysis phases are fast because - Bazel avoids unnecessary file I/O at this stage, reading only BUILD - files in order to determine the work to be done. This is by design, - and makes Bazel a good foundation for analysis tools, such as - Bazel's <a href='#query'>query</a> command, which is implemented - atop the loading phase. -</p> - -<h4 id='execution-phase'>Execution phase</h4> -<p> - The third and final phase of the build is <b>execution</b>. This - phase ensures that the outputs of each step in the build are - consistent with its inputs, re-running compilation/linking/etc. tools as - necessary. This step is where the build spends the majority of - its time, ranging from a few seconds to over an hour for a large - build. Errors reported during this phase include: missing source - files, errors in a tool executed by some build action, or failure of a tool to - produce the expected set of outputs. -</p> - - -<h2>Options</h2> - -<p> - The following sections describe the options available during a - build. When <code class='flag'>--long</code> is used on a help command, the on-line - help messages provide summary information about the meaning, type and - default value for each option. -</p> - -<p> - 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'. -</p> - -<h3>Options that affect how packages are located</h3> - -<p> - See also the <a href='#flag--show_package_location'><code class='flag'>--show_package_location</code></a> - option. -</p> - -<h4 id='flag--package_path'><code class='flag'>--package_path</code></h4> -<p> - This option specifies the set of directories that are searched to - find the BUILD file for a given package. - -</p> - -<h4 id='flag--deleted_packages'><code class='flag'>--deleted_packages</code></h4> -<p> - This option specifies a comma-separated list of packages which Bazel - should consider deleted, and not attempt to load from any directory - on the package path. This can be used to simulate the deletion of packages without - actually deleting them. -</p> - -<h3 id='checking-options'>Error checking options</h3> -<p> - These options control Bazel's error-checking and/or warnings. -</p> - -<h4 id='flag--check_constraint'><code class='flag'>--check_constraint <var>constraint</var></code></h4> -<p> - This option takes an argument that specifies which constraint - should be checked. -</p> -<p> - Bazel performs special checks on each rule that is annotated with the - given constraint. -</p> -<p> - The supported constraints and their checks are as follows: -</p> -<ul> - - <li><code>public</code>: Verify that all java_libraries marked with - <code>constraints = ['public']</code> only depend on java_libraries - that are marked as <code>constraints = ['public']</code> too. If bazel - finds a dependency that does not conform to this rule, bazel will issue - an error. - </li> -</ul> - -<h4 id='flag--check_visibility'><code class='flag'>--[no]check_visibility</code></h4> -<p> - 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. - -</p> - -<h4 id='flag--experimental_action_listener'> - <code class='flag'>--experimental_action_listener=<var>label</var></code> -</h4> -<p> - The <code>experimental_action_listener</code> option instructs Bazel to use - details from the <a href="be/extra-actions.html#action_listener" - ><code>action_listener</code></a> rule specified by <var>label</var> to - insert <a href="be/extra-actions.html#extra_action" - ><code>extra_actions</code></a> into the build graph. -</p> - -<h4 id='flag--experimental_extra_action_filter'> - <code class='flag'>--experimental_extra_action_filter=<var>regex</var></code> -</h4> -<p> - The <code>experimental_extra_action_filter</code> option instructs Bazel to - filter the set of targets to schedule <code>extra_actions</code> for. -</p> -<p> - This flag is only applicable in combination with the - <a href='#flag--experimental_action_listener' - ><code>--experimental_action_listener</code></a> flag. -</p> -<p> - By default all <code>extra_actions</code> in the transitive closure of the - requested targets-to-build get scheduled for execution. - <code>--experimental_extra_action_filter</code> will restrict scheduling to - <code>extra_actions</code> of which the owner's label matches the specified - regular expression. -</p> -<p> - The following example will limit scheduling of <code>extra_actions</code> - to only apply to actions of which the owner's label contains '/bar/': -</p> -<pre>% bazel build --experimental_action_listener=//test:al //foo/... \ - --experimental_extra_action_filter=.*/bar/.* -</pre> - -<h4 id='flag--output_filter'><code class='flag'>--output_filter <var>regex</var></code></h4> -<p> - The <code class='flag'>--output_filter</code> option will only show build and compilation - warnings for targets that match the regular expression. If a target does not - match the given regular expression and its execution succeeds, its standard - output and standard error are thrown away. This option is intended to be used - to help focus efforts on fixing warnings in packages under development. Here - are some typical values for this option: -</p> -<table> - <tr> - <td><code class='flag'>--output_filter=</code></td> - <td>Show all output.</td> - </tr> - <tr> - <td><code class='flag'>--output_filter='^//(first/project|second/project):'</code></td> - <td>Show the output for the specified packages.</td> - </tr> - <tr> - <td><code class='flag'>--output_filter='^//((?!(first/bad_project|second/bad_project):).)*$'</code></td> - <td>Don't show output for the specified packages.</td> - </tr> - <tr> - <td><code class='flag'>--output_filter=DONT_MATCH_ANYTHING</code></td> - <td>Don't show output.</td> - </tr> -</table> - -<h4 id='flag--analysis_warnings_as_errors'><code>--[no]analysis_warnings_as_errors</code></h4> -<p> - When this option is enabled, visible analysis warnings (as specified by - the output filter) are treated as errors, effectively preventing the build - phase from starting. This feature can be used to enable strict builds that - do not allow new warnings to creep into a project. -</p> - -<h3 id='flags-options'>Flags options</h3> -<p> - These options control which options Bazel will pass to other tools. -</p> - -<h4 id='flag--copt'><code class='flag'>--copt <var>gcc-option</var></code></h4> -<p> - This option takes an argument which is to be passed to gcc. - The argument will be passed to gcc whenever gcc is invoked - for preprocessing, compiling, and/or assembling C, C++, or - assembler code. It will not be passed when linking. -</p> -<p> - This option can be used multiple times. - For example: -</p> -<pre> - % bazel build --copt="-g0" --copt="-fpic" //foo -</pre> -<p> - will compile the <code>foo</code> library without debug tables, generating - position-independent code. -</p> -<p> - Note that changing <code class='flag'>--copt</code> settings will force a recompilation - of all affected object files. Also note that copts values listed in specific - cc_library or cc_binary build rules will be placed on the gcc command line - <em>after</em> these options. -</p> -<p> - Warning: C++-specific options (such as <code>-fno-implicit-templates</code>) - should be specified in <code class='flag'>--cxxopt</code>, not in - <code class='flag'>--copt</code>. Likewise, C-specific options (such as -Wstrict-prototypes) - should be specified in <code class='flag'>--conlyopt</code>, not in <code>copt</code>. - Similarly, gcc options that only have an - effect at link time (such as <code>-l</code>) should be specified in - <code class='flag'>--linkopt</code>, not in <code class='flag'>--copt</code>. -</p> - -<h4 id='flag--host_copt'><code class='flag'>--host_copt <var>gcc-option</var></code></h4> -<p> - This option takes an argument which is to be passed to gcc for source files - that are compiled in the host configuration. This is analogous to - the <a href='#flag--copt'><code class='flag'>--copt</code></a> option, but applies only to the - host configuration. -</p> - -<h4 id='flag--host_cxxopt'><code class='flag'>--host_cxxopt <var>gcc-option</var></code></h4> -<p> - This option takes an argument which is to be passed to gcc for source files - that are compiled in the host configuration. This is analogous to - the <a href='#flag--cxxopt'><code class='flag'>--cxxopt</code></a> option, but applies only to the - host configuration. -</p> - -<h4 id='flag--conlyopt'><code class='flag'>--conlyopt <var>gcc-option</var></code></h4> -<p> - This option takes an argument which is to be passed to gcc when compiling C source files. -</p> -<p> - This is similar to <code class='flag'>--copt</code>, but only applies to C compilation, - not to C++ compilation or linking. So you can pass C-specific options - (such as <code>-Wno-pointer-sign</code>) using <code class='flag'>--conlyopt</code>. -</p> -<p> - Note that copts parameters listed in specific cc_library or cc_binary build rules - will be placed on the gcc command line <em>after</em> these options. -</p> - -<h4 id='flag--cxxopt'><code class='flag'>--cxxopt <var>gcc-option</var></code></h4> -<p> - This option takes an argument which is to be passed to gcc when compiling C++ source files. -</p> -<p> - This is similar to <code class='flag'>--copt</code>, but only applies to C++ compilation, - not to C compilation or linking. So you can pass C++-specific options - (such as <code>-fpermissive</code> or <code>-fno-implicit-templates</code>) using <code class='flag'>--cxxopt</code>. - For example: -</p> -<pre> - % bazel build --cxxopt="-fpermissive" --cxxopt="-Wno-error" //foo/cruddy_code -</pre> -<p> - Note that copts parameters listed in specific cc_library or cc_binary build rules - will be placed on the gcc command line <em>after</em> these options. -</p> - -<h4 id='flag--linkopt'><code class='flag'>--linkopt <var>linker-option</var></code></h4> -<p> - This option takes an argument which is to be passed to gcc when linking. -</p> -<p> - This is similar to <code class='flag'>--copt</code>, but only applies to linking, - not to compilation. So you can pass gcc options that only make sense - at link time (such as <code>-lssp</code> or <code>-Wl,--wrap,abort</code>) - using <code class='flag'>--linkopt</code>. For example: -</p> -<pre> - % bazel build --copt="-fmudflap" --linkopt="-lmudflap" //foo/buggy_code -</pre> -<p> - Build rules can also specify link options in their attributes. This option's - settings always take precedence. Also see - <a href="be/c-cpp.html#cc_library.linkopts">cc_library.linkopts</a>. -</p> - -<h4 id='flag--strip'><code class='flag'>--strip (always|never|sometimes)</code></h4> -<p> - This option determines whether Bazel will strip debugging information from - all binaries and shared libraries, by invoking the linker with the <code>-Wl,--strip-debug</code> option. - <code class='flag'>--strip=always</code> means always strip debugging information. - <code class='flag'>--strip=never</code> means never strip debugging information. - The default value of <code class='flag'>--strip=sometimes</code> means strip iff the <code class='flag'>--compilation_mode</code> - is <code>fastbuild</code>. -</p> -<pre> - % bazel build --strip=always //foo:bar -</pre> -<p> - will compile the target while stripping debugging information from all generated - binaries. -</p> -<p> - Note that if you want debugging information, it's not enough to disable stripping; you also need to make - sure that the debugging information was generated by the compiler, which you can do by using either - <code>-c dbg</code> or <code class='flag'>--copt -g</code>. -</p> -<p> - Note also that Bazel's <code class='flag'>--strip</code> option corresponds with ld's <code>--strip-debug</code> option: - it only strips debugging information. If for some reason you want to strip <em>all</em> symbols, - not just <em>debug</em> symbols, you would need to use ld's <code>--strip-all</code> option, - which you can do by passing <code class='flag'>--linkopt=-Wl,--strip-all</code> to Bazel. -</p> - -<h4 id='flag--stripopt'><code class='flag'>--stripopt <var>strip-option</var></code></h4> -<p> - An additional option to pass to the <code>strip</code> command when generating - a <a href="be/c-cpp.html#cc_binary_implicit_outputs"><code>*.stripped</code> - binary</a>. The default is <code>-S -p</code>. This option can be used - multiple times. -</p> -<p> - Note that <code class='flag'>--stripopt</code> does not apply to the stripping of the main - binary with <code><a href='#flag--strip'>--strip</a>=(always|sometimes)</code>. -</p> - -<h4 id='flag--fdo_instrument'><code class='flag'>--fdo_instrument <var>profile-output-dir</var></code></h4> -<p> - The <code class='flag'>--fdo_instrument</code> option enables the generation of - FDO (feedback directed optimization) profile output when the - built C/C++ binary is executed. For GCC, the argument provided is used as a - directory prefix for a per-object file directory tree of .gcda files - containing profile information for each .o file. -</p> -<p> - Once the profile data tree has been generated, the profile tree - should be zipped up, and provided to the - <code class='flag'>--fdo_optimize=<var>profile-zip</var></code> - Bazel option to enable the FDO optimized compilation. - -</p> -<p> - For the LLVM compiler the argument is also the directory under which the raw LLVM profile - data file(s) is dumped, e.g. - <code class='flag'>--fdo_instrument=<var>/path/to/rawprof/dir/</var></code>. -</p> -<p> - The options <code class='flag'>--fdo_instrument</code> and <code class='flag'>--fdo_optimize</code> - cannot be used at the same time. -</p> - -<h4 id='flag--fdo_optimize'><code class='flag'>--fdo_optimize <var>profile-zip</var></code></h4> -<p> - The <code class='flag'>--fdo_optimize</code> option enables the use of the - per-object file profile information to perform FDO (feedback - directed optimization) optimizations when compiling. For GCC, the argument - provided is the zip file containing the previously-generated file tree - of .gcda files containing profile information for each .o file. -</p> -<p> - Alternatively, the argument provided can point to an auto profile - identified by the extension .afdo. - -</p> -<p> - Note that this option also accepts labels that resolve to source files. You - may need to add an <code>exports_files</code> directive to the corresponding package to - make the file visible to Bazel. -</p> -<p> - For the LLVM compiler the argument provided should point to the indexed LLVM - profile output file prepared by the llvm-profdata tool, and should have a .profdata - extension. -</p> -<p> - The options <code class='flag'>--fdo_instrument</code> and <code class='flag'> - --fdo_optimize</code> cannot be used at the same time. -</p> - -<h4 id='flag--lipo'><code class='flag'>--lipo (off|binary)</code></h4> -<p> - The <code class='flag'>--lipo=binary</code> option enables - - LIPO - (Lightweight Inter-Procedural Optimization). LIPO is an extended C/C++ optimization technique - that optimizes code across different object files. It involves compiling each C/C++ source - file differently for every binary. This is in contrast to normal compilation where compilation - outputs are reused. This means that LIPO is more expensive than normal compilation. -</p> -<p> - This option only has an effect when FDO is also enabled (see the - <a href="#flag--fdo_instrument">--fdo_instrument</a> and - <a href="#flag--fdo_optimize">--fdo_options</a>). - Currently LIPO is only supported when building a single <code>cc_binary</code> rule. -</p> -<p>Setting <code>--lipo=binary</code> implicitly sets - <code><a href="#flag--dynamic_mode">--dynamic_mode</a>=off</code>. -</p> - -<h4 id='flag--lipo_context'><code class='flag'>--lipo_context - <var>context-binary</var></code></h4> -<p> - Specifies the label of a <code>cc_binary</code> rule that was used to generate - the profile information for LIPO that was given to - the <a href='#flag--fdo_optimize'><code class='flag'>--fdo_optimize</code></a> option. -</p> -<p> - Specifying the context is mandatory when <code>--lipo=binary</code> is set. - Using this option implicitly also sets - <code><a href="#flag--linkopt">--linkopt</a>=-Wl,--warn-unresolved-symbols</code>. -</p> - -<h4 id='flag--output_symbol_counts'><code class='flag'>--[no]output_symbol_counts</code></h4> -<p> - If enabled, each gold-invoked link of a C++ executable binary will output - a <i>symbol counts</i> file (via the <code>--print-symbol-counts</code> gold - option). For each linker input, the file logs the number of symbols that were - defined and the number of symbols that were used in the binary. - This information can be used to track unnecessary link dependencies. - The symbol counts file is written to the binary's output path with the name - <code>[targetname].sc</code>. -</p> -<p> - This option is disabled by default. -</p> - -<h4 id='flag--jvmopt'><code class='flag'>--jvmopt <var>jvm-option</var></code></h4> -<p> - 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: -</p> -<pre> - % bazel build --jvmopt="-server -Xms256m" java/com/example/common/foo:all -</pre> -<p> - will use the server VM for launching all Java binaries and set the - startup heap size for the VM to 256 MB. -</p> - -<h4 id='flag--javacopt'><code class='flag'>--javacopt <var>javac-option</var></code></h4> -<p> - 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: -</p> -<pre> - % bazel build --javacopt="-g:source,lines" //myprojects:prog -</pre> -<p> - will rebuild a java_binary with the javac default debug info - (instead of the bazel default). -</p> -<p> - 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: -</p> - -<pre> - -source 8 -target 8 -encoding UTF-8 -</pre> -<p> - Note that changing <code class='flag'>--javacopt</code> 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 <em>after</em> these options. -</p> - -<h5 id='-extra_checks'><code>-extra_checks[:(off|on)]</code></h5> - -<p> - This javac option enables extra correctness checks. Any problems found will - be presented as errors. - Either <code>-extra_checks</code> or <code>-extra_checks:on</code> may be used - to force the checks to be turned on. <code>-extra_checks:off</code> completely - disables the analysis. - When this option is not specified, the default behavior is used. -</p> - -<h4 id='flag--strict_java_deps'><code class='flag'>--strict_java_deps - (default|strict|off|warn|error)</code></h4> -<p> - This option controls whether javac checks for missing direct dependencies. - Java targets must explicitly declare all directly used targets as - dependencies. This flag instructs javac to determine the jars actually used - for type checking each java file, and warn/error if they are not the output - of a direct dependency of the current target. -</p> - -<ul> - <li> <code>off</code> means checking is disabled. - </li> - <li> <code>warn</code> means javac will generate standard java warnings of - type <code>[strict]</code> for each missing direct dependency. - </li> - <li> <code>default</code>, <code>strict</code> and <code>error</code> all - mean javac will generate errors instead of warnings, causing the current - target to fail to build if any missing direct dependencies are found. - This is also the default behavior when the flag is unspecified. - </li> -</ul> - -<h3 id='semantics-options'>Semantics options</h3> -<p> - These options affect the build commands and/or the output file contents. -</p> - -<h4 id='flag--compilation_mode'><code class='flag'>--compilation_mode (fastbuild|opt|dbg)</code> (-c)</h4> -<p> - This option takes an argument of <code>fastbuild</code>, <code>dbg</code> - or <code>opt</code>, and affects various C/C++ code-generation - options, such as the level of optimization and the completeness of - debug tables. Bazel uses a different output directory for each - different compilation mode, so you can switch between modes without - needing to do a full rebuild <i>every</i> time. -</p> -<ul> - <li> <code>fastbuild</code> means build as fast as possible: - generate minimal debugging information (<code>-gmlt - -Wl,-S</code>), and don't optimize. This is the - default. Note: <code>-DNDEBUG</code> will <b>not</b> be set. - </li> - <li> <code>dbg</code> means build with debugging enabled (<code>-g</code>), - so that you can use gdb (or another debugger). - </li> - <li> <code>opt</code> means build with optimization enabled and - with <code>assert()</code> calls disabled (<code>-O2 -DNDEBUG</code>). - Debugging information will not be generated in <code>opt</code> mode - unless you also pass <code class='flag'>--copt -g</code>. - </li> -</ul> - -<h4 id='flag--cpu'><code class='flag'>--cpu <var>cpu</var></code></h4> -<p> -This option specifies the target CPU architecture to be used for -the compilation of binaries during the build. -</p> -<p> - -</p> - -<p> - Note that a particular combination of crosstool version, compiler version, - libc version, and target CPU is allowed only if it has been specified - in the currently used CROSSTOOL file. -</p> - -<h4 id='flag--host_cpu'><code class='flag'>--host_cpu <var>cpu</var></code></h4> -<p> - This option specifies the name of the CPU architecture that should be - used to build host tools. -</p> - -<h4 id='flag--fat_apk_cpu'><code class='flag'>--fat_apk_cpu <var>cpu[,cpu]*</var></code></h4> -<p> - The CPUs to build C/C++ libraries for in the transitive <code>deps</code> of - <code>android_binary</code> - - rules. Other C/C++ rules are not affected. For example, if a <code>cc_library</code> - appears in the transitive <code>deps</code> of an <code>android_binary</code> rule and a - <code>cc_binary</code> rule, the <code>cc_library</code> will be built at least twice: - once for each CPU specified with <code class='flag'>--fat_apk_cpu</code> for the - <code>android_binary</code> rule, and once for the CPU specified with - <code class='flag'>--cpu</code> for the <code>cc_binary</code> rule. - -<p> -The default is <code>armeabi-v7a</code>. -</p> - <p> - One <code>.so</code> file will be created and packaged in the APK for - each CPU specified with <code class='flag'>--fat_apk_cpu</code>. The name of the <code>.so</code> - file will be the name of the <code>android_binary</code> rule prefixed with "lib", e.g., if the name - of the <code>android_binary</code> is "foo", then the file will be <code>libfoo.so</code>. - </p> - - <p> - Note that an Android-compatible crosstool must be selected. - If an <code>android_ndk_repository</code> rule is defined in the - WORKSPACE file, an Android-compatible crosstool is automatically selected. - Otherwise, the crostool can be selected using the - <a href='#flag--android_crosstool_top'><code class='flag'>--android_crosstool_top</code></a> - or <a href='#flag--crosstool_top'><code class='flag'>--crosstool_top</code></a> flags. - </p> -</p> - -<h4 id='flag--experimental_skip_static_outputs'><code class='flag'>--experimental_skip_static_outputs</code></h4> -<p> - The <code class='flag'>--experimental_skip_static_outputs</code> option causes all - statically-linked C++ binaries to <b>not</b> be output in any meaningful - way. - -</p> -<p> - If you set this flag, you must also - set <a href="#flag--distinct_host_configuration"><code class='flag'>--distinct_host_configuration</code></a>. - It is also inherently incompatible with running tests — don't use it for - that. This option is experimental and may go away at any time. -</p> - -<h4 id='flag--per_file_copt'><code class='flag'>--per_file_copt - <var>[+-]regex[,[+-]regex]...@option[,option]...</var></code></h4> -<p> - 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 - with the given options. The label matching uses the canonical form of the label - (i.e //<code>package</code>:<code>label_name</code>). - - The execution path is the relative path to your workspace directory including the base name - (including extension) of the C++ file. It also includes any platform dependent prefixes. - Note, that if only one of the label or the execution path matches the options will be used. -</p> -<p> - <b>Notes</b>: - To match the generated files (e.g. genrule outputs) - Bazel can only use the execution path. In this case the regexp shouldn't start with '//' - since that doesn't match any execution paths. Package names can be used like this: - <code class='flag'>--per_file_copt=base/.*\.pb\.cc@-g0</code>. This will match every - <code>.pb.cc</code> file under a directory called <code>base</code>. -</p> -<p> - This option can be used multiple times. -</p> -<p> - The option is applied regardless of the compilation mode used. I.e. it is possible - to compile with <code class='flag'>--compilation_mode=opt</code> and selectively compile some - files with stronger optimization turned on, or with optimization disabled. -</p> -<p> - <b>Caveat</b>: If some files are selectively compiled with debug symbols the symbols - might be stripped during linking. This can be prevented by setting - <code class='flag'>--strip=never</code>. -</p> -<p> - <b>Syntax</b>: <code>[+-]regex[,[+-]regex]...@option[,option]...</code> Where - <code>regex</code> stands for a regular expression that can be prefixed with - a <code>+</code> to identify include patterns and with <code>-</code> to identify - exclude patterns. <code>option</code> stands for an arbitrary option that is passed - to the C++ compiler. If an option contains a <code>,</code> it has to be quoted like so - <code>\,</code>. Options can also contain <code>@</code>, since only the first - <code>@</code> is used to separate regular expressions from options. -</p> -<p> - <b>Example</b>: - <code class='flag'>--per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-O0,-fprofile-arcs</code> - adds the <code>-O0</code> and the <code>-fprofile-arcs</code> options to the command - line of the C++ compiler for all <code>.cc</code> files in <code>//foo/</code> except - <code>file.cc</code>. -</p> -<h4 id='flag--dynamic_mode'><code class='flag'>--dynamic_mode <var>mode</var></code></h4> -<p> - Determines whether C++ binaries will be linked dynamically, interacting with - the <a href='be/c-cpp.html#cc_binary.linkstatic'>linkstatic - attribute</a> on build rules. -</p> - -<p> - Modes: -</p> -<ul> - <li><code>auto</code>: Translates to a platform-dependent mode; - <code>default</code> for linux and <code>off</code> for cygwin.</li> - <li><code>default</code>: Allows bazel to choose whether to link dynamically. - See <a href='be/c-cpp.html#cc_binary.linkstatic'>linkstatic</a> for more - information.</li> - <li><code>fully</code>: Links all targets dynamically. This will speed up - linking time, and reduce the size of the resulting binaries. - - </li> - <li><code>off</code>: Links all targets in - <a href='be/c-cpp.html#cc_binary.linkstatic'>mostly static</a> mode. - If <code>-static</code> is set in linkopts, targets will change to fully - static.</li> -</ul> - -<h4 id='flag--fission'><code class='flag'>--fission (yes|no|[dbg][,opt][,fastbuild])</code></h4> -<p> - Enables - - <a href='https://gcc.gnu.org/wiki/DebugFission'>Fission</a>, - 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. - -</p> -<p> - When set to <code class='flag'>[dbg][,opt][,fastbuild]</code> (example: - <code class='flag'>--fission=dbg,fastbuild</code>), Fission is enabled - only for the specified set of compilation modes. This is useful for bazelrc - settings. When set to <code class='flag'>yes</code>, Fission is enabled - universally. When set to <code class='flag'>no</code>, Fission is disabled - universally. Default is <code class='flag'>dbg</code>. -</p> - -<h4 id='flag--force_ignore_dash_static'><code class='flag'>--force_ignore_dash_static</code></h4> -<p> - If this flag is set, any <code>-static</code> options in linkopts of - <code>cc_*</code> rules BUILD files are ignored. This is only intended as a - workaround for C++ hardening builds. -</p> - -<h4 id='flag--force_pic'><code class='flag'>--[no]force_pic</code></h4> -<p> - If enabled, all C++ compilations produce position-independent code ("-fPIC"), - links prefer PIC pre-built libraries over non-PIC libraries, and links produce - position-independent executables ("-pie"). Default is disabled. -</p> -<p> - Note that dynamically linked binaries (i.e. <code>--dynamic_mode fully</code>) - 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. -</p> - -<h4 id='flag--android_resource_shrinking'><code class='flag'>--android_resource_shrinking</code></h4> -<p> - Selects whether to perform resource shrinking for android_binary rules. Sets the default for the - <a href='be/android.html#android_binary.shrink_resources'>shrink_resources attribute</a> on - android_binary rules; see the documentation for that rule for further details. Defaults to off. -</p> - -<h4 id='flag--custom_malloc'><code class='flag'>--custom_malloc <var>malloc-library-target</var></code></h4> -<p> - When specified, always use the given malloc implementation, overriding all - <code>malloc="target"</code> attributes, including in those targets that use the - default (by not specifying any <code>malloc</code>). -</p> - -<h4 id='flag--crosstool_top'><code class='flag'>--crosstool_top <var>label</var></code></h4> -<p> - 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 - - <code class='flag'>--compiler</code>. -</p> - -<h4 id='flag--host_crosstool_top'><code class='flag'>--host_crosstool_top <var>label</var></code></h4> -<p> - If not specified, bazel uses the value of <code class='flag'>--crosstool_top</code> to compile - code in the host configuration, i.e., tools run during the build. The main purpose of this flag - is to enable cross-compilation. -</p> - -<h4 id='flag--apple_crosstool_top'><code class='flag'>--apple_crosstool_top <var>label</var></code></h4> -<p> - The crosstool to use for compiling C/C++ rules in the transitive <code>deps</code> of - objc_*, ios__*, and apple_* rules. For those targets, this flag overwrites - <code class='flag'>--crosstool_top</code>. -</p> - -<h4 id='flag--android_crosstool_top'><code class='flag'>--android_crosstool_top <var>label</var></code></h4> -<p> - The crosstool to use for compiling C/C++ rules in the transitive <code>deps</code> of - <code>android_binary</code> rules. This is useful if other targets in the - build require a different crosstool. The default is to use the crosstool - generated by the <code>android_ndk_repository</code> rule in the WORKSPACE file. - See also <a href='#flag--fat_apk_cpu'><code class='flag'>--fat_apk_cpu</code></a>. -</p> -<h4 id='flag--compiler'><code class='flag'>--compiler <var>version</var></code></h4> -<p> - This option specifies the C/C++ compiler version (e.g. <code>gcc-4.1.0</code>) - to be used for the compilation of binaries during the build. If you want to - build with a custom crosstool, you should use a CROSSTOOL file instead of - specifying this flag. -</p> -<p> - Note that only certain combinations of crosstool version, compiler version, - libc version, and target CPU are allowed. -</p> - -<h4 id='flag--glibc'><code class='flag'>--glibc <var>version</var></code></h4> -<p> - This option specifies the version of glibc that the target should be linked - against. If you want to build with a custom crosstool, you should use a - CROSSTOOL file instead of specifying this flag. In that case, Bazel will use - the CROSSTOOL file and the following options where appropriate: - <ul> - <li><a href="#flag--cpu"><code class='flag'>--cpu</code></a></li> - - </ul> -</p> -<p> - Note that only certain combinations of crosstool version, compiler version, - glibc version, and target CPU are allowed. -</p> - -<h4 id='flag--android_sdk'><code class='flag'>--android_sdk <var>label</var></code></h4> -<p> - This option specifies the Android SDK/platform toolchain - and Android runtime library that will be used to build any Android-related - rule. - - The Android SDK will be automatically selected if an <code>android_sdk_repository</code> - rule is defined in the WORKSPACE file. -</p> - -<h4 id='flag--java_toolchain'><code class='flag'>--java_toolchain <var>label</var></code></h4> -<p> - This option specifies the label of the java_toolchain used to compile Java - source files. -</p> - -<h4 id='flag--javabase'><code class='flag'>--javabase (<var>path</var>|<var>label</var>)</code></h4> -<p> - This option sets the <i>label</i> or the <i>path</i> of the base Java installation to - use for running JavaBuilder, SingleJar, for <i>bazel run</i> and <i>bazel - test</i>, and for Java binaries built by <code>java_binary</code> and <code>java_test</code> - rules. A path must be to a JDK or JRE directory that contains <code>bin/java</code>. - The various <a href='be/make-variables.html'>"Make" variables</a> for - Java (<code>JAVABASE</code>, <code>JAVA</code>, <code>JAVAC</code> and - <code>JAR</code>) are derived from this option. -</p> - -<p> - This does not select the Java compiler that is used to compile Java - source files. The compiler can be selected by settings the - <a href="#flag--java_toolchain"><code class='flag'>--java_toolchain</code></a> - option. -</p> - -<h3 id='strategy-options'>Build strategy options</h3> -<p> - 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 on the build. -</p> - -<h4 id='flag--spawn_strategy'><code class='flag'>--spawn_strategy <var>strategy</var></code></h4> -<p> - This option controls where and how commands are executed. -</p> -<ul> - - <li> - <code>standalone</code> causes commands to be executed as local subprocesses. - </li> - <li> - <code>sandboxed</code> causes commands to be executed inside a sandbox on the local machine. - This requires that all input files, data dependencies and tools are listed as direct - dependencies in the <code>srcs</code>, <code>data</code> and <code>tools</code> attributes. - This is the default on systems that support sandboxed execution. - </li> - -</ul> - -<h4 id='flag--genrule_strategy'><code class='flag'>--genrule_strategy <var>strategy</var></code></h4> -<p> - This option controls where and how genrules are executed. -</p> -<ul> - - <li> - <code>standalone</code> causes genrules to run as local subprocesses. - </li> - <li> - <code>sandboxed</code> causes genrules to run inside a sandbox on the local machine. - This requires that all input files are listed as direct dependencies in - the <code>srcs</code> attribute, and the program(s) executed are listed - in the <code>tools</code> attribute. - This is the default for Bazel on systems that support sandboxed execution. - </li> - -</ul> - -<h4 id='flag--local_genrule_timeout_seconds'><code class='flag'>--local_genrule_timeout_seconds <var>seconds</var></code></h4> -<p>Sets a timeout value for local genrules with the given number of seconds.</p> - -<h4 id='flag--jobs'><code class='flag'>--jobs <var>n</var></code> (-j)</h4> -<p> - This option, which takes an integer argument, specifies a limit on - the number of jobs that should be executed concurrently during the - execution phase of the build. The default is 200. -</p> -<p> - Note that the number of concurrent jobs that Bazel will run - is determined not only by the <code class='flag'>--jobs</code> setting, but also - by Bazel's scheduler, which tries to avoid running concurrent jobs - that will use up more resources (RAM or CPU) than are available, - based on some (very crude) estimates of the resource consumption - of each job. The behavior of the scheduler can be controlled by - the <code class='flag'>--ram_utilization_factor</code> option. -</p> - -<h4 id='flag--progress_report_interval'><code class='flag'>--progress_report_interval <var>n</var></code></h4> -<p> - - Bazel periodically prints a progress report on jobs that are not - finished yet (e.g. long running tests). This option sets the - reporting frequency, progress will be printed every <code>n</code> - seconds. -</p> -<p> - The default is 0, that means an incremental algorithm: the first - report will be printed after 10 seconds, then 30 seconds and after - that progress is reported once every minute. -</p> - -<h4 id='flag--ram_utilization_factor'><code class='flag'>--ram_utilization_factor</code> <var>percentage</var></h4> -<p> - This option, which takes an integer argument, specifies what percentage - of the system's RAM Bazel should try to use for its subprocesses. - This option affects how many processes Bazel will try to run - in parallel. The default value is 67. - If you run several Bazel builds in parallel, using a lower - value for this option may avoid thrashing and thus improve overall - throughput. Using a value higher than the default is NOT recommended. Note - that Bazel's estimates are very coarse, so the actual RAM usage may be much - higher or much lower than specified. Note also that this option does not - affect the amount of memory that the Bazel server itself will use. -</p> - -<h4 id='flag--local_resources'><code class='flag'>--local_resources</code> <var>availableRAM,availableCPU,availableIO</var></h4> -<p> - This option, which takes three comma-separated floating point arguments, -specifies the amount of local resources that Bazel can take into -consideration when scheduling build and test activities. Option expects amount of -available RAM (in MB), number of CPU cores (with 1.0 representing single full -core) and workstation I/O capability (with 1.0 representing average -workstation). By default Bazel will estimate amount of RAM and number of CPU -cores directly from system configuration and will assume 1.0 I/O resource. -</p> -<p> - If this option is used, Bazel will ignore --ram_utilization_factor. -</p> - -<h4 id='flag--build_runfile_links'><code class='flag'>--[no]build_runfile_links</code></h4> -<p> - This option, which is currently enabled by default, specifies - whether the runfiles symlinks for tests and - <code>cc_binary</code> targets should be built in the output directory. - Using <code class='flag'>--nobuild_runfile_links</code> can be useful - to validate if all targets compile without incurring the overhead - for building the runfiles trees. - - Within Bazel's output tree, the - runfiles symlink tree is typically rooted as a sibling of the corresponding - binary or test. -</p> - -<p> - When tests (or applications) are executed, their - run-time data dependencies are gathered together in one place, and - may be accessed by the test using paths of the form - <code>$TEST_SRCDIR/workspace/<var>packagename</var>/<var>filename</var></code>. - 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 - symbolic links to the required files. As the set of links grows, so - 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. -</p> -<p> - The <code class='flag'>--build_runfile_links</code> flag controls the - construction of the tree of symbolic links (for C++ applications and - tests only). The reasons only C++ non-test rules are affected are numerous - and subtle: C++ builds are more likely to be slower due to runfiles; - no C++ host tools (tools that run during the build) need their runfiles, - so this option can be used by the host configuration; and other rules - (notably Python) need their runfiles for other purposes besides test - execution. -</p> - -<h4 id='flag--discard_analysis_cache'> - <code class='flag'>--[no]discard_analysis_cache</code></h4> -<p> - When this option is enabled, Bazel will discard the analysis cache - right before execution starts, thus freeing up additional memory - (around 10%) for the <a href="#execution-phase">execution phase</a>. - The drawback is that further incremental builds will be slower. -</p> - -<h4 id='flag--keep_going'><code class='flag'>--[no]keep_going</code> (-k)</h4> -<p> - 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 - much as possible even in the face of errors. This option enables - that behavior, and when it is specified, the build will attempt to - build every target whose prerequisites were successfully built, but - will ignore errors. -</p> -<p> - While this option is usually associated with the execution phase of - a build, it also effects the analysis phase: if several targets are - specified in a build command, but only some of them can be - successfully analyzed, the build will stop with an error - unless <code class='flag'>--keep_going</code> is specified, in which case the - build will proceed to the execution phase, but only for the targets - that were successfully analyzed. -</p> - -<h4 id='flag--use_ijars'><code class='flag'>--[no]use_ijars</code></h4> -<p> - This option changes the way <code>java_library</code> targets are - compiled by Bazel. Instead of using the output of a - <code>java_library</code> for compiling dependent - <code>java_library</code> targets, Bazel will create interface jars - that contain only the signatures of non-private members (public, - protected, and default (package) access methods and fields) and use - the interface jars to compile the dependent targets. This makes it - possible to avoid recompilation when changes are only made to - method bodies or private members of a class. -</p> -<p> - Note that using <code class='flag'>--use_ijars</code> might give you a different - error message when you are accidentally referring to a non visible - member of another class: Instead of getting an error that the member - is not visible you will get an error that the member does not exist. -</p> -<p> - Note that changing the <code class='flag'>--use_ijars</code> setting will force - a recompilation of all affected classes. -</p> - -<h4 id='flag--interface_shared_objects'> - <code class='flag'>--[no]interface_shared_objects</code> -</h4> -<p> - This option enables <i>interface shared objects</i>, which makes binaries and - other shared libraries depend on the <i>interface</i> of a shared object, - rather than its implementation. When only the implementation changes, Bazel - can avoid rebuilding targets that depend on the changed shared library - unnecessarily. -</p> - -<h3 id='output-selection-options'>Output selection options</h3> -<p> - These options determine what to build or test. -</p> - -<h4 id="nobuild"><code class='flag'>--[no]build</code></h4> -<p> - 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 - skipped, and only the first two phases, loading and analysis, occur. -</p> -<p> - This option can be useful for validating BUILD files and detecting - errors in the inputs, without actually building anything. -</p> - -<h4 id='flag--build_tests_only'><code class='flag'>--[no]build_tests_only</code></h4> -<p> - If specified, Bazel will build only what is necessary to run the *_test - and test_suite rules that were not filtered due to their - <a href='#flag--test_size_filters'>size</a>, - <a href='#flag--test_timeout_filters'>timeout</a>, - <a href='#flag--test_tag_filters'>tag</a>, or - <a href='#flag--test_lang_filters'>language</a>. - If specified, Bazel will ignore other targets specified on the command line. - By default, this option is disabled and Bazel will build everything - requested, including *_test and test_suite rules that are filtered out from - testing. This is useful because running - <code>bazel test --build_tests_only foo/...</code> may not detect all build - breakages in the <code>foo</code> tree. -</p> - -<h4 id='flag--check_up_to_date'><code class='flag'>--[no]check_up_to_date</code></h4> -<p> - This option causes Bazel not to perform a build, but merely check - whether all specified targets are up-to-date. If so, the build - completes successfully, as usual. However, if any files are out of - date, instead of being built, an error is reported and the build - fails. This option may be useful to determine whether a build has - been performed more recently than a source edit (e.g. for pre-submit - checks) without incurring the cost of a build. -</p> -<p> - See also <a href="#flag--check_tests_up_to_date"><code class='flag'>--check_tests_up_to_date</code></a>. -</p> - -<h4 id='flag--compile_one_dependency'><code class='flag'>--[no]compile_one_dependency</code></h4> -<p> - Compile a single dependency of the argument files. This is useful for - syntax checking source files in IDEs, for example, by rebuilding a single - target that depends on the source file to detect errors as early as - possible in the edit/build/test cycle. This argument affects the way all - non-flag arguments are interpreted: for each source filename, one - rule that depends on it will be built. For - - C++ and Java - sources, rules in the same language space are preferentially chosen. For - 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. -</p> - -<h4 id='flag--save_temps'><code class='flag'>--save_temps</code></h4> -<p> - The <code class='flag'>--save_temps</code> option causes temporary outputs from gcc to be saved. - These include .s files (assembler code), .i (preprocessed C) and .ii - (preprocessed C++) files. These outputs are often useful for debugging. Temps will only be - generated for the set of targets specified on the command line. -</p> -<p> - Note that our implementation of <code class='flag'>--save_temps</code> does not use gcc's - <code>-save-temps</code> flag. Instead, we do two passes, one with <code>-S</code> - and one with <code>-E</code>. A consequence of this is that if your build fails, - Bazel may not yet have produced the ".i" or ".ii" and ".s" files. - If you're trying to use <code class='flag'>--save_temps</code> to debug a failed compilation, - you may need to also use <code class='flag'>--keep_going</code> so that Bazel will still try to - produce the preprocessed files after the compilation fails. -</p> -<p> - The <code class='flag'>--save_temps</code> flag currently works only for cc_* rules. -</p> -<p> - To ensure that Bazel prints the location of the additional output files, check that - your <a href='#flag--show_result'><code class='flag'>--show_result <var>n</var></code></a> - setting is high enough. -</p> - -<h4 id='flag--build_tag_filters'><code class='flag'>--build_tag_filters <var>tag[,tag]*</var></code></h4> -<p> - 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 - filter is specified as comma delimited list of tag keywords, optionally - preceded with '-' sign used to denote excluded tags. Required tags may also - have a preceding '+' sign. -</p> - -<h4 id='flag--test_size_filters'><code class='flag'>--test_size_filters <var>size[,size]*</var></code></h4> -<p> - If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code> - is also specified) only test targets with the given size. Test size filter - 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, -</p> -<pre> - % bazel test --test_size_filters=small,medium //foo:all -</pre> - and -<pre> - % bazel test --test_size_filters=-large,-enormous //foo:all -</pre> -<p> - will test only small and medium tests inside //foo. -</p> -<p> - By default, test size filtering is not applied. -</p> - -<h4 id='flag--test_timeout_filters'><code class='flag'>--test_timeout_filters <var>timeout[,timeout]*</var></code></h4> -<p> - If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code> - is also specified) only test targets with the given timeout. Test timeout filter - is specified as comma delimited list of allowed test timeout values (short, - moderate, long or eternal), optionally preceded with '-' sign used to denote - excluded test timeouts. See <a href='#flag--test_size_filters'>--test_size_filters</a> - for example syntax. -</p> -<p> - By default, test timeout filtering is not applied. -</p> - - -<h4 id='flag--test_tag_filters'><code class='flag'>--test_tag_filters <var>tag[,tag]*</var></code></h4> -<p> - If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code> - is also specified) only test targets that have at least one required tag - (if any of them are specified) and does not have any excluded tags. Test tag - filter is specified as comma delimited list of tag keywords, optionally - preceded with '-' sign used to denote excluded tags. Required tags may also - have a preceding '+' sign. -</p> -<p> - For example, -<pre> - % bazel test --test_tag_filters=performance,stress,-flaky //myproject:all -</pre> -<p> - will test targets that are tagged with either <code>performance</code> or - <code>stress</code> tag but are <b>not</b> tagged with the <code>flaky</code> - tag. -</p> -<p> - By default, test tag filtering is not applied. Note that you can also filter - on test's <code>size</code> and <code>local</code> tags in - this manner. -</p> - -<h4 id='flag--test_lang_filters'><code class='flag'>--test_lang_filters <var>lang[,lang]*</var></code></h4> -<p> - Specifies a comma-separated list of test languages for languages with an official <code>*_test</code> rule the - (see <a href="be/overview.html">build encyclopedia</a> for a full list of these). Each - language can be optionally preceded with '-' to specify excluded - languages. The name used for each language should be the same as - the language prefix in the <code>*_test</code> rule, for example, - <code>cc</code>, <code>java</code> or <code>sh</code>. -</p> -<p> - If specified, Bazel will test (or build if <code class='flag'>--build_tests_only</code> - is also specified) only test targets of the specified language(s). -</p> -<p> - For example, -</p> -<pre> - % bazel test --test_lang_filters=cc,java foo/... -</pre> -<p> - will test only the C/C++ and Java tests (defined using - <code>cc_test</code> and <code>java_test</code> rules, respectively) - in <code>foo/...</code>, while -</p> -<pre> - % bazel test --test_lang_filters=-sh,-java foo/... -</pre> -<p> - will run all of the tests in <code>foo/...</code> except for the - <code>sh_test</code> and <code>java_test</code> tests. -</p> -<p> - By default, test language filtering is not applied. -</p> - -<h4 id="flag--test_filter"><code class='flag'>--test_filter=<var>filter-expression</var></code></h4> -<p> - 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. -</p> -<p> - The particular interpretation of <var>filter-expression</var> is up to - the test framework responsible for running the test. It may be a glob, - substring, or regexp. <code class='flag'>--test_filter</code> is a convenience - over passing different <code class='flag'>--test_arg</code> filter arguments, - but not all frameworks support it. -</p> - -<h3>Verbosity options: options that control what Bazel prints</h3> - -These options control the verbosity of Bazel's output, -either to the terminal, or to additional log files. - -<h4 id='flag--explain'><code class='flag'>--explain <var>logfile</var></code></h4> -<p> - This option, which requires a filename argument, causes the - dependency checker in <code>bazel build</code>'s execution phase to - explain, for each build step, either why it is being executed, or - that it is up-to-date. The explanation is written - to <i>logfile</i>. -</p> -<p> - If you are encountering unexpected rebuilds, this option can help to - understand the reason. Add it to your <code>.bazelrc</code> so that - logging occurs for all subsequent builds, and then inspect the log - 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. -</p> - -<h4 id='flag--verbose_explanations'><code class='flag'>--verbose_explanations</code></h4> -<p> - This option increases the verbosity of the explanations generated - when the <a href='#flag--explain'>--explain</a> option is enabled. -</p> -<p> - In particular, if verbose explanations are enabled, - and an output file is rebuilt because the command used to - build it has changed, then the output in the explanation file will - include the full details of the new command (at least for most - commands). -</p> -<p> - Using this option may significantly increase the length of the - generated explanation file and the performance penalty of using - <code class='flag'>--explain</code>. -</p> -<p> - If <code class='flag'>--explain</code> is not enabled, then - <code class='flag'>--verbose_explanations</code> has no effect. -</p> - -<h4 id='flag--profile'><code class='flag'>--profile <var>file</var></code></h4> -<p> - 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 - <code>bazel analyze-profile</code> command. The Build profile can be useful in - understanding where Bazel's <code>build</code> command is spending its time. -</p> - -<h4 id='flag--show_loading_progress'><code class='flag'>--[no]show_loading_progress</code></h4> -<p> - This option causes Bazel to output package-loading progress - messages. If it is disabled, the messages won't be shown. -</p> - -<h4 id='flag--show_progress'><code class='flag'>--[no]show_progress</code></h4> -<p> - This option causes progress messages to be displayed; it is on by - default. When disabled, progress messages are suppressed. -</p> - -<h4 id='flag--show_progress_rate_limit'><code class='flag'>--show_progress_rate_limit - <var>n</var></code></h4> -<p> - This option causes bazel to display only - one progress message per <code>n</code> seconds, where <var>n</var> is a real number. - If <code>n</code> is -1, all progress messages will be displayed. The default value for - this option is 0.03, meaning bazel will limit the progress messages to one per every - 0.03 seconds. -</p> - -<h4 id='flag--show_result'><code class='flag'>--show_result <var>n</var></code></h4> -<p> - This option controls the printing of result information at the end - of a <code>bazel build</code> command. By default, if a single - build target was specified, Bazel prints a message stating whether - or not the target was successfully brought up-to-date, and if so, - the list of output files that the target created. If multiple - targets were specified, result information is not displayed. -</p> -<p> - While the result information may be useful for builds of a single - target or a few targets, for large builds (e.g. an entire top-level - project tree), this information can be overwhelming and distracting; - this option allows it to be controlled. <code class='flag'>--show_result</code> - takes an integer argument, which is the maximum number of targets - for which full result information should be printed. By default, - the value is 1. Above this threshold, no result information is - shown for individual targets. Thus zero causes the result - information to be suppressed always, and a very large value causes - the result to be printed always. -</p> -<p> - Users may wish to choose a value in-between if they regularly - alternate between building a small group of targets (for example, - during the compile-edit-test cycle) and a large group of targets - (for example, when establishing a new workspace or running - regression tests). In the former case, the result information is - very useful whereas in the latter case it is less so. As with all - options, this can be specified implicitly via - the <a href='#bazelrc'><code>.bazelrc</code></a> file. -</p> -<p> - The files are printed so as to make it easy to copy and paste the - filename to the shell, to run built executables. The "up-to-date" - or "failed" messages for each target can be easily parsed by scripts - which drive a build. -</p> - -<h4 id='flag--subcommands'><code class='flag'>--subcommands</code> (<code>-s</code>)</h4> -<p> - This option causes Bazel's execution phase to print the full command line - for each command prior to executing it. -</p> - -<pre> - >>>>> # //examples/cpp:hello-world [action 'Linking examples/cpp/hello-world'] - (cd /home/jrluser/.cache/bazel/_bazel_jrluser/4c084335afceb392cfbe7c31afee3a9f/bazel && \ - exec env - \ - /usr/bin/gcc -o bazel-out/local_linux-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) -</pre> -<p> - 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. - (The surrounding parentheses are provided to protect your shell from the - <code>cd</code> and <code>exec</code> calls; be sure to copy them!) - However some commands are implemented internally within Bazel, such as - creating symlink trees. For these there's no command line to display. - -</p> - -<p> - See also <a href="#flag--verbose_failures">--verbose_failures</a>, below. -</p> - -<h4 id='flag--verbose_failures'><code class='flag'>--verbose_failures</code></h4> -<p> - This option causes Bazel's execution phase to print the full command line - for commands that failed. This can be invaluable for debugging a - failing build. -</p> -<p> - Failing commands are printed in a Bourne shell compatible syntax, suitable - for copying and pasting to a shell prompt. -</p> - -<h4 id='flag--stamp'><code class='flag'>--[no]stamp</code></h4> -<p> - This option controls whether stamping is enabled for - rule types that support it. For most of the supported rule types stamping is - enabled by default (e.g. <code>cc_binary</code>). - - By default, stamping is disabled for all tests. Specifying - <code class='flag'>--stamp</code> does not force affected targets to be rebuilt, - if their dependencies have not changed. -</p> - -<p> - Stamping can be enabled or disabled explicitly in BUILD using - the <code>stamp</code> attribute of certain rule types, please refer to - the <a href="be/overview.html">build encyclopedia</a> for details. For - rules that are neither explicitly or implicitly configured as <code>stamp = - 0</code> or <code>stamp = 1</code>, the <code class='flag'>--[no]stamp</code> option - selects whether stamping is enabled. Bazel never stamps binaries that are - built for the host configuration, regardless of the stamp attribute. -</p> - -<h3 id='misc_build_options'>Miscellaneous options</h3> - -<h4 id='flag--symlink_prefix'><code class='flag'>--symlink_prefix <var>string</var></code></h4> -<p> - Changes the prefix of the generated convenience symlinks. The - default value for the symlink prefix is <code>bazel-</code> which - will create the symlinks <code>bazel-bin</code>, <code>bazel-testlogs</code>, and - <code>bazel-genfiles</code>. -</p> -<p> - If the symbolic links cannot be created for any reason, a warning is - issued but the build is still considered a success. In particular, - this allows you to build in a read-only directory or one that you have no - permission to write into. Any paths printed in informational - messages at the conclusion of a build will only use the - symlink-relative short form if the symlinks point to the expected - location; in other words, you can rely on the correctness of those - paths, even if you cannot rely on the symlinks being created. -</p> -<p> - Some common values of this option: -</p> -<ul> - - <li> - <p><b>Suppress symlink creation:</b> - <code class='flag'>--symlink_prefix=/</code> will cause Bazel to not - create or update any symlinks, including the <code>bazel-out</code> and - - <code>bazel-<workspace></code> - symlinks. Use this option to suppress symlink creation entirely. - </p> - </li> - <li> - <p><b>Reduce clutter:</b> - <code class='flag'>--symlink_prefix=.bazel/</code> will cause Bazel to create - symlinks called <code>bin</code> (etc) inside a hidden directory <code>.bazel</code>. - </p> - </li> -</ul> - -<h4 id='flag--platform_suffix'><code class='flag'>--platform_suffix <var>string</var></code></h4> -<p> - 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 - 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. -</p> - -<h4 id='flag--default_visibility'><code class='flag'>--default_visibility=<var>(private|public)</var></code></h4> -<p> - Temporary flag for testing bazel default visibility changes. Not intended for general use - but documented for completeness' sake. -</p> - -<h2 id='bazel-releng'>Using Bazel for releases</h2> -<p> - 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. - -</p> - -<h3>Significant options</h3> - -<p> - When using Bazel for release builds, the same issues arise as for - other scripts that perform a build, so you should read - the <a href='#scripting'>scripting</a> section of this manual. - In particular, the following options are strongly recommended: -</p> -<ul> - <li><a href='#bazelrc'><code class='flag'>--bazelrc=/dev/null</code></a></li> - <li><a href='#flag--batch'><code class='flag'>--batch</code></a></li> -</ul> - -<p> - These options (q.v.) are also important: -</p> - -<ul> - - <li><a href='#flag--package_path'><code class='flag'>--package_path</code></a></li> - <li><a href='#flag--symlink_prefix'><code class='flag'>--symlink_prefix</code></a>: - for managing builds for multiple configurations, - it may be convenient to distinguish each build - with a distinct identifier, e.g. "64bit" vs. "32bit". This option - differentiates the <code>bazel-bin</code> (etc.) symlinks. - </li> -</ul> - -<h2 id='test'>Running tests with Bazel</h2> -<p> - To build and run tests with bazel, type <code>bazel test</code> followed by - the name of the test targets. -</p> -<p> - By default, this command performs simultaneous build and test - activity, building all specified targets (including any non-test - targets specified on the command line) and testing - <code>*_test</code> and <code>test_suite</code> targets as soon as - their prerequisites are built, meaning that test execution is - interleaved with building. Doing so usually results in significant - speed gains. - -</p> - -<h3>Options for <code>bazel test</code></h3> - -<h4 id="flag--cache_test_results"><code class='flag'>--cache_test_results=(yes|no|auto)</code> (<code>-t</code>)</h4> -<p> - If this option is set to 'auto' (the default) then Bazel will only rerun a test if any of the - following conditions applies: -</p> -<ul> - <li>Bazel detects changes in the test or its dependencies</li> - <li>the test is marked as <code>external</code></li> - <li>multiple test runs were requested with <code class='flag'>--runs_per_test</code></li> - <li>the test failed.</li> -</ul> -<p> - If 'no', all tests will be executed unconditionally. -</p> -<p> - If 'yes', the caching behavior will be the same as auto - except that it may cache test failures and test runs with - <code class='flag'>--runs_per_test</code>. -</p> -<p> - Note that test results are <em>always</em> saved in Bazel's output tree, - regardless of whether this option is enabled, so - you needn't have used <code class='flag'>--cache_test_results</code> on the - prior run(s) of <code>bazel test</code> in order to get cache hits. - The option only affects whether Bazel will <em>use</em> previously - saved results, not whether it will save results of the current run. -</p> -<p> - Users who have enabled this option by default in - their <code>.bazelrc</code> file may find the - abbreviations <code>-t</code> (on) or <code>-t-</code> (off) - convenient for overriding the default on a particular run. -</p> - -<h4 id="flag--check_tests_up_to_date"><code class='flag'>--check_tests_up_to_date</code></h4> -<p> - 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 - previously built and run, or whose tests results are out-of-date (e.g. because - the source code or the build options have changed), then Bazel will report - an error message ("test result is not up-to-date"), will record the test's - status as "NO STATUS" (in red, if color output is enabled), and will return - a non-zero exit code. -</p> -<p> - This option also implies - <code><a href="#flag--check_up_to_date">--check_up_to_date</a></code> behavior. -</p> -<p> - This option may be useful for pre-submit checks. -</p> - -<h4 id="flag--test_verbose_timeout_warnings"><code class='flag'>--test_verbose_timeout_warnings</code></h4> -<p> - This option tells Bazel to explicitly warn the user if a test's timeout is -significantly longer then the test's actual execution time. While a test's -timeout should be set such that it is not flaky, a test that has a highly -over-generous timeout can hide real problems that crop up unexpectedly. -</p> -<p> -For instance, a test that normally executes in a minute or two should not have -a timeout of ETERNAL or LONG as these are much, much too generous. - - This option is useful to help users decide on a good timeout value or - sanity check existing timeout values. -</p> -<p> -Note that each test shard is allotted the timeout of the entire -<code>XX_test</code> target. Using this option does not affect a test's timeout -value, merely warns if Bazel thinks the timeout could be restricted further. -</p> - -<h4 id='flag--test_keep_going'><code class='flag'>--[no]test_keep_going</code></h4> -<p> - 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 <code class='flag'>--notest_keep_going</code> and - <code class='flag'>--keep_going</code>. -</p> - -<h4 id='flag--flaky_test_attempts'><code class='flag'>--flaky_test_attempts <var>attempts</var></code></h4> -<p> - 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 - succeeds is reported as <code>FLAKY</code> on the test summary. It is, - however, considered to be passed when it comes to identifying Bazel exit code - or total number of passed tests. Tests that fail all allowed attempts are - considered to be failed. -</p> -<p> - By default (when this option is not specified, or when it is set to - "default"), only a single attempt is allowed for regular tests, and - 3 for test rules with the <code>flaky</code> attribute set. You can specify - 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. -</p> - -<h4 id='flag--runs_per_test'><code class='flag'>--runs_per_test <var>[regex@]number</var></code></h4> -<p> - This option specifies the number of times each test should be executed. All - test executions are treated as separate tests (e.g. fallback functionality - will apply to each of them independently). -</p> -<p> - The status of a target with failing runs depends on the value of the - <code>--runs_per_test_detects_flakes</code> flag: -</p> -<ul> - <li>If absent, any failing run causes the entire test to fail.</li> - <li>If present and two runs from the same shard return PASS and FAIL, the test - will receive a status of flaky (unless other failing runs cause it to - fail).</li> -</ul> - -<p> - If a single number is specified, all tests will run that many times. - Alternatively, a regular expression may be specified using the syntax - regex@number. This constrains the effect of --runs_per_test to targets - which match the regex (e.g. "--runs_per_test=^//pizza:.*@4" runs all tests - under //pizza/ 4 times). - This form of --runs_per_test may be specified more than once. -</p> - -<h4 id='flag--runs_per_test_detects_flakes'><code - class='flag'>--[no]runs_per_test_detects_flakes</code></h4> -<p> - 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 - 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. -</p> - -<h4 id='flag--test_summary'><code class='flag'>--test_summary <var>output_style</var></code></h4> -<p> - Specifies how the test result summary should be displayed. -</p> -<ul> - <li><code>short</code> prints the results of each test along with the name of - the file containing the test output if the test failed. This is the default - value. - </li> - <li><code>terse</code> like <code>short</code>, but even shorter: only print - information about tests which did not pass. - </li> - <li><code>detailed</code> prints each individual test case that failed, not - only each test. The names of test output files are omitted. - </li> - <li><code>none</code> does not print test summary. - </li> -</ul> - -<h4 id='flag--test_output'><code class='flag'>--test_output <var>output_style</var></code></h4> -<p> - Specifies how test output should be displayed: -</p> -<ul> - <li><code>summary</code> shows a summary of whether each test passed or - failed. Also shows the output log file name for failed tests. The summary - will be printed at the end of the build (during the build, one would see - just simple progress messages when tests start, pass or fail). - This is the default behavior. - </li> - <li><code>errors</code> sends combined stdout/stderr output from failed tests - only into the stdout immediately after test is completed, ensuring that - test output from simultaneous tests is not interleaved with each other. - Prints a summary at the build as per summary output above. - </li> - <li><code>all</code> is similar to <code>errors</code> but prints output for - all tests, including those which passed. - </li> - <li><code>streamed</code> streams stdout/stderr output from each test in - real-time. - - </li> -</ul> - -<h4 id='flag--java_debug'><code class='flag'>--java_debug</code></h4> -<p> - 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. -</p> - -<h4 id='flag--verbose_test_summary'><code class='flag'>--[no]verbose_test_summary</code></h4> -<p> - 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 - <code class='flag'>--noverbose_test_summary</code> is specified, test summary will - include only test name, test status and cached test indicator and will - be formatted to stay within 80 characters when possible. -</p> - -<h4 id='flag--test_tmpdir'><code class='flag'>--test_tmpdir <var>path</var></code></h4> -<p> - Specifies temporary directory for tests executed locally. Each test will be - executed in a separate subdirectory inside this directory. The directory will - be cleaned at the beginning of the each <code>bazel test</code> command. - By default, bazel will place this directory under Bazel output base directory. - Note that this is a directory for running tests, not storing test results - (those are always stored under the <code>bazel-out</code> directory). -</p> - -<h4 id='flag--test_timeout'> - <code class='flag'>--test_timeout - <var>seconds</var></code> - OR - <code class='flag'>--test_timeout - <var>seconds</var>,<var>seconds</var>,<var>seconds</var>,<var>seconds</var> - </code> -</h4> -<p> - 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 - be used for all test timeout categories. - </p> - <p> - Alternatively, four comma-separated values may be provided, specifying - individual timeouts for short, moderate, long and eternal tests (in that - order). - In either form, zero or a negative value for any of the test sizes will - be substituted by the default timeout for the given timeout categories as - defined by the page - <a href="test-encyclopedia.html">Writing Tests</a>. - By default, Bazel will use these timeouts for all tests by - inferring the timeout limit from the test's size whether the size is - implicitly or explicitly set. -</p> -<p> - Tests which explicitly state their timeout category as distinct from their - size will receive the same value as if that timeout had been implicitly set by - 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. -</p> - -<h4 id='flag--test_arg'><code class='flag'>--test_arg <var>arg</var></code></h4> -<p> - Passes command-line options/flags/arguments to each test process. This - option can be used multiple times to pass several arguments, e.g. - <code class='flag'>--test_arg=--logtostderr --test_arg=--v=3</code>. -</p> - -<h4 id='flag--test_env'><code class='flag'>--test_env <var>variable</var>=<i>value</i></code> - OR - <code class='flag'>--test_env <var>variable</var></code></h4> -<p> - Specifies additional variables that must be injected into the test - environment for each test. If <var>value</var> is not specified it will be - inherited from the shell environment used to start the <code>bazel test</code> - command. -</p> -<p> - The environment can be accessed from within a test by using - <code>System.getenv("var")</code> (Java), - <code>getenv("var")</code> (C or C++), - -</p> - -<h4 id="flag--run_under"><code class='flag'>--run_under=<var>command-prefix</var></code></h4> -<p> - This specifies a prefix that the test runner will insert in front - of the test command before running it. The - <var>command-prefix</var> is split into words using Bourne shell - tokenization rules, and then the list of words is prepended to the - command that will be executed. -</p> -<p> - If the first word is a fully qualified label (i.e. starts with - <code>//</code>) it is built. Then the label is substituted by the - corresponding executable location that is prepended to the command - that will be executed along with the other words. -</p> - -<p> -Some caveats apply: -</p> -<ul> - <li> - The PATH used for running tests may be different than the PATH in your environment, - so you may need to use an <b>absolute path</b> for the <code class='flag'>--run_under</code> - command (the first word in <var>command-prefix</var>). - </li> - <li> - <b><code>stdin</code> is not connected</b>, so <code class='flag'>--run_under</code> - can't be used for interactive commands. - </li> - -</ul> -<p> -Examples: -</p> -<pre> - --run_under=/usr/bin/valgrind - --run_under=/usr/bin/strace - --run_under='/usr/bin/strace -c' - --run_under='/usr/bin/valgrind --quiet --num-callers=20' - -</pre> - -<h4>Test selection</h4> -<p> - As documented under <a href='#output-selection-options'>Output selection options</a>, - you can filter tests by <a href='#flag--test_size_filters'>size</a>, - <a href='#flag--test_timeout_filters'>timeout</a>, - <a href='#flag--test_tag_filters'>tag</a>, or - <a href='#flag--test_lang_filters'>language</a>. A convenience - <a href='#flag--test_filter'>general name filter</a> can forward particular - filter args to the test runner. -</p> - -<h4 id="other_options_for_bazel_test">Other options for <code>bazel test</code></h4> -<p> - The syntax and the remaining options are exactly like - <a href='#build'>bazel build</a>. -</p> - - - -<h2 id='run'>Running executables with Bazel</h2> -<p> - The <code>bazel run</code> command is similar to <code>bazel build</code>, except - it is used to build and run a single target. Here is a typical session: -</p> -<pre> - % bazel run -- java/myapp:myapp --arg1 --arg2 - Welcome to Bazel - INFO: Loading package: java/myapp - INFO: Loading package: foo/bar - INFO: Loading complete. Analyzing... - INFO: Found 1 target... - ... - Target //java/myapp:myapp up-to-date: - bazel-bin/java/myapp:myapp - INFO: Elapsed time: 0.638s, Critical Path: 0.34s - - INFO: Running command line: bazel-bin/java/myapp:myapp --arg1 --arg2 - Hello there - $EXEC_ROOT/java/myapp/myapp - --arg1 - --arg2 -</pre> - -<p> - Bazel closes stdin, so you can't use <code>bazel run</code> - if you want to start an interactive program or pipe data to it. -</p> - -<p> - Note the use of the <code>--</code>. This is needed so that Bazel - does not interpret <code>--arg1</code> and <code>--arg2</code> as - Bazel options, but rather as part of the command line for running the binary. - (The program being run simply says hello and prints out its args.) -</p> - -<h3>Options for <code>bazel run</code></h3> - -<h4 id='flag--run_under_run'><code class='flag'>--run_under=<var>command-prefix</var></code></h4> -<p> - This has the same effect as the <code class='flag'>--run_under</code> option for - <code>bazel test</code> (<a href='#flag--run_under'>see above</a>), - except that it applies to the command being run by <code>bazel - run</code> rather than to the tests being run by <code>bazel test</code> - and cannot run under label. -</p> - -<h3>Executing tests</h3> - -<p> - <code>bazel run</code> can also execute test binaries, which has the effect of -running the test, but without the setup documented on the page -<a href='test-encyclopedia.html'>Writing Tests</a>, so that the test runs -in an environment closer to the current shell environment. Note that none of the ---test_* arguments have an effect when running a test in this manner. -</p> - -<h2 id='query'>Querying the dependency graph with Bazel</h2> - -<p> - Bazel includes a query language for asking questions about the - dependency graph used during the build. The query tool is an - invaluable aid to many software engineering tasks. -</p> -<p> - The query language is based on the idea of - algebraic operations over graphs; it is documented in detail in - - <a href="query.html">Bazel Query Reference</a>. - Please refer to that document for reference, for - examples, and for query-specific command-line options. -</p> - -<p> - The query tool accepts several command-line - option. <code class='flag'>--output</code> selects the output format. - <code class='flag'>--[no]keep_going</code> (disabled by default) causes the query - tool to continue to make progress upon errors; this behavior may be - disabled if an incomplete result is not acceptable in case of errors. -</p> -<p> - The <code class='flag'>--[no]host_deps</code> option, - enabled by default, causes dependencies on "host - configuration" targets to be included in the dependency graph over - which the query operates. - -</p> -<p> - The <code class='flag'>--[no]implicit_deps</code> option, enabled by default, causes - implicit dependencies to be included in the dependency graph over which the query operates. An - implicit dependency is one that is not explicitly specified in the BUILD file - but added by bazel. -</p> -<p> - Example: "Show the locations of the definitions (in BUILD files) of - all genrules required to build all the tests in the PEBL tree." -</p> -<pre> - bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))' -</pre> - - -<h2 id='misc'>Miscellaneous Bazel commands and options</h2> - -<h3 id='help'>The <code>help</code> command</h3> - -<p> - The <code>help</code> command provides on-line help. By default, it - shows a summary of available commands and help topics, as shown in - the <a href='#overview'><i>Bazel overview</i></a> section above. - Specifying an argument displays detailed help for a particular - topic. Most topics are Bazel commands, e.g. <code>build</code> - or <code>query</code>, but there are some additional help topics - that do not correspond to commands. -</p> - -<h4 id='flag--long'><code class='flag'>--[no]long</code> (<code>-l</code>)</h4> -<p> - By default, <code>bazel help [<var>topic</var>]</code> prints only a - summary of the relevant options for a topic. If - the <code class='flag'>--long</code> option is specified, the type, default value - and full description of each option is also printed. -</p> - -<h3 id='shutdown'>The <code>shutdown</code> command</h3> - -<p> - Bazel server processes (see <a href='#client/server'>Client/server - implementation</a>) may be stopped by using the <code>shutdown</code> - command. This command causes the Bazel server to exit as soon as it - becomes idle (i.e. after the completion of any builds or other - commands that are currently in progress). - - Bazel servers stop themselves after an idle timeout, so this command - is rarely necessary; however, it can be useful in scripts when it is - known that no further builds will occur in a given workspace. -</p> -<p> - <code>shutdown</code> accepts one - option, <code class='flag'>--iff_heap_size_greater_than <i>n</i></code>, which - requires an integer argument (in MB). If specified, this makes the shutdown - conditional on the amount of memory already consumed. This is - 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. -</p> - -<h3 id='info'>The <code>info</code> command</h3> - -<p> - The <code>info</code> command prints various values associated with - the Bazel server instance, or with a specific build configuration. - (These may be used by scripts that drive a build.) -</p> - -<p> - The <code>info</code> command also permits a single (optional) - argument, which is the name of one of the keys in the list below. - In this case, <code>bazel info <var>key</var></code> 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 <code>sed -ne /key:/s/key://p</code>: -</p> - -<h4>Configuration-independent data</h4> -<ul> - <li><code>release</code>: the release label for this Bazel - instance, or "development version" if this is not a released - binary. - </li> - <li><code>workspace</code> the absolute path to the base workspace - directory. - </li> - <li><code>install_base</code>: the absolute path to the installation - directory used by this Bazel instance for the current user. Bazel - installs its internally required executables below this directory. - - </li> - <li><code>output_base</code>: the absolute path to the base output - directory used by this Bazel instance for the current user and - workspace combination. Bazel puts all of its scratch and build - output below this directory. - </li> - <li><code>execution_root</code>: the absolute path to the execution - root directory under output_base. This directory is the root for all files - accessible to commands executed during the build, and is the working - directory for those commands. If the workspace directory is writable, a - symlink named - - <code>bazel-<workspace></code> - is placed there pointing to this directory. - </li> - <li><code>output_path</code>: the absolute path to the output - directory beneath the execution root used for all files actually - generated as a result of build commands. If the workspace directory is - writable, a symlink named <code>bazel-out</code> is placed there pointing - to this directory. - </li> - <li><code>server_pid</code>: the process ID of the Bazel server - process. </li> - <li><code>command_log</code>: the absolute path to the command log file; - this contains the interleaved stdout and stderr streams of the most recent - Bazel command. Note that running <code>bazel info</code> will overwrite the - contents of this file, since it then becomes the most recent Bazel command. - However, the location of the command log file will not change unless you - change the setting of the <code class='flag'>--output_base</code> or - <code class='flag'>--output_user_root</code> options. - </li> - - <li><code>used-heap-size</code>, - <code>committed-size</code>, - <code>max-heap-size</code>: reports various JVM heap size - parameters. Respectively: memory currently used, memory currently - guaranteed to be available to the JVM from the system, maximum - possible allocation. - </li> - <li><code>gc-count</code>, <code>gc-time</code>: The cumulative count of - garbage collections since the start of this Bazel server and the time spent - to perform them. Note that these values are not reset at the start of every - build. - </li> - <li><code>package_path</code>: A colon-separated list of paths which would be - searched for packages by bazel. Has the same format as the - <code class='flag'>--package_path</code> build command line argument. - </li> -</ul> -<p> - Example: the process ID of the Bazel server. -</p> -<pre>% bazel info server_pid -1285 -</pre> - -<h4>Configuration-specific data</h4> -<p> - These data may be affected by the configuration options passed - to <code>bazel info</code>, for - example <code class='flag'>--cpu</code>, <code class='flag'>--compilation_mode</code>, - etc. The <code>info</code> command accepts all - the <a href='#analysis-options'>options that control dependency - analysis</a>, since some of these determine the location of the - output directory of a build, the choice of compiler, etc. -</p> -<ul> - <li> - <code>bazel-bin</code>, <code>bazel-testlogs</code>, - <code>bazel-genfiles</code>: reports the absolute path to - the <code>bazel-*</code> directories in which programs generated by the - build are located. This is usually, though not always, the same as - the <code>bazel-*</code> symlinks created in the base workspace directory after a - successful build. However, if the workspace directory is read-only, - no <code>bazel-*</code> symlinks can be created. Scripts that use - the value reported by <code>bazel info</code>, instead of assuming the - existence of the symlink, will be more robust. - </li> - <li> - The complete - <a href='be/make-variables.html' - >"Make" environment</a>. If the <code class='flag'>--show_make_env</code> flag is - specified, all variables in the current configuration's "Make" environment - are also displayed (e.g. <code>CC</code>, <code>GLIBC_VERSION</code>, etc). - These are the variables accessed using the <code>$(CC)</code> - or <code>varref("CC")</code> syntax inside BUILD files. - </li> -</ul> - -<p> - Example: the C++ compiler for the current configuration. - This is the <code>$(CC)</code> variable in the "Make" environment, - so the <code class='flag'>--show_make_env</code> flag is needed. -</p> - -<pre> - % bazel info --show_make_env -c opt COMPILATION_MODE - opt -</pre> - -<p> - Example: the <code>bazel-bin</code> output directory for the current - configuration. This is guaranteed to be correct even in cases where - the <code>bazel-bin</code> symlink cannot be created for some reason - (e.g. you are building from a read-only directory). -</p> - -<h3 id='version'>The <code>version</code> command</h3> - -<p> - The version command prints version details about the built Bazel - binary, including the changelist at which it was built and the date. - These are particularly useful in determining if you have the latest - Bazel, or if you are reporting bugs. Some of the interesting values - are: -</p> -<ul> - <li><code>changelist</code>: the changelist at which this version of - Bazel was released. - </li> - <li><code>label</code>: the release label for this Bazel - instance, or "development version" if this is not a released - binary. Very useful when reporting bugs. - </li> -</ul> - -<h3 id='mobile-install'>The <code>mobile-install</code> command</h3> -<p> - The <code>mobile-install</code> command installs apps to mobile devices. - Currently only Android devices running ART are supported. - - See <a href="mobile-install.html">bazel mobile-install</a> - for more information. -</p> -<p> - Note that this command does not install the same thing that - <code>bazel build</code> produces: Bazel tweaks the app so that it can be - built, installed and re-installed quickly. This should, however, be mostly - transparent to the app. -</p> -<p> - The following options are supported: -</p> -<h4 id='flag--incremental'><code class='flag'>--incremental</code></h4> -<p> - 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 - referenced from <code>AndroidManifest.xml</code>, native code or Java - resources (i.e. ones referenced by <code>Class.getResource()</code>). If these - things change, this option must be omitted. Contrary to the spirit of Bazel - and due to limitations of the Android platform, it is the - <b>responsibility of the user</b> to know when this command is good enough and - when a full install is needed. - - If you are using a device with Marshmallow or later, consider the - <a href='#flag--split_apks'><code class='flag'>--split_apks</code></a> flag. -</p> -<h4 id='flag--split_apks'><code class='flag'>--split_apks</code></h4> -<p> - 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 - <a href='#flag--incremental'><code class='flag'>--incremental</code></a> flag - is not necessary when using <code class='flag'>--split_apks</code>. -</p> -<h4 id='flag--start_app'><code class='flag'>--start_app</code></h4> -<p> - Starts the app in a clean state after installing. Equivalent to - <code>--start=COLD</code>. -</p> -<h4 id='flag--debug_app'><code class='flag'>--debug_app</code></h4> -<p> - Waits for debugger to be attached before starting the app in a clean state after installing. - Equivalent to <code>--start=DEBUG</code>. -</p> -<h4 id='flag--start'><code class='flag'>--start=<i>start_type</i></code></h4> -<p> - How the app should be started after installing it. Supported <i>start_type</i>s are: - <ul> - <li><code>NO</code> Does not start the app. This is the default.</li> - <li><code>COLD</code> Starts the app from a clean state after install.</li> - <li><code>WARM</code> Preserves and restores the application state on incremental installs.</li> - <li><code>DEBUG</code> Waits for the debugger before starting the app in a clean state after install.</li> - </ul> - Note that if more than one of <code class='flag'>--start=<i>start_type</i></code>, - <code class='flag'>--start_app</code> or - <code class='flag'>--debug_app</code> is set, the last value will be used. -</p> -<h4 id='flag--adb'><code class='flag'>--adb <var>path</var></code></h4> -<p> - Indicates the <code>adb</code> binary to be used. - - The default is to use the adb in the Android SDK specified by - <a href='#flag--android_sdk'><code class='flag'>--android_sdk</code></a>. - -</p> -<h4 id='flag--adb_arg'><code class='flag'>--adb_arg <var>arg</var></code></h4> -<p> - Extra arguments to <code>adb</code>. 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: -<pre>% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef -</pre> -will invoke <code>adb</code> as -<pre> -adb -s deadbeef install ... -</pre> -</p> -<h4 id='flag--adb_jobs'><code class='flag'>--adb_jobs <var>number</var></code></h4> -<p> - The number of instances of adb to use in parallel to update files on the - device. -</p> -<h4 id='flag--incremental_install_verbosity'><code class='flag'>--incremental_install_verbosity <var>number</var></code></h4> -<p> - The verbosity for incremental install. Set to 1 for debug logging to be - printed to the console. -</p> - -<h3 id='analyze-profile'>The <code>analyze-profile</code> command</h3> - -<p> - The <code>analyze-profile</code> command analyzes data previously gathered - during the build using <code class='flag'>--profile</code> option. It provides several - options to either perform analysis of the build execution or export data in - the specified format. - -</p> -<p> - The following options are supported: -</p> -<ul> - <li><code id='flag--dump'>--dump=text</code> displays all gathered data in a - <a href='#dump-text-format'>human-readable format</a></li> - <li><code>--dump=raw</code> displays all gathered data in a - <a href='#dump-raw-format'>script-friendly format</a></li> - <li><code id='flag--html'>--html</code> generates an <a href='#dump-html-format'>HTML file</a> visualizing the - actions and rules executed in the build, as well as summary statistics for the build - <ul> - <li><code id='flag--html_details'>--html_details</code> adds more fine-grained - information on actions and rules to the HTML visualization</li> - <ul> - <li><code id='flag--html_histograms'>--html_histograms</code> adds histograms for Skylark - functions clicked in the statistics table. This will increase file size massively</li> - <li><code id='flag--nochart'>--nochart</code> hides the task chart from generated HTML - </li> - </ul> - </ul> - </li> - <li><code id='flag--combine'>--combine</code> combines multiple profile data files into a single - report. Does not generate HTML task charts</li> - <li><code id='flag--task_tree'>--task_tree</code> prints the tree of tasks matching the given - regular expression - <ul> - <li><code id='flag--task_tree_threshold'>--task_tree_threshold</code> skip tasks with duration - less than threshhold, in milliseconds. Default is 50ms</li> - </ul> - </li> -</ul> - -<p> - See the section on <a href='#profiling'>Troubleshooting performance by profiling</a> for - format details and usage help. - -</p> - -<h3 id='canonicalize'>The <code>canonicalize-flags</code> command</h3> - -<p> - The <code>canonicalize-flags</code> command, which takes a list of options for - a Bazel command and returns a list of options that has the same effect. The - new list of options is canonical, i.e., two lists of options with the same - effect are canonicalized to the same new list. -</p> -<p> - The <code class='flag'>--for_command</code> option can be used to select between different - commands. At this time, only <code>build</code> and <code>test</code> are - supported. Options that the given command does not support cause an error. -</p> -<p> - Note that a small number of options cannot be reordered, because Bazel cannot - ensure that the effect is identical. -</p> - -<h3 id='startup_options'>Bazel startup options</h3> - -<p> - The options described in this section affect the startup of the Java - virtual machine used by Bazel server process, and they apply to all - subsequent commands handled by that server. If there is an already - running Bazel server and the startup options do not match, it will - be restarted. -</p> -<p> - All of the options described in this section must be specified using the - <code class='flag'>--key=value</code> or <code class='flag'>--key value</code> - syntax. Also, these options must appear <i>before</i> the name of the Bazel - command. -</p> - -<h4 id='flag--output_base'><code class='flag'>--output_base=<var>dir</var></code></h4> -<p> - This option requires a path argument, which must specify a - writable directory. Bazel will use this location to write all its - output. The output base is also the key by which the client locates - the Bazel server. By changing the output base, you change the server - which will handle the command. -</p> -<p> - By default, the output base is derived from the user's login name, - and the name of the workspace directory (actually, its MD5 digest), - so a typical value looks like: - - <code>/var/tmp/google/_bazel_jrluser/d41d8cd98f00b204e9800998ecf8427e</code>. - Note that the client uses the output base to find the Bazel server - instance, so if you specify a different output base in a Bazel - command, a different server will be found (or started) to handle the - request. It's possible to perform two concurrent builds in the same - workspace directory by varying the output base. -</p> - -<p>For example:</p> -<pre> - % bazel --output_base /tmp/1 build //foo & bazel --output_base /tmp/2 build //bar -</pre> -<p> - In this command, the two Bazel commands run concurrently (because of - the shell <code>&</code> operator), each using a different Bazel - server instance (because of the different output bases). - In contrast, if the default output base was used in both commands, - then both requests would be sent to the same server, which would - handle them sequentially: building <code>//foo</code> first, followed - by an incremental build of <code>//bar</code>. -</p> -<p> - We recommend you do not use NFS locations for the output base, as - the higher access latency of NFS will cause noticeably slower - builds. -</p> - -<h4 id='flag--output_user_root'><code class='flag'>--output_user_root=<var>dir</var></code></h4> -<p> - By default, the <code>output_base</code> value is chosen to as to - avoid conflicts between multiple users building in the same workspace directory. - In some situations, though, it is desirable to build from a directory - shared between multiple users; release engineers often do this. In - those cases it may be useful to deliberately override the default so - as to ensure "conflicts" (i.e., sharing) between multiple users. - Use the <code class='flag'>--output_user_root</code> option to achieve this: the - output base is placed in a subdirectory of the output user root, - with a unique name based on the workspace, so the result of using an - output user root that is not a function of <code>$USER</code> is - sharing. Of course, it is important to ensure (via umask and group - membership) that all the cooperating users can read/write each - others files. -</p> -<p> - If the <code class='flag'>--output_base</code> option is specified, it overrides - using <code class='flag'>--output_user_root</code> to calculate the output base. -</p> -<p> - The install base location is also calculated based on - <code class='flag'>--output_user_root</code>, plus the MD5 identity of the Bazel embedded - binaries. -</p> -<p> - You can also use the <code class='flag'>--output_user_root</code> option to choose an - alternate base location for all of Bazel's output (install base and output - base) if there is a better location in your filesystem layout. -</p> - -<h4 id='flag--host_jvm_args'><code class='flag'>--host_jvm_args=<var>string</var></code></h4> -<p> - Specifies a startup option to be passed to the Java virtual machine in which <i>Bazel itself</i> - runs. This can be used to set the stack size, for example: -</p> -<pre> - % bazel --host_jvm_args="-Xss256K" build //foo -</pre> -<p> - 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, - each of which will be interpreted as a separate JVM argument, but this feature will soon be - deprecated. - -</p> -<p> - That this does <i>not</i> affect any JVMs used by - subprocesses of Bazel: applications, tests, tools, etc. To pass - JVM options to executable Java programs, whether run by <code>bazel - run</code> or on the command-line, you should use - the <code>--jvm_flags</code> argument which - all <code>java_binary</code> and <code>java_test</code> programs - support. Alternatively for tests, use <code>bazel - test --test_arg=--jvm_flags=foo ...</code>. -</p> - -<h4 id='flag--host_jvm_debug'><code class='flag'>--host_jvm_debug</code></h4> -<p> - This option causes the Java virtual machine to wait for a connection - from a JDWP-compliant debugger before - calling the main method of <i>Bazel itself</i>. This is primarily - intended for use by Bazel developers. -</p> -<p> - (Please note that this does <i>not</i> affect any JVMs used by - subprocesses of Bazel: applications, tests, tools, etc.) -</p> - -<h4 id='flag--batch'><code class='flag'>--batch</code></h4> -<p> - This switch will cause bazel to be run in batch mode, instead of the - standard client/server mode described <a href='#client/server'>above</a>. - Doing so provides more predictable semantics with respect to signal handling, - job control, and environment variable inheritance, and is necessary for running - bazel in a chroot jail. -</p> - -<p> - Batch mode retains proper queueing semantics within the same output_base. - That is, simultaneous invocations will be processed in order, without overlap. - If a batch mode bazel is run on a client with a running server, it first - kills the server before processing the command. -</p> - -<p> - Bazel will run slower in batch mode, compared to client/server mode. - Among other things, the build file cache is memory-resident, so it is not - preserved between sequential batch invocations. - Therefore, using batch mode often makes more sense in cases where performance - is less critical, such as continuous builds. -</p> - -<h4 id='flag--max_idle_secs'><code class='flag'>--max_idle_secs <var>n</var></code></h4> -<p> - This option specifies how long, in seconds, the Bazel server process - should wait after the last client request, before it exits. The - default value is 10800 (3 hours). -</p> -<p> - This option may be used by scripts that invoke Bazel to ensure that - they do not leave Bazel server processes on a user's machine when they - would not be running otherwise. - For example, a presubmit script might wish to - invoke <code>bazel query</code> to ensure that a user's pending - change does not introduce unwanted dependencies. However, if the - user has not done a recent build in that workspace, it would be - undesirable for the presubmit script to start a Bazel server just - for it to remain idle for the rest of the day. - By specifying a small value of <code class='flag'>--max_idle_secs</code> in the - query request, the script can ensure that <i>if</i> it caused a new - server to start, that server will exit promptly, but if instead - 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. -</p> - -<h4 id='flag--block_for_lock'><code class='flag'>--[no]block_for_lock</code></h4> -<p> - If enabled, Bazel will wait for other Bazel commands holding the - server lock to complete before progressing. If disabled, Bazel will - exit in error if it cannot immediately acquire the lock and - proceed. - - Developers might use this in presubmit checks to avoid long waits caused - by another Bazel command in the same client. -</p> - -<h4 id='flag--io_nice_level'><code class='flag'>--io_nice_level <var>n</var></code></h4> -<p> - 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. -</p> - -<h4 id='flag--batch_cpu_scheduling'><code class='flag'>--batch_cpu_scheduling</code></h4> -<p> - Use <code>batch</code> 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. -</p> - -<h3 id='misc_options'>Miscellaneous options</h3> - -<h4 id='flag--announce_rc'><code class='flag'>--[no]announce_rc</code></h4> -<p> - Controls whether Bazel announces command options read from the bazelrc file when - starting up. (Startup options are unconditionally announced.) -</p> - -<h4 id='flag--color'><code class='flag'>--color (yes|no|auto)</code></h4> -<p> - This option determines whether Bazel will use colors to highlight - its output on the screen. -</p> -<p> - If this option is set to <code>yes</code>, color output is enabled. - If this option is set to <code>auto</code>, Bazel will use color output only if - the output is being sent to a terminal and the TERM environment variable - is set to a value other than <code>dumb</code>, <code>emacs</code>, or <code>xterm-mono</code>. - If this option is set to <code>no</code>, color output is disabled, - regardless of whether the output is going to a terminal and regardless - of the setting of the TERM environment variable. -</p> - -<h4 id='flag--config'><code class='flag'>--config <var>name</var></code></h4> -<p> - Selects additional config section from the rc files; for the current - <code>command</code>, it also pulls in the options from - <code>command:name</code> if such a section exists. Can be specified multiple - times to add flags from several config sections. Expansions can refer to other - definitions (i.e. expansions can be chained). -</p> - -<h4 id='flag--curses'><code class='flag'>--curses (yes|no|auto)</code></h4> -<p> - This option determines whether Bazel will use cursor controls - in its screen output. This results in less scrolling data, and a more - compact, easy-to-read stream of output from Bazel. This works well with - <code class='flag'>--color</code>. -</p> -<p> - If this option is set to <code>yes</code>, use of cursor controls is enabled. - If this option is set to <code>no</code>, use of cursor controls is disabled. - If this option is set to <code>auto</code>, use of cursor controls will be - enabled under the same conditions as for <code class='flag'>--color=auto</code>. -</p> - -<h4 id='flag--show_timestamps'><code class='flag'>--[no]show_timestamps</code></h4> -<p> - If specified, a timestamp is added to each message generated by - Bazel specifying the time at which the message was displayed. -</p> - -<h2 id='scripting'>Calling Bazel from scripts</h2> - -<p> - Bazel can be called from scripts in order to perform a build, run - tests or query the dependency graph. Bazel has been designed to - enable effective scripting, but this section lists some details to - bear in mind to make your scripts more robust. -</p> - -<h3>Choosing the output base</h3> - -<p> - The <code class='flag'>--output_base</code> option controls where the Bazel process should - write the outputs of a build to, as well as various working files used - internally by Bazel, one of which is a lock that guards against - concurrent mutation of the output base by multiple Bazel processes. -</p> -<p> - Choosing the correct output base directory for your script depends - on several factors. If you need to put the build outputs in a - specific location, this will dictate the output base you need to - use. If you are making a "read only" call to Bazel - (e.g. <code>bazel query</code>), the locking factors will be more important. - In particular, if you need to run multiple instances of your script - concurrently, you will need to give each one a different (or random) output - base. -</p> -<p> - If you use the default output base value, you will be contending for - the same lock used by the user's interactive Bazel commands. If the - user issues long-running commands such as builds, your script will - have to wait for those commands to complete before it can continue. -</p> - -<h3>Server or no server?</h3> - -<p> - By default, Bazel uses a long-running <a - href='#client/server'>server process</a> as an optimization; this - behavior can be disabled using the <a - href='#flag--batch'><code class='flag'>--batch</code></a> option. There's no hard and - fast rule about whether or not your script should use a server, but - in general, the trade-off is between performance and reliability. - The server mode makes a sequence of builds, especially incremental - builds, faster, but its behavior is more complex and prone to - failure. We recommend in most cases that you use batch mode unless - the performance advantage is critical. -</p> -<p> - If you do use the server, don't forget to call <code>shutdown</code> - when you're finished with it, or, specify - <code class='flag'>--max_idle_secs=5</code> so that idle servers shut themselves - down promptly. -</p> - -<h3>What exit code will I get?</h3> - -<p> - Bazel attempts to differentiate failures due to the source code under -consideration from external errors that prevent Bazel from executing properly. -Bazel execution can result in following exit codes: -</p> - -<b>Exit Codes common to all commands:</b> -<ul> - <li><code>0</code> - Success</li> - <li><code>2</code> - Command Line Problem, Bad or Illegal flags or command - combination, or Bad Environment Variables. Your command line must be - modified.</li> - <li><code>8</code> - Build Interrupted but we terminated with an orderly shutdown.</li> - <li><code>32</code> - External Environment Failure not on this machine.</li> - <li><code>33</code> - OOM failure. You need to modify your command line.</li> - - <li><code>34</code> - Reserved for Google-internal use.</li> - <li><code>35</code> - Reserved for Google-internal use.</li> - <li><code>36</code> - Local Environmental Issue, suspected permanent.</li> - <li><code>37</code> - Unhandled Exception / Internal Bazel Error.</li> - <li><code>38</code> - Reserved for Google-internal use.</li> - <li><code>40-44</code> - Reserved for errors in Bazel's command line launcher, - <code>bazel.cc</code> that are not command line - related. Typically these are related to bazel server - being unable to launch itself.</li> -</ul> - -<b>Return codes for commands <code>bazel build</code>, <code>bazel test</code>.</b> -<ul> - <li><code>1</code> - Build failed.</li> - <li><code>3</code> - Build OK, but some tests failed or timed out.</li> - <li><code>4</code> - Build successful but no tests were found even though - testing was requested.</li> -</ul> - -<b>For <code>bazel run</code>:</b> -<ul> - <li><code>1</code> - Build failed.</li> - <li><code>6</code> - Run command failure. The executed subprocess returned a - non-zero exit code. The actual subprocess exit code is - given in stderr.</li> -</ul> - - -<b>For - - <code>bazel query</code>:</b> -<ul> - <li><code>3</code> - Partial success, but the query encountered 1 or more - errors in the input BUILD file set and therefore the - results of the operation are not 100% reliable. - This is likely due to a <code class='flag'>--keep_going</code> option - on the command line.</li> - <li><code>7</code> - Command failure.</li> -</ul> - -<p> - Future Bazel versions may add additional exit codes, replacing generic failure - exit code <code>1</code> with a different non-zero value with a particular - meaning. However, all non-zero exit values will always constitute an error. -</p> - -<h3>Reading the .bazelrc file</h3> - -<p> - By default, Bazel will read the <a - href='#bazelrc'><code>.bazelrc</code> file</a> from the base workspace - directory or the user's home directory. Whether or not this is - desirable is a choice for your script; if your script needs to be - perfectly hermetic (e.g. when doing release builds), you should - disable reading the .bazelrc file by using the option - <code class='flag'>--bazelrc=/dev/null</code>. If you want to perform a build - using the user's preferred settings, the default behavior is better. -</p> - -<h3>Command log</h3> - -<p> - The Bazel output is also available in a command log file which you can - find with the following command: -</p> - -<pre> -% bazel info command_log -</pre> - -<p> - The command log file contains the interleaved stdout and stderr streams - of the most recent Bazel command. Note that running <code>bazel info</code> - will overwrite the contents of this file, since it then becomes the most - recent Bazel command. However, the location of the command log file will - not change unless you change the setting of the <code class='flag'>--output_base</code> - or <code class='flag'>--output_user_root</code> options. -</p> - -<h3>Parsing output</h3> - -<p> - The Bazel output is quite easy to parse for many purposes. Two - options that may be helpful for your script are - <code class='flag'>--noshow_progress</code> which suppresses progress messages, - and <code class='flag'>--show_result <var>n</var></code>, which controls whether - or not "build up-to-date" messages are printed; these messages may - be parsed to discover which targets were successfully built, and the - location of the output files they created. Be sure to specify a - very large value of <i>n</i> if you rely on these messages. -</p> - -<h2 id='profiling'>Troubleshooting performance by profiling</h2> - -<p> - The first step in analyzing the performance of your build is to profile your build with the - <a href='#flag--profile'><code class='flag'>--profile</code></a> option. -</p> - -<p> - The file generated by the <a href='#flag--profile'><code class='flag'>--profile</code></a> - command is a binary file. Once you have generated this binary profile, you can analyze it using - Bazel's <a href='#analyze-profile'><code>analyze-profile</code></a> command. By default, it will - print out summary analysis information for each of the specified profile datafiles. This includes - cumulative statistics for different task types for each build phase and an analysis of the - critical execution path. -</p> - -<p> - The first section of the default output describes an overview of the time spent on the different - build phases: -</p> -<pre> -=== PHASE SUMMARY INFORMATION === - -Total launch phase time 6.00 ms 0.01% -Total init phase time 864 ms 1.11% -Total loading phase time 21.841 s 28.05% -Total analysis phase time 5.444 s 6.99% -Total preparation phase time 155 ms 0.20% -Total execution phase time 49.473 s 63.54% -Total finish phase time 83.9 ms 0.11% -Total run time 77.866 s 100.00% -</pre> - -<p> - The following sections show the execution time of different tasks happening during a particular - phase: -</p> -<pre> -=== INIT PHASE INFORMATION === - -Total init phase time 864 ms - -Total time (across all threads) spent on: - Type Total Count Average - VFS_STAT 2.72% 1 23.5 ms - VFS_READLINK 32.19% 1 278 ms - -=== LOADING PHASE INFORMATION === - -Total loading phase time 21.841 s - -Total time (across all threads) spent on: - Type Total Count Average - SPAWN 3.26% 154 475 ms - VFS_STAT 10.81% 65416 3.71 ms -[...] -SKYLARK_BUILTIN_FN 13.12% 45138 6.52 ms - -=== ANALYSIS PHASE INFORMATION === - -Total analysis phase time 5.444 s - -Total time (across all threads) spent on: - Type Total Count Average - SKYFRAME_EVAL 9.35% 1 4.782 s - SKYFUNCTION 89.36% 43332 1.06 ms - -=== EXECUTION PHASE INFORMATION === - -Total preparation time 155 ms -Total execution phase time 49.473 s -Total time finalizing build 83.9 ms - -Action dependency map creation 0.00 ms -Actual execution time 49.473 s - -Total time (across all threads) spent on: - Type Total Count Average - ACTION 2.25% 12229 10.2 ms -[...] - SKYFUNCTION 1.87% 236131 0.44 ms -</pre> - -<p> - The last section shows the critical path: -</p> -<pre> -Critical path (32.078 s): - Id Time Percentage Description -1109746 5.171 s 16.12% Building [...] -1109745 164 ms 0.51% Extracting interface [...] -1109744 4.615 s 14.39% Building [...] -[...] -1109639 2.202 s 6.86% Executing genrule [...] -1109637 2.00 ms 0.01% Symlinking [...] -1109636 163 ms 0.51% Executing genrule [...] - 4.00 ms 0.01% [3 middleman actions] -</pre> - -<p> - You can use the following options to display more detailed information: -</p> - -<ul> - <li id='dump-text-format'><a href='#flag--dump'><code>--dump=text</code></a> - <p> - This option prints all recorded tasks in the order they occurred. Nested tasks are indented - relative to the parent. For each task, output includes the following information: - </p> -<pre> -[task type] [task description] -Thread: [thread id] Id: [task id] Parent: [parent task id or 0 for top-level tasks] -Start time: [time elapsed from the profiling session start] Duration: [task duration] -[aggregated statistic for nested tasks, including count and total duration for each nested task] -</pre> - </li> - <li id='dump-raw-format'><a href='#flag--dump'><code>--dump=raw</code></a> - <p> - This option is most useful for automated analysis with scripts. It outputs each task record on - a single line using '|' delimiter between fields. Fields are printed in the following order: - </p> - <ol> - <li>thread id - integer positive number, identifies owner thread for the task</li> - <li>task id - integer positive number, identifies specific task</li> - <li>parent task id for nested tasks or 0 for root tasks</li> - <li>task start time in ns, relative to the start of the profiling session</li> - <li>task duration in ns. Please note that this will include duration of all subtasks.</li> - <li>aggregated statistic for immediate subtasks per type. This will include type name (lower - case), number of subtasks for that type and their cumulative duration. Types are - space-delimited and information for single type is comma-delimited.</li> - <li>task type (upper case)</li> - <li>task description</li> - </ol> - - Example: -<pre> -1|1|0|0|0||PHASE|Launch Bazel -1|2|0|6000000|0||PHASE|Initialize command -1|3|0|168963053|278111411||VFS_READLINK|/[...] -1|4|0|571055781|23495512||VFS_STAT|/[...] -1|5|0|869955040|0||PHASE|Load packages -[...] -</pre> - </li> - <li id='dump-html-format'><a href='#flag--html'><code>--html</code></a> - <p> - This option writes a file called <code><profile-file>.html</code> in the directory of the - profile file. Open it in your browser to see the visualization of the actions in your build. - Note that the file can be quite large and may push the capabilities of your browser – - please wait for the file to load. - </p> - <p> - In most cases, the HTML output from <a href='#flag--html'><code>--html</code></a> is easier to - read than the <a href='#flag--dump'><code>--dump</code></a> output. - It includes a Gantt chart that displays time on the horizontal axis and - threads of execution along the vertical axis. If you click on the Statistics link in the top - right corner of the page, you will jump to a section that lists summary analysis information - from your build. - </p> - <ul> - <li><a href='#flag--html_details'><code>--html_details</code></a> - <p> - Additionally passing this option will render a more detailed execution chart and additional - tables on the performance of built-in and user-defined Skylark functions. Beware that this - increases the file size and the load on the browser considerably. - </p> - </li> - </ul></li> -</ul> - -<p>If Bazel appears to be hung, you can hit <kbd><kbd>ctrl</kbd> + <kbd>\</kbd></kbd> or send - Bazel a <code>SIGQUIT</code> signal (<code>kill -3 $(bazel info server_pid)</code>) to get a - thread dump in the file <code>$(bazel info output_base)/server/jvm.out</code>. -</p> - -<p> - Since you may not be able to run <code>bazel info</code> if bazel is hung, the - <code>output_base</code> directory is usually the parent of the <code>bazel-<workspace></code> - symlink in your workspace directory. -</p> diff --git a/site/versions/master/docs/build-ref.html b/site/versions/master/docs/build-ref.html deleted file mode 100644 index 96521c09e5..0000000000 --- a/site/versions/master/docs/build-ref.html +++ /dev/null @@ -1,1021 +0,0 @@ ---- -layout: documentation -title: BUILD files ---- -<h1>Bazel: Build Files and Terminology</h1> -<p> - This document provides an overview of the source tree layout and the - terminology used in Bazel. -</p> -<h2>Table of Contents</h2> - -<ul> - <li><a href="#intro">Introduction</a></li> - - <li><a href="#packages_targets">Workspace, Packages and Targets</a> - <ul> - <li><a href="#workspace">Workspace</a></li> - <li><a href="#packages">Packages</a></li> - <li><a href="#targets">Targets</a></li> - <li><a href="#labels">Labels</a></li> - <li><a href="#lexi">Lexical Specifications of a Label</a></li> - <li><a href="#rules">Rules</a></li> - </ul> - </li> - <li><a href="#BUILD_files">BUILD Files</a> - <ul> - <li><a href="#core_build_language">The Core Build Language</a></li> - - <li><a href="#declaring_build_rules">Declaring Build Rules</a></li> - </ul> - </li> - <li><a href="#funcs">Types of Build Rules</a></li> - - <li><a href="#dependencies">Dependencies</a> - <ul> - <li><a href="#actual_and_declared_dependencies">Actual and Declared Dependencies</a></li> - <li><a href="#types_of_dependencies">Types of Dependencies</a></li> - <li><a href="#label_directory">Using Labels to Reference Directories</a></li> - </ul> - </li> -</ul> - -<h2 id="intro">Introduction</h2> - -<p>Bazel builds software from source code organized in a directory called - a workspace. Source files in the workspace are organized in a nested - hierarchy of packages, where each package is a directory that contains a set - of related source files and one BUILD file. The BUILD file specifies what - software outputs can be built from the source. -</p> -<h2 id="packages_targets">Workspace, Packages and Targets</h2> -<h3 id="workspace">Workspace</h3> - -<p>A <em>workspace</em> is a directory on your filesystem that contains the - source files for the software you want to build, as well as symbolic links - to directories that contain the build outputs. Each workspace directory has - a text file named <code>WORKSPACE</code> which may be empty, or may contain - references to <a href="/docs/external.html">external dependencies</a> - required to build the outputs. See also the <a - href="/docs/be/workspace.html">Workspace Rules</a> section in the Build - Encyclopedia. -</p> -<h3 id="packages">Packages</h3> -<p> - The primary unit of code organization in a workspace is - the <i>package</i>. A package is collection of related files and a - specification of the dependencies among them. -</p> -<p> - A package is defined as a directory containing a file - named <code>BUILD</code>, residing beneath the top-level directory in the - workspace. A package includes all files in its directory, plus all - subdirectories beneath it, except those which themselves contain a BUILD - file. -</p> -<p> - For example, in the following directory tree - there are two packages, <code>my/app</code>, - and the subpackage <code>my/app/tests</code>. - Note that <code>my/app/data</code> is not a package, but a directory - belonging to package <code>my/app</code>. -</p> - -<pre> -src/my/app/BUILD -src/my/app/app.cc -src/my/app/data/input.txt -src/my/app/tests/BUILD -src/my/app/tests/test.cc -</pre> -<h3 id="targets">Targets</h3> - -<p> - A package is a container. The elements of a package are called - <i>targets</i>. Most targets are one of two principal kinds, <i>files</i> - and <i>rules</i>. Additionally, there is another kind of target, - <a href="be/functions.html#package_group">package groups</a>, - but they are far less numerous. -</p> - -<div style='margin:auto; text-align: center'> -<div class='graphviz dot'><!-- -digraph G1 { - node [shape=ellipse]; - Target -> Rule; - Rule -> cc_library - Rule -> java_test - Rule -> "..." - Target -> File; - File -> Source; - File -> Generated; - Target -> "Package group" -} ---></div> -<p><i>Hierarchy of targets.</i></p> -</div> - -<p> - Files are further divided into two kinds. - <i>Source files</i> are usually written by the efforts of people, - and checked in to the repository. - <i>Generated files</i>, sometimes called derived files, - are not checked in, but are generated by the build tool from source - files according to specific rules. -</p> - -<p> - The second kind of target is the <i>rule</i>. A rule specifies the - relationship between a set of input and a set of output files, - including the necessary steps to derive the outputs from the inputs. - The outputs of a rule are always generated files. The inputs to a - rule may be source files, but they may be generated files also; - consequently, outputs of one rule may be the inputs to another, - allowing long chains of rules to be constructed. -</p> - -<p> - Whether the input to a rule is a source file or a generated file is - in most cases immaterial; what matters is only the contents of that - file. This fact makes it easy to replace a complex source file with - a generated file produced by a rule, such as happens when the burden - of manually maintaining a highly structured file becomes too - tiresome, and someone writes a program to derive it. No change is - required to the consumers of that file. Conversely, a generated - file may easily be replaced by a source file with only local - changes. -</p> - -<p> - The inputs to a rule may also include <i>other rules</i>. The - precise meaning of such relationships is often quite complex and - language- or rule-dependent, but intuitively it is simple: a C++ - library rule A might have another C++ library rule B for an input. - The effect of this dependency is that the B's header files are - available to A during compilation, B's symbols are available to A - during linking, and B's runtime data is available to A during - execution. -</p> - -<p> - An invariant of all rules is that the files generated by a rule - always belong to the same package as the rule itself; it is not - possible to generate files into another package. It is not uncommon - for a rule's inputs to come from another package, though. -</p> - -<p> - Package groups are sets of packages whose purpose is to limit accessibility - of certain rules. Package groups are defined by the - <code>package_group</code> function. They have two properties: the list of - packages they contain and their name. The only allowed ways to refer to them - are from the <code>visibility</code> attribute of rules or from the - <code>default_visibility</code> attribute of the <code>package</code> - function; they do not generate or consume files. For more information, refer - to the appropriate section of the <a - href='be/functions.html#package_group'>Build Encyclopedia</a>. -</p> - - -<h3 id="labels">Labels</h3> - -<p> - All targets belong to exactly one package. The name of a target is - called its <em>label</em>, and a typical label in canonical form - looks like this: -</p> - -<pre> -//my/app/main:app_binary -</pre> - -<p> - - Each label has two parts, a package name (<code>my/app/main</code>) - and a target name (<code>app_binary</code>). Every label uniquely - identifies a target. Labels sometimes appear in other forms; when - the colon is omitted, the target name is assumed to be the same as - the last component of the package name, so these two labels are - equivalent: -</p> - -<pre> -//my/app -//my/app:app -</pre> - -<p> - Short-form labels such as <code>//my/app</code> are not to - be confused with package names. Labels start with <code>//</code>, - but package names never do, thus <code>my/app</code> is the - package containing <code>//my/app</code>. - - (A common misconception is that <code>//my/app</code> refers - to a package, or to <em>all</em> the targets in a package; neither - is true.) -</p> - -<p> - Within a BUILD file, the package-name part of label may be omitted, - and optionally the colon too. So within the BUILD file for package - <code>my/app</code> (i.e. <code>//my/app:BUILD</code>), - the following "relative" labels are all equivalent: -</p> - -<pre> -//my/app:app -//my/app -:app -app -</pre> - -<p> - (It is a matter of convention that the colon is omitted for files, - but retained for rules, but it is not otherwise significant.) -</p> - -<p> - Similarly, within a BUILD file, files belonging to the package may - be referenced by their unadorned name relative to the package - directory: -</p> - - -<pre> -generate.cc -testdata/input.txt -</pre> - -<p> - But from other packages, or from the command-line, these file - targets must always be referred to by their complete label, e.g. - <code>//my/app:generate.cc</code>. -</p> - -<p> - Relative labels cannot be used to refer to targets in other - packages; the complete package name must always be specified in this - case. For example, if the source tree contains both the package - <code>my/app</code> and the package - <code>my/app/testdata</code> (i.e., each of these two - packages has its own BUILD file). The latter package contains a - file named <code>testdepot.zip</code>. Here are two ways (one - wrong, one correct) to refer to this file within - <code>//my/app:BUILD</code>: -</p> - -<pre> -<span class="discouraged">testdata/testdepot.zip</span> # Wrong: testdata is a different package. -//my/app/testdata:testdepot.zip # Right. -</pre> - -<p> - If, by mistake, you refer to <code>testdepot.zip</code> by the wrong - label, such as <code>//my/app:testdata/testdepot.zip</code> - or <code>//my:app/testdata/testdepot.zip</code>, you will get an - error from the build tool saying that the label "crosses a package - boundary". You should correct the label by putting the colon after - the directory containing the innermost enclosing BUILD file, i.e., - <code>//my/app/testdata:testdepot.zip</code>. -</p> - -<h3 id="lexi">Lexical specification of a label</h3> - -<p> - The syntax of labels is intentionally strict, so as to - forbid metacharacters that have special meaning to the shell. This - helps to avoid inadvertent quoting problems, and makes it easier to - construct tools and scripts that manipulate labels, such as the - - <a href="query.html">Bazel Query Language</a>. - All of the following are forbidden in labels: any sort of white - space, braces, brackets, or parentheses; wildcards such - as <code>*</code>; shell metacharacters such - as <code>></code>, <code>&</code> and <code>|</code>; etc. - This list is not comprehensive; the precise details are below. -</p> - -<h4 id="name">Target names, <code>//...:<b>target-name</b></code></h4> - -<p><code>target-name</code> is the name of the target within the package. - The name of a rule is the value of the <code>name</code> - parameter in the rule's declaration in a BUILD file; the name - of a file is its pathname relative to the directory containing - the BUILD file. - Target names must be composed entirely of - characters drawn from the set <code>a</code>–<code>z</code>, - <code>A</code>–<code>Z</code>, <code>0</code>–<code>9</code>, - and the punctuation symbols <code>_/.+-=,@~</code>. - Do not use <code>..</code> to refer to files in other packages; use - <code>//<var>packagename</var>:<var>filename</var></code> instead. - Filenames must be relative pathnames in normal form, which means - they must neither start nor end with a slash - (e.g. <code>/foo</code> and <code>foo/</code> are forbidden) nor - contain multiple consecutive slashes as path separators - (e.g. <code>foo//bar</code>). Similarly, up-level references - (<code>..</code>) and current-directory references - (<code>./</code>) are forbidden. The sole exception to this - rule is that a target name may consist of exactly - '<code>.</code>'. -</p> - -<p>While it is common to use <code>/</code> in the name of a file - target, we recommend that you avoid the use of <code>/</code> in the - names of rules. Especially when the shorthand form of a label is - used, it may confuse the reader. The - label <code>//foo/bar/wiz</code> is always a shorthand - for <code>//foo/bar/wiz:wiz</code>, even if there is no such package - <code>foo/bar/wiz</code>; it never refers to <code>//foo:bar/wiz</code>, - even if that target exists.</p> - -<p>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.</p> - -<h4>Package names, <code>//<b>package-name</b>:...</code></h4> -<p> - The name of a package is the name of the directory containing its - - BUILD file, relative to the top-level directory of the source tree. - For example: <code>my/app</code>. - - Package names must be composed entirely of characters drawn from - the set <code>A</code>-<code>Z</code>, <code>a</code>–<code>z</code>, - <code>0</code>–<code>9</code>, '<code>/</code>', '<code>-</code>', - '<code>.</code>', and '<code>_</code>', and cannot start with - a slash. -<p> - For a language with a directory structure that is significant - to its module system (e.g. Java), it is important to choose directory names - that are valid identifiers in the language. -</p> - -<p> - Although Bazel allows a package at the build root (e.g. <code>//:foo</code>), this - is not advised and projects should attempt to use more descriptively named - packages. -</p> -<p> - Package names may not contain the substring <code>//</code>, nor - end with a slash. -</p> - -<h3 id="rules">Rules</h3> - -<p> - A rule specifies the relationship between inputs and outputs, and the - steps to build the outputs. Rules can be of one of many different - kinds or <i>classes</i>, which produce compiled - executables and libraries, test executables and other supported - outputs as described in the - <a href="be/overview.html">Build Encyclopedia</a>. -</p> - -<p> - Every rule has a name, specified by the <code>name</code> attribute, - of type string. The name must be a syntactically valid target name, - as specified <a href='#name'>above</a>. In some cases, the name is - somewhat arbitrary, and more interesting are the names of the files - generated by the rule; this is true of genrules. In other - cases, the name is significant: for <code>*_binary</code> - and <code>*_test</code> rules, for example, the rule name determines - the name of the executable produced by the build. -</p> - -<p> - Every rule has a set of <i>attributes</i>; the applicable attributes - for a given rule, and the significance and semantics of each - attribute are a function of the rule's class; see - the <a href='be/overview.html'>Build - Encyclopedia</a> for the full list of supported rules and their - corresponding attributes. Each attribute has a name and a - type. The full set of types that an attribute can have is: integer, - label, list of labels, string, list of strings, output label, - list of output labels. Not all attributes need to be specified in - every rule. Attributes thus form a dictionary from keys (names) to - optional, typed values. -</p> - -<p> - The <code>srcs</code> attribute present in many rules has type "list - of label"; its value, if present, is a list of labels, each being - the name of a target that is an input to this rule. -</p> - -<p> - The <code>outs</code> attribute present in many rules has type "list - of output labels"; this is similar to the type of - the <code>srcs</code> attribute, but differs in two significant - ways. Firstly, due to the invariant that the outputs of a rule - belong to the same package as the rule itself, output labels cannot - include a package component; they must be in one of the "relative" - forms shown above. Secondly, the relationship implied by an - (ordinary) label attribute is inverse to that implied by an output - label: a rule <i>depends on</i> its <code>srcs</code>, whereas a rule <i>is - depended on by</i> its <code>outs</code>. The two types of label attributes - thus assign direction to the edges between targets, giving rise to a - dependency graph. -</p> - -<p> - The figure below represents an example fragment of the build - dependency graph, and illustrates: files (circles) and rules - (boxes); dependencies from generated files to rules; dependencies - from rules to files, and from rules to other rules. Conventionally, - dependency arrows are represented as pointing from a target towards - its prerequisites. -</p> - -<div style="margin:auto; text-align:center"> -<div class='graphviz dot'><!-- -digraph G1 { - graph [rankdir=BT]; - node [fontname="Courier-Bold",fontsize=10,fontcolor="#006000"]; - - node [shape=box,label="rule"]; r1; r2; - - node [shape=circle,width=.4,fixedsize=1]; - node [label="in"]; s1; s2; s3; s4; - node [label="out"]; o1; o2; - - r1 -> s1; - r1 -> s2; - r1 -> s3; - r2 -> s4; - r2 -> r1; - o1 -> r1; - o2 -> r2; -} ---></div> -<p><i>Source files, rules, and generated files.</i></p> -</div> - -<p> - This directed acyclic graph over targets is called the - "target graph" or "build dependency graph", and is the domain over - which the - - <a href="query.html">Bazel Query tool</a></li> - operates. -</p> - - -<h2 id="BUILD_files">BUILD Files</h2> - -<p> - The previous section described packages, targets and labels, and the - build dependency graph abstractly. In this section, we'll look at - the concrete syntax used to define a package. -</p> - -<p> - By definition, every package contains a BUILD file, which is a short - program written in the Build Language. Most BUILD files - appear to be little more than a series of declarations of build - rules; indeed, the declarative style is strongly encouraged when - writing BUILD files. -</p> - -<p> - However, the build language is in fact an imperative language, and - BUILD files are interpreted as a sequential list of statements. - Build rule functions, such as <code>cc_library</code>, are procedures whose - side-effect is to create an abstract build rule inside the build tool. -</p> - -<p> - The concrete syntax of BUILD files is a subset of Python. - Originally, the syntax <i>was</i> that of Python, but experience - showed that users rarely used more than a tiny subset of Python's - features, and when they did, it often resulted in complex and - fragile BUILD files. In many cases, the use of such features was - unnecessary, and the same result could be achieved by using an - external program, e.g. via a <code>genrule</code> build rule. -</p> - -<p> - Crucially, programs in the build language are unable to perform - arbitrary I/O (though many users try!). This invariant makes the - interpretation of BUILD files hermetic, i.e. dependent only on a - known set of inputs, which is essential for ensuring that builds are - reproducible. -</p> - -<h3 id="core_build_language">The Core Build Language</h3> - -<p> - <b>Lexemes</b>: the lexical syntax of the core language is a strict - subset of Python 2.6, and we refer the reader to the <a - href='http://docs.python.org/reference/lexical_analysis.html'>Python - specification</a> for details. - Lexical features of Python that are not - supported include: floating-point literals, hexadecimal and Unicode - escapes within string literals. -</p> - -<p> - BUILD files should be written using only ASCII characters, - although technically they are interpreted using the Latin-1 - character set. The use - of <a href='http://www.python.org/dev/peps/pep-0263/'><code>coding:</code></a> - declarations is forbidden. -</p> - -<p> - <b>Grammar</b>: the grammar of the core language is shown below, - using EBNF notation. Ambiguity is resolved using precedence, which - is defined as for Python. -</p> - -<pre> -file_input ::= (simple_stmt? '\n')* - -simple_stmt ::= small_stmt (';' small_stmt)* ';'? - -small_stmt ::= expr - | assign_stmt - -assign_stmt ::= IDENTIFIER '=' expr - -expr ::= INTEGER - | STRING+ - | IDENTIFIER - | IDENTIFIER '(' arg_list? ')' - | expr '.' IDENTIFIER - | expr '.' IDENTIFIER '(' arg_list? ')' - | '[' expr_list? ']' - | '[' expr ('for' IDENTIFIER 'in' expr)+ ']' - | '(' expr_list? ')' - | '{' dict_entry_list? '}' - | '{' dict_entry ('for' IDENTIFIER 'in' expr)+ '}' - | expr '+' expr - | expr '-' expr - | expr '%' expr - | '-' expr - | expr '[' expr? ':' expr? ']' - | expr '[' expr ']' - -expr_list ::= (expr ',')* expr ','? - -dict_entry_list ::= (dict_entry ',')* dict_entry ','? - -dict_entry ::= expr ':' expr - -arg_list ::= (arg ',')* arg ','? - -arg ::= IDENTIFIER '=' expr - | expr -</pre> - -<p> - For each expression of the core language, the semantics are - identical to the corresponding Python semantics, except in the - following cases: -</p> -<ul> - <li>certain overloads of the binary <code>%</code> operator are not - supported. Only the <code>int % int</code> and <code>str % - tuple</code> forms are supported. Only the <code>%s</code> - and <code>%d</code> format specifiers may be - used; <code>%(var)s</code> is illegal.</li> - -</ul> - -<p> - Many Python features are missing: control-flow constructs (loops, - conditionals, exceptions), basic datatypes (floating-point numbers, big - integers), <code>import</code> and the module system, support for - definition of classes, some Python's built-in functions. Function - definitions and <code>for</code> statements are allowed only in - extension files (<code>.bzl</code>). - - Available functions are documented in - - the <a href="skylark/lib/globals.html">library section</a>. -<h3 id="declaring_build_rules">Declaring build rules</h3> - -<p> - The build language is an imperative language, so in general, order - does matter: variables must be defined before they are used, for - example. However, most BUILD files consist only of declarations of - build rules, and the relative order of these statements is - immaterial; all that matters is <em>which</em> rules were declared, - and with what values, by the time package evaluation completes. - - So, in simple BUILD files, rule declarations can be re-ordered - freely without changing the behavior. -</p> - -<p> - BUILD file authors are encouraged to use comments liberally to - document the role of each build target, whether it is intended for - public use, and anything else that would help users and future - maintainers, including a <code># Description:</code> comment at the - top, explaining the role of the package. -</p> - -<p> - The Python comment syntax of <code>#...</code> is supported. - Triple-quoted string literals may span multiple lines, and can be used - for multi-line comments. -</p> - -<h2 id="funcs">Types of build rule</h2> - -<p> - The majority of build rules come in families, grouped together by - language. For - example, <code>cc_binary</code>, <code>cc_library</code> - and <code>cc_test</code> are the build rules for C++ binaries, - libraries, and tests, respectively. Other languages use the same - naming scheme, with a different prefix, e.g. <code>java_*</code> for - Java. These functions are all documented in the - <a href="be/overview.html">Build Encyclopedia</a>. -</p> - -<ul> - <li><p><code>*_binary</code> - rules build executable programs in a given language. After a - build, the executable will reside in the build tool's binary - output tree at the corresponding name for the rule's label, - so <code>//my:program</code> would appear at - (e.g.) <code>$(BINDIR)/my/program</code>. </p> - - <p>Such rules also create a runfiles directory - - containing all the files mentioned in a <code>data</code> - attribute belonging to the rule, or any rule in its transitive - closure of dependencies; this set of files is gathered together in - one place for ease of deployment to production.</p> - </li> - - <li><p><code>*_test</code> - rules are a specialization of a <code>*_binary</code> rule, used for automated - testing. Tests are simply programs that return zero on success. - - </p> - - <p> - Like binaries, tests also have runfiles trees, and the files - beneath it are the only files that a test may legitimately open - at runtime. For example, a program <code>cc_test(name='x', - data=['//foo:bar'])</code> may open and - - read <code>$TEST_SRCDIR/workspace/foo/bar</code> during execution. - (Each programming language has its own utility function for - accessing the value of <code>$TEST_SRCDIR</code>, but they are all - equivalent to using the environment variable directly.) - Failure to observe the rule will cause the test to fail when it is - executed on a remote testing host. - - </p> - </li> - - <li><code>*_library</code> - rules specify separately-compiled modules in the given - programming language. Libraries can depend on other libraries, - and binaries and tests can depend on libraries, with the expected - separate-compilation behavior. - </li> -</ul> - -<h2 id="dependencies">Dependencies</h2> - -<p> - A target <code>A</code> <i>depends upon</i> a target - <code>B</code> if <code>B</code> is needed by <code>A</code> at - build or execution time. The <i>depends upon</i> relation induces a - directed acyclic graph (DAG) over targets, and we call this a - <em>dependency graph</em>. - - A target's <em>direct</em> dependencies are those other targets - reachable by a path of length 1 in the dependency graph. A target's - <em>transitive</em> dependencies are those targets upon which it - depends via a path of any length through the graph. -</p> - -<p> - In fact, in the context of builds, there are two dependency graphs, - the graph of <em>actual dependencies</em> and the graph of - <em>declared dependencies</em>. 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. -</p> - -<h3 id="actual_and_declared_dependencies">Actual and declared dependencies</h3> - -<p> - A target <code>X</code> is <i>actually dependent</i> on target - <code>Y</code> iff <code>Y</code> must be present, built and - up-to-date in order for <code>X</code> to be built correctly. - "Built" could mean generated, processed, compiled, linked, - archived, compressed, executed, or any of the other kinds of tasks - that routinely occur during a build. -</p> - -<p> - A target <code>X</code> has a <i>declared dependency</i> on target - <code>Y</code> iff there is a dependency edge from <code>X</code> to - <code>Y</code> in the package of <code>X</code>. -</p> - -<p> - For correct builds, the graph of actual dependencies <i>A</i> must - be a subgraph of the graph of declared dependencies <i>D</i>. That - is, every pair of directly-connected nodes <code>x --> y</code> - in <i>A</i> must also be directly connected in <i>D</i>. We say - <i>D</i> is an <em>overapproximation</em> of <i>A</i>. -</p> - -<p> - It is important that it not be too much of an overapproximation, - though, since redundant declared dependencies can make builds slower and - binaries larger. -</p> - -<p> - What this means for BUILD file writers is that every rule must - explicitly declare all of its actual direct dependencies to the - build system, and no more. - - Failure to observe this principle causes undefined behavior: the - build may fail, but worse, the build may depend on some prior - operations, or upon which transitive declared dependencies the target - happens to have. The build tool attempts aggressively to check for - missing dependencies and report errors, but it is not possible for - this checking to be complete in all cases. -</p> - -<p> - - You need not (and should not) attempt to list everything indirectly imported, - even if it is "needed" by A at execution time. -</p> - -<p> - During a build of target <code>X</code>, the build tool inspects the - entire transitive closure of dependencies of <code>X</code> to ensure that - any changes in those targets are reflected in the final result, - rebuilding intermediates as needed. -</p> - -<p> - The transitive nature of dependencies leads to a common mistake. - Through careless programming, code in one file may use code provided - by an <em>indirect</em> dependency, i.e. a transitive but not direct - edge in the declared dependency graph. Indirect dependencies do not - appear in the BUILD file. Since the rule doesn't - directly depend on the provider, there is no way to track changes, - as shown in the following example timeline: -</p> - -<div class="greenbox"> -<p><b>1. At first, everything works</b></p> - -<p>The code in package <code>a</code> uses code in package <code>b</code>. -The code in package <code>b</code> uses code in package <code>c</code>, -and thus <code>a</code> transitively depends on <code>c</code>.</p> - -<div style="float:left; width: 49%; margin-top: -20px;"> -<p><code>a/BUILD</code></p> -<pre class="code"> -<b>rule( - name = "a", - srcs = "a.in", - deps = "//b:b", -)</b> -</pre> -<p><code>a/a.in</code></p> -<pre class="code"> -<b>import b; -b.foo();</b> -</pre> -</div> -<div style="float:right; width: 49%; margin-top: -20px; "> -<p><code>b/BUILD</code></p> -<pre class="code"> -<b>rule( - name = "b", - srcs = "b.in", - deps = "//c:c", -)</b> -</pre> -<p><code>b/b.in</code></p> -<pre class="code"> -<b>import c; -function foo() { - c.bar(); -}</b> -</pre> -</div> -<pre style="clear: both;"> -Declared dependency graph: a --> b --> c - -Actual dependency graph: a --> b --> c -</pre> -The declared dependencies overapproximate the actual dependencies. -All is well. -</div> - -<div class="greenbox"> -<p><b>2. A latent hazard is introduced.</b></p> -<p> - Someone carelessly adds code to <code>a</code> that creates a direct - actual dependency on <code>c</code>, but forgets to declare it. -</p> -<div style="float:left; width: 49%; margin-top: -20px; "> -<p><code>a/a.in</code></p> -<pre class="code"> -import b; -<b>import c;</b> -b.foo(); -<b>c.garply();</b> -</pre> -</div> - -<pre style="clear: both;"> -Declared dependency graph: a --> b --> c - -Actual dependency graph: a --> b -->_c - \_________/| -</pre> -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: <code>a</code> has an -actual but undeclared dependency on <code>c</code>. -</div> - -<div class="greenbox"> -<p><b>3. The hazard is revealed</b> </p> -<p> - Someone refactors <code>b</code> so that it no longer depends on - <code>c</code>, inadvertently breaking <code>a</code> through no - fault of their own. -</p> -<div style="float:right; width: 49%; margin-top: -20px; "> -<p><code>b/BUILD</code></p> -<pre class="code"> -rule( - name = "b", - srcs = "b.in", - <b>deps = "//d:d"</b>, -) -</pre> -<p><code>b/b.in</code></p> -<pre class="code"> -<b>import d;</b> -function foo() { - <b>d.baz();</b> -} -</pre> -</div> -<pre style="clear: both;"> -Declared dependency graph: a --> b c - -Actual dependency graph: a --> b _c - \_________/| -</pre> -<p> - The declared dependency graph is now an underapproximation of the - actual dependencies, even when transitively closed; the build is - likely to fail. - - The problem could have been averted by ensuring that the actual - dependency from <code>a</code> to <code>c</code> introduced in Step - 2 was properly declared in the BUILD file. -</div> - -<h3 id="types_of_dependencies">Types of dependencies</h3> - -<p> - Most build rules have three attributes for specifying different kinds - of generic dependencies: <code>srcs</code>, <code>deps</code> and - <code>data</code>. These are explained below. See also - <a href='be/common-definitions.html'>Attributes common - to all rules</a> in the Build Encyclopedia.) -</p> - -<p> - Many rules also have additional attributes for rule-specific kinds - of dependency, e.g. <code>compiler</code>, <code>resources</code>, - etc. These are detailed in the Build Encyclopedia. -</p> - -<h4 id="srcs"><code>srcs</code> dependencies</h4> -<p> - Files consumed directly by the rule or rules that output source files. -</p> - -<h4 id="deps"><code>deps</code> dependencies</h4> -<p> - Rule pointing to separately-compiled modules providing header files, - symbols, libraries, data, etc. -</p> - -<h4 id="data"><code>data</code> dependencies</h4> -<p>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 unit test might compare a function's output - to the contents of a file. When we build the unit test, we - don't need the file; but we do need it when we run the test. The - same applies to tools that are launched during execution. - -<p>The build system runs tests in an isolated directory where only files - listed as "data" are available. Thus, if a binary/library/test - needs some files to run, specify them (or a build rule containing - them) in data. For example: -</p> - -<pre> -# I need a config file from a directory named env: -java_binary( - name = "setenv", - ... - data = [":env/default_env.txt"], -) - -# I need test data from another directory -sh_test( - name = "regtest", - srcs = ["regtest.sh"], - data = [ - "//data:file1.txt", - "//data:file2.txt", - ... - ], -) -</pre> - -<p>These files are available using the relative path -<code>path/to/data/file</code>. In tests, it is also possible to refer to -them by joining the paths of the test's source directory and the workspace-relative -path, e.g. - -<code>${TEST_SRCDIR}/workspace/path/to/data/file</code>. - <h3 id="label_directory">Using Labels to Reference Directories</h3> - - <p>As you look over our <code>BUILD</code> files, you might notice - that some <code>data</code> labels refer to directories. - These labels end with <code>/.</code> or <code>/</code> like so: - -<pre> -<span style="text-decoration: line-through">data = ["//data/regression:unittest/."]</span> # don't use this -</pre> -<p> -or like so: -</p> -<pre> -<span style="text-decoration: line-through">data = ["testdata/."]</span> # don't use this -</pre> - -<p> -or like so: -</p> - -<pre> -<span style="text-decoration: line-through">data = ["testdata/"]</span> # don't use this -</pre> - <p>This seems convenient, particularly for tests (since it allows a test to - use all the data files in the directory). - </p> - - <p>But try not to do this. In order to ensure correct incremental rebuilds (and - re-execution of tests) after a change, the build system must be - aware of the complete set of files that are inputs to the build (or - test). When you specify a directory, the build system will perform - a rebuild only when the directory itself changes (due to addition or - deletion of files), but won't be able to detect edits to individual - files as those changes do not affect the enclosing directory. - Rather than specifying directories as inputs to the build system, - you should enumerate the set of files contained within them, either - explicitly or using the - <a href='be/functions.html#glob'><code>glob()</code></a> function. - (Use <code>**</code> to force the <a href='be/functions.html#glob'> - <code>glob()</code></a> to be recursive.) - </p> - -<pre> -data = glob(["testdata/**"]) # use this instead -</pre> - - <p>Unfortunately, there are some scenarios where directory labels must be used. - For example, if the <code>testdata</code> directory contains files whose - names do not conform to the strict <a href='#lexi'>label syntax</a> - (e.g. they contain certain punctuation symbols), then explicit - enumeration of files, or use of the - <a href='be/functions.html#glob'><code>glob()</code></a> function will - produce an invalid labels error. You must use directory labels in this case, - but beware of the concomitant risk of incorrect rebuilds described above. - </p> - - <p>If you must use directory labels, keep in mind that you can't refer to the parent - package with a relative "<code>../</code>" path; instead, use an absolute path like - "<code>//data/regression:unittest/.</code>". - </p> - - <p>Note that directory labels are only valid for data dependencies. If you try to use - a directory as a label in an argument other than <code>data</code>, it - will fail and you will get a (probably cryptic) error message. - </p> - diff --git a/site/versions/master/docs/docs_style.css b/site/versions/master/docs/docs_style.css deleted file mode 100644 index bb225e1fd9..0000000000 --- a/site/versions/master/docs/docs_style.css +++ /dev/null @@ -1,61 +0,0 @@ -* { - font-family: "Open Sans", sans-serif; -} - -h1, h2, h3, h4, h5, h6 { - color: #444; - font-weight: 400; -} - -p, li { - font-size: 14px; - color: #444; - font-weight: 400; -} - -a { - color: #49b; - font-weight: 600; -} - -code { - font-family: monospace; - font-size: 13px; - color: #000; -} - -pre { - display: block; - background-color: #f5f7f9; - border: 1px solid #9ab; - padding: 0.5em; -} - -table { - border-spacing: 0px; - border: 1px solid #9ab; -} - -th, td { - border-left: 1px solid #9ab; -} - -th:first-child, td:first-child { - border-left: none; -} - -th { - padding: 0.5em; -} - -td { - padding: 0.3em; -} - -tr:nth-child(odd) { - background: #eee; -} - -tr:nth-child(even) { - background: #fff; -} diff --git a/site/versions/master/docs/external.md b/site/versions/master/docs/external.md deleted file mode 100644 index dae89f88bc..0000000000 --- a/site/versions/master/docs/external.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -layout: documentation -title: External Dependencies ---- - -# Working with external dependencies - -External dependencies can be specified in the `WORKSPACE` file of the -[workspace directory](/docs/build-ref.html#workspace). This `WORKSPACE` file -uses the same syntax as BUILD files, but allows a different set of -rules. The full list of rules are in the Build Encyclopedia's -[Workspace Rules](/docs/be/workspace.html). - -External dependencies are all downloaded and symlinked under a directory named -`external`. You can see this directory by running: - -``` -ls $(bazel info output_base)/external -``` - -Note that running `bazel clean` will not actually delete the external -directory. To remove all external artifacts, use `bazel clean --expunge`. - -## Supported types of external dependencies - -A few basic types of external dependencies can be used: - -- [Dependencies on other Bazel projects](#bazel-projects) -- [Dependencies on non-Bazel projects](#non-bazel-projects) -- [Dependencies on external packages](#external-packages) - -<a name="bazel-projects"></a> -### Depending on other Bazel projects - -If you want to use targets from a second Bazel project, you can -use -[`local_repository`](http://bazel.build/docs/be/workspace.html#local_repository), -[`git_repository`](https://bazel.build/docs/be/workspace.html#git_repository) -or [`http_archive`](http://bazel.build/docs/be/workspace.html#http_archive) -to symlink it from the local filesystem, reference a git repository or download -it (respectively). - -For example, suppose you are working on a project, `my-project/`, and you want -to depend on targets from your coworker's project, `coworkers-project/`. Both -projects use Bazel, so you can add your coworker's project as an external -dependency and then use any targets your coworker has defined from your own -BUILD files. You would add the following to `my_project/WORKSPACE`: - -```python -local_repository( - name = "coworkers-project", - path = "/path/to/coworkers-project", -) -``` - -If your coworker has a target `//foo:bar`, your project can refer to it as -`@coworkers-project//foo:bar`. - -<a name="non-bazel-projects"></a> -### Depending on non-Bazel projects - -Rules prefixed with `new_` (e.g., -[`new_local_repository`](http://bazel.build/docs/be/workspace.html#new_local_repository), -[`new_git_repository`](https://bazel.build/docs/be/workspace.html#new_git_repository) -and [`new_http_archive`](http://bazel.build/docs/be/workspace.html#new_http_archive) -) allow you to create targets from projects that do not use Bazel. - -For example, suppose you are working on a project, `my-project/`, and you want -to depend on your coworker's project, `coworkers-project/`. Your coworker's -project uses `make` to build, but you'd like to depend on one of the .so files -it generates. To do so, add the following to `my_project/WORKSPACE`: - -```python -new_local_repository( - name = "coworkers-project", - path = "/path/to/coworkers-project", - build_file = "coworker.BUILD", -) -``` - -`build_file` specifies a BUILD file to overlay on the existing project, for -example: - -```python -java_library( - name = "some-lib", - srcs = glob(["**"]), - visibility = ["//visibility:public"], -) -``` - -You can then depend on `@coworkers-project//:some-lib` from your project's BUILD -files. - -<a name="external-packages"></a> -### Depending on external packages - -#### Maven repositories - -Use the rule [`maven_jar`](https://bazel.build/versions/master/docs/be/workspace.html#maven_jar) -(and optionally the rule [`maven_server`](https://bazel.build/versions/master/docs/be/workspace.html#maven_server)) -to download a jar from a Maven repository and make it available as a Java -dependency. - -## Fetching dependencies - -By default, external dependencies are fetched as needed during `bazel build`. If -you would like to disable this behavior or prefetch dependencies, use -[`bazel fetch`](http://bazel.build/docs/bazel-user-manual.html#fetch). - -## Using Proxies - -Bazel will pick up proxy addresses from the `HTTPS_PROXY` and `HTTP_PROXY` -environment variables and use these to download HTTP/HTTPS files (if specified). - -<a name="transitive-dependencies"></a> -## Transitive dependencies - -Bazel only reads dependencies listed in your `WORKSPACE` file. If your project -(`A`) depends on another project (`B`) which list a dependency on a third -project (`C`) in its `WORKSPACE` file, you'll have to add both `B` -and `C` to your project's `WORKSPACE` file. This requirement can balloon the -`WORKSPACE` file size, but hopefully limits the chances of having one library -include `C` at version 1.0 and another include `C` at 2.0. - -## Generate a `WORKSPACE` file - -Bazel provides a tool to help generate these expansive `WORKSPACE` files, called -`generate_workspace`. This tool is not included with the binary installer, so -you'll need to clone the [GitHub repo](https://github.com/bazelbuild/bazel) to -use it. We recommend using the tag corresponding to your current version of -bazel, which you can check by running `bazel version`. - -`cd` to the GitHub clone, `git checkout` the appropriate tag, and run the -following to build the tool and see usage: - -``` -bazel run //src/tools/generate_workspace -``` - -Note that you need run this command from your Bazel source folder even if you -build your binary from source. - -You can specify directories containing Bazel projects (i.e., directories -containing a `WORKSPACE` file), Maven projects (i.e., directories containing a -`pom.xml` file), or Maven artifact coordinates directly. For example: - -```bash -$ bazel run //src/tools/generate_workspace -- \ -> --maven_project=/path/to/my/project \ -> --bazel_project=/path/to/skunkworks \ -> --bazel_project=/path/to/teleporter/project \ -> --artifact=groupId:artifactId:version \ -> --artifact=groupId:artifactId:version -Wrote: -/tmp/1437415510621-0/2015-07-20-14-05-10.WORKSPACE -/tmp/1437415510621-0/2015-07-20-14-05-10.BUILD -``` - -The `WORKSPACE` file will contain the transitive dependencies of the given -projects and artifacts. The `BUILD` file will contain a single target, -`transitive-deps`, that contains all of the dependencies. You can copy these -files to your project and add `transitive-deps` as a dependency of your `java_` -targets in `BUILD` files. - -If you specify multiple Bazel projects, Maven projects, or artifacts, they will -all be combined into one `WORKSPACE` file (e.g., if the Bazel project depends on -junit and the Maven project also depends on junit, junit will only appear once -as a dependency in the output). - -You may wish to curate the generated `WORKSPACE` file to ensure it is using the -correct version of each dependency. If several different versions of an artifact -are requested (by different libraries that depend on it), then -`generate_workspace` chooses a version and annotates the `maven_jar` with the -other versions requested, for example: - -```python -# org.springframework:spring:2.5.6 -# javax.mail:mail:1.4 -# httpunit:httpunit:1.6 wanted version 1.0.2 -# org.springframework:spring-support:2.0.2 wanted version 1.0.2 -# org.slf4j:nlog4j:1.2.24 wanted version 1.0.2 -maven_jar( - name = "javax_activation_activation", - artifact = "javax.activation:activation:1.1", -) -``` - -The example above indicates that `org.springframework:spring:2.5.6`, -`javax.mail:mail:1.4`, `httpunit:httpunit:1.6`, -`org.springframework:spring-support:2.0.2`, and `org.slf4j:nlog4j:1.2.24` -all depend on javax.activation. However, two of these libraries wanted -version 1.1 and three of them wanted 1.0.2. The `WORKSPACE` file is using -version 1.1, but that might not be the right version to use. - -You may also want to break `transitive-deps` into smaller targets, as it is -unlikely that all of your targets depend on the transitive closure of your -maven jars. - -## Caching of external dependencies - -Bazel caches external dependencies and re-downloads or updates them when -the `WORKSPACE` file changes. diff --git a/site/versions/master/docs/getting-started.md b/site/versions/master/docs/getting-started.md deleted file mode 100644 index 66a87e40c1..0000000000 --- a/site/versions/master/docs/getting-started.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -layout: documentation -title: Getting Started ---- - -# Getting Started with Bazel - -## Setup - -Use the [installation instructions](/docs/install.html) to install a copy of -Bazel on your machine. - -## Using a Workspace - -All Bazel builds take place in a [_workspace_](/docs/build-ref.html#workspaces), -a directory on your filesystem that contains source code for the software you -want to build, as well symbolic links to directories that contain the build -outputs (for example, `bazel-bin` and `bazel-out`). The location of the -workspace directory is not significant, but it must contain a file called -`WORKSPACE` in the top-level directory; an empty file is a valid workspace. -The `WORKSPACE` file can be used to reference -[external dependencies](/docs/external.html) required to build the outputs. -One workspace can be shared among multiple projects if desired. - -```bash -touch WORKSPACE -``` - -## Creating a Build File - -To know which targets can be built in your project, Bazel inspects `BUILD` -files. They are written in Bazel's build language which is syntactically -similar to Python. Usually they are just a sequence of declarations of rules. -Each rule specifies its inputs, outputs, and a way to compute the outputs from -the inputs. - -The rule probably most familiar to people who have used `Makefile`s before (as -it is the only rule available there) is the -[genrule](/docs/be/general.html#genrule), which specifies how the output can -be generated by invoking a shell command. - -``` -genrule( - name = "hello", - outs = ["hello_world.txt"], - cmd = "echo Hello World > $@", -) -``` - -The shell command may contain [Make variables](/docs/be/make-variables.html). - -Using the above `BUILD` file, you can ask Bazel to generate the target. - -``` -$ bazel build :hello -. -INFO: Found 1 target... -Target //:hello up-to-date: - bazel-genfiles/hello_world.txt -INFO: Elapsed time: 2.255s, Critical Path: 0.07s -``` - -We note two things. First, targets are normally referred to by their -[label](/docs/build-ref.html#labels), which is specified by the -[name](/docs/be/general.html#genrule.name) attribute of the rule. (Referencing -them by the output file name is also possible, but this is not the preferred -way.) Second, Bazel puts the generated files into a separate directory (the -`bazel-genfiles` directory is actually a symbolic link) so as not to pollute -your source tree. - -Rules may use the output of other rules as input, as in the following -example. Again, the generated sources are referred to by their label. - -``` -genrule( - name = "hello", - outs = ["hello_world.txt"], - cmd = "echo Hello World > $@", -) - -genrule( - name = "double", - srcs = [":hello"], - outs = ["double_hello.txt"], - cmd = "cat $< $< > $@", -) -``` - -Finally, note that, while the [genrule](/docs/be/general.html#genrule) might -seem familiar, it usually is _not_ the best rule to use. It is preferrable to -use one of the specialized [rules](/docs/be/overview.html#rules) for various -languages. - -# Next Steps - -Next, check out the tutorial on building [Java](/docs/tutorial/java.html) -or [C++](/docs/tutorial/cpp.html) programs. diff --git a/site/versions/master/docs/install-compile-source.md b/site/versions/master/docs/install-compile-source.md deleted file mode 100644 index 453d5658df..0000000000 --- a/site/versions/master/docs/install-compile-source.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -layout: documentation -title: Compile Bazel from Source ---- - -# <a name="compiling-from-source"></a>Compile Bazel from source - -1. Ensure that you have OpenJDK 8 installed on your system. - For a system based on debian packages (e.g. Debian, Ubuntu), install - OpenJDK 8 by running the command `sudo apt-get install openjdk-8-jdk`. - -2. The standard way of compiling a release version of Bazel from source is to - use a distribution archive. Download `bazel-<VERSION>-dist.zip` from the - [release page](https://github.com/bazelbuild/bazel/releases) for the desired - version. We recommend to also verify the signature made by our - [release key](https://bazel.build/bazel-release.pub.gpg) 48457EE0. - The distribution archive also contains generated files in addition to the - versioned sources, so this step _cannot_ be short cut by using a checkout - of the source tree. - -3. Unzip the archive and call `bash ./compile.sh`; this will create a bazel - binary in `output/bazel`. This binary is self-contained, so it can be copied - to a directory on the PATH (such as `/usr/local/bin`) or used in-place. - -## <a name="compiling-from-source-issues"></a>Known issues when compiling from source - -### On Windows: - -* version 0.4.4 and below: `compile.sh` may fail right after start with an error - like this: - - ``` - File not found - *.jar - no error prone jar - ``` - - Workaround is to run this (and add it to your `~/.bashrc`): - - ``` - export PATH="/bin:/usr/bin:$PATH" - ``` - -* version 0.4.3 and below: `compile.sh` may fail fairly early with many Java - compilation errors. The errors look similar to: - - ``` - C:\...\bazel_VR1HFY7x\src\com\google\devtools\build\lib\remote\ExecuteServiceGrpc.java:11: error: package io.grpc.stub does not exist - import static io.grpc.stub.ServerCalls.asyncUnaryCall; - ^ - ``` - - This is caused by a bug in one of the bootstrap scripts - (`scripts/bootstrap/compile.sh`). Manually apply this one-line fix if you - want to build Bazel purely from source (without using an existing Bazel - binary): [5402993a5e9065984a42eca2132ec56ca3aa456f]( https://github.com/bazelbuild/bazel/commit/5402993a5e9065984a42eca2132ec56ca3aa456f). - -* version 0.3.2 and below: - [github issue #1919](https://github.com/bazelbuild/bazel/issues/1919) diff --git a/site/versions/master/docs/install-os-x.md b/site/versions/master/docs/install-os-x.md deleted file mode 100644 index 249524b91e..0000000000 --- a/site/versions/master/docs/install-os-x.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -layout: documentation -title: Installing Bazel on macOS ---- - -# <a name="mac-os-x"></a>Install Bazel on macOS (OS X) - -> Note: Bazel release 0.5.0 contains a bug in the compiler detection on macOS which -> requires Xcode and the iOS tooling to be installed -> ([corresponding issue #3063](https://github.com/bazelbuild/bazel/issues/3063)). -> If you had Command Line Tools installed, you also need to switch to Xcode using -> `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`. - -Install Bazel on macOS (OS X) using one of the following methods: - -* [Use Homebrew (recommended)](#install-on-mac-os-x-homebrew) -* [Use the binary installer](#install-with-installer-mac-os-x) -* [Compile Bazel from source](install-compile-source.md) - -Bazel comes with two completion scripts. After installing Bazel, you can: - -* access the [bash completion script](install.md) -* install the [zsh completion script](install.md) - -## <a name="install-on-mac-os-x-homebrew"></a>Install using Homebrew - -### 1. Install JDK 8 - -JDK 8 can be downloaded from [Oracle's JDK -Page](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html). - -Look for "Mac OS X" under "Java SE Development Kit". This will download a DMG -image with an install wizard. - -### 2. Install Homebrew on macOS (OS X) - -Installing Homebrew is a one-time setup: - -```bash -/usr/bin/ruby -e "$(curl -fsSL -https://raw.githubusercontent.com/Homebrew/install/master/install)" -``` - -### 3. Install Bazel Homebrew Package - -```bash -brew install bazel -``` - -You are all set. You can confirm Bazel is installed successfully by running -`bazel version`. - -You can later upgrade to newer version of Bazel with `brew upgrade bazel`. - -## <a name="install-with-installer-mac-os-x"></a>Install using binary installer - -The binary installers are on Bazel's [GitHub releases page](https://github.com/bazelbuild/bazel/releases). - -The installer contains the Bazel binary and the required JDK. Some additional -libraries must also be installed for Bazel to work. - -### 1. Install XCode command line tools - -Xcode can be downloaded from the [Apple Developer -Site](https://developer.apple.com/xcode/downloads/) (this link redirects to -their App Store). - -For `objc_*` and `ios_*` rule support, you must have Xcode 6.1 or later with iOS -SDK 8.1 installed on your system. - -Once XCode is installed you can trigger signing the license with the following -command: - -``` -sudo gcc --version -``` - -### 2. Download the Bazel installer - -Go to Bazel's [GitHub releases page](https://github.com/bazelbuild/bazel/releases). - -Download the binary installer `bazel-0.5.0-installer-darwin-x86_64.sh`. This -installer contains the Bazel binary and the required JDK, and can be used even -if a JDK is already installed. - -Note that `bazel-0.5.0-without-jdk-installer-darwin-x86_64.sh` is a version of -the installer without embedded JDK 8. Only use this installer if you already -have JDK 8 installed. - -Note that two other versions of the installer exist: -* `bazel-0.5.0-without-jdk-installer-darwin-x86_64.sh`: version without - embedded JDK 8. Only use this installer if you already have JDK 8 installed. -* `bazel-0.5.0-jdk7-installer-darwin-x86_64.sh`: last release compatible - with JDK 7. - -### 3. Run the installer - -Run the installer: - -<pre> -chmod +x bazel-0.5.0-installer-darwin-x86_64.sh -./bazel-0.5.0-installer-darwin-x86_64.sh --user -</pre> - -The `--user` flag installs Bazel to the `$HOME/bin` directory on your system and -sets the `.bazelrc` path to `$HOME/.bazelrc`. Use the `--help` command to see -additional installation options. - -### 4. Set up your environment - -If you ran the Bazel installer with the `--user` flag as above, the Bazel -executable is installed in your `$HOME/bin` directory. It's a good idea to add -this directory to your default paths, as follows: - -```bash -export PATH="$PATH:$HOME/bin" -``` - -You can also add this command to your `~/.bashrc` file. - -You are all set. You can confirm Bazel is installed successfully by running -```bash -bazel version -``` - -Once installed, you can upgrade to a newer version of Bazel with: - -```bash -sudo apt-get upgrade bazel -``` diff --git a/site/versions/master/docs/install-ubuntu.md b/site/versions/master/docs/install-ubuntu.md deleted file mode 100644 index e2e5d5aa97..0000000000 --- a/site/versions/master/docs/install-ubuntu.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -layout: documentation -title: Installing Bazel on Ubuntu ---- - -# <a name="ubuntu"></a>Install Bazel on Ubuntu - -Supported Ubuntu Linux platforms: - -* 16.04 (LTS) -* 15.10 -* 14.04 (LTS) - -Install Bazel on Ubuntu using one of the following methods: - -* [Use our custom APT repository (recommended)](#install-on-ubuntu) -* [Use the binary installer](#install-with-installer-ubuntu) -* [Compile Bazel from source](install-compile-source.md) - -Bazel comes with two completion scripts. After installing Bazel, you can: - -* access the [bash completion script](install.md) -* install the [zsh completion script](install.md) - -## <a name="install-on-ubuntu"></a> Using Bazel custom APT repository (recommended) - -### 1. Add Bazel distribution URI as a package source (one time setup) - -``` -echo "deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8" | sudo tee /etc/apt/sources.list.d/bazel.list -curl https://bazel.build/bazel-release.pub.gpg | sudo apt-key add - -``` - -If you want to install the testing version of Bazel, replace `stable` with -`testing`. - -### 2. Install and update Bazel - -```bash -sudo apt-get update && sudo apt-get install bazel -``` - -Once installed, you can upgrade to a newer version of Bazel with: - -```bash -sudo apt-get upgrade bazel -``` - -## <a name="install-with-installer-ubuntu"></a>Install using binary installer - -The binary installers are on Bazel's [GitHub releases page](https://github.com/bazelbuild/bazel/releases). - -The installer contains the Bazel binary and the required JDK. Some additional -libraries must also be installed for Bazel to work. - -### 1. Install required packages - -``` -sudo apt-get install pkg-config zip g++ zlib1g-dev unzip -``` - -### 2. Download Bazel - -Go to Bazel's [GitHub releases page](https://github.com/bazelbuild/bazel/releases). - -Download the binary installer `bazel-0.5.0-installer-linux-x86_64.sh`. This -installer contains the Bazel binary and the required JDK, and can be used even -if JDK is already installed. - -Note that two other versions of the installer exist: -* `bazel-0.5.0-without-jdk-installer-linux-x86_64.sh`: version without - embedded JDK 8. Only use this installer if you already have JDK 8 installed. -* `bazel-0.5.0-jdk7-installer-linux-x86_64.sh`: last release compatible - with JDK 7. - -### 3. Run the installer - -Run the installer: - -```bash -chmod +x bazel-0.5.0-installer-linux-x86_64.sh -./bazel-0.5.0-installer-linux-x86_64.sh --user -``` - -The `--user` flag installs Bazel to the `$HOME/bin` directory on your system and -sets the `.bazelrc` path to `$HOME/.bazelrc`. Use the `--help` command to see -additional installation options. - -### 4. Set up your environment - -If you ran the Bazel installer with the `--user` flag as above, the Bazel -executable is installed in your `$HOME/bin` directory. It's a good idea to add -this directory to your default paths, as follows: - -```bash -export PATH="$PATH:$HOME/bin" -``` - -You can also add this command to your `~/.bashrc` file. - -Once installed, you can upgrade to a newer version of Bazel with: - -```bash -sudo apt-get upgrade bazel -``` diff --git a/site/versions/master/docs/install-windows.md b/site/versions/master/docs/install-windows.md deleted file mode 100644 index 44713c291e..0000000000 --- a/site/versions/master/docs/install-windows.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -layout: documentation -title: Installing Bazel on Windows ---- - -# <a name="windows"></a>Install Bazel on Windows - -Windows support is highly experimental. Known issues are [marked with -label "Windows"](https://github.com/bazelbuild/bazel/issues?q=is%3Aissue+is%3Aopen+label%3A%22category%3A+multi-platform+%3E+windows%22) -on GitHub issues. - -We currently support only 64 bit Windows 7 or higher and we compile Bazel as a -MSYS2 binary. - -Install Bazel on Windows using one of the following methods: - - * [Use Chocolatey](#install-on-windows-chocolatey) - * [Use the binary distribution](#download-binary-windows) - * [Compile Bazel from source](install-compile-source.md) -- make sure - your machine meets the [requirements](windows.md#requirements) - - -## <a name="install-on-windows-chocolatey"></a>Install using Chocolatey - -You can install the unofficial package using the -[chocolatey](https://chocolatey.org) package manager: - -```sh -choco install bazel -``` - -This will install the latest available version of Bazel, and dependencies. - -This package is experimental. Please provide feedback to `@petemounce` in GitHub -issue tracker. See the [Chocolatey installation and package -maintenance](windows-chocolatey-maintenance.md) guide for more information. - - -## <a name="download-binary-windows"></a>Install using the binary distribution - -We provide binary versions on our -<a href="https://github.com/bazelbuild/bazel/releases">GitHub releases page</a> - -The installer contains only the Bazel binary. You'll need additional software -(e.g. msys2 shell of the right version) and some setup in your environment to -run Bazel. See these requirements on our -[Windows page](windows.md#requirements). diff --git a/site/versions/master/docs/install.md b/site/versions/master/docs/install.md deleted file mode 100644 index fe7c46e650..0000000000 --- a/site/versions/master/docs/install.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -layout: documentation -title: Installing Bazel ---- - -# Installing Bazel - -See the instructions for installing Bazel on: - -* [Ubuntu Linux (16.04, 15.10, and 14.04)](install-ubuntu.md) -* [Mac OS X](install-os-x.md) -* [Windows (experimental)](install-windows.md) - -For other platforms, you can try to [compile from source](install-compile-source.md). - -Required Java version: - -Java JDK 8 or later is required. To address the problem of JDK 8 not being -available on some machines, Bazel's binary installer embeds a JDK by default. - -**Note:** Homebrew and Debian packages do not contain the embedded JDK. The -shell installers are the only ones with an embedded JDK. - -Extras: - -* [Bash completion](#bash) -* [zsh completion](#zsh) - -For more information on using Bazel, see -[Getting Started with Bazel](getting-started.html). - - -## <a name="jdk7"></a>Using Bazel with JDK 7 - -Bazel version _0.5.0_ does run with JDK 7. However, starting with version -_0.5.1_ Bazel must use JDK 8. - -The installers available for _0.5.0_ are: - -* `bazel-0.5.0-installer.sh`: default version with embedded JDK -* `bazel-0.5.0-without-jdk-installer.sh`: version without embedded JDK -* `bazel-0.5.0-jdk7-installer.sh`: version compatible with JDK 7, will not be - available in later releases - -## <a name="bash"></a>Getting bash completion - -Bazel comes with a bash completion script, which the installer copies into the -`bin` directory. If you ran the installer with `--user`, this will be -`$HOME/.bazel/bin`. If you ran the installer as root, this will be -`/usr/local/bazel/bin`. - -Copy the `bazel-complete.bash` script to your completion folder -(`/etc/bash_completion.d` directory under Ubuntu). If you don't have a -completion folder, you can copy it wherever suits you and insert -`source /path/to/bazel-complete.bash` in your `~/.bashrc` file (under OS X, put -it in your `~/.bash_profile` file). - -If you built Bazel from source, the bash completion target is in the `//scripts` -package: - -1. Build it with Bazel: `bazel build //scripts:bazel-complete.bash`. -2. Copy the script `bazel-bin/scripts/bazel-complete.bash` to one of the - locations described above. - -## <a name="zsh"></a>Getting zsh completion - -Bazel also comes with a zsh completion script. To install it: - -1. Add this script to a directory on your $fpath: - - ``` - fpath[1,0]=~/.zsh/completion/ - mkdir -p ~/.zsh/completion/ - cp scripts/zsh_completion/_bazel ~/.zsh/completion - ``` - - You may have to call `rm -f ~/.zcompdump; compinit` - the first time to make it work. - -2. Optionally, add the following to your .zshrc. - - ``` - # This way the completion script does not have to parse Bazel's options - # repeatedly. The directory in cache-path must be created manually. - zstyle ':completion:*' use-cache on - zstyle ':completion:*' cache-path ~/.zsh/cache - ``` diff --git a/site/versions/master/docs/mobile-install.md b/site/versions/master/docs/mobile-install.md deleted file mode 100644 index f273871d0d..0000000000 --- a/site/versions/master/docs/mobile-install.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -layout: documentation -title: mobile-install ---- - -# bazel mobile-install - -<p class="lead">Fast iterative development for Android</p> - -## TL;DR - -To install small changes to an Android app very quickly, do the following: - - 1. Find the `android_binary` rule of the app you want to install. - 2. Disable Proguard by removing the `proguard_specs` attribute. - 3. Set the `multidex` attribute to `native`. - 4. Set the `dex_shards` attribute to `10`. - 5. Connect your device running ART (not Dalvik) over USB and enable USB - debugging on it. - 6. Run `bazel mobile-install :your_target`. App startup will be a little - slower than usual. - 7. Edit the code or Android resources. - 8. Run `bazel mobile-install --incremental :your_target`. - 9. Enjoy not having to wait a lot. - -Some command line options to Bazel that may be useful: - - - `--adb` tells Bazel which adb binary to use - - `--adb_arg` can be used to add extra arguments to the command line of `adb`. - One useful application of this is to select which device you want to install - to if you have multiple devices connected to your workstation: - `bazel mobile-install --adb_arg=-s --adb_arg=<SERIAL> :your_target` - - `--start_app` automatically starts the app - -When in doubt, look at the -[example](https://github.com/bazelbuild/bazel/tree/master/examples/android) -or [contact us](https://groups.google.com/forum/#!forum/bazel-discuss). - -## Introduction - -One of the most important attributes of a developer's toolchain is speed: there -is a world of difference between changing the code and seeing it run within a -second and having to wait minutes, sometimes hours, before you get any feedback -on whether your changes do what you expect them to. - -Unfortunately, the traditional Android toolchain for building an .apk entails -many monolithic, sequential steps and all of these have to be done in order to -build an Android app. At Google, waiting five minutes to build a single-line -change was not unusual on larger projects like Google Maps. - -`bazel mobile-install` makes iterative development for Android much faster by -using a combination of change pruning, work sharding, and clever manipulation of -Android internals, all without changing any of your app's code. - -## Problems with traditional app installation - -We identified the following bottlenecks of building an Android app: - -- Dexing. By default, "dx" is invoked exactly once in the build and it does not -know how to reuse work from previous builds: it dexes every method again, even -though only one method was changed. - -- Uploading data to the device. adb does not use the full bandwidth of a USB 2.0 -connection, and larger apps can take a lot of time to upload. The entire app is -uploaded, even if only small parts have changed, for example, a resource or a -single method, so this can be a major bottleneck. - -- Compilation to native code. Android L introduced ART, a new Android runtime, -which compiles apps ahead-of-time rather than compiling them just-in-time like -Dalvik. This makes apps much faster at the cost of longer installation -time. This is a good tradeoff for users because they typically install an app -once and use it many times, but results in slower development where an app is -installed many times and each version is run at most a handful of times. - -## The approach of `bazel mobile-install` - -`bazel mobile-install `makes the following improvements: - - - Sharded dexing. After building the app's Java code, Bazel shards the class - files into approximately equal-sized parts and invokes `dx` separately on - them. `dx` is not invoked on shards that did not change since the last build. - - - Incremental file transfer. Android resources, .dex files, and native - libraries are removed from the main .apk and are stored in under a separate - mobile-install directory. This makes it possible to update code and Android - resources independently without reinstalling the whole app. Thus, - transferring the files takes less time and only the .dex files that have - changed are recompiled on-device. - - - Loading parts of the app from outside the .apk. A tiny stub application is - put into the .apk that loads Android resources, Java code and native code - from the on-device mobile-install directory, then transfers control to the - actual app. This is all transparent to the app, except in a few corner cases - described below. - -### Sharded Dexing - -Sharded dexing is reasonably straightforward: once the .jar files are built, a -[tool](https://github.com/bazelbuild/bazel/blob/master/src/tools/android/java/com/google/devtools/build/android/ziputils/DexMapper.java) -shards them into separate .jar files of approximately equal size, then invokes -`dx` on those that were changed since the previous build. The logic that -determines which shards to dex is not specific to Android: it just uses the -general change pruning algorithm of Bazel. - -The first version of the sharding algorithm simply ordered the .class files -alphabetically, then cut the list up into equal-sized parts, but this proved to -be suboptimal: if a class was added or removed (even a nested or an anonymous -one), it would cause all the classes alphabetically after it to shift by one, -resulting in dexing those shards again. Thus, we settled upon sharding not -individual classes, but Java packages instead. Of course, this still results in -dexing many shards if a new package is added or removed, but that is much less -frequent than adding or removing a single class. - -The number of shards is controlled by the BUILD file (using the -`android_binary.dex_shards` attribute). In an ideal world, Bazel would -automatically determine how many shards are best, but Bazel currently must know -the set of actions (i.e. commands to be executed during the build) before -executing any of them, so it cannot determine the optimal number of shards -because it doesn't know how many Java classes there will eventually be in the -app. Generally speaking, the more shards, the faster the build and the -installation will be, but the slower app startup becomes, because the dynamic -linker has to do more work. The sweet spot is usually between 10 and 50 shards. - -### Incremental File Transfer - -After building the app, the next step is to install it, preferably with the -least effort possible. Installation consists of the following steps: - - 1. Installing the .apk (i.e. `adb install`) - 2. Uploading the .dex files, Android resources, and native libraries to the - mobile-install directory - -There is not much incrementality in the first step: the app is either installed -or not. Bazel currently relies on the user to indicate if it should do this step -through the `--incremental` command line option because it cannot determine in -all cases if it is necessary. - -In the second step, the app's files from the build are compared to an on-device -manifest file that lists which app files are on the device and their -checksums. Any new files are uploaded to the device, any files that have changed -are updated, and any files that have been removed are deleted from the -device. If the manifest is not present, it is assumed that every file needs to -be uploaded. - -Note that it is possible to fool the incremental installation algorithm by -changing a file on the device, but not its checksum in the manifest. We could -have safeguarded against this by computing the checksum of the files on the -device, but this was deemed to be not worth the increase in installation time. - -### The Stub Application - -The stub application is where the magic to load the dexes, native code and -Android resources from the on-device `mobile-install` directory happens. - -The actual loading is implemented by subclassing `BaseDexClassLoader` and is a -reasonably well-documented technique. This happens before any of the app's -classes are loaded, so that any application classes that are in the apk can be -placed in the on-device `mobile-install` directory so that they can be updated -without `adb install`. - -This needs to happen before any of the -classes of the app are loaded, so that no application class needs to be in the -.apk which would mean that changes to those classes would require a full -re-install. - -This is accomplished by replacing the `Application` class specified in -`AndroidManifest.xml` with the -[stub application](https://github.com/bazelbuild/bazel/blob/master/src/tools/android/java/com/google/devtools/build/android/incrementaldeployment/StubApplication.java). This -takes control when the app is started, and tweaks the class loader and the -resource manager appropriately at the earliest moment (its constructor) using -Java reflection on the internals of the Android framework. - -Another thing the stub application does is to copy the native libraries -installed by mobile-install to another location. This is necessary because the -dynamic linker needs the `X` bit to be set on the files, which is not possible to -do for any location accessible by a non-root `adb`. - -Once all these things are done, the stub application then instantiates the -actual `Application` class, changing all references to itself to the actual -application within the Android framework. - -## Results - -### Performance - -In general, `bazel mobile-install` results in a 4x to 10x speedup of building -and installing large apps after a small change. We computed the following -numbers for a few Google products: - -<img src="/assets/mobile-install-performance.svg"/> - -This, of course, depends on the nature of the change: recompilation after -changing a base library takes more time. - -### Limitations - -The tricks the stub application plays don't work in every case. We have -identified the following cases where it does not work as expected: - - - When `Context` is cast to the `Application` class in - `ContentProvider#onCreate()`. This method is called during application - startup before we have a chance to replace the instance of the `Application` - class, therefore, `ContentProvider` will still reference the stub application - instead of the real one. Arguably, this is not a bug since you are not - supposed to downcast `Context` like this, but this seems to happen in a few - apps at Google. - - - Resources installed by `bazel mobile-install` are only available from within - the app. If resources are accessed by other apps via - `PackageManager#getApplicationResources()`, these resources will be from the - last non-incremental install. - - - Devices that aren't running ART. While the stub application works well on - Froyo and later, Dalvik has a bug that makes it think that the app is - incorrect if its code is distributed over multiple .dex files in certain - cases, for example, when Java annotations are used in a - [specific](https://code.google.com/p/android/issues/detail?id=78144) way. As - long as your app doesn't tickle these bugs, it should work with Dalvik, too - (note, however, that support for old Android versions isn't exactly our - focus) diff --git a/site/versions/master/docs/output_directories.md b/site/versions/master/docs/output_directories.md deleted file mode 100644 index 20858c6101..0000000000 --- a/site/versions/master/docs/output_directories.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -layout: documentation -title: Output Directory Layout ---- - -# Output Directory Layout - -## Requirements - -Requirements for an output directory layout: - -* Don't collide if multiple users are building on the same box. -* Support building in multiple workspaces at the same time. -* Support building for multiple target configurations in the same workspace. -* Don't collide with any other tools. -* Be easy to access. -* Be easy to clean, even selectively. -* Is unambiguous, even if the user relies on symbolic links when changing into - his/her client directory. -* All the build state per user should be underneath one directory ("I'd like to - clean all the .o files from all my clients.") - -## Documentation of the current Bazel output directory layout - -The solution that's currently implemented: - -* Bazel must be invoked from a directory containing a WORKSPACE file. It reports - an error if it is not. We call this the _workspace directory_. -* The _outputRoot_ directory is ~/.cache/bazel. (Unless `$TEST_TMPDIR` is - set, as in a test of bazel itself, in which case this directory is used - instead.) -* We stick the Bazel user's build state beneath `outputRoot/_bazel_$USER`. This - is called the _outputUserRoot_ directory. -* Beneath the `outputUserRoot` directory, we create an `installBase` directory - whose name is "install" plus the MD5 hash of the Bazel installation manifest. -* Beneath the `outputUserRoot` directory, we also create an `outputBase` - directory whose name is the MD5 hash of the path name of the workspace - directory. So, for example, if Bazel is running in the workspace directory - `/home/user/src/my-project` (or in a directory symlinked to that one), then we - create an output base directory called: - `/home/.cache/bazel/_bazel_user/7ffd56a6e4cb724ea575aba15733d113`. -* Users can use Bazel's `--output_base` startup option to override the default - output base directory. For example, - `bazel --output_base=/tmp/bazel/output build x/y:z`. -* Users can also use Bazel's `--output_user_root` startup option to override the - default install base and output base directories. For example: - `bazel --output_user_root=/tmp/bazel build x/y:z`. - -We put symlinks "bazel-<workspace-name>" and "bazel-out", as well as -"bazel-bin", "bazel-genfiles", and "bazel-includes" in the workspace directory; -these symlinks points to some directories inside a target-specific directory -inside the output directory. These symlinks are only for the user's convenience, -as Bazel itself does not use them. Also, we only do this if the workspace -directory is writable. The names of the "bazel-bin", "bazel-genfiles", and -"bazel-include" symlinks are affected by the `--symlink_prefix` option to bazel, -but "bazel-<workspace-name>" and "bazel-out" are not. - -## Bazel internals: Directory layout - -The directories are laid out as follows: - -<pre> -<workspace-name>/ <== The workspace directory - bazel-my-project => <...my-project> <== Symlink to execRoot - bazel-out => <...bin> <== Convenience symlink to outputPath - bazel-bin => <...bin> <== Convenience symlink to most recent written bin dir $(BINDIR) - bazel-genfiles => <...genfiles> <== Convenience symlink to most recent written genfiles dir $(GENDIR) - -/home/user/.cache/bazel/ <== Root for all Bazel output on a machine: outputRoot - _bazel_$USER/ <== Top level directory for a given user depends on the user name: - outputUserRoot - install/ - fba9a2c87ee9589d72889caf082f1029/ <== Hash of the Bazel install manifest: installBase - _embedded_binaries/ <== Contains binaries and scripts unpacked from the data section of - the bazel executable on first run (e.g. helper scripts and the - main Java file BazelServer_deploy.jar) - 7ffd56a6e4cb724ea575aba15733d113/ <== Hash of the client's workspace directory (e.g. - /home/some-user/src/my-project): outputBase - action_cache/ <== Action cache directory hierarchy - This contains the persistent record of the file metadata - (timestamps, and perhaps eventually also MD5 sums) used by the - FilesystemValueChecker. - action_outs/ <== Action output directory. This contains a file with the - stdout/stderr for every action from the most recent bazel run - that produced output. - command.log <== A copy of the stdout/stderr output from the most recent bazel - command. - external/ <== The directory that remote repositories are downloaded/symlinked - into. - server/ <== The Bazel server puts all server-related files (such as socket - file, logs, etc) here. - jvm.out <== The debugging output for the server. - <workspace-name>/ <== Working tree for the Bazel build & root of symlink forest: execRoot - _bin/ <== Helper tools are linked from or copied to here. - - bazel-out/ <== All actual output of the build is under here: outputPath - local_linux-fastbuild/ <== one subdirectory per unique target BuildConfiguration instance; - this is currently encoded - bin/ <== Bazel outputs binaries for target configuration here: $(BINDIR) - foo/bar/_objs/baz/ <== Object files for a cc_* rule named //foo/bar:baz - foo/bar/baz1.o <== Object files from source //foo/bar:baz1.cc - other_package/other.o <== Object files from source //other_package:other.cc - foo/bar/baz <== foo/bar/baz might be the artifact generated by a cc_binary named - //foo/bar:baz - foo/bar/baz.runfiles/ <== The runfiles symlink farm for the //foo/bar:baz executable. - MANIFEST - <workspace-name>/ - ... - genfiles/ <== Bazel puts generated source for the target configuration here: - $(GENDIR) - foo/bar.h e.g. foo/bar.h might be a headerfile generated by //foo:bargen - testlogs/ <== Bazel internal test runner puts test log files here - foo/bartest.log e.g. foo/bar.log might be an output of the //foo:bartest test with - foo/bartest.status foo/bartest.status containing exit status of the test (e.g. - PASSED or FAILED (Exit 1), etc) - include/ <== a tree with include symlinks, generated as needed. The - bazel-include symlinks point to here. This is used for - linkstamp stuff, etc. - host/ <== BuildConfiguration for build host (user's workstation), for - building prerequisite tools, that will be used in later stages - of the build (ex: Protocol Compiler) - <packages>/ <== Packages referenced in the build appear as if under a regular workspace -</pre> - -The layout of the *.runfiles directories is documented in more detail in the places pointed to by RunfilesSupport. - -## `bazel clean` - -`bazel clean` does an `rm -rf` on the `outputPath` and the `action_cache` -directory. It also removes the workspace symlinks. The `--expunge` option -will clean the entire outputBase. diff --git a/site/versions/master/docs/query-how-to.md b/site/versions/master/docs/query-how-to.md deleted file mode 100644 index 98e8f87b48..0000000000 --- a/site/versions/master/docs/query-how-to.md +++ /dev/null @@ -1,461 +0,0 @@ ---- -layout: documentation -title: Query how-to ---- - -<a name="_Bazel_Query_How_To"> </a> -# Bazel query how-to - -This is a quick tutorial to get you started using Bazel's query language to -trace dependencies in your code. - -For a language details and `--output` flag details, please see the reference -manual, [Bazel query reference](query.html). You can get help for Bazel query -by typing `bazel help query`. - -To execute a query while ignoring errors such as missing targets, use the -`--keep_going` flag. - -<a name="_Contents"></a> -## Contents - -* [Finding the Dependencies of a Rule](#Finding_the_Dependencies_of_a_Ru) -* [Tracing the Dependency Chain between Two - Packages](#Tracing_the_Dependency_Chain_bet) - * [Aside: implicit dependencies](#Aside_implicit_dependencies) -* [Reverse Dependencies](#Reverse_Dependencies) -* [Miscellaneous Uses](#Miscellaneous_Uses) - * [What exists ...](#What_exists_) - * [What packages exist beneath - `foo`?](#What_packages_exist_beneath_foo_) - * [What rules are defined in the `foo` - package?](#What_rules_are_defined_in_the_foo) - * [What files are generated by rules in the `foo` - package?](#What_files_are_generated_by_rule) - * [What's the set of BUILD files needed to build - `//foo`?](#What_s_the_set_of_BUILD_files_ne) - * [What are the individual tests that a `test_suite` expands - to?](#What_are_the_individual_tests_th) - * [Which of those are C++ tests?](#Which_of_those_are_C_tests_) - * [Which of those are small? Medium? - Large?](#Which_of_those_are_small_Medium_) - * [What are the tests beneath `foo` that match a - pattern?](#What_are_the_tests_beneath_foo_t) - * [What package contains file - `src/main/java/com/example/cache/LRUCache.java`? - ](#What_package_contains_file_java_) - * [What is the build label for - `src/main/java/com/example/cache/LRUCache.java`? - ](#What_is_the_build_label_for_java) - * [What build rule contains file - `src/main/java/com/example/cache/LRUCache.java` as a - source?](#What_build_rule_contains_file_ja) - * [What package dependencies exist ...](#What_package_dependencies_exist_) - * [What packages does `foo` depend on? (What do I need to check out - to build `foo`)](#What_packages_does_foo_depend_on) - * [What packages does the `foo` tree depend on, excluding - `foo/contrib`?](#What_packages_does_the_foo_) - * [What rule dependencies exist ...](#What_rule_dependencies_exist_) - * [What genproto rules does bar depend - upon?](#What_genproto_rules_does_bar_) - * [Find the definition of some JNI (C++) library that is transitively - depended upon by a Java binary rule in the servlet - tree.](#Find_the_definition_of_some_JNI_) - * [...Now find the definitions of all the Java binaries that - depend on them](#_Now_find_the_definitions_of_all) - * [What file dependencies exist ...](#What_file_dependencies_exist_) - * [What's the complete set of Java source files required to build - QUX?](#What_s_the_complete_set_of_Java_) - * [What is the complete set of Java source files required to build - QUX's tests?](#What_is_the_complete_set_of_Java) - * [What differences in dependencies between X and Y exist - ...](#What_differences_in_dependencies) - * [What targets does `//foo` depend on that `//foo:foolib` does - not?](#What_targets_does_foo_depend_on_) - * [What C++ libraries do the `foo` tests depend on that the `//foo` - production binary does _not_ depend - on?](#What_C_libraries_do_the_foo_test) - * [Why does this dependency exist ...](#Why_does_this_dependency_exist_) - * [Why does `bar` depend on - `groups2`?](#Why_does_bar_depend_on_groups) - * [Show me a path from `docker/updater:updater_systest` (a `py_test`) - to some `cc_library` that it depends - upon:](#Show_me_a_path_from_docker_updater) - * [Why does library `//photos/frontend:lib` depend on two variants of - the same library `//third_party/jpeglib` and - `//third_party/jpeg`?](#Why_does_library_photos_fronten) - * [What depends on ...](#What_depends_on_) - * [What rules under bar depend on Y?](#What_rules_under_bar_depend_o) - * [How do I break a dependency ...](#How_do_I_break_a_dependency_) - * [What dependency paths do I have to break to make `bar` no longer - depend on X?](#What_dependency_paths_do_I_have_) - * [Misc ...](#Misc_) - * [How many sequential steps are there in the `ServletSmokeTests` - build?](#How_many_sequential_steps_are_th) - -<a name="Finding_the_Dependencies_of_a_Ru"></a> -## Finding the Dependencies of a Rule - -To see the dependencies of `//src/main/java/com/example/base:base`, use the -`deps` function in bazel query: - -``` -$ bazel query "deps(src/main/java/com/example/base:base)" -//resources:translation.xml -//src/main/java/com/example/base:AbstractPublishedUri.java -... -``` - -This is the set of all targets required to build <code>//src/main/java/com/example/base:base</code>. - -<a name="Tracing_the_Dependency_Chain_bet"></a> -## Tracing the Dependency Chain between Two Packages - -The library `//third_party/zlib:zlibonly` isn't in the BUILD file for -`//src/main/java/com/example/base`, but it is an indirect dependency. How can -we trace this dependency path? There are two useful functions here: -`allpaths` and `somepath` - -``` -$ bazel query "somepath(src/main/java/com/example/base:base, third_party/zlib:zlibonly)" -//src/main/java/com/example/base:base -//translations/tools:translator -//translations/base:base -//third_party/py/MySQL:MySQL -//third_party/py/MySQL:_MySQL.so -//third_party/mysql:mysql -//third_party/zlib:zlibonly -$ bazel query "allpaths(src/main/java/com/example/common/base:base, third_party/...)" - ...many errors detected in BUILD files... -//src/main/java/com/example/common/base:base -//third_party/java/jsr166x:jsr166x -//third_party/java/sun_servlet:sun_servlet -//src/main/java/com/example/common/flags:flags -//src/main/java/com/example/common/flags:base -//translations/tools:translator -//translations/tools:aggregator -//translations/base:base -//tools/pkg:pex -//tools/pkg:pex_phase_one -//tools/pkg:pex_lib -//third_party/python:python_lib -//translations/tools:messages -//third_party/py/xml:xml -//third_party/py/xml:utils/boolean.so -//third_party/py/xml:parsers/sgmlop.so -//third_party/py/xml:parsers/pyexpat.so -//third_party/py/MySQL:MySQL -//third_party/py/MySQL:_MySQL.so -//third_party/mysql:mysql -//third_party/openssl:openssl -//third_party/zlib:zlibonly -//third_party/zlib:zlibonly_v1_2_3 -//third_party/python:headers -//third_party/openssl:crypto -``` - -<a name="Aside_implicit_dependencies"></a> -### Aside: implicit dependencies - -The BUILD file for `src/main/java/com/example/common/base` never references -`//translations/tools:aggregator`. So, where's the direct dependency? - -Certain rules include implicit dependencies on additional libraries or tools. -For example, to build a `genproto` rule, you need first to build the Protocol -Compiler, so every `genproto` rule carries an implicit dependency on the -protocol compiler. These dependencies are not mentioned in the build file, -but added in by the build tool. The full set of implicit dependencies is -currently undocumented; read the source code of -[`RuleClassProvider`](https://github.com/bazelbuild/bazel/tree/master/src/main/java/com/example/devtools/build/lib/packages/RuleClassProvider.java). - -<a name="Reverse_Dependencies"></a> -## Reverse Dependencies - -You might want to know the set of targets that depends on some target. e.g., -if you're going to change some code, you might want to know what other code -you're about to break. You can use `rdeps(u, x)` to find the reverse -dependencies of the targets in `x` within the transitive closure of `u`. - -Unfortunately, invoking, e.g., `rdeps(..., daffie/annotations2:constants-lib)` -is not practical for a large tree, because it requires parsing every BUILD file -and building a very large dependency graph (Bazel may run out of memory). If -you would like to execute this query across a large repository, you may have to -query subtrees and then combine the results. - -<a name="Miscellaneous_Uses"></a> -## Miscellaneous Uses - -You can use `bazel query` to analyze many dependency relationships. - -<a name="What_exists_"></a> -### What exists ... - -<a name="What_packages_exist_beneath_foo_"></a> -#### What packages exist beneath `foo`? - -```sh -bazel query 'foo/...' --output package -``` - -<a name="What_rules_are_defined_in_the_gw"></a> -#### What rules are defined in the `foo` package? - -```sh -bazel query 'kind(rule, foo:all)' --output label_kind -``` - -<a name="What_files_are_generated_by_rule"></a> -#### What files are generated by rules in the `foo` package? - -```sh -bazel query 'kind("generated file", //foo:*)' -``` - -<a name="What_s_the_set_of_BUILD_files_ne"></a> -#### What's the set of BUILD files needed to build `//foo`? - -bazel query 'buildfiles(deps(//foo))' --output location | cut -f1 -d: - -<a name="What_are_the_individual_tests_th"></a> -#### What are the individual tests that a `test_suite` expands to? - -```sh -bazel query 'tests(//foo:smoke_tests)' -``` - -<a name="Which_of_those_are_C_tests_"></a> -##### Which of those are C++ tests? - -```sh -bazel query 'kind(cc_.*, tests(//foo:smoke_tests))' -``` - -<a name="Which_of_those_are_small_Medium_"></a> -#### Which of those are small? Medium? Large? - -```sh -bazel query 'attr(size, small, tests(//foo:smoke_tests))' - -bazel query 'attr(size, medium, tests(//foo:smoke_tests))' - -bazel query 'attr(size, large, tests(//foo:smoke_tests))' -``` - -<a name="What_are_the_tests_beneath_foo_t"></a> -#### What are the tests beneath `foo` that match a pattern? - -```sh -bazel query 'filter("pa?t", kind(".*_test rule", //foo/...))' -``` - -The pattern is a regex and is applied to the full name of the rule. It's similar to doing - -```sh -bazel query 'kind(".*_test rule", //foo/...)' | grep -E 'pa?t' -``` - -<a name="What_package_contains_file_java_"></a> -#### What package contains file src/main/java/com/example/cache/LRUCache.java`? - -```sh -bazel query 'buildfiles(src/main/java/com/example/cache/LRUCache.java)' --output=package -``` - -<a name="What_is_the_build_label_for_java"></a> -#### What is the build label for src/main/java/com/example/cache/LRUCache.java? - -```sh -bazel query src/main/java/com/example/cache/LRUCache.java -``` - -<a name="What_build_rule_contains_file_ja"></a> -#### What build rule contains file `src/main/java/com/example/cache/LRUCache.java` as a source? - -```sh -fullname=$(bazel query src/main/java/com/example/cache/LRUCache.java) -bazel query "attr('srcs', $fullname, ${fullname//:*/}:*)" -``` - -<a name="What_package_dependencies_exist_"></a> -### What package dependencies exist ... - -<a name="What_packages_does_foo_depend_on"></a> -#### What packages does `foo` depend on? (What do I need to check out to build `foo`) - -```sh -bazel query 'buildfiles(deps(//foo:foo))' --output package -``` - -Note, `buildfiles` is required in order to correctly obtain all files -referenced by `subinclude`; see the reference manual for details. - -<a name="What_packages_does_the_foo_"></a> -#### What packages does the `foo` tree depend on, excluding `foo/contrib`? - -```sh -bazel query 'deps(foo/... except foo/contrib/...)' --output package -``` - -<a name="What_rule_dependencies_exist_"></a> -### What rule dependencies exist ... - -<a name="What_genproto_rules_does_bar_"></a> -#### What genproto rules does bar depend upon? - -```sh -bazel query 'kind(genproto, deps(bar/...))' -``` - -<a name="Find_the_definition_of_some_JNI_"></a> -#### Find the definition of some JNI (C++) library that is transitively depended upon by a Java binary rule in the servlet tree. - -```sh -bazel query 'some(kind(cc_.*library, deps(kind(java_binary, src/main/java/com/example/frontend/...))))' --output location -``` - -<a name="_Now_find_the_definitions_of_all"></a> -##### ...Now find the definitions of all the Java binaries that depend on them - -```sh -bazel query 'let jbs = kind(java_binary, src/main/java/com/example/frontend/...) in - let cls = kind(cc_.*library, deps($jbs)) in - $jbs intersect allpaths($jbs, $cls)' -``` - -<a name="What_file_dependencies_exist_"></a> -### What file dependencies exist ... - -<a name="What_s_the_complete_set_of_Java_"></a> -#### What's the complete set of Java source files required to build QUX? - -Source files: - -```sh -bazel query 'kind("source file", deps(src/main/java/com/example/qux/...))' | grep java$ -``` - -Generated files: - -```sh -bazel query 'kind("generated file", deps(src/main/java/com/example/qux/...))' | grep java$ -``` - -<a name="What_is_the_complete_set_of_Java"></a> -#### What is the complete set of Java source files required to build QUX's tests? - -Source files: - -```sh -bazel query 'kind("source file", deps(kind(".*_test rule", javatests/com/example/qux/...)))' | grep java$ -``` - -Generated files: - -```sh -bazel query 'kind("generated file", deps(kind(".*_test rule", javatests/com/example/qux/...)))' | grep java$ -``` - -<a name="What_differences_in_dependencies"></a> -### What differences in dependencies between X and Y exist ... - -<a name="What_targets_does_foo_depend_on_"></a> -#### What targets does `//foo` depend on that `//foo:foolib` does not? - -```sh -bazel query 'deps(//foo) except deps(//foo:foolib)' -``` - -<a name="What_C_libraries_do_the_foo_test"></a> -#### What C++ libraries do the `foo` tests depend on that the `//foo` production binary does _not_ depend on? - -```sh -bazel query 'kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo))' -``` - -<a name="Why_does_this_dependency_exist_"></a> -### Why does this dependency exist ... - -<a name="Why_does_bar_depend_on_groups"></a> -#### Why does <code>bar</code> depend on <code>groups2</code>? - -```sh -bazel query 'somepath(bar/...,groups2/...:*)' -``` - -Once you have the results of this query, you will often find that a single -target stands out as being an unexpected or egregious and undesirable -dependency of `bar`. The query can then be further refined to: - -<a name="Show_me_a_path_from_docker_updater"></a> -#### Show me a path from `docker/updater:updater_systest` (a `py_test`) to some `cc_library` that it depends upon: - -```sh -bazel query 'let cc = kind(cc_library, deps(docker/updater:updater_systest)) in - somepath(docker/updater:updater_systest, $cc)' -``` - -<a name="Why_does_library_photos_fronten"></a> -#### Why does library `//photos/frontend:lib` depend on two variants of the same library `//third_party/jpeglib` and `//third_party/jpeg`? - -This query boils down to: "show me the subgraph of `//photos/frontend:lib` that -depends on both libraries". When shown in topological order, the last element -of the result is the most likely culprit. - -``` -% bazel query 'allpaths(//photos/frontend:lib, //third_party/jpeglib) - intersect - allpaths(//photos/frontend:lib, //third_party/jpeg)' -//photos/frontend:lib -//photos/frontend:lib_impl -//photos/frontend:lib_dispatcher -//photos/frontend:icons -//photos/frontend/modules/gadgets:gadget_icon -//photos/thumbnailer:thumbnail_lib -//third_party/jpeg/img:renderer -``` - -<a name="What_depends_on_"></a> -### What depends on ... - -<a name="What_rules_under_bar_depend_o"></a> -#### What rules under bar depend on Y? - -```sh -bazel query 'bar/... intersect allpaths(bar/..., Y)' -``` - -Note: `X intersect allpaths(X, Y)` is the general idiom for the query "which X -depend on Y?" If expression X is non-trivial, it may be convenient to bind a -name to it using `let` to avoid duplication. - -<a name="How_do_I_break_a_dependency_"></a> -### How do I break a dependency ... - -<!-- TODO find a convincing value of X to plug in here --> -<a name="What_dependency_paths_do_I_have_"></a> -#### What dependency paths do I have to break to make `bar` no longer depend on X? - -To output the graph to a `png` file: - -```sh -bazel query 'allpaths(bar/...,X)' --output graph | dot -Tpng > /tmp/dep.png -``` - -<a name="Misc_"></a> -### Misc ... - -<a name="How_many_sequential_steps_are_th"></a> -#### How many sequential steps are there in the `ServletSmokeTests` build? - -Unfortunately, the query language can't currently give you the longest path -from x to y, but it can find the (or rather _a_) most distant node from the -starting point, or show you the _lengths_ of the longest path from x to every -y that it depends on. Use `maxrank`: - -```sh -% bazel query 'deps(//src/test/java/com/example/servlet:ServletSmokeTests)' --output maxrank | tail -1 -85 //third_party/zlib:zutil.c -``` - -The result indicates that there exist paths of length 85 that must occur in -order in this build. diff --git a/site/versions/master/docs/rule-challenges.md b/site/versions/master/docs/rule-challenges.md deleted file mode 100644 index fece635b5a..0000000000 --- a/site/versions/master/docs/rule-challenges.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -layout: documentation -title: Challenges of Writing Rules. ---- - -# Challenges of Writing Rules. - -We have heard feedback from various people that they have -difficulty to write efficient Bazel rules. There is no single root cause, but -it’s due to a combination of historical circumstances and intrinsic complexity -in the problem domain. This document attempts to give a high level overview of -the specific issues that we believe to be the main contributors. - -* Assumption: Aim for Correctness, Throughput, Ease of Use & Latency -* Assumption: Large Scale Repositories -* Assumption: BUILD-like Description Language -* Intrinsic: Remote Execution and Caching are Hard -* Historic: Hard Separation between Loading, Analysis, and Execution is - Outdated, but still affects the API -* Intrinsic: Using Change Information for Correct and Fast Incremental Builds - requires Unusual Coding Patterns -* Intrinsic: Avoiding Quadratic Time and Memory Consumption is Hard - -## Assumption: Aim for Correctness, Throughput, Ease of Use & Latency - -We assume that the build system needs to be first and foremost correct with -respect to incremental builds, i.e., for a given source tree, the output of the -same build should always be the same, regardless of what the output tree looks -like. In the first approximation, this means Bazel needs to know every single -input that goes into a given build step, such that it can rerun that step if any -of the inputs change. There are limits to how correct Bazel can get, as it leaks -some information such as date / time of the build, and ignores certain types of -changes such as changes to file attributes. Sandboxing helps ensure correctness -by preventing reads to undeclared input files. Besides the intrinsic limits of -the system, there are a few known correctness issues, most of which are related -to Fileset or the C++ rules, which are both hard problems. We have long-term -efforts to fix these. - -The second goal of the build system is to have high throughput; we are -permanently pushing the boundaries of what can be done within the current -machine allocation for a remote execution service. If the remote execution -service gets overloaded, nobody can get work done. - -Ease of use comes next, i.e., of multiple correct approaches with the same (or -similar) footprint of the remote execution service, we choose the one that is -easier to use. - -For the purpose of this document, latency denotes the time it takes from -starting a build to getting the intended result, whether that is a test log from -a passing or failing test, or an error message that a BUILD file has a -typo. - -Note that these goals often overlap; latency is as much a function of throughput -of the remote execution service as is correctness relevant for ease of use. - - -## Assumption: Large Scale Repositories - -The build system needs to operate at the scale of large repositories where large -scale means that it does not fit on a single hard drive, so it is impossible to -do a full checkout on virtually all developer machines. A medium-sized build -will need to read and parse tens of thousands of BUILD files, and evaluate -hundreds of thousands of globs. While it is theoretically possible to read all -BUILD files on a single machine, we have not yet been able to do so within a -reasonable amount of time and memory. As such, it is critical that BUILD files -can be loaded and parsed independently. - - -## Assumption: BUILD-like Description Language - -For the purpose of this document, we assume a configuration language that is -roughly similar to BUILD files, i.e., declaration of library and binary rules -and their interdependencies. BUILD files can be read and parsed independently, -and we avoid even looking at source files whenever we can (except for -existence). - - -## Intrinsic: Remote Execution and Caching are Hard - -Remote execution and caching improve build times in large repositories by -roughly two orders of magnitude compared to running the build on a single -machine. However, the scale at which it needs to perform is staggering: Google's -remote execution service is designed to handle a huge number of requests per -second, and the protocol carefully avoids unnecessary roundtrips as well as -unnecessary work on the service side. - -At this time, the protocol requires that the build system knows all inputs to a -given action ahead of time; the build system then computes a unique action -fingerprint, and asks the scheduler for a cache hit. If a cache hit is found, -the scheduler replies with the digests of the output files; the files itself are -addressed by digest later on. However, this imposes restrictions on the Bazel -rules, which need to declare all input files ahead of time. - - -## Historic: Hard Separation between Loading, Analysis, and Execution is Outdated, but still affects the API - -Technically, it is sufficient for a rule to know the input and output files of -an action just before the action is sent to remote execution. However, the -original Bazel code base had a strict separation of loading packages, then -analyzing rules using a configuration (command-line flags, essentially), and -only then running any actions. This distinction is still part of the rules API -today, even though the core of Bazel no longer requires it (more details below). - -That means that the rules API requires a declarative description of the rule -interface (what attributes it has, types of attributes). There are some -exceptions where the API allows custom code to run during the loading phase to -compute implicit names of output files and implicit values of attributes. For -example, a java_library rule named ‘foo’ implicitly generates an output named -‘libfoo.jar’, which can be referenced from other rules in the build graph. - -Furthermore, the analysis of a rule cannot read any source files or inspect the -output of an action; instead, it needs to generate a partial directed bipartite -graph of build steps and output file names that is only determined from the rule -itself and its dependencies. - - -## Intrinsic: Using Change Information for Correct and Fast Incremental Builds requires Unusual Coding Patterns - -Above, we argued that in order to be correct, Bazel needs to know all the input -files that go into a build step in order to detect whether that build step is -still up-to-date. The same is true for package loading and rule analysis, and we -have designed [Skyframe] (http://www.bazel.build/docs/skyframe.html) to handle this -in general. Skyframe is a graph library and evaluation framework that takes a -goal node (such as ‘build //foo with these options’), and breaks it down into -its constituent parts, which are then evaluated and combined to yield this -result. As part of this process, Skyframe reads packages, analyzes rules, and -executes actions. - -At each node, Skyframe tracks exactly which nodes any given node used to compute -its own output, all the way from the goal node down to the input files (which -are also Skyframe nodes). Having this graph explicitly represented in memory -allows the build system to identify exactly which nodes are affected by a given -change to an input file (including creation or deletion of an input file), doing -the minimal amount of work to restore the output tree to its intended state. - -As part of this, each node performs a dependency discovery process; i.e., each -node can declare dependencies, and then use the contents of those dependencies -to declare even further dependencies. In principle, this maps well to a -thread-per-node model. However, medium-sized builds contain hundreds of -thousands of Skyframe nodes, which isn’t easily possible with current Java -technology (and for historical reasons, we’re currently tied to using Java, so -no lightweight threads and no continuations). - -Instead, Bazel uses a fixed-size thread pool. However, that means that if a node -declares a dependency that isn’t available yet, we may have to abort that -evaluation and restart it (possibly in another thread), when the dependency is -available. This, in turn, means that nodes should not do this excessively; a -node that declares N dependencies serially can potentially be restarted N times, -costing O(N^2) time. Instead, we aim for up-front bulk declaration of -dependencies, which sometimes requires reorganizing the code, or even splitting -a node into multiple nodes to limit the number of restarts. - -Note that this technology isn’t currently available in the rules API; instead, -the rules API is still defined using the legacy concepts of loading, analysis, -and execution phases. However, a fundamental restriction is that all accesses to -other nodes have to go through the framework so that it can track the -corresponding dependencies. Regardless of the language in which the build system -is implemented or in which the rules are written (they don’t have to be the -same), rule authors must not use standard libraries or patterns that bypass -Skyframe. For Java, that means avoiding java.io.File as well as any form of -reflection, and any library that does either. Libraries that support dependency -injection of these low-level interfaces still need to be setup correctly for -Skyframe. - -This strongly suggests to avoid exposing rule authors to a full language runtime -in the first place. The danger of accidental use of such APIs is just too big - -several Bazel bugs in the past were caused by rules using unsafe APIs, even -though the rules were written by the Bazel team, i.e., by the domain experts. - - -## Intrinsic: Avoiding Quadratic Time and Memory Consumption is Hard - -To make matters worse, apart from the requirements imposed by Skyframe, the -historical constraints of using Java, and the outdatedness of the rules API, -accidentally introducing quadratic time or memory consumption is a fundamental -problem in any build system based on library and binary rules. There are two -very common patterns that introduce quadratic memory consumption (and therefore -quadratic time consumption). - -1. Chains of Library Rules - -Consider the case of a chain of library rules A depends on B, depends on C, and -so on. Then, we want to compute some property over the transitive closure of -these rules, such as the Java runtime classpath, or the C++ linker command for -each library. Naively, we might take a standard list implementation; however, -this already introduces quadratic memory consumption: the first library -contains one entry on the classpath, the second two, the third three, and so -on, for a total of 1+2+3+...+N = O(N^2) entries. - -2. Binary Rules Depending on the Same Library Rules - -Consider the case where a set of binaries that depend on the same library -rules; for example, you might have a number of test rules that test the same -library code. Let’s say out of N rules, half the rules are binary rules, and -the other half library rules. Now consider that each binary makes a copy of -some property computed over the transitive closure of library rules, such as -the Java runtime classpath, or the C++ linker command line. For example, it -could expand the command line string representation of the C++ link action. N/2 -copies of N/2 elements is O(N^2) memory. - - -### Custom Collections Classes to Avoid Quadratic Complexity - -Bazel is heavily affected by both of these scenarios, so we introduced a set of -custom collection classes that effectively compress the information in memory by -avoiding the copy at each step. Almost all of these data structures have set -semantics, so we called the class NestedSet. The majority of changes to reduce -Bazel’s memory consumption over the past several years were changes to use -NestedSet instead of whatever was previously used. - -Unfortunately, usage of NestedSet does not automatically solve all the issues; -in particular, even just iterating over a NestedSet in each rule re-introduces -quadratic time consumption. NestedSet also has some helper methods to facilitate -interoperability with normal collections classes; unfortunately, accidentally -passing a NestedSet to one of these methods leads to copying behavior, and -reintroduces quadratic memory consumption. diff --git a/site/versions/master/docs/skylark/aspects.md b/site/versions/master/docs/skylark/aspects.md deleted file mode 100644 index 5dcaf1bedf..0000000000 --- a/site/versions/master/docs/skylark/aspects.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -layout: documentation -title: Aspects ---- -# Aspects - -**Status: Experimental**. We may make breaking changes to the API, but we will - help you update your code. - -Aspects allow augmenting build dependency graphs with additional information -and actions. Some typical scenarios when aspects can be useful: - -* IDEs that integrate Bazel can use aspects to collect information about the - project -* Code generation tools can leverage aspects to execute on their inputs in - "target-agnostic" manner. As an example, BUILD files can specify a hierarchy - of [protobuf](https://developers.google.com/protocol-buffers/) library - definitions, and language-specific rules can use aspects to attach - actions generating protobuf support code for a particular language - -## Aspect basics - -Bazel BUILD files provide a description of a project’s source code: what source -files are part of the project, what artifacts (_targets_) should be built from -those files, what the dependencies between those files are, etc. Bazel uses -this information to perform a build, that is, it figures out the set of actions -needed to produce the artifacts (such as running compiler or linker) and -executes those actions. Bazel accomplishes this by constructing a _dependency -graph_ between targets and visiting this graph to collect those actions. - -Consider the following BUILD file: - -```python -java_library(name = 'W', ...) -java_library(name = 'Y', deps = [':W'], ...) -java_library(name = 'Z', deps = [':W'], ...) -java_library(name = 'Q', ...) -java_library(name = 'T', deps = [':Q'], ...) -java_library(name = 'X', deps = [':Y',':Z'], runtime_deps = [':T'], ...) -``` - -This BUILD file defines a dependency graph shown in Fig 1. - -<img src="build-graph.png" alt="Build Graph" width="250px" /> - -Bazel analyzes this dependency graph by calling implementations of -[rules](rules.md) (in this case "java_library" starting from leaves of -the dependency graph). These implementations generate actions that build -artifacts (such as Jar files), and provide information (such as locations -and names of those artifacts) to their dependencies in providers that -they return. Their dependencies can access those providers through the -[Target object](lib/Target.html). In other words, every target -defined in the BUILD file generates a node in the dependency graph, and -the appropriate rule implementation function is called for every node. - -Aspects are similar to rules in that they have an implementation function that -generates actions and returns providers. However, their power comes from -the way the dependency graph is built for them. An aspect has an implementation -and a list of all attributes it propagates along. Consider an aspect A that -propagates along attributes named "deps". This aspect can be applied to -a target X, yielding an aspect application node A(X). During its application, -aspect A is applied recursively to all targets that X refers to in its "deps" -attribute (all attributes in A's propagation list). Thus a single act of -applying aspect A to a target X yields a "shadow graph" of the original -dependency graph of targets (see Fig.2). - - - -The only edges that are shadowed are the edges along the attributes in -the propagation set, thus the `runtime_deps` edge is not shadowed in this -example. An aspect implementation function is then invoked on all nodes in -the shadow graph similar to how rule implementations are invoked on the nodes -of the original graph. - -## Defining aspects - -Aspect definitions are similiar to rule definitions. Let's take a look at -the example: - -```python -metal_proto_aspect = aspect(implementation = _metal_proto_aspect_impl, - attr_aspects = ["deps"], - attrs = { - "_protoc" : attr.label( - default=Label("//tools:metal_protoc"), - executable = True - ) - } -) -``` - -Just like a rule, an aspect has an implementation function. ``attr_aspects`` -specify the aspect's propagation set: a list of attributes of rules along which -the aspect propagates. - -``attrs`` defines a set of attributes for aspects. Aspects are only allowed -to have private attributes of types ``label`` or ``label_list``. Attributes -can be used to specify dependencies on tools or libraries that are needed -for actions generated by aspects. - -### Implementation functions - -Aspect implementation functions are similiar to the rule implementation -functions. They return [providers](rules.md#providers), can generate -[actions](rules.md#actions) and take two arguments: - -* `target`: the [target](lib/Target.html) the aspect is being applied to. -* `ctx`: [`ctx`](lib/ctx.html) object that can be used to access attributes and - generate outputs and actions. - -Example: - -```python -def _metal_proto_aspect_impl(target, ctx): - # For every `src` in proto_library, generate an output file - proto_sources = [f for src in ctx.rule.attr.srcs - for f in src.files] - outputs = [ctx.new_file(f.short_path + ".metal") - for f in proto_sources] - ctx.action( - executable = ctx.executable._protoc, - argument = ... - inputs = proto_sources - outputs = outputs) - transitive_outputs = depset(outputs) - for dep in ctx.rule.attr.deps: - transitive_outputs = transitive_outputs | dep.metal_proto.transitive_outputs - return struct( - metal_proto = struct(direct_outputs = outputs, - transitive_outputs = transitive_outputs)) -``` - -The implementation function can access the attributes of the target rule via -[`ctx.rule.attr`](lib/ctx.html#rule). It can examine providers that are -provided by the target to which it is applied (via the `target` argument). - -Just like a rule implementation function, an aspect implementation function -returns a struct of providers that are accessible to its dependencies. - -* The set of providers for an aspect application A(X) is the union of providers - that come from the implementation of a rule for target X and from - the implementation of aspect A. It is an error if a target and an aspect that - is applied to it each provide a provider with the same name. -* For the aspect implementation, the values of attributes along which - the aspect is propagated (from the `attr_aspect` list) are replaced with - the results of an application of the aspect to them. For example, if target - X has Y and Z in its deps, `ctx.rule.attr.deps` for A(X) will be [A(Y), A(Z)]. - In the `_metal_proto_aspect_impl` function above, ctx.rule.attr.deps will be - Target objects that are the results of applying the aspect to the 'deps' - of the original target to which the aspect has been applied. - That allows the aspect to examine `metal_proto` provider on them. - - -## Applying aspects - -Aspect propagation can be initiated either from a rule or from the command line. - -### Applying aspects to rule attributes - -Rules can specify that they want to apply aspects to their dependencies. -The aspects to be applied to a particular attribute can be specified -using the `aspects` parameter to `attr.label` or `attr.label_list` function: - -```python -metal_proto_library = rule(implementation = _impl, - attrs = { - 'proto_deps' : attr.label_list(aspects = [metal_proto_aspect]), - }, -) -``` - -If a rule specifies an aspect on its attributes, the values of that attribute -will be replaced by the result of aspect application to them (similar to -what happens during aspect propagation). Thus implementation of -`metal_proto_library` will have access to `metal_proto` providers -on the target objects representing its `proto_deps` attribute values. - -### Applying aspects from command line. - -Aspects can also be applied on the command line, using the `--aspects` flag: - - -``` -bazel build //java/com/company/example:main \ - --aspects path/to/extension.bzl%metal_proto_aspect -``` - -`--aspects` flag takes one argument, which is a specification of the aspect in -the format `<extension file path>%<aspect top-level name>`. - - diff --git a/site/versions/master/docs/skylark/build-graph-aspect.svg b/site/versions/master/docs/skylark/build-graph-aspect.svg deleted file mode 100644 index 508a916bd3..0000000000 --- a/site/versions/master/docs/skylark/build-graph-aspect.svg +++ /dev/null @@ -1,4 +0,0 @@ -<?xml version="1.0" standalone="yes"?> - -<svg version="1.1" viewBox="0.0 0.0 960.0 720.0" fill="none" stroke="none" stroke-linecap="square" stroke-miterlimit="10" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"><clipPath id="p.0"><path d="m0 0l960.0 0l0 720.0l-960.0 0l0 -720.0z" clip-rule="nonzero"></path></clipPath><g clip-path="url(#p.0)"><path fill="#000000" fill-opacity="0.0" d="m0 0l960.0 0l0 720.0l-960.0 0z" fill-rule="nonzero"></path><path fill="#cfe2f3" d="m110.0 326.28873l0 0c0 -8.288635 10.5195465 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192383 23.496063 15.007874l0 0c0 8.288605 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976517 0 -23.496063 -6.719269 -23.496063 -15.007874z" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m110.0 326.28873l0 0c0 -8.288635 10.5195465 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192383 23.496063 15.007874l0 0c0 8.288605 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976517 0 -23.496063 -6.719269 -23.496063 -15.007874z" fill-rule="nonzero"></path><path fill="#000000" d="m127.3524 333.2087l5.265625 -7.09375l-4.640625 -6.5l2.140625 0l2.46875 3.484375q0.78125 1.078125 1.09375 1.671875q0.453125 -0.75 1.078125 -1.546875l2.734375 -3.609375l1.96875 0l-4.78125 6.40625l5.140625 7.1875l-2.21875 0l-3.421875 -4.859375q-0.296875 -0.40625 -0.59375 -0.90625q-0.453125 0.75 -0.65625 1.03125l-3.40625 4.734375l-2.171875 0z" fill-rule="nonzero"></path><path fill="#cfe2f3" d="m79.0 141.00787l0 0c0 -8.28862 10.5195465 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192535 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976517 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m79.0 141.00787l0 0c0 -8.28862 10.5195465 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192535 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976517 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path fill="#000000" d="m101.57115 147.92787l0 -5.765625l-5.234375 -7.828125l2.1875 0l2.671875 4.09375q0.75 1.15625 1.390625 2.296875q0.609375 -1.0625 1.484375 -2.40625l2.625 -3.984375l2.109375 0l-5.4375 7.828125l0 5.765625l-1.796875 0z" fill-rule="nonzero"></path><path fill="#cfe2f3" d="m163.51181 141.00787l0 0c0 -8.28862 10.5195465 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192535 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976517 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m163.51181 141.00787l0 0c0 -8.28862 10.5195465 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192535 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976517 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path fill="#000000" d="m181.68489 147.92787l0 -1.671875l6.96875 -8.703125q0.75 -0.9375 1.421875 -1.625l-7.59375 0l0 -1.59375l9.734375 0l0 1.59375l-7.625 9.4375l-0.828125 0.953125l8.6875 0l0 1.609375l-10.765625 0z" fill-rule="nonzero"></path><path fill="#cfe2f3" d="m0 141.00787l0 0c0 -8.28862 10.519546 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192535 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976518 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m0 141.00787l0 0c0 -8.28862 10.519546 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192535 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976518 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path fill="#000000" d="m22.719948 147.92787l0 -12.0l-4.46875 0l0 -1.59375l10.765625 0l0 1.59375l-4.5 0l0 12.0l-1.796875 0z" fill-rule="nonzero"></path><path fill="#cfe2f3" d="m110.0 19.007874l0 0c0 -8.288619 10.5195465 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192545 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976517 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m110.0 19.007874l0 0c0 -8.288619 10.5195465 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192545 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976517 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path fill="#000000" d="m128.53548 25.927872l-3.6093674 -13.59375l1.84375 0l2.0624924 8.90625q0.34375 1.40625 0.578125 2.78125q0.515625 -2.171875 0.609375 -2.515625l2.59375 -9.171875l2.171875 0l1.953125 6.875q0.734375 2.5625 1.046875 4.8125q0.265625 -1.28125 0.6875 -2.953125l2.125 -8.734375l1.8125 0l-3.734375 13.59375l-1.734375 0l-2.859375 -10.359375q-0.359375 -1.296875 -0.421875 -1.59375q-0.21875 0.9375 -0.40625 1.59375l-2.890625 10.359375l-1.828125 0z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m133.49606 311.28085l-30.992126 -155.2756" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m133.49606 311.28085l-29.817726 -149.39166" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m105.29812 161.56589l-2.5080414 -4.127014l-0.7315216 4.7736206z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m133.49606 311.28085l53.51181 -155.2756" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m133.49606 311.28085l51.5569 -149.60301" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m186.61456 162.216l-0.08300781 -4.8286285l-3.0401917 3.752304z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m102.49606 126.0l30.992126 -92.0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m102.49606 126.0l29.076675 -86.313965" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m133.13803 40.21334l-0.11654663 -4.8279343l-3.0140533 3.7733269z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m187.00787 126.0l-53.51181 -92.0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m187.00787 126.0l-50.495102 -86.81353" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m137.94055 38.356003l-3.7094727 -3.0923195l0.85391235 4.75325z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m110.0 326.28873l-86.48819 -170.26773" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m110.0 326.28873l-83.77092 -164.9183" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m27.701717 160.6224l-3.5278435 -3.2980194l0.5825653 4.7940826z" fill-rule="evenodd"></path><path fill="#cfe2f3" d="m0 19.007874l0 0c0 -8.288619 10.519546 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192545 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976518 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m0 19.007874l0 0c0 -8.288619 10.519546 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192545 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976518 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path fill="#000000" d="m28.005974 24.474747q1.265625 0.859375 2.3125 1.265625l-0.53125 1.25q-1.453125 -0.53125 -2.921875 -1.671875q-1.5 0.84375 -3.328125 0.84375q-1.84375 0 -3.359375 -0.890625q-1.5 -0.890625 -2.3125 -2.5q-0.8125 -1.625 -0.8125 -3.640625q0 -2.015625 0.8125 -3.65625q0.828125 -1.65625 2.328125 -2.515625q1.515625 -0.875 3.375 -0.875q1.890625 0 3.390625 0.90625q1.515625 0.890625 2.3125 2.5q0.796875 1.609375 0.796875 3.625q0 1.6875 -0.515625 3.03125q-0.515625 1.328125 -1.546875 2.328125zm-3.953125 -2.296875q1.5625 0.421875 2.5625 1.296875q1.59375 -1.453125 1.59375 -4.359375q0 -1.65625 -0.5625 -2.875q-0.5625 -1.234375 -1.640625 -1.921875q-1.078125 -0.6875 -2.421875 -0.6875q-2.015625 0 -3.34375 1.390625q-1.328125 1.375 -1.328125 4.109375q0 2.65625 1.3125 4.078125q1.3125 1.40625 3.359375 1.40625q0.953125 0 1.8125 -0.359375q-0.84375 -0.546875 -1.78125 -0.78125l0.4375 -1.296875z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m23.496063 126.0l0 -92.0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m23.496063 126.0l0 -86.0" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m25.147795 40.0l-1.6517315 -4.5380974l-1.6517334 4.5380974z" fill-rule="evenodd"></path><path fill="#ffff00" d="m244.7559 329.46457l0 0c0 -8.288635 20.82051 -15.007874 46.503952 -15.007874l0 0c25.68341 0 46.503937 6.7192383 46.503937 15.007874l0 0c0 8.288605 -20.820526 15.007874 -46.503937 15.007874l0 0c-25.683441 0 -46.503952 -6.719269 -46.503952 -15.007874z" fill-rule="nonzero"></path><path stroke="#ff0000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m244.7559 329.46457l0 0c0 -8.288635 20.82051 -15.007874 46.503952 -15.007874l0 0c25.68341 0 46.503937 6.7192383 46.503937 15.007874l0 0c0 8.288605 -20.820526 15.007874 -46.503937 15.007874l0 0c-25.683441 0 -46.503952 -6.719269 -46.503952 -15.007874z" fill-rule="nonzero"></path><path fill="#000000" d="m272.57236 336.38455l5.234375 -13.59375l1.9375 0l5.5625 13.59375l-2.046875 0l-1.59375 -4.125l-5.6875 0l-1.484375 4.125l-1.921875 0zm3.921875 -5.578125l4.609375 0l-1.40625 -3.78125q-0.65625 -1.703125 -0.96875 -2.8125q-0.265625 1.3125 -0.734375 2.59375l-1.5 4.0zm12.990448 9.578125q-1.375 -1.75 -2.328125 -4.078125q-0.953125 -2.34375 -0.953125 -4.84375q0 -2.21875 0.703125 -4.234375q0.84375 -2.34375 2.578125 -4.671875l1.2030945 0q-1.1249695 1.921875 -1.4843445 2.75q-0.5625 1.28125 -0.890625 2.671875q-0.40625 1.734375 -0.40625 3.484375q0 4.46875 2.7812195 8.921875l-1.2030945 0zm1.8532715 -4.0l5.265625 -7.09375l-4.640625 -6.5l2.140625 0l2.46875 3.484375q0.78125 1.078125 1.09375 1.671875q0.453125 -0.75 1.078125 -1.546875l2.734375 -3.609375l1.96875 0l-4.78125 6.40625l5.140625 7.1875l-2.21875 0l-3.421875 -4.859375q-0.296875 -0.40625 -0.59375 -0.90625q-0.453125 0.75 -0.65625 1.03125l-3.40625 4.734375l-2.171875 0zm14.709198 4.0l-1.1875 0q2.765625 -4.453125 2.765625 -8.921875q0 -1.734375 -0.390625 -3.453125q-0.328125 -1.390625 -0.890625 -2.671875q-0.359375 -0.84375 -1.484375 -2.78125l1.1875 0q1.75 2.328125 2.578125 4.671875q0.71875 2.015625 0.71875 4.234375q0 2.5 -0.96875 4.84375q-0.953125 2.328125 -2.328125 4.078125z" fill-rule="nonzero"></path><path fill="#ffff00" d="m217.57217 216.36745l0 0c0 -8.28862 20.820526 -15.007874 46.503937 -15.007874l0 0c25.68341 0 46.503937 6.7192535 46.503937 15.007874l0 0c0 8.28862 -20.820526 15.007889 -46.503937 15.007889l0 0c-25.68341 0 -46.503937 -6.719269 -46.503937 -15.007889z" fill-rule="nonzero"></path><path stroke="#ff0000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m217.57217 216.36745l0 0c0 -8.28862 20.820526 -15.007874 46.503937 -15.007874l0 0c25.68341 0 46.503937 6.7192535 46.503937 15.007874l0 0c0 8.28862 -20.820526 15.007889 -46.503937 15.007889l0 0c-25.68341 0 -46.503937 -6.719269 -46.503937 -15.007889z" fill-rule="nonzero"></path><path fill="#000000" d="m245.38861 223.28745l5.234375 -13.59375l1.9375 0l5.5625 13.59375l-2.046875 0l-1.59375 -4.125l-5.6875 0l-1.484375 4.125l-1.921875 0zm3.921875 -5.578125l4.609375 0l-1.40625 -3.78125q-0.65625 -1.703125 -0.96875 -2.8125q-0.265625 1.3125 -0.734375 2.59375l-1.5 4.0zm12.990448 9.578125q-1.375 -1.75 -2.328125 -4.078125q-0.953125 -2.34375 -0.953125 -4.84375q0 -2.21875 0.703125 -4.234375q0.84375 -2.34375 2.578125 -4.671875l1.203125 0q-1.125 1.921875 -1.484375 2.75q-0.5625 1.28125 -0.890625 2.671875q-0.40625 1.734375 -0.40625 3.484375q0 4.46875 2.78125 8.921875l-1.203125 0zm7.072052 -4.0l0 -5.765625l-5.234375 -7.828125l2.1875 0l2.671875 4.09375q0.75 1.15625 1.390625 2.296875q0.609375 -1.0625 1.484375 -2.40625l2.625 -3.984375l2.109375 0l-5.4375 7.828125l0 5.765625l-1.796875 0zm9.490448 4.0l-1.1875 0q2.765625 -4.453125 2.765625 -8.921875q0 -1.734375 -0.390625 -3.453125q-0.328125 -1.390625 -0.890625 -2.671875q-0.359375 -0.84375 -1.484375 -2.78125l1.1875 0q1.75 2.328125 2.578125 4.671875q0.71875 2.015625 0.71875 4.234375q0 2.5 -0.96875 4.84375q-0.953125 2.328125 -2.328125 4.078125z" fill-rule="nonzero"></path><path fill="#ffff00" d="m372.01575 141.00787l0 0c0 -8.28862 20.820526 -15.007874 46.503937 -15.007874l0 0c25.68341 0 46.503937 6.7192535 46.503937 15.007874l0 0c0 8.28862 -20.820526 15.007874 -46.503937 15.007874l0 0c-25.68341 0 -46.503937 -6.7192535 -46.503937 -15.007874z" fill-rule="nonzero"></path><path stroke="#ff0000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m372.01575 141.00787l0 0c0 -8.28862 20.820526 -15.007874 46.503937 -15.007874l0 0c25.68341 0 46.503937 6.7192535 46.503937 15.007874l0 0c0 8.28862 -20.820526 15.007874 -46.503937 15.007874l0 0c-25.68341 0 -46.503937 -6.7192535 -46.503937 -15.007874z" fill-rule="nonzero"></path><path fill="#000000" d="m400.356 147.92787l5.234375 -13.59375l1.9375 0l5.5625 13.59375l-2.046875 0l-1.59375 -4.125l-5.6875 0l-1.484375 4.125l-1.921875 0zm3.921875 -5.578125l4.609375 0l-1.40625 -3.78125q-0.65625 -1.703125 -0.96875 -2.8125q-0.265625 1.3125 -0.734375 2.59375l-1.5 4.0zm12.990448 9.578125q-1.375 -1.75 -2.328125 -4.078125q-0.953125 -2.34375 -0.953125 -4.84375q0 -2.21875 0.703125 -4.234375q0.84375 -2.34375 2.578125 -4.671875l1.203125 0q-1.125 1.921875 -1.484375 2.75q-0.5625 1.28125 -0.890625 2.671875q-0.40625 1.734375 -0.40625 3.484375q0 4.46875 2.78125 8.921875l-1.203125 0zm2.150177 -4.0l0 -1.671875l6.96875 -8.703125q0.75 -0.9375 1.421875 -1.625l-7.59375 0l0 -1.59375l9.734375 0l0 1.59375l-7.625 9.4375l-0.828125 0.953125l8.6875 0l0 1.609375l-10.765625 0zm13.364716 4.0l-1.1875 0q2.765625 -4.453125 2.765625 -8.921875q0 -1.734375 -0.390625 -3.453125q-0.328125 -1.390625 -0.890625 -2.671875q-0.359375 -0.84375 -1.484375 -2.78125l1.1875 0q1.75 2.328125 2.578125 4.671875q0.71875 2.015625 0.71875 4.234375q0 2.5 -0.96875 4.84375q-0.953125 2.328125 -2.328125 4.078125z" fill-rule="nonzero"></path><path fill="#ffff00" d="m295.0 19.007874l0 0c0 -8.288619 20.820526 -15.007874 46.503937 -15.007874l0 0c25.68341 0 46.503937 6.7192545 46.503937 15.007874l0 0c0 8.28862 -20.820526 15.007874 -46.503937 15.007874l0 0c-25.68341 0 -46.503937 -6.7192535 -46.503937 -15.007874z" fill-rule="nonzero"></path><path stroke="#ff0000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m295.0 19.007874l0 0c0 -8.288619 20.820526 -15.007874 46.503937 -15.007874l0 0c25.68341 0 46.503937 6.7192545 46.503937 15.007874l0 0c0 8.28862 -20.820526 15.007874 -46.503937 15.007874l0 0c-25.68341 0 -46.503937 -6.7192535 -46.503937 -15.007874z" fill-rule="nonzero"></path><path fill="#000000" d="m320.2339 25.927872l5.234375 -13.59375l1.9375 0l5.5625 13.59375l-2.046875 0l-1.59375 -4.125l-5.6875 0l-1.484375 4.125l-1.921875 0zm3.921875 -5.578125l4.609375 0l-1.40625 -3.78125q-0.65625 -1.703125 -0.96875 -2.8125q-0.265625 1.3125 -0.734375 2.59375l-1.5 4.0zm12.990448 9.578125q-1.375 -1.75 -2.328125 -4.078125q-0.953125 -2.34375 -0.953125 -4.84375q0 -2.21875 0.703125 -4.234375q0.84375 -2.34375 2.578125 -4.671875l1.203125 0q-1.125 1.921875 -1.484375 2.75q-0.5625 1.28125 -0.890625 2.671875q-0.40625 1.734375 -0.40625 3.484375q0 4.46875 2.78125 8.921875l-1.203125 0zm5.618927 -4.0l-3.609375 -13.59375l1.84375 0l2.0625 8.90625q0.34375 1.40625 0.578125 2.78125q0.515625 -2.171875 0.609375 -2.515625l2.59375 -9.171875l2.171875 0l1.953125 6.875q0.734375 2.5625 1.046875 4.8125q0.265625 -1.28125 0.6875 -2.953125l2.125 -8.734375l1.8125 0l-3.734375 13.59375l-1.734375 0l-2.859375 -10.359375q-0.359375 -1.296875 -0.421875 -1.59375q-0.21875 0.9375 -0.40625 1.59375l-2.890625 10.359375l-1.828125 0zm16.108673 4.0l-1.1875 0q2.765625 -4.453125 2.765625 -8.921875q0 -1.734375 -0.390625 -3.453125q-0.328125 -1.390625 -0.890625 -2.671875q-0.359375 -0.84375 -1.484375 -2.78125l1.1875 0q1.75 2.328125 2.578125 4.671875q0.71875 2.015625 0.71875 4.234375q0 2.5 -0.96875 4.84375q-0.953125 2.328125 -2.328125 4.078125z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m244.7559 329.46457l-87.74803 -3.1810913" fill-rule="nonzero"></path><path stroke="#ff0000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m244.7559 329.46457l-81.75197 -2.9637146" fill-rule="evenodd"></path><path fill="#ff0000" stroke="#ff0000" stroke-width="1.0" stroke-linecap="butt" d="m163.06378 324.8502l-4.5949707 1.4862366l4.475281 1.8150635z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m291.25986 314.4567l-27.181122 -83.086624" fill-rule="nonzero"></path><path stroke="#0000ff" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m291.25986 314.4567l-25.315552 -77.384" fill-rule="evenodd"></path><path fill="#0000ff" stroke="#0000ff" stroke-width="1.0" stroke-linecap="butt" d="m267.51416 236.55911l-2.9808655 -3.799591l-0.158844 4.826721z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m291.25986 314.4567l127.27557 -158.4252" fill-rule="nonzero"></path><path stroke="#0000ff" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m291.25986 314.4567l123.51779 -153.74771" fill-rule="evenodd"></path><path fill="#0000ff" stroke="#0000ff" stroke-width="1.0" stroke-linecap="butt" d="m416.06528 161.74347l1.5545654 -4.572296l-4.129883 2.5033264z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m231.19287 205.75528l-112.09449 -54.141724" fill-rule="nonzero"></path><path stroke="#ff0000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m231.19287 205.7553l-106.6917 -51.53218" fill-rule="evenodd"></path><path fill="#ff0000" stroke="#ff0000" stroke-width="1.0" stroke-linecap="butt" d="m125.21955 152.73578l-4.8047867 -0.48640442l3.3680267 3.4610596z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m372.01575 141.00787l-161.51181 0" fill-rule="nonzero"></path><path stroke="#ff0000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m372.01575 141.00787l-155.51181 0" fill-rule="evenodd"></path><path fill="#ff0000" stroke="#ff0000" stroke-width="1.0" stroke-linecap="butt" d="m216.50394 139.35614l-4.538101 1.6517334l4.538101 1.6517334z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m264.0761 201.35957l77.41733 -167.33858" fill-rule="nonzero"></path><path stroke="#0000ff" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m264.0761 201.35957l74.89804 -161.8931" fill-rule="evenodd"></path><path fill="#0000ff" stroke="#0000ff" stroke-width="1.0" stroke-linecap="butt" d="m340.47324 40.160004l0.40637207 -4.812214l-3.404541 3.4251518z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m418.51968 126.0l-77.00787 -92.0" fill-rule="nonzero"></path><path stroke="#0000ff" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m418.51968 126.0l-73.15671 -87.39908" fill-rule="evenodd"></path><path fill="#0000ff" stroke="#0000ff" stroke-width="1.0" stroke-linecap="butt" d="m346.62955 37.54074l-4.179413 -2.4197235l1.6462708 4.5400887z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m295.0 19.007874l-138.01575 0" fill-rule="nonzero"></path><path stroke="#ff0000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m295.0 19.007874l-132.01575 0" fill-rule="evenodd"></path><path fill="#ff0000" stroke="#ff0000" stroke-width="1.0" stroke-linecap="butt" d="m162.98425 17.356142l-4.538101 1.6517315l4.538101 1.6517334z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m137.17401 206.24611l11.842514 46.771652l-29.102364 7.3700867l-11.842514 -46.771667z" fill-rule="nonzero"></path><path fill="#000000" d="m121.81724 223.98074l0.69675446 -0.17645264q-0.9483261 -0.30786133 -1.2091141 -1.3378601q-0.16491699 -0.6513214 0.05670166 -1.3038177q0.22162628 -0.65249634 0.79623413 -1.1203918q0.57460785 -0.46788025 1.4228363 -0.6826935q0.83306885 -0.21096802 1.5685654 -0.10710144q0.75447845 0.11517334 1.240921 0.57225037q0.50159454 0.4532318 0.6741791 1.1348419q0.1265564 0.4998474 0.014221191 0.94737244q-0.112342834 0.44752502 -0.38420868 0.77427673l2.7415695 -0.6943054l0.23779297 0.93911743l-7.6340103 1.9332886l-0.22244263 -0.8785248zm2.0088654 -3.6517944q-1.0602798 0.2685089 -1.4792023 0.84202576q-0.39993286 0.5848236 -0.24652863 1.1907043q0.15724182 0.6210327 0.76447296 0.91856384q0.60723877 0.29753113 1.6372223 0.036697388q1.1360092 -0.2876892 1.5549316 -0.8612213q0.42275238 -0.55836487 0.2578354 -1.2096863q-0.15724182 -0.6210327 -0.7796173 -0.9147186q-0.6034012 -0.2823944 -1.7091141 -0.0023651123zm1.2829971 9.141266l0.12427521 1.0000916q-0.90574646 -0.012390137 -1.5325394 -0.5145111q-0.62680054 -0.5021057 -0.86841583 -1.4563751q-0.3068161 -1.2117615 0.25512695 -2.111618q0.5619354 -0.8998718 1.9100037 -1.241272q1.4086609 -0.35673523 2.3462524 0.16337585q0.9565811 0.5314331 1.2442245 1.6674652q0.28379822 1.1208649 -0.29711914 2.00943q-0.56578064 0.88471985 -1.9441376 1.2337799q-0.075737 0.019180298 -0.24235535 0.06138611l-1.0431747 -4.119995q-0.8973007 0.275589 -1.2669449 0.8527527q-0.36580658 0.5923004 -0.18938446 1.2890625q0.13039398 0.5149994 0.4799347 0.813324q0.36468506 0.29447937 1.0242538 0.35310364zm0.7361374 -3.458435l0.78237915 3.0899963q0.6814194 -0.23704529 0.95692444 -0.61305237q0.41508484 -0.5886688 0.23482513 -1.3005829q-0.16490936 -0.6513214 -0.71539307 -0.9793396q-0.5353317 -0.3318634 -1.2587357 -0.19702148zm-4.1481476 6.40654l7.649147 -1.9371185l0.21861267 0.8633728l-0.7118988 0.1802826q0.485672 0.19937134 0.7936096 0.524353q0.30792236 0.32496643 0.44599915 0.8702698q0.17642212 0.6967621 -0.049041748 1.3341064q-0.22544861 0.6373596 -0.822876 1.0787811q-0.58229065 0.43759155 -1.3850708 0.6408844q-0.8482208 0.21481323 -1.6065292 0.084487915q-0.74316406 -0.13415527 -1.2562637 -0.63282776q-0.5092621 -0.4835205 -0.6703415 -1.1197052q-0.118888855 -0.46955872 -0.017860413 -0.8981018q0.10486603 -0.4133911 0.34643555 -0.7324524l-2.6961365 0.68278503l-0.23778534 -0.93911743zm5.06176 -0.3792572q-1.0602798 0.26852417 -1.4640503 0.8381958q-0.3886261 0.56585693 -0.23521423 1.1717377q0.15724182 0.62101746 0.7834549 0.9298706q0.645195 0.32014465 1.7660599 0.03630066q1.0451355 -0.26467896 1.4640503 -0.8381958q0.42276 -0.5583801 0.26934814 -1.1642609q-0.15341187 -0.60588074 -0.83273315 -0.9335022q-0.67549133 -0.31248474 -1.7509155 -0.040145874zm0.07243347 4.805786l0.38542175 0.8856201q-0.54125977 0.21765137 -0.7559891 0.64276123q-0.19573975 0.43640137 -0.03466797 1.072586q0.16491699 0.6513214 0.499115 0.8890381q0.33803558 0.2528839 0.701561 0.16082764q0.31808472 -0.080566406 0.43081665 -0.39923096q0.07131958 -0.2276001 0.07646179 -1.0348206q-0.0032958984 -1.0951996 0.074920654 -1.5502014q0.09718323 -0.44369507 0.37672424 -0.7401428q0.28337097 -0.28129578 0.69233704 -0.38487244q0.37867737 -0.09588623 0.72380066 -0.005996704q0.36026 0.08607483 0.6490326 0.3353119q0.2203064 0.16986084 0.4222107 0.52168274q0.2019043 0.3518219 0.30929565 0.77593994q0.16491699 0.6513214 0.10588074 1.1820526q-0.0552063 0.5458832 -0.3309021 0.8574829q-0.25672913 0.3229065 -0.763855 0.54803467l-0.35128784 -0.87812805q0.40493774 -0.18313599 0.5554352 -0.5436249q0.16947937 -0.34916687 0.031417847 -0.89445496q-0.16491699 -0.6513214 -0.4460144 -0.8702698q-0.28108215 -0.2189331 -0.5688782 -0.14605713q-0.1817627 0.046035767 -0.29122925 0.18658447q-0.120788574 0.15953064 -0.16545105 0.42874146q-0.010925293 0.14782715 -0.031417847 0.89445496q-0.0082092285 1.0497589 -0.07510376 1.4857788q-0.06690979 0.4360199 -0.3426056 0.7476196q-0.26055908 0.30775452 -0.7452545 0.43049622q-0.4695511 0.118927 -0.9475479 -0.05015564q-0.47799683 -0.16908264 -0.8356018 -0.62654114q-0.35759735 -0.4574585 -0.5225067 -1.1087799q-0.27230072 -1.0754395 0.021217346 -1.7622681q0.3125 -0.6755066 1.1526642 -1.049469z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m120.55516 255.70743l18.960632 -44.377945l28.283463 12.094482l-18.960632 44.377945z" fill-rule="nonzero"></path><path fill="#000000" d="m143.51901 250.92964l-0.6608734 -0.28259277q0.56707764 0.8202667 0.14962769 1.7973175q-0.26397705 0.6178436 -0.83592224 1.0020447q-0.5719452 0.3841858 -1.3124847 0.4073944q-0.74053955 0.023208618 -1.5450745 -0.3208313q-0.79016113 -0.33789062 -1.3117828 -0.8668213q-0.52986145 -0.54945374 -0.6392975 -1.2080231q-0.123794556 -0.66470337 0.15246582 -1.3112946q0.20259094 -0.4741516 0.56333923 -0.761734q0.36073303 -0.28756714 0.7750244 -0.38230896l-2.600357 -1.1119537l0.3806305 -0.8908539l7.240753 3.096283l-0.35604858 0.833374zm-3.8118286 1.6837463q1.005661 0.43003845 1.6865234 0.2283783q0.67263794 -0.22218323 0.91819763 -0.7969208q0.25169373 -0.5891113 -0.05050659 -1.1941528q-0.30221558 -0.60505676 -1.2791443 -1.0228119q-1.0774994 -0.4607544 -1.7583466 -0.25907898q-0.6747284 0.18730164 -0.93870544 0.80514526q-0.25169373 0.5891113 0.06488037 1.2003021q0.30833435 0.590683 1.3571014 1.0391388zm4.5248566 -8.045364l0.50782776 -0.8704376q0.7124481 0.55955505 0.9061127 1.3391113q0.19366455 0.7795563 -0.19308472 1.6847687q-0.49111938 1.1494751 -1.4836121 1.5237732q-0.9924927 0.37428284 -2.2711334 -0.1724701q-1.3360901 -0.5713501 -1.7658844 -1.553833q-0.4380188 -1.003006 0.022399902 -2.0806427q0.45428467 -1.0632629 1.4550018 -1.417038q0.98635864 -0.35992432 2.2937164 0.1991272q0.07183838 0.030715942 0.22987366 0.09828186l-1.6697998 3.9082336q0.8804016 0.3255005 1.5243073 0.091033936q0.6500397 -0.24884033 0.9324341 -0.90979004q0.20872498 -0.4885254 0.111831665 -0.9378052q-0.11126709 -0.45542908 -0.59999084 -0.90231323zm-2.6828613 2.3024597l1.2523499 -2.9311676q-0.6854248 -0.22512817 -1.1324921 -0.093429565q-0.6870117 0.21603394 -0.97554016 0.8913574q-0.26397705 0.6178436 -0.025375366 1.2126923q0.22424316 0.58869934 0.88105774 0.9205475zm7.183197 -2.5752563l-7.255142 -3.102417l0.3499298 -0.81900024l0.67523193 0.28874207q-0.26512146 -0.45324707 -0.31277466 -0.898468q-0.047668457 -0.44522095 0.17333984 -0.96247864q0.2823944 -0.6609497 0.8481903 -1.030777q0.56581116 -0.36982727 1.3084412 -0.3581543q0.7282715 0.0055389404 1.4897003 0.33113098q0.80451965 0.34403992 1.3282471 0.90786743q0.50935364 0.5576782 0.61473083 1.2654877q0.11151123 0.69343567 -0.14633179 1.2969208q-0.19030762 0.4454193 -0.5305481 0.72476196q-0.3340912 0.26498413 -0.71965027 0.37200928l2.557251 1.0935364l-0.38061523 0.8908386zm-4.253525 -2.770523q1.005661 0.43003845 1.6721497 0.222229q0.6521301 -0.21395874 0.8976898 -0.7886963q0.25169373 -0.5891113 -0.05873108 -1.2146606q-0.31866455 -0.64608765 -1.3817902 -1.1006927q-0.9913025 -0.42388916 -1.6721649 -0.222229q-0.67471313 0.18730164 -0.9202728 0.7620392q-0.24555969 0.57473755 0.095687866 1.247467q0.34739685 0.6583557 1.3674316 1.0945435zm2.8573914 -3.8642426l0.2308197 -0.937912q0.56225586 0.15545654 0.9907837 -0.05215454q0.42030334 -0.2281189 0.67814636 -0.83158875q0.26397705 -0.6178436 0.14251709 -1.0096588q-0.11531067 -0.4061737 -0.46011353 -0.5536194q-0.30169678 -0.1289978 -0.5845947 0.055908203q-0.19474792 0.13764954 -0.6884613 0.77619934q-0.6616821 0.8726196 -0.99983215 1.1868439q-0.3463745 0.29371643 -0.74838257 0.35972595q-0.39587402 0.051635742 -0.78378296 -0.114227295q-0.35916138 -0.15359497 -0.57896423 -0.43450928q-0.23416138 -0.2870636 -0.31251526 -0.66044617q-0.07209778 -0.2687378 -0.019180298 -0.6709595q0.05290222 -0.40220642 0.22479248 -0.8045349q0.26397705 -0.6178436 0.63282776 -1.0039062q0.37498474 -0.4004364 0.7831421 -0.4808197q0.3999176 -0.100875854 0.9395752 0.027923584l-0.2534027 0.91127014q-0.43295288 -0.10017395 -0.77124023 0.09503174q-0.34649658 0.17471313 -0.5675049 0.6919861q-0.26397705 0.6178436 -0.1733551 0.96247864q0.09063721 0.344635 0.36360168 0.46136475q0.1723938 0.07371521 0.3446808 0.028427124q0.19276428 -0.053512573 0.3915558 -0.24040222q0.098358154 -0.11088562 0.56752014 -0.6919708q0.6432648 -0.82951355 0.960907 -1.1355133q0.3176422 -0.306015 0.72579956 -0.38638306q0.39378357 -0.086517334 0.8535156 0.110076904q0.44535828 0.19044495 0.72276306 0.61494446q0.27738953 0.42451477 0.28416443 1.005188q0.0067749023 0.5806885 -0.25720215 1.1985321q-0.4358673 1.0201569 -1.0857849 1.3880005q-0.6581421 0.34733582 -1.5527954 0.13470459z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m81.12184 104.50765l17.41732 -44.976383l28.692917 11.118114l-17.41732 44.97637z" fill-rule="nonzero"></path><path fill="#000000" d="m103.909035 98.94311l-0.6701889 -0.25969696q0.59490204 0.80026245 0.21121216 1.7910614q-0.24263 0.6265335 -0.80107117 1.030159q-0.55844116 0.40361786 -1.2977829 0.45227814q-0.7393341 0.04865265 -1.5552292 -0.2674942q-0.8013153 -0.3105011 -1.340805 -0.8211746q-0.54842377 -0.5308838 -0.6803894 -1.1852722q-0.14653015 -0.6600342 0.10738373 -1.315712q0.186203 -0.48082733 0.5368805 -0.7806244q0.3506775 -0.29979706 0.76148224 -0.40872955l-2.6370697 -1.0218277l0.34983826 -0.90338135l7.34301 2.8453217l-0.3272705 0.8450928zm-3.7519302 1.8137894q1.0198593 0.39518738 1.6934204 0.17022705q0.66464233 -0.2451706 0.8903427 -0.8279953q0.23134613 -0.59739685 -0.09146118 -1.1916733q-0.32279968 -0.5942764 -1.3135223 -0.9781647q-1.0927124 -0.42341614 -1.7662735 -0.19845581q-0.667923 0.21038055 -0.910553 0.8369217q-0.23134613 0.5973892 0.106025696 1.197319q0.32844543 0.5797043 1.3920212 0.9918213zm4.246277 -8.195946l0.47768402 -0.887352q0.73124695 0.5347061 0.951561 1.307106q0.2203064 0.77240753 -0.13516998 1.6903534q-0.4514084 1.1656494 -1.4305115 1.5738373q-0.9791031 0.4081955 -2.2757797 -0.09425354q-1.3549652 -0.52503204 -1.8182373 -1.4921188q-0.4721985 -0.9873123 -0.04901123 -2.080101q0.41754913 -1.0782242 1.4055786 -1.4662018q0.97345734 -0.39362335 2.2992783 0.12011719q0.07285309 0.02822876 0.23311615 0.09033203l-1.5347672 3.9631958q0.8910904 0.29502106 1.5265884 0.03855896q0.6411438 -0.27103424 0.90070343 -0.9412842q0.19184113 -0.49539948 0.079582214 -0.94107056q-0.12683105 -0.4513092 -0.63061523 -0.8811188zm-2.6023788 2.3932877l1.1510773 -2.9724045q-0.6927643 -0.20140839 -1.1350708 -0.05441284q-0.67920685 0.23952484 -0.9444046 0.9243469q-0.24263 0.6265335 0.01625061 1.2127991q0.24430847 0.5806198 0.9121475 0.8896713zm7.0908585 -2.820671l-7.3575745 -2.8509598l0.32162476 -0.83052826l0.68476105 0.26533508q-0.2805252 -0.44384003 -0.34342957 -0.88713837q-0.06291199 -0.44330597 0.14022064 -0.9678421q0.259552 -0.67024994 0.81235504 -1.0593033q0.5527954 -0.38904572 1.2954178 -0.40291595q0.72805023 -0.019515991 1.5002365 0.2796936q0.81588745 0.31614685 1.3586655 0.8616028q0.5282059 0.5398102 0.657814 1.2435608q0.13524628 0.68917084 -0.101737976 1.3011398q-0.17491913 0.45168304 -0.50538635 0.74256134q-0.32482147 0.27629852 -0.70648956 0.39652252l2.593361 1.0048904l-0.34983826 0.90338135zm-4.346245 -2.6225052q1.019867 0.39517975 1.6788559 0.1645813q0.64443207 -0.2362442 0.87013245 -0.8190689q0.2313385 -0.59739685 -0.10038757 -1.2118912q-0.34065247 -0.6347122 -1.4187927 -1.052475q-1.0052948 -0.389534 -1.6788559 -0.1645813q-0.667923 0.21038818 -0.893631 0.7932129q-0.22570038 0.5828247 0.13845062 1.243393q0.36979675 0.6460037 1.4042282 1.0468292zm2.7232208 -3.9600906l0.19850159 -0.9452667q0.56728363 0.1360321 0.9884491 -0.08618164q0.41223907 -0.24243164 0.64923096 -0.854393q0.24262238 -0.62654114 0.107795715 -1.0139236q-0.12918854 -0.40195465 -0.47885895 -0.53744507q-0.30595398 -0.11856079 -0.5823517 0.07596588q-0.18991089 0.14425659 -0.661438 0.7993927q-0.6313782 0.8948288 -0.9585571 1.2204895q-0.33611298 0.3054428 -0.73563385 0.38523102q-0.39388275 0.065223694 -0.78725433 -0.08720398q-0.36424255 -0.14113617 -0.59355927 -0.41432953q-0.24388885 -0.27882385 -0.33501434 -0.64927673q-0.08126831 -0.2660904 -0.04219055 -0.66986847q0.03907776 -0.4037857 0.19706726 -0.81175995q0.24263 -0.62654114 0.59802246 -1.0250549q0.3610382 -0.4130783 0.76620483 -0.50743866q0.39624023 -0.11457825 0.9400253 -0.00440979l-0.2219925 0.9194031q-0.43615723 -0.08522034 -0.76755524 0.12150574q-0.34031677 0.18651581 -0.5434494 0.7110596q-0.24263 0.6265335 -0.14022064 0.9678421q0.10240173 0.3413086 0.37922668 0.44857025q0.1748352 0.06774902 0.34545135 0.016563416q0.19084167 -0.060112 0.38310242 -0.25372314q0.09449768 -0.11419678 0.54345703 -0.7110596q0.6144409 -0.85111237 0.9214096 -1.1678467q0.30697632 -0.3167343 0.71214294 -0.41109467q0.39059448 -0.1000061 0.85681915 0.08065033q0.45165253 0.17501068 0.7434616 0.5897064q0.29180908 0.41469574 0.31850433 0.9947815q0.026695251 0.58008575 -0.21593475 1.2066193q-0.4006195 1.0345078 -1.0375519 1.4244766q-0.64585876 0.36975098 -1.5473099 0.1880188z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m171.07939 43.463318l21.732285 43.08661l-26.803146 13.511818l-21.732285 -43.086617z" fill-rule="nonzero"></path><path fill="#000000" d="m159.94344 64.10798l0.6417999 -0.32354355q-0.9926758 -0.094516754 -1.4711609 -1.0431747q-0.30256653 -0.59988785 -0.22807312 -1.284874q0.07450867 -0.6849899 0.5337219 -1.2664528q0.45922852 -0.58145905 1.2405548 -0.9753418q0.76737976 -0.38684464 1.5079498 -0.4452057q0.7615509 -0.051445007 1.3357697 0.2890129q0.58818054 0.3334236 0.90483093 0.96121216q0.23220825 0.46038055 0.21983337 0.92157364q-0.012390137 0.46119308 -0.20675659 0.83914566l2.5253906 -1.2730789l0.43626404 0.8649521l-7.032013 3.5449257l-0.40811157 -0.8091507zm1.1671906 -4.0005302q-0.9766693 0.49235153 -1.2609406 1.1431007q-0.26327515 0.65766907 0.018188477 1.215702q0.28849792 0.57198715 0.94595337 0.7305031q0.65745544 0.15851593 1.6062164 -0.319767q1.0464325 -0.5275192 1.3307037 -1.1782722q0.29130554 -0.63679886 -0.011276245 -1.2366867q-0.28849792 -0.57198334 -0.9598999 -0.72346497q-0.65042114 -0.14456558 -1.6689453 0.36888504zm3.239624 8.643436l0.33872986 0.94911957q-0.8868866 0.18462372 -1.6079102 -0.16932678q-0.72102356 -0.35394287 -1.1643372 -1.2328491q-0.56292725 -1.116066 -0.2099762 -2.1164017q0.3529358 -1.0003357 1.594696 -1.6263275q1.2975769 -0.6541214 2.3259277 -0.35011292q1.0493164 0.31093597 1.5770721 1.3572464q0.5207062 1.0323639 0.14677429 2.0257797q-0.35998535 0.98638916 -1.6296539 1.626442q-0.06976318 0.03517151 -0.22323608 0.1125412l-1.9139557 -3.7946396q-0.81604004 0.46387482 -1.0514221 1.1074753q-0.22833252 0.657547 0.09535217 1.2992859q0.23924255 0.47433472 0.64530945 0.6895828q0.4200287 0.2082138 1.0766296 0.12218475zm-0.033187866 -3.5353851l1.4354706 2.8459778q0.6136627 -0.37934875 0.8008728 -0.8061905q0.27722168 -0.66469574 -0.053497314 -1.3203888q-0.30256653 -0.59989166 -0.9112549 -0.80049133q-0.59472656 -0.20763397 -1.2715912 0.081092834zm-2.656723 7.153839l7.0459595 -3.5519638l0.40109253 0.79520416l-0.6557617 0.33057404q0.5174408 0.08911133 0.88868713 0.3394165q0.37124634 0.25029755 0.62457275 0.75253296q0.3236847 0.6417389 0.24214172 1.3127747q-0.08154297 0.67103577 -0.5687866 1.2316284q-0.47329712 0.55355835 -1.2127686 0.9263382q-0.78134155 0.39388275 -1.5499268 0.4313736q-0.7546387 0.030464172 -1.3639221 -0.3448105q-0.60224915 -0.36132812 -0.8977814 -0.9472656q-0.21813965 -0.43247986 -0.212677 -0.8726883q0.012496948 -0.42625427 0.17897034 -0.79013824l-2.4835358 1.251976l-0.43626404 -0.8649521zm4.8588104 -1.4694977q-0.9766693 0.49234772 -1.2469788 1.1360626q-0.25636292 0.63668823 0.025100708 1.1947174q0.28849792 0.57199097 0.9669342 0.7374191q0.6994324 0.17235565 1.7319183 -0.34812927q0.9627075 -0.48532104 1.2469788 -1.1360703q0.2913208 -0.6368027 0.009841919 -1.1948318q-0.28146362 -0.5580368 -1.0158386 -0.7302704q-0.72732544 -0.15828705 -1.7179565 0.3411026zm1.1154175 4.67482l0.5687561 0.78066254q-0.48104858 0.33000183 -0.5982666 0.79154205q-0.096206665 0.46846008 0.19932556 1.0543976q0.3025818 0.59988403 0.6804962 0.75933075q0.384964 0.17339325 0.7198181 0.0045928955q0.29299927 -0.14770508 0.33377075 -0.48322296q0.020141602 -0.23763275 -0.15029907 -1.0266113q-0.24130249 -1.0682297 -0.26387024 -1.5293045q-0.0015716553 -0.4541626 0.20687866 -0.8042145q0.21546936 -0.33609772 0.5921936 -0.5260086q0.34880066 -0.17583466 0.70526123 -0.16304779q0.37039185 0.0057525635 0.7064667 0.18630219q0.25198364 0.11794281 0.52557373 0.41748047q0.27357483 0.29953766 0.4705963 0.690155q0.3025818 0.59989166 0.36032104 1.130722q0.06477356 0.5447769 -0.1366272 0.90878296q-0.18040466 0.37091827 -0.6265259 0.70079803l-0.5338135 -0.7807846q0.355484 -0.26669312 0.42404175 -0.6512146q0.089538574 -0.37760162 -0.16378784 -0.87983704q-0.30256653 -0.59988403 -0.6245575 -0.7525253q-0.32199097 -0.15264893 -0.58709717 -0.019012451q-0.16741943 0.08440399 -0.2437439 0.24536133q-0.083221436 0.1819458 -0.06829834 0.45439148q0.021469116 0.14665985 0.16377258 0.87983704q0.22018433 1.0263748 0.2496643 1.4664688q0.02947998 0.440094 -0.17193604 0.8040924q-0.18743896 0.35697174 -0.6339264 0.5820465q-0.43252563 0.21804047 -0.9358978 0.15682983q-0.5033722 -0.061210632 -0.9519043 -0.43003845q-0.4485321 -0.3688202 -0.75109863 -0.96871185q-0.49960327 -0.99050903 -0.36238098 -1.724617q0.15821838 -0.7271881 0.8970947 -1.274643z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m61.231503 170.96638l41.700787 76.44095l-26.330704 14.362198l-41.70079 -76.44093z" fill-rule="nonzero"></path><path fill="#000000" d="m48.99513 188.71129l5.006748 -2.730957l0.41156006 0.75442505l-0.7544441 0.41151428q0.6995926 0.009963989 0.9988899 0.16706848q0.29929733 0.15711975 0.45643616 0.44517517q0.23945236 0.43893433 0.20455933 1.0275116l-0.93901443 0.13842773q0.006214142 -0.41275024 -0.16588974 -0.72824097q-0.1496582 -0.27433777 -0.43398666 -0.40402222q-0.28433228 -0.12966919 -0.63848877 -0.061080933q-0.5274925 0.10974121 -1.0624619 0.40153503l-2.6199684 1.4290771l-0.46393967 -0.85043335zm3.495327 6.4072113l0.7407265 -0.40402222q-1.172226 -0.12593079 -1.7184715 -1.1272583q-0.23945236 -0.43893433 -0.29185104 -0.9264984q-0.031196594 -0.4813385 0.11095047 -0.80804443q0.16334915 -0.32048035 0.49629593 -0.5910797q0.21697617 -0.18954468 0.76566315 -0.4888153l3.1000671 -1.6909485l0.46393967 0.85043335l-2.7708588 1.511383q-0.6721382 0.36660767 -0.87540054 0.54867554q-0.2843132 0.26187134 -0.34165955 0.6135254q-0.049865723 0.36535645 0.15965271 0.74942017q0.20952225 0.38407898 0.58115005 0.6085205q0.39282608 0.23069763 0.7968674 0.18829346q0.41775513 -0.04989624 1.0487442 -0.39405823l2.6885529 -1.4664917l0.46393967 0.85043335l-5.006748 2.730957l-0.41156006 -0.75442505zm1.0423317 1.9106903l5.006748 -2.730957l0.41904068 0.76812744l-0.71329117 0.3890686q1.1223412 0.099746704 1.69104 1.1422119q0.24693298 0.45265198 0.29184723 0.9264984q0.058631897 0.46636963 -0.11843109 0.79434204q-0.15586472 0.33418274 -0.46761322 0.61102295q-0.2244606 0.17582703 -0.8142967 0.4975586l-3.0726357 1.6759796l-0.46393585 -0.85043335l3.0452003 -1.661026q0.5212517 -0.28431702 0.71577835 -0.51501465q0.20824432 -0.23817444 0.2169609 -0.5810852q0.029911041 -0.33668518 -0.1571579 -0.6796112q-0.29183197 -0.5349426 -0.8517647 -0.74568176q-0.5599289 -0.21072388 -1.533844 0.3204956l-2.7297058 1.4889374l-0.46393967 -0.85043335zm4.6103287 6.6566315l-0.6808624 0.5137634q-0.27685547 -0.31173706 -0.42651367 -0.5860748q-0.25441742 -0.46636963 -0.24570465 -0.8092804q0.016197205 -0.32920837 0.1895256 -0.5661316q0.18081284 -0.22322083 0.9489708 -0.6422119l2.8805962 -1.571228l-0.34421158 -0.6309662l0.65842056 -0.35914612l0.34421158 0.6309662l1.234539 -0.6733856l0.9777069 0.5523987l-1.7557907 0.95770264l0.4714203 0.864151l-0.6584244 0.35914612l-0.4714203 -0.864151l-2.935463 1.6011505q-0.35664368 0.1945343 -0.44393158 0.2955475q-0.06608963 0.10723877 -0.082294464 0.24066162q0.0049934387 0.1396637 0.10227203 0.3179779q0.08230972 0.15089417 0.23695374 0.3691101zm5.5927467 -2.0809174l0.9739151 -0.5312195l0.46393585 0.85043335l-0.9739151 0.5312195l-0.46393585 -0.85043335zm-5.9395103 3.2397308l5.006748 -2.7309418l0.46393585 0.85043335l-5.006748 2.7309418l-0.46393585 -0.85043335zm1.1263084 2.064621l5.006748 -2.730957l0.41904068 0.7681427l-0.6995735 0.38157654q0.49757004 0.031173706 0.92656326 0.29553223q0.43647766 0.2780609 0.7058563 0.77186584q0.30680084 0.5623779 0.2681656 1.0462189q-0.024925232 0.47633362 -0.36784363 0.8591614q1.1996613 0.11097717 1.7159805 1.0574188q0.41155243 0.75442505 0.21704102 1.3766632q-0.19451141 0.6222534 -1.0449677 1.0861359l-3.442997 1.878006l-0.45645523 -0.8367157l3.1549377 -1.7208862q0.5075302 -0.27682495 0.682106 -0.47885132q0.18829346 -0.20948792 0.20574188 -0.5037689q0.017448425 -0.29429626 -0.13969421 -0.5823517q-0.29183197 -0.5349426 -0.84303284 -0.697052q-0.54371643 -0.14837646 -1.3118744 0.27061462l-2.9080276 1.5861969l-0.46393585 -0.85043335l3.2509575 -1.7732391q0.562397 -0.3067627 0.7382164 -0.6696472q0.1758194 -0.36286926 -0.07859802 -0.8292389q-0.19455719 -0.35662842 -0.55870056 -0.56736755q-0.35666275 -0.19702148 -0.8018532 -0.13217163q-0.43147278 0.057373047 -1.1173286 0.43147278l-2.592537 1.4141083l-0.46393585 -0.85043335zm7.740425 10.338898l0.36917114 0.9377136q-0.8804016 0.21325684 -1.6124344 -0.1171875q-0.73202515 -0.33044434 -1.2034454 -1.1945953q-0.598629 -1.0973358 -0.27818298 -2.1086426q0.3204422 -1.0113068 1.5412674 -1.6772003q1.2756958 -0.6958313 2.31324 -0.4252472q1.058754 0.2768097 1.6199646 1.3055573q0.5537338 1.0150299 0.21208954 2.020111q-0.32792664 0.9975891 -1.5761871 1.6784515q-0.06858063 0.03741455 -0.21947479 0.11972046l-2.0353317 -3.7309418q-0.8005829 0.49006653 -1.0150452 1.1409912q-0.20697784 0.6646576 0.13723755 1.2956238q0.2544098 0.46635437 0.66719055 0.6683655q0.4264984 0.19451904 1.0799408 0.08728027zm-0.14730835 -3.5326996l1.5265045 2.7982025q0.60105896 -0.3990326 0.7743759 -0.83174133q0.25561523 -0.67337036 -0.096076965 -1.3180542q-0.32176208 -0.5898285 -0.9365616 -0.7706299q-0.60108185 -0.1882782 -1.2682419 0.1222229zm-2.850727 6.454727l0.61727524 -0.33668518l3.0679703 5.6238403l-0.6172714 0.33668518l-3.067974 -5.6238403zm6.958576 8.187897l0.6309891 -0.34417725q-0.9951477 -0.062332153 -1.5039749 -0.9950714q-0.3217697 -0.58981323 -0.26942444 -1.2769012q0.052345276 -0.687088 0.49253082 -1.2831421q0.44017792 -0.59606934 1.2083359 -1.0150604q0.7544403 -0.41151428 1.4926834 -0.4938202q0.7594452 -0.07608032 1.3443222 0.24563599q0.59859467 0.31422424 0.9353256 0.9314728q0.24693298 0.45265198 0.24944305 0.914032q0.0025177002 0.46139526 -0.17953491 0.845459l2.4827957 -1.354248l0.46394348 0.85043335l-6.9134293 3.7709656l-0.43400574 -0.795578zm1.0373535 -4.036484q-0.96019745 0.5237427 -1.2232895 1.1833954q-0.24189758 0.66589355 0.057418823 1.2145538q0.3067932 0.5623932 0.9689789 0.69955444q0.66218567 0.13716125 1.5949478 -0.3716278q1.0287857 -0.5611572 1.2918854 -1.2208099q0.27057648 -0.64593506 -0.051185608 -1.2357483q-0.30680084 -0.5623932 -0.98270416 -0.6920624q-0.65470123 -0.1234436 -1.6560516 0.42274475zm3.5167618 8.534607l0.3691635 0.9377136q-0.8804016 0.21325684 -1.6124268 -0.1171875q-0.7320328 -0.33044434 -1.2034531 -1.1945953q-0.5986252 -1.0973358 -0.27818298 -2.1086426q0.32044983 -1.0113068 1.5412674 -1.6772003q1.2756958 -0.6958313 2.3132477 -0.4252472q1.0587463 0.2768097 1.6199646 1.3055573q0.5537262 1.0150452 0.21208191 2.020111q-0.32792664 0.9975891 -1.5761871 1.6784515q-0.06858063 0.03741455 -0.21946716 0.11972046l-2.0353394 -3.7309418q-0.8005829 0.49006653 -1.0150452 1.1410065q-0.20697784 0.66464233 0.13723755 1.2956085q0.25441742 0.46636963 0.6671982 0.6683655q0.42649078 0.19451904 1.0799408 0.08728027zm-0.14730835 -3.5326996l1.5264969 2.7982025q0.60105896 -0.3990326 0.7743759 -0.83174133q0.25561523 -0.67337036 -0.096076965 -1.3180542q-0.32176208 -0.5898285 -0.9365616 -0.7706299q-0.60108185 -0.1882782 -1.2682343 0.1222229zm-2.4242096 7.2365875l6.927147 -3.7784576l0.4265213 0.78186035l-0.6447067 0.35165405q0.52001953 0.07232666 0.8991318 0.31048584q0.37911224 0.23817444 0.64849854 0.7319641q0.34420776 0.63098145 0.28437805 1.3043518q-0.059822083 0.67337036 -0.5286865 1.2494812q-0.4551468 0.5686188 -1.1821518 0.9651642q-0.76815796 0.41900635 -1.5350876 0.48136902q-0.753212 0.054870605 -1.3742523 -0.3005066q-0.6135559 -0.3416748 -0.9278412 -0.9177704q-0.23196411 -0.42521667 -0.24071503 -0.8654022q-0.0012664795 -0.4264679 0.15335083 -0.795578l-2.4416504 1.3318176l-0.46393585 -0.85043335zm4.8085175 -1.6261292q-0.96019745 0.5237427 -1.2095795 1.1759186q-0.23565674 0.64468384 0.06365967 1.1933594q0.3067932 0.5623779 0.99018097 0.70578q0.7045822 0.14962769 1.7196503 -0.40405273q0.9464798 -0.51626587 1.2095795 -1.1759186q0.27057648 -0.64593506 -0.02873993 -1.1946106q-0.2993164 -0.5486603 -1.0388184 -0.69703674q-0.7320175 -0.13467407 -1.7059326 0.39656067zm1.2656784 4.636566l0.5936203 0.76190186q-0.47011566 0.3454132 -0.5723572 0.8105469q-0.0810318 0.47135925 0.23324585 1.0474548q0.32176208 0.58981323 0.70461273 0.73695374q0.39032745 0.16085815 0.71954346 -0.018707275q0.28805542 -0.15711975 0.31797028 -0.49380493q0.012458801 -0.23817444 -0.18335724 -1.021286q-0.27565002 -1.0599213 -0.31307983 -1.5200653q-0.016227722 -0.45388794 0.18078613 -0.8105316q0.20449829 -0.34292603 0.5748596 -0.54493713q0.34293365 -0.1870575 0.69958496 -0.18580627q0.37036896 -0.0062408447 0.71206665 0.16334534q0.25564575 0.10972595 0.53874207 0.40026855q0.28308868 0.2905426 0.49260712 0.6746063q0.32176208 0.58981323 0.39661407 1.1185455q0.0823288 0.5424347 -0.10720825 0.91278076q-0.16833496 0.3765869 -0.6035385 0.72076416l-0.5587082 -0.7631378q0.34666443 -0.27809143 0.402771 -0.6646576q0.077293396 -0.38032532 -0.19208527 -0.87413025q-0.32176208 -0.58981323 -0.64849854 -0.7319641q-0.32672882 -0.14215088 -0.58735657 1.5258789E-5q-0.16460419 0.089782715 -0.23567963 0.25312805q-0.077308655 0.18455505 -0.053596497 0.45640564q0.026191711 0.14588928 0.19207764 0.87413025q0.25319672 1.0187836 0.29685974 1.4577179q0.043670654 0.43893433 -0.1458664 0.8092804q-0.17581177 0.36288452 -0.61476135 0.6023102q-0.42523193 0.2319336 -0.9302826 0.1870575q-0.5050583 -0.044891357 -0.96523285 -0.39901733q-0.46017456 -0.35414124 -0.78193665 -0.94395447q-0.5312805 -0.9738922 -0.41783142 -1.7120972q0.13464355 -0.73197937 0.85541534 -1.3031158z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m53.480316 46.299507l0 50.92914l-29.984253 0l0 -50.92914z" fill-rule="nonzero"></path><path fill="#000000" d="m34.240314 59.721382l0.71875 0q-0.84375 -0.53125 -0.84375 -1.59375q0 -0.671875 0.375 -1.25q0.375 -0.578125 1.046875 -0.890625q0.671875 -0.3125 1.546875 -0.3125q0.859375 0 1.546875 0.28125q0.703125 0.296875 1.0625 0.859375q0.375 0.5625 0.375 1.265625q0 0.515625 -0.21875 0.921875q-0.21875 0.40625 -0.5625 0.65625l2.828125 0l0 0.96875l-7.875 0l0 -0.90625zm2.84375 -3.046875q-1.09375 0 -1.640625 0.453125q-0.53125 0.46875 -0.53125 1.09375q0 0.640625 0.515625 1.078125q0.515625 0.4375 1.578125 0.4375q1.171875 0 1.71875 -0.453125q0.546875 -0.4375 0.546875 -1.109375q0 -0.640625 -0.53125 -1.078125q-0.515625 -0.421875 -1.65625 -0.421875zm-1.0 9.176498l-0.125 1.0q-0.875 -0.234375 -1.359375 -0.875q-0.484375 -0.640625 -0.484375 -1.625q0 -1.25 0.765625 -1.984375q0.765625 -0.734375 2.15625 -0.734375q1.453125 0 2.234375 0.734375q0.796875 0.75 0.796875 1.921875q0 1.15625 -0.78125 1.875q-0.765625 0.71875 -2.1875 0.71875q-0.078125 0 -0.25 0l0 -4.25q-0.9375 0.046875 -1.4375 0.515625q-0.5 0.484375 -0.5 1.203125q0 0.53125 0.265625 0.90625q0.28125 0.375 0.90625 0.59375zm1.5625 -3.171875l0 3.1875q0.71875 -0.0625 1.078125 -0.359375q0.546875 -0.46875 0.546875 -1.203125q0 -0.671875 -0.453125 -1.125q-0.4375 -0.453125 -1.171875 -0.5zm-5.59375 5.1921234l7.890625 0l0 0.890625l-0.734375 0q0.421875 0.3125 0.640625 0.703125q0.21875 0.390625 0.21875 0.953125q0 0.71875 -0.375 1.28125q-0.375 0.5625 -1.0625 0.84375q-0.671875 0.28125 -1.5 0.28125q-0.875 0 -1.578125 -0.3125q-0.6875 -0.3125 -1.0625 -0.921875q-0.375 -0.59375 -0.375 -1.25q0 -0.484375 0.203125 -0.875q0.203125 -0.375 0.515625 -0.625l-2.78125 0l0 -0.96875zm5.0 0.875q-1.09375 0 -1.625 0.453125q-0.515625 0.453125 -0.515625 1.078125q0 0.640625 0.53125 1.09375q0.546875 0.46875 1.703125 0.46875q1.078125 0 1.625 -0.453125q0.546875 -0.4375 0.546875 -1.0625q0 -0.625 -0.578125 -1.109375q-0.578125 -0.46875 -1.6875 -0.46875zm-1.109375 4.6764984l0.15625 0.953125q-0.578125 0.078125 -0.890625 0.4375q-0.296875 0.375 -0.296875 1.03125q0 0.671875 0.265625 0.984375q0.265625 0.328125 0.640625 0.328125q0.328125 0 0.515625 -0.28125q0.125 -0.203125 0.328125 -0.984375q0.265625 -1.0625 0.453125 -1.484375q0.203125 -0.40625 0.546875 -0.625q0.34375 -0.203125 0.765625 -0.203125q0.390625 0 0.703125 0.171875q0.328125 0.171875 0.546875 0.484375q0.171875 0.21875 0.28125 0.609375q0.109375 0.390625 0.109375 0.828125q0 0.671875 -0.1875 1.171875q-0.1875 0.515625 -0.53125 0.75q-0.328125 0.25 -0.875 0.34375l-0.125 -0.9375q0.4375 -0.078125 0.671875 -0.390625q0.25 -0.296875 0.25 -0.859375q0 -0.671875 -0.21875 -0.953125q-0.21875 -0.28125 -0.515625 -0.28125q-0.1875 0 -0.328125 0.109375q-0.15625 0.125 -0.265625 0.375q-0.046875 0.140625 -0.25 0.859375q-0.265625 1.015625 -0.4375 1.421875q-0.171875 0.40625 -0.515625 0.640625q-0.328125 0.234375 -0.828125 0.234375q-0.484375 0 -0.90625 -0.28125q-0.421875 -0.28125 -0.65625 -0.8125q-0.234375 -0.53125 -0.234375 -1.203125q0 -1.109375 0.453125 -1.703125q0.46875 -0.578125 1.375 -0.734375z" fill-rule="nonzero"></path></g></svg> - diff --git a/site/versions/master/docs/skylark/build-graph-aspects.png b/site/versions/master/docs/skylark/build-graph-aspects.png Binary files differdeleted file mode 100644 index fb8042a5b7..0000000000 --- a/site/versions/master/docs/skylark/build-graph-aspects.png +++ /dev/null diff --git a/site/versions/master/docs/skylark/build-graph.png b/site/versions/master/docs/skylark/build-graph.png Binary files differdeleted file mode 100644 index 2efd68ac59..0000000000 --- a/site/versions/master/docs/skylark/build-graph.png +++ /dev/null diff --git a/site/versions/master/docs/skylark/build-graph.svg b/site/versions/master/docs/skylark/build-graph.svg deleted file mode 100644 index cbad06dcb2..0000000000 --- a/site/versions/master/docs/skylark/build-graph.svg +++ /dev/null @@ -1,4 +0,0 @@ -<?xml version="1.0" standalone="yes"?> - -<svg version="1.1" viewBox="0.0 0.0 960.0 720.0" fill="none" stroke="none" stroke-linecap="square" stroke-miterlimit="10" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"><clipPath id="p.0"><path d="m0 0l960.0 0l0 720.0l-960.0 0l0 -720.0z" clip-rule="nonzero"></path></clipPath><g clip-path="url(#p.0)"><path fill="#000000" fill-opacity="0.0" d="m0 0l960.0 0l0 720.0l-960.0 0z" fill-rule="nonzero"></path><path fill="#cfe2f3" d="m105.04724 275.39633l0 0c0 -8.288635 10.5195465 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192383 23.496063 15.007874l0 0c0 8.288605 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976517 0 -23.496063 -6.719269 -23.496063 -15.007874z" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m105.04724 275.39633l0 0c0 -8.288635 10.5195465 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192383 23.496063 15.007874l0 0c0 8.288605 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976517 0 -23.496063 -6.719269 -23.496063 -15.007874z" fill-rule="nonzero"></path><path fill="#000000" d="m122.39964 282.3163l5.265625 -7.09375l-4.640625 -6.5l2.140625 0l2.46875 3.484375q0.78125 1.078125 1.09375 1.671875q0.453125 -0.75 1.078125 -1.546875l2.734375 -3.609375l1.96875 0l-4.78125 6.40625l5.140625 7.1875l-2.21875 0l-3.421875 -4.859375q-0.296875 -0.40625 -0.59375 -0.90625q-0.453125 0.75 -0.65625 1.03125l-3.40625 4.734375l-2.171875 0z" fill-rule="nonzero"></path><path fill="#cfe2f3" d="m79.0 141.00787l0 0c0 -8.28862 10.5195465 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192535 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976517 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m79.0 141.00787l0 0c0 -8.28862 10.5195465 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192535 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976517 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path fill="#000000" d="m101.57115 147.92787l0 -5.765625l-5.234375 -7.828125l2.1875 0l2.671875 4.09375q0.75 1.15625 1.390625 2.296875q0.609375 -1.0625 1.484375 -2.40625l2.625 -3.984375l2.109375 0l-5.4375 7.828125l0 5.765625l-1.796875 0z" fill-rule="nonzero"></path><path fill="#cfe2f3" d="m163.51181 141.00787l0 0c0 -8.28862 10.5195465 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192535 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976517 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m163.51181 141.00787l0 0c0 -8.28862 10.5195465 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192535 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976517 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path fill="#000000" d="m181.68489 147.92787l0 -1.671875l6.96875 -8.703125q0.75 -0.9375 1.421875 -1.625l-7.59375 0l0 -1.59375l9.734375 0l0 1.59375l-7.625 9.4375l-0.828125 0.953125l8.6875 0l0 1.609375l-10.765625 0z" fill-rule="nonzero"></path><path fill="#cfe2f3" d="m0 141.00787l0 0c0 -8.28862 10.519546 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192535 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976518 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m0 141.00787l0 0c0 -8.28862 10.519546 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192535 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976518 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path fill="#000000" d="m22.719948 147.92787l0 -12.0l-4.46875 0l0 -1.59375l10.765625 0l0 1.59375l-4.5 0l0 12.0l-1.796875 0z" fill-rule="nonzero"></path><path fill="#cfe2f3" d="m110.0 19.007874l0 0c0 -8.288619 10.5195465 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192545 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976517 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m110.0 19.007874l0 0c0 -8.288619 10.5195465 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192545 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976517 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path fill="#000000" d="m128.53548 25.927872l-3.6093674 -13.59375l1.84375 0l2.0624924 8.90625q0.34375 1.40625 0.578125 2.78125q0.515625 -2.171875 0.609375 -2.515625l2.59375 -9.171875l2.171875 0l1.953125 6.875q0.734375 2.5625 1.046875 4.8125q0.265625 -1.28125 0.6875 -2.953125l2.125 -8.734375l1.8125 0l-3.734375 13.59375l-1.734375 0l-2.859375 -10.359375q-0.359375 -1.296875 -0.421875 -1.59375q-0.21875 0.9375 -0.40625 1.59375l-2.890625 10.359375l-1.828125 0z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m128.5433 260.38846l-26.047241 -104.37796" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m128.5433 260.38846l-24.594505 -98.55649" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m105.551384 161.43205l-2.7013626 -4.0031433l-0.5038147 4.8029785z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m128.5433 260.38846l58.456696 -104.37796" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m128.5433 260.38846l55.52487 -99.143036" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m185.50931 162.05252l0.7763519 -4.7665253l-3.6585846 3.1523438z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m102.49606 126.0l30.992126 -92.0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m102.49606 126.0l29.076675 -86.313965" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m133.13803 40.21334l-0.11654663 -4.8279343l-3.0140533 3.7733269z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m187.00787 126.0l-53.51181 -92.0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m187.00787 126.0l-50.495102 -86.81353" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m137.94055 38.356003l-3.7094727 -3.0923195l0.85391235 4.75325z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m105.04724 275.39633l-81.543304 -119.37009" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m105.04724 275.39633l-78.158905 -114.41571" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m28.25222 160.04893l-3.9236736 -2.8155518l1.1959076 4.6789246z" fill-rule="evenodd"></path><path fill="#cfe2f3" d="m0 19.007874l0 0c0 -8.288619 10.519546 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192545 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976518 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m0 19.007874l0 0c0 -8.288619 10.519546 -15.007874 23.496063 -15.007874l0 0c12.976517 0 23.496063 6.7192545 23.496063 15.007874l0 0c0 8.28862 -10.5195465 15.007874 -23.496063 15.007874l0 0c-12.976518 0 -23.496063 -6.7192535 -23.496063 -15.007874z" fill-rule="nonzero"></path><path fill="#000000" d="m28.005974 24.474747q1.265625 0.859375 2.3125 1.265625l-0.53125 1.25q-1.453125 -0.53125 -2.921875 -1.671875q-1.5 0.84375 -3.328125 0.84375q-1.84375 0 -3.359375 -0.890625q-1.5 -0.890625 -2.3125 -2.5q-0.8125 -1.625 -0.8125 -3.640625q0 -2.015625 0.8125 -3.65625q0.828125 -1.65625 2.328125 -2.515625q1.515625 -0.875 3.375 -0.875q1.890625 0 3.390625 0.90625q1.515625 0.890625 2.3125 2.5q0.796875 1.609375 0.796875 3.625q0 1.6875 -0.515625 3.03125q-0.515625 1.328125 -1.546875 2.328125zm-3.953125 -2.296875q1.5625 0.421875 2.5625 1.296875q1.59375 -1.453125 1.59375 -4.359375q0 -1.65625 -0.5625 -2.875q-0.5625 -1.234375 -1.640625 -1.921875q-1.078125 -0.6875 -2.421875 -0.6875q-2.015625 0 -3.34375 1.390625q-1.328125 1.375 -1.328125 4.109375q0 2.65625 1.3125 4.078125q1.3125 1.40625 3.359375 1.40625q0.953125 0 1.8125 -0.359375q-0.84375 -0.546875 -1.78125 -0.78125l0.4375 -1.296875z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m23.496063 126.0l0 -92.0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m23.496063 126.0l0 -86.0" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m25.147795 40.0l-1.6517315 -4.5380974l-1.6517334 4.5380974z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m137.17401 181.13062l11.842514 46.771652l-29.102364 7.3700867l-11.842514 -46.771652z" fill-rule="nonzero"></path><path fill="#000000" d="m121.81724 198.86525l0.69675446 -0.17643738q-0.9483261 -0.30786133 -1.2091141 -1.3378601q-0.16491699 -0.6513214 0.05670166 -1.303833q0.22162628 -0.65249634 0.79623413 -1.1203766q0.57460785 -0.46788025 1.4228363 -0.6826935q0.83306885 -0.21096802 1.5685654 -0.10710144q0.75447845 0.11517334 1.240921 0.5722351q0.50159454 0.4532318 0.6741791 1.1348572q0.1265564 0.4998474 0.014221191 0.94737244q-0.112342834 0.44752502 -0.38420868 0.7742615l2.7415695 -0.69429016l0.23779297 0.93911743l-7.6340103 1.9332886l-0.22244263 -0.87854004zm2.0088654 -3.6517944q-1.0602798 0.2685089 -1.4792023 0.842041q-0.39993286 0.5848236 -0.24652863 1.1907043q0.15724182 0.6210327 0.76447296 0.91856384q0.60723877 0.29753113 1.6372223 0.03668213q1.1360092 -0.2876892 1.5549316 -0.86120605q0.42275238 -0.5583801 0.2578354 -1.2097015q-0.15724182 -0.62101746 -0.7796173 -0.9147186q-0.6034012 -0.28237915 -1.7091141 -0.0023651123zm1.2829971 9.141281l0.12427521 1.0000916q-0.90574646 -0.012390137 -1.5325394 -0.5145111q-0.62680054 -0.502121 -0.86841583 -1.4563751q-0.3068161 -1.2117615 0.25512695 -2.1116333q0.5619354 -0.8998718 1.9100037 -1.2412567q1.4086609 -0.35673523 2.3462524 0.16337585q0.9565811 0.53141785 1.2442245 1.66745q0.28379822 1.1208801 -0.29711914 2.00943q-0.56578064 0.88471985 -1.9441376 1.2337952q-0.075737 0.019180298 -0.24235535 0.06137085l-1.0431747 -4.11998q-0.8973007 0.275589 -1.2669449 0.8527527q-0.36580658 0.5923004 -0.18938446 1.2890625q0.13039398 0.5149994 0.4799347 0.813324q0.36468506 0.29447937 1.0242538 0.35310364zm0.7361374 -3.458435l0.78237915 3.089981q0.6814194 -0.23703003 0.95692444 -0.61305237q0.41508484 -0.5886688 0.23482513 -1.3005676q-0.16490936 -0.6513214 -0.71539307 -0.97935486q-0.5353317 -0.33184814 -1.2587357 -0.19700623zm-4.1481476 6.40654l7.649147 -1.9371338l0.21861267 0.86338806l-0.7118988 0.1802826q0.485672 0.19937134 0.7936096 0.52433777q0.30792236 0.3249817 0.44599915 0.8702698q0.17642212 0.6967621 -0.049041748 1.3341217q-0.22544861 0.63734436 -0.822876 1.0787811q-0.58229065 0.4375763 -1.3850708 0.6408844q-0.8482208 0.21481323 -1.6065292 0.084487915q-0.74316406 -0.13417053 -1.2562637 -0.632843q-0.5092621 -0.4835205 -0.6703415 -1.11969q-0.118888855 -0.46955872 -0.017860413 -0.8981018q0.10486603 -0.4133911 0.34643555 -0.73246765l-2.6961365 0.68278503l-0.23778534 -0.9391022zm5.06176 -0.3792572q-1.0602798 0.2685089 -1.4640503 0.8381958q-0.3886261 0.5658417 -0.23521423 1.1717224q0.15724182 0.6210327 0.7834549 0.9298706q0.645195 0.3201599 1.7660599 0.03630066q1.0451355 -0.26467896 1.4640503 -0.8381958q0.42276 -0.55836487 0.26934814 -1.1642456q-0.15341187 -0.60588074 -0.83273315 -0.93351746q-0.67549133 -0.31248474 -1.7509155 -0.040130615zm0.07243347 4.805786l0.38542175 0.88560486q-0.54125977 0.21766663 -0.7559891 0.64276123q-0.19573975 0.43641663 -0.03466797 1.072586q0.16491699 0.6513214 0.499115 0.88905334q0.33803558 0.2528839 0.701561 0.16081238q0.31808472 -0.08055115 0.43081665 -0.39923096q0.07131958 -0.2276001 0.07646179 -1.0348053q-0.0032958984 -1.0952148 0.074920654 -1.5502167q0.09718323 -0.4436798 0.37672424 -0.74012756q0.28337097 -0.28131104 0.69233704 -0.38487244q0.37867737 -0.09590149 0.72380066 -0.005996704q0.36026 0.08605957 0.6490326 0.33529663q0.2203064 0.16986084 0.4222107 0.52168274q0.2019043 0.35183716 0.30929565 0.77593994q0.16491699 0.6513214 0.10588074 1.1820679q-0.0552063 0.5458832 -0.3309021 0.85746765q-0.25672913 0.3229065 -0.763855 0.5480499l-0.35128784 -0.8781433q0.40493774 -0.18313599 0.5554352 -0.5436096q0.16947937 -0.34916687 0.031417847 -0.89445496q-0.16491699 -0.6513214 -0.4460144 -0.8702698q-0.28108215 -0.21894836 -0.5688782 -0.14605713q-0.1817627 0.046020508 -0.29122925 0.18656921q-0.120788574 0.1595459 -0.16545105 0.42874146q-0.010925293 0.1478424 -0.031417847 0.8944702q-0.0082092285 1.0497589 -0.07510376 1.4857788q-0.06690979 0.4360199 -0.3426056 0.74760437q-0.26055908 0.30776978 -0.7452545 0.43051147q-0.4695511 0.11891174 -0.9475479 -0.0501709q-0.47799683 -0.16906738 -0.8356018 -0.6265259q-0.35759735 -0.4574585 -0.5225067 -1.1087799q-0.27230072 -1.0754395 0.021217346 -1.7622681q0.3125 -0.67552185 1.1526642 -1.049469z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m136.62865 226.32948l18.960632 -44.37796l28.283463 12.094498l-18.960632 44.377945z" fill-rule="nonzero"></path><path fill="#000000" d="m159.5925 221.55168l-0.66085815 -0.28259277q0.5670624 0.8202667 0.14961243 1.7973328q-0.26397705 0.6178436 -0.83592224 1.0020294q-0.57192993 0.38420105 -1.3124847 0.4073944q-0.74053955 0.023208618 -1.5450745 -0.32081604q-0.79016113 -0.33789062 -1.3117828 -0.86683655q-0.52986145 -0.54945374 -0.6392822 -1.2080078q-0.123794556 -0.6647186 0.15245056 -1.3112946q0.20259094 -0.47416687 0.56333923 -0.761734q0.3607483 -0.28756714 0.7750397 -0.38230896l-2.600357 -1.111969l0.38061523 -0.8908386l7.2407684 3.0962677l-0.35606384 0.833374zm-3.8118286 1.6837616q1.005661 0.43003845 1.6865234 0.22836304q0.67263794 -0.22216797 0.91819763 -0.7969055q0.25169373 -0.5891113 -0.05050659 -1.1941681q-0.30220032 -0.6050415 -1.2791443 -1.0227966q-1.0774841 -0.4607544 -1.7583466 -0.25909424q-0.6747284 0.18730164 -0.93870544 0.80514526q-0.25169373 0.5891113 0.06488037 1.2003021q0.3083496 0.590683 1.3571014 1.039154zm4.524872 -8.04538l0.50782776 -0.8704376q0.71243286 0.55955505 0.9061127 1.3391113q0.19366455 0.7795563 -0.19309998 1.6847687q-0.49111938 1.1494751 -1.4836121 1.5237732q-0.9924927 0.3742981 -2.2711182 -0.1724701q-1.3361053 -0.57133484 -1.7658997 -1.5538177q-0.4380188 -1.003006 0.022399902 -2.0806427q0.45428467 -1.0632629 1.4550171 -1.4170532q0.9863434 -0.35992432 2.2937164 0.1991272q0.07182312 0.030715942 0.2298584 0.09829712l-1.6697998 3.9082336q0.88041687 0.32548523 1.5243073 0.091033936q0.6500397 -0.24884033 0.9324341 -0.90979004q0.20872498 -0.4885254 0.111831665 -0.9378052q-0.11126709 -0.45542908 -0.5999756 -0.9023285zm-2.6828766 2.3024597l1.2523499 -2.9311676q-0.6854248 -0.22512817 -1.1324921 -0.09341431q-0.68699646 0.21603394 -0.9755249 0.8913574q-0.26397705 0.6178436 -0.025390625 1.212677q0.22424316 0.5887146 0.88105774 0.9205475zm7.183197 -2.575241l-7.255127 -3.102417l0.34991455 -0.8190155l0.67523193 0.28874207q-0.26512146 -0.4532318 -0.31277466 -0.89845276q-0.0476532 -0.44522095 0.17333984 -0.9624939q0.2823944 -0.6609497 0.84820557 -1.030777q0.5657959 -0.369812 1.3084259 -0.35813904q0.7282715 0.0055236816 1.4897003 0.33113098q0.8045349 0.34402466 1.3282471 0.9078522q0.50935364 0.5576782 0.61473083 1.2654877q0.11151123 0.6934509 -0.14631653 1.2969208q-0.19030762 0.44543457 -0.5305481 0.7247772q-0.33410645 0.26498413 -0.7196655 0.37200928l2.557251 1.0935211l-0.38061523 0.8908539zm-4.253525 -2.770523q1.005661 0.43003845 1.6721497 0.22221375q0.6521301 -0.21394348 0.8976898 -0.78868103q0.25170898 -0.5891113 -0.05873108 -1.2146759q-0.31866455 -0.6460724 -1.3817902 -1.1006775q-0.9913025 -0.42390442 -1.6721497 -0.222229q-0.6747284 0.18728638 -0.9202881 0.7620392q-0.24555969 0.57473755 0.095687866 1.247467q0.34739685 0.6583557 1.3674316 1.0945435zm2.8574066 -3.8642578l0.23080444 -0.937912q0.56225586 0.1554718 0.9907837 -0.052139282q0.42030334 -0.2281189 0.67814636 -0.831604q0.26397705 -0.6178436 0.14251709 -1.0096436q-0.11531067 -0.4061737 -0.46011353 -0.5536194q-0.30169678 -0.12901306 -0.5845947 0.055892944q-0.19473267 0.13764954 -0.68844604 0.7762146q-0.6616974 0.8726196 -0.9998474 1.1868439q-0.3463745 0.29371643 -0.74838257 0.35972595q-0.39587402 0.051635742 -0.7837677 -0.11424255q-0.35917664 -0.15357971 -0.5789795 -0.43450928q-0.23416138 -0.2870636 -0.31251526 -0.66044617q-0.07208252 -0.26872253 -0.019180298 -0.6709442q0.05290222 -0.40222168 0.22480774 -0.8045349q0.2639618 -0.6178436 0.6328125 -1.0039215q0.37498474 -0.4004364 0.7831421 -0.48080444q0.3999176 -0.10089111 0.93959045 0.027923584l-0.25341797 0.9112549q-0.43295288 -0.10017395 -0.77124023 0.095047q-0.34649658 0.17471313 -0.5675049 0.6919708q-0.26397705 0.6178436 -0.17333984 0.96247864q0.09062195 0.34465027 0.36358643 0.46138q0.17240906 0.07371521 0.3446808 0.028427124q0.19277954 -0.053512573 0.39157104 -0.24040222q0.098342896 -0.11088562 0.5675049 -0.6919861q0.6432648 -0.82951355 0.960907 -1.1355133q0.31765747 -0.30599976 0.72579956 -0.3863678q0.39378357 -0.086517334 0.8535156 0.110061646q0.44535828 0.19044495 0.72276306 0.6149597q0.27738953 0.4244995 0.28416443 1.005188q0.0067749023 0.5806732 -0.25720215 1.1985168q-0.4358673 1.0201569 -1.0857849 1.3880005q-0.65812683 0.34733582 -1.5527802 0.13470459z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m81.12184 104.50765l17.41732 -44.976383l28.692917 11.118114l-17.41732 44.97637z" fill-rule="nonzero"></path><path fill="#000000" d="m103.909035 98.94311l-0.6701889 -0.25969696q0.59490204 0.80026245 0.21121216 1.7910614q-0.24263 0.6265335 -0.80107117 1.030159q-0.55844116 0.40361786 -1.2977829 0.45227814q-0.7393341 0.04865265 -1.5552292 -0.2674942q-0.8013153 -0.3105011 -1.340805 -0.8211746q-0.54842377 -0.5308838 -0.6803894 -1.1852722q-0.14653015 -0.6600342 0.10738373 -1.315712q0.186203 -0.48082733 0.5368805 -0.7806244q0.3506775 -0.29979706 0.76148224 -0.40872955l-2.6370697 -1.0218277l0.34983826 -0.90338135l7.34301 2.8453217l-0.3272705 0.8450928zm-3.7519302 1.8137894q1.0198593 0.39518738 1.6934204 0.17022705q0.66464233 -0.2451706 0.8903427 -0.8279953q0.23134613 -0.59739685 -0.09146118 -1.1916733q-0.32279968 -0.5942764 -1.3135223 -0.9781647q-1.0927124 -0.42341614 -1.7662735 -0.19845581q-0.667923 0.21038055 -0.910553 0.8369217q-0.23134613 0.5973892 0.106025696 1.197319q0.32844543 0.5797043 1.3920212 0.9918213zm4.246277 -8.195946l0.47768402 -0.887352q0.73124695 0.5347061 0.951561 1.307106q0.2203064 0.77240753 -0.13516998 1.6903534q-0.4514084 1.1656494 -1.4305115 1.5738373q-0.9791031 0.4081955 -2.2757797 -0.09425354q-1.3549652 -0.52503204 -1.8182373 -1.4921188q-0.4721985 -0.9873123 -0.04901123 -2.080101q0.41754913 -1.0782242 1.4055786 -1.4662018q0.97345734 -0.39362335 2.2992783 0.12011719q0.07285309 0.02822876 0.23311615 0.09033203l-1.5347672 3.9631958q0.8910904 0.29502106 1.5265884 0.03855896q0.6411438 -0.27103424 0.90070343 -0.9412842q0.19184113 -0.49539948 0.079582214 -0.94107056q-0.12683105 -0.4513092 -0.63061523 -0.8811188zm-2.6023788 2.3932877l1.1510773 -2.9724045q-0.6927643 -0.20140839 -1.1350708 -0.05441284q-0.67920685 0.23952484 -0.9444046 0.9243469q-0.24263 0.6265335 0.01625061 1.2127991q0.24430847 0.5806198 0.9121475 0.8896713zm7.0908585 -2.820671l-7.3575745 -2.8509598l0.32162476 -0.83052826l0.68476105 0.26533508q-0.2805252 -0.44384003 -0.34342957 -0.88713837q-0.06291199 -0.44330597 0.14022064 -0.9678421q0.259552 -0.67024994 0.81235504 -1.0593033q0.5527954 -0.38904572 1.2954178 -0.40291595q0.72805023 -0.019515991 1.5002365 0.2796936q0.81588745 0.31614685 1.3586655 0.8616028q0.5282059 0.5398102 0.657814 1.2435608q0.13524628 0.68917084 -0.101737976 1.3011398q-0.17491913 0.45168304 -0.50538635 0.74256134q-0.32482147 0.27629852 -0.70648956 0.39652252l2.593361 1.0048904l-0.34983826 0.90338135zm-4.346245 -2.6225052q1.019867 0.39517975 1.6788559 0.1645813q0.64443207 -0.2362442 0.87013245 -0.8190689q0.2313385 -0.59739685 -0.10038757 -1.2118912q-0.34065247 -0.6347122 -1.4187927 -1.052475q-1.0052948 -0.389534 -1.6788559 -0.1645813q-0.667923 0.21038818 -0.893631 0.7932129q-0.22570038 0.5828247 0.13845062 1.243393q0.36979675 0.6460037 1.4042282 1.0468292zm2.7232208 -3.9600906l0.19850159 -0.9452667q0.56728363 0.1360321 0.9884491 -0.08618164q0.41223907 -0.24243164 0.64923096 -0.854393q0.24262238 -0.62654114 0.107795715 -1.0139236q-0.12918854 -0.40195465 -0.47885895 -0.53744507q-0.30595398 -0.11856079 -0.5823517 0.07596588q-0.18991089 0.14425659 -0.661438 0.7993927q-0.6313782 0.8948288 -0.9585571 1.2204895q-0.33611298 0.3054428 -0.73563385 0.38523102q-0.39388275 0.065223694 -0.78725433 -0.08720398q-0.36424255 -0.14113617 -0.59355927 -0.41432953q-0.24388885 -0.27882385 -0.33501434 -0.64927673q-0.08126831 -0.2660904 -0.04219055 -0.66986847q0.03907776 -0.4037857 0.19706726 -0.81175995q0.24263 -0.62654114 0.59802246 -1.0250549q0.3610382 -0.4130783 0.76620483 -0.50743866q0.39624023 -0.11457825 0.9400253 -0.00440979l-0.2219925 0.9194031q-0.43615723 -0.08522034 -0.76755524 0.12150574q-0.34031677 0.18651581 -0.5434494 0.7110596q-0.24263 0.6265335 -0.14022064 0.9678421q0.10240173 0.3413086 0.37922668 0.44857025q0.1748352 0.06774902 0.34545135 0.016563416q0.19084167 -0.060112 0.38310242 -0.25372314q0.09449768 -0.11419678 0.54345703 -0.7110596q0.6144409 -0.85111237 0.9214096 -1.1678467q0.30697632 -0.3167343 0.71214294 -0.41109467q0.39059448 -0.1000061 0.85681915 0.08065033q0.45165253 0.17501068 0.7434616 0.5897064q0.29180908 0.41469574 0.31850433 0.9947815q0.026695251 0.58008575 -0.21593475 1.2066193q-0.4006195 1.0345078 -1.0375519 1.4244766q-0.64585876 0.36975098 -1.5473099 0.1880188z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m171.07939 43.463318l21.732285 43.08661l-26.803146 13.511818l-21.732285 -43.086617z" fill-rule="nonzero"></path><path fill="#000000" d="m159.94344 64.10798l0.6417999 -0.32354355q-0.9926758 -0.094516754 -1.4711609 -1.0431747q-0.30256653 -0.59988785 -0.22807312 -1.284874q0.07450867 -0.6849899 0.5337219 -1.2664528q0.45922852 -0.58145905 1.2405548 -0.9753418q0.76737976 -0.38684464 1.5079498 -0.4452057q0.7615509 -0.051445007 1.3357697 0.2890129q0.58818054 0.3334236 0.90483093 0.96121216q0.23220825 0.46038055 0.21983337 0.92157364q-0.012390137 0.46119308 -0.20675659 0.83914566l2.5253906 -1.2730789l0.43626404 0.8649521l-7.032013 3.5449257l-0.40811157 -0.8091507zm1.1671906 -4.0005302q-0.9766693 0.49235153 -1.2609406 1.1431007q-0.26327515 0.65766907 0.018188477 1.215702q0.28849792 0.57198715 0.94595337 0.7305031q0.65745544 0.15851593 1.6062164 -0.319767q1.0464325 -0.5275192 1.3307037 -1.1782722q0.29130554 -0.63679886 -0.011276245 -1.2366867q-0.28849792 -0.57198334 -0.9598999 -0.72346497q-0.65042114 -0.14456558 -1.6689453 0.36888504zm3.239624 8.643436l0.33872986 0.94911957q-0.8868866 0.18462372 -1.6079102 -0.16932678q-0.72102356 -0.35394287 -1.1643372 -1.2328491q-0.56292725 -1.116066 -0.2099762 -2.1164017q0.3529358 -1.0003357 1.594696 -1.6263275q1.2975769 -0.6541214 2.3259277 -0.35011292q1.0493164 0.31093597 1.5770721 1.3572464q0.5207062 1.0323639 0.14677429 2.0257797q-0.35998535 0.98638916 -1.6296539 1.626442q-0.06976318 0.03517151 -0.22323608 0.1125412l-1.9139557 -3.7946396q-0.81604004 0.46387482 -1.0514221 1.1074753q-0.22833252 0.657547 0.09535217 1.2992859q0.23924255 0.47433472 0.64530945 0.6895828q0.4200287 0.2082138 1.0766296 0.12218475zm-0.033187866 -3.5353851l1.4354706 2.8459778q0.6136627 -0.37934875 0.8008728 -0.8061905q0.27722168 -0.66469574 -0.053497314 -1.3203888q-0.30256653 -0.59989166 -0.9112549 -0.80049133q-0.59472656 -0.20763397 -1.2715912 0.081092834zm-2.656723 7.153839l7.0459595 -3.5519638l0.40109253 0.79520416l-0.6557617 0.33057404q0.5174408 0.08911133 0.88868713 0.3394165q0.37124634 0.25029755 0.62457275 0.75253296q0.3236847 0.6417389 0.24214172 1.3127747q-0.08154297 0.67103577 -0.5687866 1.2316284q-0.47329712 0.55355835 -1.2127686 0.9263382q-0.78134155 0.39388275 -1.5499268 0.4313736q-0.7546387 0.030464172 -1.3639221 -0.3448105q-0.60224915 -0.36132812 -0.8977814 -0.9472656q-0.21813965 -0.43247986 -0.212677 -0.8726883q0.012496948 -0.42625427 0.17897034 -0.79013824l-2.4835358 1.251976l-0.43626404 -0.8649521zm4.8588104 -1.4694977q-0.9766693 0.49234772 -1.2469788 1.1360626q-0.25636292 0.63668823 0.025100708 1.1947174q0.28849792 0.57199097 0.9669342 0.7374191q0.6994324 0.17235565 1.7319183 -0.34812927q0.9627075 -0.48532104 1.2469788 -1.1360703q0.2913208 -0.6368027 0.009841919 -1.1948318q-0.28146362 -0.5580368 -1.0158386 -0.7302704q-0.72732544 -0.15828705 -1.7179565 0.3411026zm1.1154175 4.67482l0.5687561 0.78066254q-0.48104858 0.33000183 -0.5982666 0.79154205q-0.096206665 0.46846008 0.19932556 1.0543976q0.3025818 0.59988403 0.6804962 0.75933075q0.384964 0.17339325 0.7198181 0.0045928955q0.29299927 -0.14770508 0.33377075 -0.48322296q0.020141602 -0.23763275 -0.15029907 -1.0266113q-0.24130249 -1.0682297 -0.26387024 -1.5293045q-0.0015716553 -0.4541626 0.20687866 -0.8042145q0.21546936 -0.33609772 0.5921936 -0.5260086q0.34880066 -0.17583466 0.70526123 -0.16304779q0.37039185 0.0057525635 0.7064667 0.18630219q0.25198364 0.11794281 0.52557373 0.41748047q0.27357483 0.29953766 0.4705963 0.690155q0.3025818 0.59989166 0.36032104 1.130722q0.06477356 0.5447769 -0.1366272 0.90878296q-0.18040466 0.37091827 -0.6265259 0.70079803l-0.5338135 -0.7807846q0.355484 -0.26669312 0.42404175 -0.6512146q0.089538574 -0.37760162 -0.16378784 -0.87983704q-0.30256653 -0.59988403 -0.6245575 -0.7525253q-0.32199097 -0.15264893 -0.58709717 -0.019012451q-0.16741943 0.08440399 -0.2437439 0.24536133q-0.083221436 0.1819458 -0.06829834 0.45439148q0.021469116 0.14665985 0.16377258 0.87983704q0.22018433 1.0263748 0.2496643 1.4664688q0.02947998 0.440094 -0.17193604 0.8040924q-0.18743896 0.35697174 -0.6339264 0.5820465q-0.43252563 0.21804047 -0.9358978 0.15682983q-0.5033722 -0.061210632 -0.9519043 -0.43003845q-0.4485321 -0.3688202 -0.75109863 -0.96871185q-0.49960327 -0.99050903 -0.36238098 -1.724617q0.15821838 -0.7271881 0.8970947 -1.274643z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m62.48595 164.64017l52.724415 69.291336l-23.874016 18.173233l-52.724415 -69.29135z" fill-rule="nonzero"></path><path fill="#000000" d="m53.061855 184.02805l4.53796 -3.4543457l0.52038574 0.6838989l-0.68379974 0.5205231q0.6930313 -0.09553528 1.0125313 0.014709473q0.31950378 0.11026001 0.5181961 0.37138367q0.30277252 0.39790344 0.35688782 0.98509216l-0.9073601 0.2783203q-0.055992126 -0.4090271 -0.27360916 -0.6950226q-0.18923187 -0.24868774 -0.48981094 -0.33407593q-0.30057907 -0.08538818 -0.64033127 0.03578186q-0.50489426 0.18797302 -0.9897728 0.5570679l-2.3746567 1.8076172l-0.58662033 -0.7709503zm4.4196167 5.8083496l0.67136765 -0.5110626q-1.1776772 0.052078247 -1.8683739 -0.85565186q-0.30277252 -0.39790344 -0.42796326 -0.8720703q-0.10329819 -0.47120667 -0.01197052 -0.8156433q0.113220215 -0.34146118 0.40159607 -0.6591644q0.1859436 -0.22007751 0.68325424 -0.5986481l2.809803 -2.138855l0.58662033 0.77093506l-2.5114174 1.9117279q-0.60920715 0.46374512 -0.78271484 0.6743622q-0.24161911 0.30174255 -0.24536896 0.6580658q0.005710602 0.36875916 0.2706375 0.71691895q0.2649231 0.34817505 0.6660614 0.5140991q0.42303085 0.1689148 0.8160324 0.06611633q0.40543365 -0.11224365 0.9773407 -0.54759216l2.436821 -1.85495l0.58662033 0.7709503l-4.53796 3.454361l-0.52038574 -0.6838989zm1.3179626 1.7320862l4.537956 -3.454361l0.52985 0.69633484l-0.64650345 0.49212646q1.1244316 -0.07044983 1.8435097 0.87457275q0.31223297 0.41033936 0.42796326 0.8720856q0.1281662 0.4522705 0.0025100708 0.80319214q-0.103759766 0.3538971 -0.3702469 0.6745758q-0.19540405 0.20765686 -0.730011 0.61460876l-2.7849388 2.119934l-0.5866165 -0.7709503l2.7600708 -2.100998q0.47244644 -0.3596344 0.6300087 -0.6170349q0.16999054 -0.26686096 0.12697601 -0.60720825q-0.021110535 -0.33740234 -0.25765228 -0.6482544q-0.3690033 -0.48495483 -0.9542084 -0.608963q-0.5852051 -0.12399292 -1.4679298 0.5479431l-2.474121 1.8833313l-0.5866165 -0.77093506zm5.5593147 5.886963l-0.5956726 0.61053467q-0.3205986 -0.26651 -0.5098305 -0.515213q-0.32169342 -0.42277527 -0.36470413 -0.7631378q-0.033546448 -0.32792664 0.10211563 -0.58828735q0.14512634 -0.2479248 0.841362 -0.7779083l2.6108818 -1.987442l-0.43523407 -0.57199097l0.59677124 -0.4542694l0.43523407 0.57199097l1.1189499 -0.85176086l1.0495987 0.39888l-1.5913925 1.2113953l0.59607697 0.783371l-0.59677124 0.4542694l-0.59607697 -0.783371l-2.660614 2.025299q-0.32324982 0.24606323 -0.39432907 0.35906982q-0.04918289 0.115982056 -0.04511261 0.25035095q0.025959015 0.1373291 0.14896011 0.2989807q0.1040802 0.13677979 0.2897873 0.3292389zm5.215065 -2.8999329l0.8827286 -0.67193604l0.5866165 0.77093506l-0.88272095 0.6719513l-0.58662415 -0.7709503zm-5.3833847 4.0979156l4.537964 -3.454361l0.5866165 0.7709503l-4.537956 3.4543457l-0.58662415 -0.77093506zm1.4241486 1.8716278l4.537956 -3.454361l0.5298462 0.6963501l-0.6340637 0.48265076q0.49652863 -0.044128418 0.9603729 0.15261841q0.47331238 0.20916748 0.8139343 0.6568146q0.3879242 0.50982666 0.42256927 0.9940033q0.047073364 0.47473145 -0.23426056 0.90489197q1.2025452 -0.071014404 1.8553925 0.78697205q0.52038574 0.6839142 0.42179108 1.3284302q-0.098594666 0.644516 -0.86943054 1.2312927l-3.1206207 2.3754578l-0.57715607 -0.7585144l2.8595352 -2.176712q0.4600067 -0.35017395 0.6021652 -0.5762024q0.15458679 -0.23548889 0.12753296 -0.52908325q-0.027061462 -0.29359436 -0.22575378 -0.554718q-0.3690033 -0.48495483 -0.9382553 -0.5621948q-0.55979156 -0.06478882 -1.2560272 0.4651947l-2.6357422 2.006363l-0.58662415 -0.7709503l2.9465637 -2.2429657q0.50974274 -0.38801575 0.6289139 -0.7732849q0.11916351 -0.3852539 -0.2025299 -0.8080292q-0.2460022 -0.32330322 -0.63768005 -0.47680664q-0.3822174 -0.1410675 -0.81251526 -0.009887695q-0.41786957 0.12171936 -1.039505 0.5949249l-2.3497925 1.7886963l-0.5866165 -0.7709503zm9.207695 9.056122l0.5060806 0.87153625q-0.83815765 0.34346008 -1.611496 0.12702942q-0.7733383 -0.21644592 -1.3694229 -0.9998169q-0.7569275 -0.99476624 -0.59241486 -2.042923q0.16451263 -1.048172 1.2710266 -1.8904572q1.1562424 -0.8801575 2.22258 -0.76893616q1.0882263 0.11419678 1.7978439 1.0467987q0.70015717 0.92015076 0.5137558 1.9653473q-0.17397308 1.0357208 -1.3053589 1.8969574q-0.062156677 0.047317505 -0.1989212 0.15141296l-2.573555 -3.3822021q-0.7175751 0.6051483 -0.8315811 1.2810211q-0.104537964 0.688324 0.3306961 1.260315q0.32169342 0.42277527 0.76013184 0.560318q0.4508667 0.12808228 1.0806351 -0.07640076zm-0.67742157 -3.4706116l1.9301605 2.5366516q0.53406525 -0.4850769 0.64024353 -0.9390106q0.15129852 -0.7042694 -0.293396 -1.2886963q-0.4068451 -0.5346985 -1.0417786 -0.62083435q-0.6225052 -0.09561157 -1.2352295 0.31188965zm-1.8461914 6.8112946l0.55947113 -0.4258728l3.8792496 5.098175l-0.55947113 0.4258728l-3.8792496 -5.098175zm8.111038 7.0471954l0.57190704 -0.43533325q-0.9930649 0.088272095 -1.6364517 -0.75727844q-0.40685272 -0.5346832 -0.45854187 -1.2219086q-0.051696777 -0.6872101 0.2936859 -1.3428497q0.34537506 -0.65563965 1.0416107 -1.1856232q0.68379974 -0.5205231 1.4011459 -0.7131195q0.7392502 -0.18962097 1.3658218 0.04034424q0.63899994 0.22052002 1.0647736 0.7800751q0.31223297 0.41033936 0.38417053 0.86613464q0.07194519 0.4557953 -0.050186157 0.8629608l2.250328 -1.7129822l0.5866165 0.77093506l-6.2661133 4.7698517l-0.5487671 -0.72120667zm0.4177475 -4.1471863q-0.87029266 0.6624756 -1.0310516 1.3543243q-0.13887024 0.69480896 0.2395935 1.1921997q0.38793182 0.5098114 1.0631332 0.54566956q0.67520905 0.035858154 1.5206375 -0.60769653q0.932457 -0.7097931 1.093216 -1.4016418q0.17021942 -0.67941284 -0.23662567 -1.2140961q-0.3879242 -0.5098114 -1.0755692 -0.5362091q-0.66574097 -0.023422241 -1.5733337 0.66744995zm4.761055 7.908478l0.5060806 0.871521q-0.83815765 0.34346008 -1.611496 0.12702942q-0.77334595 -0.21643066 -1.3694229 -0.9998169q-0.7569275 -0.99476624 -0.59241486 -2.042923q0.16451263 -1.0481567 1.2710266 -1.8904572q1.1562424 -0.8801422 2.22258 -0.7689209q1.0882263 0.11419678 1.7978439 1.0467834q0.70015717 0.920166 0.5137558 1.9653625q-0.17397308 1.0357208 -1.3053589 1.8969421q-0.062164307 0.047317505 -0.1989212 0.15142822l-2.573555 -3.3822174q-0.7175751 0.6051483 -0.8315811 1.2810364q-0.104537964 0.688324 0.3306961 1.260315q0.32169342 0.42277527 0.76013184 0.560318q0.4508667 0.12806702 1.0806351 -0.07640076zm-0.67742157 -3.4706268l1.9301605 2.5366669q0.53406525 -0.48509216 0.64024353 -0.9390106q0.15129852 -0.70428467 -0.293396 -1.2887115q-0.4068451 -0.5346832 -1.0417862 -0.62083435q-0.62249756 -0.09561157 -1.2352219 0.31188965zm-1.3068848 7.5200806l6.278549 -4.779312l0.53930664 0.70877075l-0.58434296 0.4447937q0.5249176 -0.0068359375 0.93551636 0.1715393q0.41059875 0.17837524 0.7512207 0.62602234q0.43523407 0.57199097 0.47746277 1.2467651q0.0422287 0.67477417 -0.33450317 1.3150177q-0.3643036 0.6307678 -1.0232391 1.13237q-0.69623566 0.5299835 -1.4449387 0.7071686q-0.7362747 0.16772461 -1.4036636 -0.09008789q-0.65792084 -0.24537659 -1.0553131 -0.76763916q-0.29330444 -0.38546753 -0.36821747 -0.81936646q-0.065452576 -0.421463 0.031814575 -0.8096924l-2.2130356 1.6845856l-0.5866165 -0.77093506zm4.5083313 -2.332138q-0.87029266 0.6624756 -1.0186157 1.3448486q-0.13589478 0.6729126 0.24256897 1.1703033q0.3879242 0.5098114 1.085022 0.548645q0.71899414 0.041793823 1.6390152 -0.6585388q0.8578644 -0.65301514 1.0186234 -1.3448639q0.17022705 -0.6793976 -0.2082367 -1.1767883q-0.37846375 -0.4973755 -1.1317902 -0.5326843q-0.74385834 -0.022872925 -1.6265869 0.64907837zm1.949089 4.3935547l0.7014847 0.6638794q-0.41270447 0.41233826 -0.44374084 0.88760376q-0.009140015 0.47825623 0.38824463 1.0005035q0.4068451 0.5346832 0.8074341 0.62249756q0.41004944 0.100234985 0.70843506 -0.12690735q0.26109314 -0.19874573 0.23997498 -0.5361328q-0.023536682 -0.23736572 -0.33499146 -0.9821167q-0.43202972 -1.0064392 -0.53829956 -1.4557495q-0.084373474 -0.44631958 0.056678772 -0.8286133q0.15052032 -0.3698578 0.48620605 -0.6253967q0.31082153 -0.23658752 0.66355133 -0.28909302q0.3651657 -0.061965942 0.7284546 0.054229736q0.26922607 0.06997681 0.5927963 0.3146057q0.32357025 0.24461365 0.58849335 0.59277344q0.4068451 0.5346985 0.5604248 1.0461731q0.16304016 0.5239105 0.031440735 0.9186249q-0.109703064 0.39770508 -0.48807526 0.8035431l-0.66716003 -0.6703491q0.30081177 -0.32717896 0.2980652 -0.7178192q0.01915741 -0.38768005 -0.3214569 -0.83532715q-0.40685272 -0.5346832 -0.7512207 -0.62602234q-0.34436798 -0.09132385 -0.5805893 0.08850098q-0.14919281 0.11355591 -0.19485474 0.28578186q-0.04863739 0.19410706 0.015724182 0.45932007q0.047851562 0.14030457 0.3214569 0.83532715q0.40364838 0.96913147 0.5128937 1.3965302q0.10923767 0.42741394 -0.022361755 0.8221283q-0.11916351 0.38526917 -0.51701355 0.68811035q-0.38541412 0.29338074 -0.8914032 0.3250885q-0.5059967 0.031707764 -1.014183 -0.24909973q-0.50818634 -0.28082275 -0.91503143 -0.815506q-0.6717758 -0.8828583 -0.6707611 -1.6298218q0.022903442 -0.7440033 0.64938354 -1.4172668z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m53.480316 55.42551l0 49.165356l-29.984253 0l0 -49.165356z" fill-rule="nonzero"></path><path fill="#000000" d="m34.240314 68.84738l0.71875 0q-0.84375 -0.53125 -0.84375 -1.59375q0 -0.671875 0.375 -1.25q0.375 -0.578125 1.046875 -0.890625q0.671875 -0.3125 1.546875 -0.3125q0.859375 0 1.546875 0.28125q0.703125 0.296875 1.0625 0.859375q0.375 0.5625 0.375 1.265625q0 0.515625 -0.21875 0.921875q-0.21875 0.40625 -0.5625 0.65625l2.828125 0l0 0.96875l-7.875 0l0 -0.90625zm2.84375 -3.046875q-1.09375 0 -1.640625 0.453125q-0.53125 0.46875 -0.53125 1.09375q0 0.640625 0.515625 1.078125q0.515625 0.4375 1.578125 0.4375q1.171875 0 1.71875 -0.453125q0.546875 -0.4375 0.546875 -1.109375q0 -0.640625 -0.53125 -1.078125q-0.515625 -0.421875 -1.65625 -0.421875zm-1.0 9.176498l-0.125 1.0q-0.875 -0.234375 -1.359375 -0.875q-0.484375 -0.640625 -0.484375 -1.625q0 -1.25 0.765625 -1.984375q0.765625 -0.734375 2.15625 -0.734375q1.453125 0 2.234375 0.734375q0.796875 0.75 0.796875 1.921875q0 1.15625 -0.78125 1.875q-0.765625 0.71875 -2.1875 0.71875q-0.078125 0 -0.25 0l0 -4.25q-0.9375 0.046875 -1.4375 0.515625q-0.5 0.484375 -0.5 1.203125q0 0.53125 0.265625 0.90625q0.28125 0.375 0.90625 0.59375zm1.5625 -3.171875l0 3.1875q0.71875 -0.0625 1.078125 -0.359375q0.546875 -0.46875 0.546875 -1.203125q0 -0.671875 -0.453125 -1.125q-0.4375 -0.453125 -1.171875 -0.5zm-5.59375 5.1921234l7.890625 0l0 0.890625l-0.734375 0q0.421875 0.3125 0.640625 0.703125q0.21875 0.390625 0.21875 0.953125q0 0.71875 -0.375 1.28125q-0.375 0.5625 -1.0625 0.84375q-0.671875 0.28125 -1.5 0.28125q-0.875 0 -1.578125 -0.3125q-0.6875 -0.3125 -1.0625 -0.921875q-0.375 -0.59375 -0.375 -1.25q0 -0.484375 0.203125 -0.875q0.203125 -0.375 0.515625 -0.625l-2.78125 0l0 -0.96875zm5.0 0.875q-1.09375 0 -1.625 0.453125q-0.515625 0.453125 -0.515625 1.078125q0 0.640625 0.53125 1.09375q0.546875 0.46875 1.703125 0.46875q1.078125 0 1.625 -0.453125q0.546875 -0.4375 0.546875 -1.0625q0 -0.625 -0.578125 -1.109375q-0.578125 -0.46875 -1.6875 -0.46875zm-1.109375 4.6764984l0.15625 0.953125q-0.578125 0.078125 -0.890625 0.4375q-0.296875 0.375 -0.296875 1.03125q0 0.671875 0.265625 0.984375q0.265625 0.328125 0.640625 0.328125q0.328125 0 0.515625 -0.28125q0.125 -0.203125 0.328125 -0.984375q0.265625 -1.0625 0.453125 -1.484375q0.203125 -0.40625 0.546875 -0.625q0.34375 -0.203125 0.765625 -0.203125q0.390625 0 0.703125 0.171875q0.328125 0.171875 0.546875 0.484375q0.171875 0.21875 0.28125 0.609375q0.109375 0.390625 0.109375 0.828125q0 0.671875 -0.1875 1.171875q-0.1875 0.515625 -0.53125 0.75q-0.328125 0.25 -0.875 0.34375l-0.125 -0.9375q0.4375 -0.078125 0.671875 -0.390625q0.25 -0.296875 0.25 -0.859375q0 -0.671875 -0.21875 -0.953125q-0.21875 -0.28125 -0.515625 -0.28125q-0.1875 0 -0.328125 0.109375q-0.15625 0.125 -0.265625 0.375q-0.046875 0.140625 -0.25 0.859375q-0.265625 1.015625 -0.4375 1.421875q-0.171875 0.40625 -0.515625 0.640625q-0.328125 0.234375 -0.828125 0.234375q-0.484375 0 -0.90625 -0.28125q-0.421875 -0.28125 -0.65625 -0.8125q-0.234375 -0.53125 -0.234375 -1.203125q0 -1.109375 0.453125 -1.703125q0.46875 -0.578125 1.375 -0.734375z" fill-rule="nonzero"></path></g></svg> - diff --git a/site/versions/master/docs/skylark/build-style.md b/site/versions/master/docs/skylark/build-style.md deleted file mode 100644 index d7787593aa..0000000000 --- a/site/versions/master/docs/skylark/build-style.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -layout: documentation -title: Style guide for BUILD files ---- - -# BUILD file style guide - -In `BUILD` files, we take the same approach as in Go: We let the machine take care -of most formatting issues. -[Buildifier](https://github.com/bazelbuild/buildifier) is a tool that parses and -emits the source code in a standard style. Every `BUILD` file is therefore -formatted in the same automated way, which makes formatting a non-issue during -code reviews. It also makes it easier for tools to understand, edit, and -generate `BUILD` files. - -`BUILD` file formatting must match the output of `buildifier`. - -## Formatting example - -```python -package(default_visibility = ["//visibility:public"]) - -py_test( - name = "foo_test", - srcs = glob(["*.py"]), - data = [ - "//data/production/foo:startfoo", - "//foo", - "//third_party/java/jdk:jdk-k8", - ], - flaky = 1, - deps = [ - ":check_bar_lib", - ":foo_data_check", - ":pick_foo_port", - "//pyglib", - "//testing/pybase", - ], -) -``` - -## File structure - -We recommend to use the following order (every element is optional): - - * Package description (a comment) - - * All `load()` statements - - * The `package()` function. - - * Calls to rules and macros - -Buildifier makes a distinction between a standalone comment and a comment -attached to an element. If a comment is not attached to a specific element, use -an empty line after it. The distinction is important when doing automated -changes (e.g. to decide if we keep or remove a comment when we delete a rule). - -```python -# Standalone comment (e.g. to make a section in a file) - -# Comment for the cc_library below -cc_library(name = "cc") -``` - -## Conventions - - * Use uppercase and underscores to declare constants (e.g. `GLOBAL_CONSTANT`), - use lowercase and underscores to declare variables (e.g. `my_variable`). - - * Labels should be canonicalized. Use `//foo/bar` instead of `//foo/bar:bar`. - Use `:bar` if it is defined in the same package. *Rationale*: It makes clear - if a label is local to a package. Sorting a list of labels is messy if all - labels do not use the same conventions. - - * Labels should never be split, even if they are longer than 79 characters. - Labels should be string literals whenever possible. Rationale: It makes - find and replace easy. It also improves readability. - - * The value of the name attribute should be a literal constant string (except - in macros). *Rationale*: External tools use the name attribute to refer a - rule. They need to find rules without having to interpret code. - -## Differences with Python style guide - -Although compatibility with -[Python style guide](https://www.python.org/dev/peps/pep-0008/) is a goal, there -are a few differences: - - * No strict line length limit. Long comments and long strings are often split - to 79 columns, but it is not required. It should not be enforced in code - reviews or presubmit scripts. *Rationale*: Labels can be long and exceed this - limit. It is common for `BUILD` files to be generated or edited by tools, which - does not go well with a line length limit. - - * Implicit string concatenation is not supported. Use the `+` operator. - *Rationale*: `BUILD` files contain many string lists. It is easy to forget a - comma, which leads to a complete different result. This has created many bugs - in the past. [See also this discussion.](https://lwn.net/Articles/551438/) - - * Use spaces around the `=` sign for keywords arguments in rules. *Rationale*: - Named arguments are much more frequent than in Python and are always on a - separate line. Spaces improve readability. This convention has been around - for a long time, and we don't think it is worth modifying all existing - `BUILD` files. - - * By default, use double quotation marks for strings. *Rationale*: This is not - specified in the Python style guide, but it recommends consistency. So we - decided to use only double-quoted strings. Many languages use double-quotes - for string literals. - - * Use a single blank line between two top-level definitions. *Rationale*: The - structure of a `BUILD` file is not like a typical Python file. It has only - top-level statements. Using a single-blank line makes `BUILD` files shorter. diff --git a/site/versions/master/docs/skylark/bzl-style.md b/site/versions/master/docs/skylark/bzl-style.md deleted file mode 100644 index 66c2d2918e..0000000000 --- a/site/versions/master/docs/skylark/bzl-style.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -layout: documentation -title: Style guide for bzl files ---- - -# .bzl file style guide - -## Style - -* When in doubt, follow the - [Python style guide](https://www.python.org/dev/peps/pep-0008/). - -* Code should be documented using - [docstrings](https://www.python.org/dev/peps/pep-0257/). Use a docstring at - the top of the file, and a docstring for each public function. - -* Variables and function names use lowercase with words separated by underscores - (`[a-z][a-z0-9_]*`), e.g. `cc_library`. Top-level private values start with - one underscore. Bazel enforces that private values cannot be used from other - files. - -* As in BUILD files, there is no strict line length limit as labels can be long. - When possible, try to use at most 79 characters per line. - -* In keyword arguments, spaces around the equal sign are optional. In general, - we follow the BUILD file convention when calling macros and native rules, and - the Python convention for other functions, e.g. - -```python -def fct(name, srcs): - filtered_srcs = my_filter(source=srcs) - native.cc_library( - name = name, - srcs = filtered_srcs, - ) -``` - -## Macros - -A [macro](macros.md) is a function which instantiates one or many rules during -the loading phase. - -* Macros must accept a name attribute and each invocation should specify a name. - The generated name attribute of rules should include the name attribute as a - prefix. For example, `my_macro(name = "foo")` can generate a rule `foo` and a - rule `foo_gen`. *Rationale*: Users should be able to find easily which macro - generated a rule. Also, automated refactoring tools need a way to identify a - specific rule to edit. - -* When calling a macro, use only keyword arguments. *Rationale*: This is for - consistency with rules, it greatly improves readability. - diff --git a/site/versions/master/docs/skylark/concepts.md b/site/versions/master/docs/skylark/concepts.md deleted file mode 100644 index 8caf553dfb..0000000000 --- a/site/versions/master/docs/skylark/concepts.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -layout: documentation -title: Extensions - Overview ---- -# Overview - - -## Loading an extension - -Extensions are files with the `.bzl` extension. Use the `load` statement to -import a symbol from an extension. - -```python -load("//build_tools/rules:maprule.bzl", "maprule") -``` - -This code will load the file `build_tools/rules/maprule.bzl` and add the -`maprule` symbol to the environment. This can be used to load new rules, -functions or constants (e.g. a string, a list, etc.). Multiple symbols can be -imported by using additional arguments to the call to `load`. Arguments must -be string literals (no variable) and `load` statements must appear at -top-level, i.e. they cannot be in a function body. - -`load` also supports aliases, i.e. you can assign different names to the -imported symbols. - -```python -load("//build_tools/rules:maprule.bzl", maprule_alias = "maprule") -``` - -You can define multiple aliases within one `load` statement. Moreover, the -argument list can contain both aliases and regular symbol names. The following -example is perfectly legal (please note when to use quotation marks). - -```python -load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule") -``` - -In a `.bzl` file, symbols starting with `_` are private and cannot be loaded -from another file. Visibility doesn't affect loading (yet): you don't need to -use `exports_files` to make a `.bzl` file visible. - -## Macros and rules - -A [macro](macros.md) is a function that instantiates rules. It is useful when a -BUILD file is getting too repetitive or too complex, as it allows you to reuse -some code. The function is evaluated as soon as the BUILD file is read. After -the evaluation of the BUILD file, Bazel has little information about macros: if -your macro generates a `genrule`, Bazel will behave as if you wrote the -`genrule`. As a result, `bazel query` will only list the generated `genrule`. - -A [rule](rules.md) is more powerful than a macro. It can access Bazel internals -and have full control over what is going on. It may for example pass information -to other rules. - -If you want to reuse simple logic, start with a macro. If a macro becomes -complex, it is often a good idea to make it a rule. Support for a new language -is typically done with a rule. Rules are for advanced users: we expect that most -people will never have to write one, they will only load and call existing -rules. - -## Evaluation model - -A build consists of three phases. - -* **Loading phase**. First, we load and evaluate all extensions and all BUILD - files that are needed for the build. The execution of the BUILD files simply - instantiates rules (each time a rule is called, it gets added to a graph). - This is where macros are evaluated. - -* **Analysis phase**. The code of the rules is executed (their `implementation` - function), and actions are instantiated. An action describes how to generate - a set of outputs from a set of inputs, e.g. "run gcc on hello.c and get - hello.o". It is important to note that we have to list explicitly which - files will be generated before executing the actual commands. In other words, - the analysis phase takes the graph generated by the loading phase and - generates an action graph. - -* **Execution phase**. Actions are executed, when at least one of their outputs is - required. If a file is missing or if a command fails to generate one output, - the build fails. Tests are also run during this phase. - -Bazel uses parallelism to read, parse and evaluate the `.bzl` files and `BUILD` -files. A file is read at most once per build and the result of the evaluation is -cached and reused. A file is evaluated only once all its dependencies (`load()` -statements) have been resolved. By design, loading a `.bzl` file has no visible -side-effect, it only defines values and functions. - -Bazel tries to be clever: it uses dependency analysis to know which files must -be loaded, which rules must be analyzed, and which actions must be executed. For -example, if a rule generates actions that we don't need for the current build, -they will not be executed. - -## Backward-incompatible changes - -As we make changes and polish the extension mechanism, old features may be -removed and new features that are not backwards-compatible may be added. - -Each release, new incompatible changes will be behind a flag with its default -value set to `false`. In later releases, the flag will be enabled by default, or -the flag will be removed entirely. - -To check if your code will be compatible with future releases: - -* build your code with the flag `--all_incompatible_changes`, or -* use boolean flags to enable/disable specific incompatible changes. - -This following are the planned incompatible changes that are implemented and -guarded behind flags. - -### Set constructor - -We are removing the `set` constructor. Use `depset` instead. `set` and `depset` -are equivalent, you just need to do search and replace to update the old code. - -We are doing this to reduce confusion between the specialized -[depset](depsets.md) data structure and Python's set datatype. - -* Flag: `--incompatible_disallow_set_constructor=true` -* Introduced in: 0.5.1 - -### Keyword-only arguments - -Keyword-only parameters are parameters that can be called only using their name. - -``` python -def foo(arg1, *, arg2): pass - -foo(3, arg2=3) -``` - -``` python -def bar(arg1, *rest, arg2): pass - -bar(3, arg2=3) -``` - -In both examples, `arg2` must be named at the call site. To preserve syntactic -compatibility with Python 2, we are removing this feature (which we have never -documented). - -* Flag: `--incompatible_disallow_keyword_only_args=true` -* Introduced in: 0.5.1 - -### Mutating `+=` - -We are changing `left += right` when `left` is a list. The old behavior is -equivalent to `left = left + right`, which creates a new list and assigns it to -`left`. The new behavior does not rebind `left`, but instead just mutates the -list in-place. - -``` python -def fct(): - li = [1] - alias = li - li += [2] - # Old behavior: alias == [1] - # New behavior: alias == [1, 2] -``` - -This change makes Skylark more compatible with Python and avoids performance -issues. The `+=` operator for tuples is unaffected. - -* Flag: `--incompatible_list_plus_equals_inplace=true` -* Introduced in: 0.5.1 - -### Dictionary concatenation - -We are removing the `+` operator on dictionaries. This includes the `+=` form -where the left-hand side is a dictionary. This is done to improve compatibility -with Python. A possible workaround is to use the `.update` method instead. - -* Flag: `--incompatible_disallow_dict_plus=true` -* Introduced in: 0.5.1 - -## Upcoming changes - -The following items are upcoming changes. - -* Comprehensions currently "leak" the values of their loop variables into the - surrounding scope (Python 2 semantics). This will be changed so that - comprehension variables are local (Python 3 semantics). - -* Previously dictionaries were guaranteed to use sorted order for their keys. - Going forward, there is no guarantee on order besides that it is - deterministic. As an implementation matter, some kinds of dictionaries may - continue to use sorted order while others may use insertion order. - -These changes concern the `load()` syntax in particular. - -* Currently a `load()` statement can appear anywhere in a file so long as it is - at the top-level (not in an indented block of code). In the future they will - be required to appear at the beginning of the file, i.e., before any - non-`load()` statement. - -* In BUILD files, `load()` can overwrite an existing variable with the loaded - symbol. This will be disallowed in order to improve consistency with .bzl - files. Use load aliases to avoid name clashes. - -* The .bzl file can be specified as either a path or a label. In the future only - the label form will be allowed. - -* Cross-package visibility restrictions do not yet apply to loaded .bzl files. - At some point this will change. In order to load a .bzl from another package - it will need to be exported, such as by using an `exports_files` declaration. - The exact syntax has not yet been decided. - - -## Profiling the code - -To profile your code and analyze the performance, use the `--profile` flag: - -``` -$ bazel build --nobuild --profile=/tmp/prof //path/to:target -$ bazel analyze-profile /tmp/prof --html --html_details -``` - -Then, open the generated HTML file (`/tmp/prof.html` in the example). - - diff --git a/site/versions/master/docs/skylark/cookbook.md b/site/versions/master/docs/skylark/cookbook.md deleted file mode 100644 index 28303e2457..0000000000 --- a/site/versions/master/docs/skylark/cookbook.md +++ /dev/null @@ -1,950 +0,0 @@ ---- -layout: documentation -title: Extensions examples ---- -# Extensions examples - -## <a name="macro"></a>Macro creating a rule - -An example of a macro creating a rule. - -`empty.bzl`: - -```python -def _impl(ctx): - print("This rule does nothing") - -empty = rule(implementation=_impl) -``` - -`extension.bzl`: - -```python -# Loading the rule. The rule doesn't have to be in a separate file. -load("//pkg:empty.bzl", "empty") - -def macro(name, visibility=None): - # Creating the rule. - empty(name = name, visibility = visibility) -``` - -`BUILD`: - -```python -load("//pkg:extension.bzl", "macro") - -macro(name = "myrule") -``` - -## <a name="macro_native"></a>Macro creating a native rule - -An example of a macro creating a native rule. Native rules are special rules -that are automatically available (without <code>load</code>). They are -accessed using the <a href="lib/native.html">native</a> module. - -`extension.bzl`: - -```python -def macro(name, visibility=None): - # Creating a native genrule. - native.genrule( - name = name, - outs = [name + '.txt'], - cmd = 'echo hello > $@', - visibility = visibility, - ) -``` - -`BUILD`: - -```python -load("//pkg:extension.bzl", "macro") - -macro(name = "myrule") -``` - -## <a name="macro_compound"></a>Macro multiple rules - -There's currently no easy way to create a rule that directly uses the -action of a native rule. You can work around this using macros: - -```python -def _impl(ctx): - return struct([...], - # When instrumenting this rule, again hide implementation from - # users. - instrumented_files( - source_attributes = ["srcs", "csrcs"], - dependency_attributes = ["deps", "cdeps"])) - -# This rule is private and can only be accessed from the current file. -_cc_and_something_else_binary = rule(implementation=_impl) - - -# This macro is public, it's the public interface to instantiate the rule. -def cc_and_something_else_binary(name, srcs, deps, csrcs, cdeps): - cc_binary_name = "%s.cc_binary" % name - - native.cc_binary( - name = cc_binary_name, - srcs = csrcs, - deps = cdeps, - visibility = ["//visibility:private"] - ) - - _cc_and_something_else_binary( - name = name, - srcs = srcs, - deps = deps, - # A label attribute so that this depends on the internal rule. - cc_binary = cc_binary_name, - # Redundant labels attributes so that the rule with this target name knows - # about everything it would know about if cc_and_something_else_binary - # were an actual rule instead of a macro. - csrcs = csrcs, - cdeps = cdeps) -``` - - -## <a name="conditional-instantiation"></a>Conditional instantiation - -Macros can look at previously instantiated rules. This is done with -`native.existing_rule`, which returns information on a single rule defined in the same -`BUILD` file, eg., - -```python -native.existing_rule("descriptor_proto") -``` - -This is useful to avoid instantiating the same rule twice, which is an -error. For example, the following macro will simulate a test suite, -instantiating tests for diverse flavors of the same test. - -`extension.bzl`: - -```python -def system_test(name, test_file, flavor): - n = "system_test_%s_%s_test" % (test_file, flavor) - if native.existing_rule(n) == None: - native.py_test( - name = n, - srcs = [ - "test_driver.py", - test_file, - ], - args = ["--flavor=" + flavor], - ) - return n - -def system_test_suite(name, flavors=["default"], test_files=[]): - ts = [] - for flavor in flavors: - for test in test_files: - ts.append(system_test(name, test, flavor)) - native.test_suite(name = name, tests = ts) -``` - -In the following BUILD file, note how `(basic_test.py, fast)` is emitted for -both the `smoke` test suite and the `thorough` test suite. - -`BUILD`: - -```python -load("//pkg:extension.bzl", "system_test_suite") - -# Run all files through the 'fast' flavor. -system_test_suite( - name = "smoke", - flavors = ["fast"], - test_files = glob(["*_test.py"]), -) - -# Run the basic test through all flavors. -system_test_suite( - name = "thorough", - flavors = [ - "fast", - "debug", - "opt", - ], - test_files = ["basic_test.py"], -) -``` - - -## <a name="aggregation"></a>Aggregating over the BUILD file - -Macros can collect information from the BUILD file as processed so far. We call -this aggregation. The typical example is collecting data from all rules of a -certain kind. This is done by calling -<a href="lib/native.html#existing_rules">native.existing\_rules</a>, which -returns a dictionary representing all rules defined so far in the current BUILD -file. The dictionary has entries of the form `name` => `rule`, with the values -using the same format as `native.existing_rule`. - -```python -def archive_cc_src_files(tag): - """Create an archive of all C++ sources that have the given tag.""" - all_src = [] - for r in native.existing_rules().values(): - if tag in r["tags"] and r["kind"] == "cc_library": - all_src.append(r["srcs"]) - native.genrule(cmd = "zip $@ $^", srcs = all_src, outs = ["out.zip"]) -``` - -Since `native.existing_rules` constructs a potentially large dictionary, you should avoid -calling it repeatedly within BUILD file. - -## <a name="empty"></a>Empty rule - -Minimalist example of a rule that does nothing. If you build it, the target will -succeed (with no generated file). - -`empty.bzl`: - -```python -def _impl(ctx): - # You may use print for debugging. - print("This rule does nothing") - -empty = rule(implementation=_impl) -``` - -`BUILD`: - -```python -load("//pkg:empty.bzl", "empty") - -empty(name = "nothing") -``` - -## <a name="attr"></a>Rule with attributes - -Example of a rule that shows how to declare attributes and access them. - -`printer.bzl`: - -```python -def _impl(ctx): - # You may use print for debugging. - print("Rule name = %s, package = %s" % (ctx.label.name, ctx.label.package)) - - # This prints the labels of the deps attribute. - print("There are %d deps" % len(ctx.attr.deps)) - for i in ctx.attr.deps: - print("- %s" % i.label) - # A label can represent any number of files (possibly 0). - print(" files = %s" % [f.path for f in i.files]) - -printer = rule( - implementation=_impl, - attrs={ - # Do not declare "name": It is added automatically. - "number": attr.int(default = 1), - "deps": attr.label_list(allow_files=True), - }) -``` - -`BUILD`: - -```python -load("//pkg:printer.bzl", "printer") - -printer( - name = "nothing", - deps = [ - "BUILD", - ":other", - ], -) - -printer(name = "other") -``` - -If you execute this file, some information is printed as a warning by the -rule. No file is generated. - -## <a name="shell"></a>Simple shell command - -Example of a rule that runs a shell command on an input file specified by -the user. The output has the same name as the rule, with a `.size` suffix. - -While convenient, Shell commands should be used carefully. Generating the -command-line can lead to escaping and injection issues. It can also create -portability problems. It is often better to declare a binary target in a -BUILD file and execute it. See the example [executing a binary](#execute-bin). - -`size.bzl`: - -```python -def _impl(ctx): - output = ctx.outputs.out - input = ctx.file.file - # The command may only access files declared in inputs. - ctx.action( - inputs=[input], - outputs=[output], - progress_message="Getting size of %s" % input.short_path, - command="stat -L -c%%s %s > %s" % (input.path, output.path)) - -size = rule( - implementation=_impl, - attrs={"file": attr.label(mandatory=True, allow_files=True, single_file=True)}, - outputs={"out": "%{name}.size"}, -) -``` - -`foo.txt`: - -``` -Hello -``` - -`BUILD`: - -```python -load("//pkg:size.bzl", "size") - -size( - name = "foo_size", - file = "foo.txt", -) -``` - -## <a name="file"></a>Write string to a file - -Example of a rule that writes a string to a file. - -`file.bzl`: - -```python -def _impl(ctx): - output = ctx.outputs.out - ctx.file_action(output=output, content=ctx.attr.content) - -file = rule( - implementation=_impl, - attrs={"content": attr.string()}, - outputs={"out": "%{name}.txt"}, -) -``` - -`BUILD`: - -```python -load("//pkg:file.bzl", "file") - -file( - name = "hello", - content = "Hello world", -) -``` - - -## <a name="execute-bin"></a>Execute a binary - -This rule executes an existing binary. In this particular example, the -binary is a tool that merges files. During the analysis phase, we cannot -access any arbitrary label: the dependency must have been previously -declared. To do so, the rule needs a label attribute. In this example, we -will give the label a default value and make it private (so that it is not -visible to end users). Keeping the label private can simplify maintenance, -since you can easily change the arguments and flags you pass to the tool. - -`execute.bzl`: - -```python -def _impl(ctx): - # The list of arguments we pass to the script. - args = [ctx.outputs.out.path] + [f.path for f in ctx.files.srcs] - # Action to call the script. - ctx.action( - inputs=ctx.files.srcs, - outputs=[ctx.outputs.out], - arguments=args, - progress_message="Merging into %s" % ctx.outputs.out.short_path, - executable=ctx.executable._merge_tool) - -concat = rule( - implementation=_impl, - attrs={ - "srcs": attr.label_list(allow_files=True), - "out": attr.output(mandatory=True), - "_merge_tool": attr.label(executable=True, cfg="host", allow_files=True, - default=Label("//pkg:merge")) - } -) -``` - -Any executable target can be used. In this example, we will use a -`sh_binary` rule that concatenates all the inputs. - -`BUILD`: - -``` -load("execute", "concat") - -concat( - name = "sh", - srcs = [ - "header.html", - "body.html", - "footer.html", - ], - out = "page.html", -) - -# This target is used by the shell rule. -sh_binary( - name = "merge", - srcs = ["merge.sh"], -) -``` - -`merge.sh`: - -```python -#!/bin/bash - -out=$1 -shift -cat $* > $out -``` - -`header.html`: - -``` -<html><body> -``` - -`body.html`: - -``` -content -``` - -`footer.html`: - -``` -</body></html> -``` - -## <a name="execute"></a>Execute an input binary - -This rule has a mandatory `binary` attribute. It is a label that can refer -only to executable rules or files. - -`execute.bzl`: - -```python -def _impl(ctx): - # ctx.new_file is used for temporary files. - # If it should be visible for user, declare it in rule.outputs instead. - f = ctx.new_file(ctx.configuration.bin_dir, "hello") - # As with outputs, each time you declare a file, - # you need an action to generate it. - ctx.file_action(output=f, content=ctx.attr.input_content) - - ctx.action( - inputs=[f], - outputs=[ctx.outputs.out], - executable=ctx.executable.binary, - progress_message="Executing %s" % ctx.executable.binary.short_path, - arguments=[ - f.path, - ctx.outputs.out.path, # Access the output file using - # ctx.outputs.<attribute name> - ] - ) - -execute = rule( - implementation=_impl, - attrs={ - "binary": attr.label(cfg="host", mandatory=True, allow_files=True, - executable=True), - "input_content": attr.string(), - "out": attr.output(mandatory=True), - }, -) -``` - -`a.sh`: - -```bash -#!/bin/bash - -tr 'a-z' 'A-Z' < $1 > $2 -``` - -`BUILD`: - -```python -load("//pkg:execute.bzl", "execute") - -execute( - name = "e", - input_content = "some text", - binary = "a.sh", - out = "foo", -) -``` - -## <a name="runfiles"></a>Runfiles and location substitution - -`execute.bzl`: - -```python -def _impl(ctx): - executable = ctx.outputs.executable - command = ctx.attr.command - # Expand the label in the command string to a runfiles-relative path. - # The second arg is the list of labels that may be expanded. - command = ctx.expand_location(command, ctx.attr.data) - # Create the output executable file with command as its content. - ctx.file_action( - output=executable, - content=command, - executable=True) - - return [DefaultInfo( - # Create runfiles from the files specified in the data attribute. - # The shell executable - the output of this rule - can use them at runtime. - # It is also possible to define data_runfiles and default_runfiles. - # However if runfiles is specified it's not possible to define the above - # ones since runfiles sets them both. - # Remember, that the struct returned by the implementation function needs - # to have a field named "runfiles" in order to create the actual runfiles - # symlink tree. - runfiles=ctx.runfiles(files=ctx.files.data) - )] - -execute = rule( - implementation=_impl, - executable=True, - attrs={ - "command": attr.string(), - "data": attr.label_list(cfg="data", allow_files=True), - }, -) -``` - -`data.txt`: - -``` -Hello World! -``` - -`BUILD`: - -```python -load("//pkg:execute.bzl", "execute") - -execute( - name = "e", - # The location will be expanded to "pkg/data.txt", and it will reference - # the data.txt file in runfiles when this target is invoked as - # "bazel run //pkg:e". - command = "cat $(location :data.txt)", - data = [':data.txt'] -) -``` - -## <a name="late-bound"></a>Computed dependencies - -Bazel needs to know about all dependencies before doing the analysis phase and -calling the implementation function. Dependencies can be computed based on the -rule attributes: to do so, use a function as the default -value of an attribute (the attribute must be private and have type `label` or -`list of labels`). The parameters of this function must correspond to the -attributes that are accessed in the function body. - -Note: For legacy reasons, the function takes the configuration as an additional -parameter. Please do not rely on the configuration since it will be removed in -the future. - -The example below computes the md5 sum of a file. The file can be preprocessed -using a filter. The exact dependencies depend on the filter chosen by the user. - -`hash.bzl`: - -```python -_filters = { - "comments": Label("//pkg:comments"), - "spaces": Label("//pkg:spaces"), - "none": None, -} - -def _get_filter(filter, cfg=None): # requires attribute "filter" - # Return the value for the attribute "_filter_bin" - # It can be a label or None. - return _filters[filter] - -def _impl(ctx): - src = ctx.file.src - - if not ctx.attr._filter_bin: - # Skip the processing - processed = src - else: - processed = ctx.new_file(ctx.label.name + "_processed") - # Run the selected binary - ctx.action( - outputs = [processed], - inputs = [ctx.file.src], - progress_message="Apply filter '%s'" % ctx.attr.filter, - arguments = [ctx.file.src.path, processed.path], - executable = ctx.executable._filter_bin) - - # Compute the hash - out = ctx.outputs.text - ctx.action( - outputs = [out], - inputs = [processed], - command = "md5sum < %s > %s" % (processed.path, out.path)) - -md5_sum = rule( - implementation=_impl, - attrs={ - "filter": attr.string(values=_filters.keys(), default="none"), - "src": attr.label(mandatory=True, single_file=True, allow_files=True), - "_filter_bin": attr.label(default=_get_filter, executable=True), - }, - outputs = {"text": "%{name}.txt"}) -``` - -`BUILD`: - -```python -load("//pkg:hash.bzl", "md5_sum") - -md5_sum( - name = "hash", - src = "hello.txt", - filter = "spaces", -) - -sh_binary( - name = "comments", - srcs = ["comments.sh"], -) - -sh_binary( - name = "spaces", - srcs = ["spaces.sh"], -) -``` - -`hello.txt`: - -``` -Hello World! -``` - -`comments.sh`: - -``` -#!/bin/bash -grep -v '^ *#' $1 > $2 # Remove lines with only a Python-style comment -``` - -`spaces.sh`: - -``` -#!/bin/bash -tr -d ' ' < $1 > $2 # Remove spaces -``` - -## <a name="mandatory-providers"></a>Mandatory providers - -In this example, rules have a `number` attribute. Each rule adds its -number with the numbers of its transitive dependencies, and write the -result in a file. This shows how to transfer information from a dependency -to its dependents. - -`sum.bzl`: - -```python -NumberInfo = provider() - -def _impl(ctx): - result = ctx.attr.number - for dep in ctx.attr.deps: - result += dep[NumberInfo].number - ctx.file_action(output=ctx.outputs.out, content=str(result)) - - # Return the provider with result, visible to other rules. - return [NumberInfo(number=result)] - -sum = rule( - implementation=_impl, - attrs={ - "number": attr.int(default=1), - # All deps must provide all listed providers. - "deps": attr.label_list(providers=[NumberInfo]), - }, - outputs = {"out": "%{name}.sum"} -) -``` - -`BUILD`: - -```python -load("//pkg:sum.bzl", "sum") - -sum( - name = "n", - deps = ["n2", "n5"], -) - -sum( - name = "n2", - number = 2, -) - -sum( - name = "n5", - number = 5, -) -``` - -## <a name="optional-providers"></a>Optional providers - -This is a similar example, but dependencies may not provide a number. - -`sum.bzl`: - -```python -NumberInfo = provider() - -def _impl(ctx): - result = ctx.attr.number - for dep in ctx.attr.deps: - if NumberInfo in dep: - result += dep[NumberInfo].number - ctx.file_action(output=ctx.outputs.out, content=str(result)) - - # Return the provider with result, visible to other rules. - return [NumberInfo(number=result)] - -sum = rule( - implementation=_impl, - attrs={ - "number": attr.int(default=1), - "deps": attr.label_list(), - }, - outputs = {"out": "%{name}.sum"} -) -``` - -`BUILD`: - -```python -load("//pkg:sum.bzl", "sum") - -sum( - name = "n", - deps = ["n2", "n5"], -) - -sum( - name = "n2", - number = 2, -) - -sum( - name = "n5", - number = 5, -) -``` - -## <a name="outputs-executable"></a>Default executable output - -This example shows how to create a default executable output. - -`extension.bzl`: - -```python -def _impl(ctx): - ctx.file_action( - # Access the executable output file using ctx.outputs.executable. - output=ctx.outputs.executable, - content="#!/bin/bash\necho Hello!", - executable=True - ) - # The executable output is added automatically to this target. - -executable_rule = rule( - implementation=_impl, - executable=True -) -``` - -`BUILD`: - -```python -load("//pkg:extension.bzl", "executable_rule") - -executable_rule(name = "my_rule") -``` - -## <a name="outputs-default"></a>Default outputs - -This example shows how to create default outputs for a rule. - -`extension.bzl`: - -```python -def _impl(ctx): - ctx.file_action( - # Access the default outputs using ctx.outputs.<output name>. - output=ctx.outputs.my_output, - content="Hello World!" - ) - # The default outputs are added automatically to this target. - -rule_with_outputs = rule( - implementation=_impl, - outputs = { - # %{name} is substituted with the rule's name - "my_output": "%{name}.txt" - } -) -``` - -`BUILD`: - -```python -load("//pkg:extension.bzl", "rule_with_outputs") - -rule_with_outputs(name = "my_rule") -``` - -## <a name="outputs-custom"></a>Custom outputs - -This example shows how to create custom (user defined) outputs for a rule. -This rule takes a list of output file name templates from the user and -creates each of them containing a "Hello World!" message. - -`extension.bzl`: - -```python -def _impl(ctx): - # Access the custom outputs using ctx.outputs.<attribute name>. - for output in ctx.outputs.outs: - ctx.file_action( - output=output, - content="Hello World!" - ) - # The custom outputs are added automatically to this target. - -rule_with_outputs = rule( - implementation=_impl, - attrs={ - "outs": attr.output_list() - } -) -``` - -`BUILD`: - -```python -load("//pkg:extension.bzl", "rule_with_outputs") - -rule_with_outputs( - name = "my_rule", - outs = ["my_output.txt"] -) -``` - -## <a name="master-rule"></a>Master rules - -This example shows how to create master rules to bind other rules together. The -code below uses genrules for simplicity, but this technique is more useful with -other rules. For example, if you need to compile C++ files, you can reuse -`cc_library`. - -`extension.bzl`: - -```python -def _impl(ctx): - # Aggregate the output files from the depending rules - files = depset() - files += ctx.attr.dep_rule_1.files - files += ctx.attr.dep_rule_2.files - return [DefaultInfo(files=files)] - -# This rule binds the depending rules together -master_rule = rule( - implementation=_impl, - attrs={ - "dep_rule_1": attr.label(), - "dep_rule_2": attr.label() - } -) - -def macro(name, cmd, input): - # Create the depending rules - name_1 = name + "_dep_1" - name_2 = name + "_dep_2" - native.genrule( - name = name_1, - cmd = cmd, - outs = [name_1 + ".txt"] - ) - native.genrule( - name = name_2, - cmd = "echo " + input + " >$@", - outs = [name_2 + ".txt"] - ) - # Create the master rule - master_rule( - name = name, - dep_rule_1 = ":" + name_1, - dep_rule_2 = ":" + name_2 - ) -``` - -`BUILD`: - -```python -load("//pkg:extension.bzl", "macro") - -# This creates the target :my_rule -macro( - name = "my_rule", - cmd = "echo something > $@", - input = "Hello World" -) -``` - -## <a name="debugging-tips"></a>Debugging tips - -Here are some examples on how to debug macros and rules using -<a href="lib/globals.html#print">print</a>. - -`debug.bzl`: - -```python -print("print something when the module is loaded") - -def _impl(ctx): - print("print something when the rule implementation is executed") - print(type("abc")) # prints string, the type of "abc" - print(dir(ctx)) # prints all the fields and methods of ctx - print(dir(ctx.attr)) # prints all the attributes of the rule - # prints the objects each separated with new line - print("object1", "object2", sep="\n") - -debug = rule(implementation=_impl) -``` - -`BUILD`: - -```python -load("//pkg:debug.bzl", "debug") - -debug( - name = "printing_rule" -) -``` - diff --git a/site/versions/master/docs/skylark/deploying.md b/site/versions/master/docs/skylark/deploying.md deleted file mode 100644 index 658445175e..0000000000 --- a/site/versions/master/docs/skylark/deploying.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -layout: documentation -title: Deploying new Skylark rules ---- -# Deploying new Skylark rules - -This documentation is for Skylark rule writers who are planning to make their -rules available to others. - -## Where to put new rules - -In general, new rules should go into their own GitHub repository under your -organization. Contact the [bazel-dev mailing -list](https://groups.google.com/forum/#!forum/bazel-dev) if you feel like your -rules belong in the bazelbuild organization. - -You can see lots of examples of what your repository should look like on GitHub: -see all of the repositories named `rules_whatever`. In particular, -[rules_scala](https://github.com/bazelbuild/rules_scala) is a nice example of -how to set up your repo. - -Rules can be grouped either by language (e.g., Scala) or some notion of platform -(e.g., Android). - -## What a rule repository should contain - -Every rule repository should have a certain layout so that users can quickly -understand new rules. - -For example, suppose we are writing new Skylark rules for the (make-believe) -chaiscript language. We would have the following structure: - -``` -.travis.yml -README.md -WORKSPACE -chaiscript/ - BUILD - chaiscript.bzl -tests/ - BUILD - some_test.sh - another_test.py -examples/ - BUILD - bin.chai - lib.chai - test.chai -``` - -### README.md - -At the top level, there should be a README.md that contains (at least) what -users will need to copy-paste into their WORKSPACE file to use your rule. -In general, this will be a `git_repository` pointing to your GitHub repo and -a macro call that downloads/configures any tools your rule needs. For example, -for the [Go -rules](https://github.com/bazelbuild/rules_go/blob/master/README.md#setup), this -looks like: - -``` -git_repository( - name = "io_bazel_rules_go", - remote = "https://github.com/bazelbuild/rules_go.git", - tag = "0.0.2", -) -load("@io_bazel_rules_go//go:def.bzl", "go_repositories") - -go_repositories() -``` - -If your rules depend on another repository's rules, specify both in the -`README.md` (see the [Skydoc rules](https://github.com/bazelbuild/skydoc#setup), -which depend on the Sass rules, for an example of this). - -### Tests - -There should be tests that verify that the rules are working as expected. This -can either be in the standard location for the language the rules are for or a -`tests/` directory at the top level. - -### Optional: Examples - -It is useful to users to have an `examples/` directory that shows users a couple -of basic ways that the rules can be used. - -## Testing - -Set up Travis as described in their [getting started -docs](https://docs.travis-ci.com/user/getting-started/). Then add a -`.travis.yml` file to your repository with the following content: - -``` -language: - - java -jdk: - - oraclejdk8 # Building Bazel requires JDK8. -before_install: - - wget https://github.com/bazelbuild/bazel/archive/0.3.0.zip # Replace with desired version - - unzip 0.3.0.zip - - cd bazel-0.3.0 - - ./compile.sh - - sudo cp output/bazel /usr/bin/bazel - - cd .. - - rm -rf bazel-0.3.0 -script: - - bazel build //... - - bazel test //... -``` - -Right now Bazel has to be compiled from source, as Travis does not support a -version of GCC that works with the precompiled Bazel binaries. Thus, the -`before_install` steps download the Bazel source, compile it, and "install" the -Bazel binary in /usr/bin. - -If your repository is under the [bazelbuild organization](https://github.com/bazelbuild), -contact the [bazel-dev](https://groups.google.com/forum/#!forum/bazel-dev) list -to have it added to [ci.bazel.build](http://ci.bazel.build). - -## Documentation - -See the [Skydoc documentation](https://github.com/bazelbuild/skydoc) for -instructions on how to comment your rules so that documentation can be generated -automatically. - -## FAQs - -### Why can't we add our rule to the Bazel GitHub repository? - -We want to decouple rules from Bazel releases as much as possible. It's clearer -who owns individual rules, reducing the load on Bazel developers. For our users, -decoupling makes it easier to modify, upgrade, downgrade, and replace rules. -Contributing to rules can be lighter weight than contributing to Bazel - -depending on the rules -, including full submit access to the corresponding -GitHub repository. Getting submit access to Bazel itself is a much more involved -process. - -The downside is a more complicated one-time installation process for our users: -they have to copy-paste a rule into their WORKSPACE file, as shown in the -README section above. - -We used to have all of the Skylark rules in the Bazel repository (under -`//tools/build_rules` or `//tools/build_defs`). We still have a couple rules -there, but we are working on moving the remaining rules out. diff --git a/site/versions/master/docs/skylark/depsets.md b/site/versions/master/docs/skylark/depsets.md deleted file mode 100644 index 24114b3200..0000000000 --- a/site/versions/master/docs/skylark/depsets.md +++ /dev/null @@ -1,401 +0,0 @@ ---- -layout: documentation -title: Depsets ---- - -# Depsets - -Depsets are a specialized data structure for efficiently collecting data across -a target’s transitive dependencies. Since this use case concerns the [analysis -phase](concepts.md#evaluation-model), depsets are useful for authors of rules -and aspects, but probably not macros. - -The main feature of depsets is that they support a time- and space-efficient -merge operation, whose cost is independent of the size of the existing contents. -Depsets also have well-defined ordering semantics. - -Example uses of depsets include: - -* storing the paths of all object files for a program’s libraries, which can - then be passed to a linker action - -* for an interpreted language, storing the transitive source files that will - be included in an executable's runfiles - - -## Full example - -Suppose we have a hypothetical interpreted language Foo. In order to build each -`foo_binary` we need to know all the \*.foo files that it directly or indirectly -depends on. - -```python -# //mypackage:BUILD - -load(":foo.bzl", "foo_library", "foo_binary") - -# Our hypothetical Foo compiler. -py_binary( - name = "foocc", - srcs = ["foocc.py"], -) - -foo_library( - name = "a", - srcs = ["a.foo", "a_impl.foo"], -) - -foo_library( - name = "b", - srcs = ["b.foo", "b_impl.foo"], - deps = [":a"], -) - -foo_library( - name = "c", - srcs = ["c.foo", "c_impl.foo"], - deps = [":a"], -) - -foo_binary( - name = "d", - srcs = ["d.foo"], - deps = [":b", ":c"], -) -``` - -```python -# //mypackage:foocc.py - -# "Foo compiler" that just concatenates its inputs to form its output. -import sys - -if __name__ == "__main__": - assert len(sys.argv) >= 1 - output = open(sys.argv[1], "wt") - for path in sys.argv[2:]: - input = open(path, "rt") - output.write(input.read()) -``` - -Here, the transitive sources of the binary `d` are all of the \*.foo files in -the `srcs` fields of `a`, `b`, `c`, and `d`. In order for the `foo_binary` -target to know about any file besides `d.foo`, the `foo_library` targets need to -pass them along in a provider. Each library receives the providers from its own -dependencies, adds its own immediate sources, and passes on a new provider with -the augmented contents. The `foo_binary` rule does the same, except that instead -of returning a provider, it uses the complete list of sources to construct a -command line for an action. - -Here’s a complete implementation of the `foo_library` and `foo_binary` rules. - -```python -# //mypackage/foo.bzl - -# A provider with one field, transitive_sources. -FooFiles = provider() - -def get_transitive_srcs(srcs, deps): - """Obtain the source files for a target and its transitive dependencies. - - Args: - srcs: a list of source files - deps: a list of targets that are direct dependencies - Returns: - a collection of the transitive sources - """ - trans_srcs = depset() - for dep in deps: - trans_srcs += dep[FooFiles].transitive_sources - trans_srcs += srcs - return trans_srcs - -def _foo_library_impl(ctx): - trans_srcs = get_transitive_srcs(ctx.files.srcs, ctx.attr.deps) - return [FooFiles(transitive_sources=trans_srcs)] - -foo_library = rule( - implementation = _foo_library_impl, - attrs = { - "srcs": attr.label_list(allow_files=True), - "deps": attr.label_list(), - }, -) - -def _foo_binary_impl(ctx): - foocc = ctx.executable._foocc - out = ctx.outputs.out - trans_srcs = get_transitive_srcs(ctx.files.srcs, ctx.attr.deps) - srcs_list = trans_srcs.to_list() - cmd_string = (foocc.path + " " + out.path + " " + - " ".join([src.path for src in srcs_list])) - ctx.action(command=cmd_string, - inputs=srcs_list + [foocc], - outputs=[out]) - -foo_binary = rule( - implementation = _foo_binary_impl, - attrs = { - "srcs": attr.label_list(allow_files=True), - "deps": attr.label_list(), - "_foocc": attr.label(default=Label("//mypackage:foocc"), - allow_files=True, executable=True, cfg="host") - }, - outputs = {"out": "%{name}.out"}, -) -``` - -You can test this by copying these files into a fresh package, renaming the -labels appropriately, creating the source \*.foo files with dummy content, and -building the `d` target. - -## Description and operations - -Conceptually, a depset is a directed acyclic graph (DAG) that typically looks -similar to the target graph. It is constructed from the leaves up to the root. -Each target in a dependency chain can add its own contents on top of the -previous without having to read or copy them. - -Each node in the DAG holds a list of direct elements and a list of child nodes. -The contents of the depset are the transitive elements, i.e. the direct elements -of all the nodes. A new depset with direct elements but no children can be -created using the [depset](lib/globals.html#depset) constructor. Given an -existing depset, the `+` operator can be used to form a new depset that has -additional contents. Specifically, for the operation `a + b` where `a` is a -depset, the result is a copy of `a` where: - -* if `b` is a depset, then `b` is appended to `a`’s list of children; and - otherwise, - -* if `b` is an iterable, then `b`’s elements are appended to `a`’s list of - direct elements. - -In all cases, the original depset is left unmodified because depsets are -immutable. The returned value shares most of its internal structure with the old -depset. As with other immutable types, `s += t` is shorthand for `s = s + t`. - -```python -s = depset(["a", "b", "c"]) -t = s -s += depset(["d", "e"]) - -print(s) # depset(["d", "e", "a", "b", "c"]) -print(t) # depset(["a", "b", "c"]) -``` - -To retrieve the contents of a depset, use the -[to_list()](lib/depset.html#to_list) method. It returns a list of all transitive -elements, not including duplicates. There is no way to directly inspect the -precise structure of the DAG, although this structure does affect the order in -which the elements are returned. - -```python -s = depset(["a", "b", "c"]) - -print("c" in s.to_list()) # True -print(s.to_list() == ["a", "b", "c"]) # True -``` - -The allowed items in a depset are restricted, just as the allowed keys in -dictionaries are restricted. In particular, depset contents may not be mutable. - -Depsets use reference equality: a depset is equal to itself, but unequal to any -other depset, even if they have the same contents and same internal structure. - -```python -s = depset(["a", "b", "c"]) -t = s -print(s == t) # True - -t = depset(["a", "b", "c"]) -print(s == t) # False - -t = s -# Trivial modification that adds no elements -t += [] -print(s == t) # False - -d = {} -d[s] = None -d[t] = None -print(len(d)) # 2 -``` - -To compare depsets by their contents, convert them to sorted lists. - -```python -s = depset(["a", "b", "c"]) -t = depset(["c", "b", "a"]) -print(sorted(s.to_list()) == sorted(t.to_list())) # True -``` - -There is no ability to remove elements from a depset. If this is needed, you -must read out the entire contents of the depset, filter the elements you want to -remove, and reconstruct a new depset. This is not particularly efficient. - -```python -s = depset(["a", "b", "c"]) -t = depset(["b", "c"]) - -# Compute set difference s - t. Precompute t.to_list() so it's not done -# in a loop, and convert it to a dictionary for fast membership tests. -t_items = {e: None for e in t.to_list()} -diff_items = [x for x in s.to_list() if x not in t_items] -# Convert back to depset if it's still going to be used for merge operations. -s = depset(diff_items) -print(s) # depset(["a"]) -``` - -## Order - -The `to_list` operation performs a traversal over the DAG. The kind of traversal -depends on the *order* that was specified at the time the depset was -constructed. It is useful for Bazel to support multiple orders because sometimes -tools care about the order of their inputs. For example, a linker action may -need to ensure that if `B` depends on `A`, then `A.o` comes before `B.o` on the -linker’s command line. Other tools might have the opposite requirement. - -Three traversal orders are supported: `postorder`, `preorder`, and -`topological`. The first two work exactly like [tree -traversals](https://en.wikipedia.org/wiki/Tree_traversal#Depth-first_search) -except that they operate on DAGs and skip already visited nodes. The third order -works as a topological sort from root to leaves, essentially the same as -preorder except that shared children are listed only after all of their parents. -Preorder and postorder operate as left-to-right traversals, but note that within -each node direct elements have no order relative to children. For topological -order, there is no left-to-right guarantee, and even the -all-parents-before-child guarantee does not apply in the case that there are -duplicate elements in different nodes of the DAG. - -```python -# This demonstrates how the + operator interacts with traversal orders. - -def create(order): - # Create s with "a" and "b" as direct elements. - s = depset(["a", "b"], order=order) - # Add a new child with contents "c" and "d". - s += depset(["c", "d"], order=order) - # Append "e" and "f" as direct elements. - s += ["e", "f"] - # Add a new child with contents "g" and "h" - s += depset(["g", "h"], order=order) - # During postorder traversal, all contents of children are emitted first, - # then the direct contents. - return s - -print(create("postorder").to_list()) # ["c", "d", "g", "h", "a", "b", "e", "f"] -print(create("preorder").to_list()) # ["a", "b", "e", "f", "c", "d", "g", "h"] -``` - -```python -# This demonstrates different orders on a diamond graph. - -def create(order): - a = depset(["a"], order=order) - b = depset(["b"], order=order) - b += a - c = depset(["c"], order=order) - c += a - d = depset(["d"], order=order) - d = d + b + c - return d - -print(create("postorder").to_list()) # ["a", "b", "c", "d"] -print(create("preorder").to_list()) # ["d", "b", "a", "c"] -print(create("topological").to_list()) # ["d", "b", "c", "a"] -``` - -Due to how traversals are implemented, the order must be specified at the time -the depset is created with the constructor’s `order` keyword argument. If this -argument is omitted, the depset has the special `default` order, in which case -there are no guarantees about the order of any of its elements. - -For safety, depsets with different orders cannot be merged with the `+` operator -unless one of them uses the default order; the resulting depset’s order is the -same as the left operand. Note that when two depsets of different order are -merged in this way, the child may appear to have had its elements rearranged -when it is traversed via the parent. - -## Performance - -To see the motivation for using depsets, consider what would have happened if we -had implemented `get_transitive_srcs()` without them. A naive way of writing -this function would be to collect the sources in a list. - -```python -def get_transitive_srcs(srcs, deps): - trans_srcs = [] - for dep in deps: - trans_srcs += dep[FooFiles].transitive_sources - trans_srcs += srcs - return trans_srcs -``` - -However, this does not take into account duplicates, so the source files for `a` -will appear twice on the command line and twice in the contents of the output -file. - -The next alternative is using a general set, which can be simulated by a -dictionary where the keys are the elements and all the keys map to `None`. - -```python -def get_transitive_srcs(srcs, deps): - trans_srcs = {} - for dep in deps: - for file in dep[FooFiles].transitive_sources: - trans_srcs[file] = None - for file in srcs: - trans_srcs[file] = None - return trans_srcs -``` - -This gets rid of the duplicates, but it makes the order of the command line -arguments (and therefore the contents of the files) unspecified, although still -deterministic. - -Moreover, both this approach and the list-based one are asymptotically worse -than the depset-based approach. Consider the case where there is a long chain of -dependencies on Foo libraries. Processing every rule requires copying all of the -transitive sources that came before it into a new data structure. This means -that the time and space cost for analyzing an individual library or binary -target is proportional to its own height in the chain. For a chain of length n, -foolib_1 ← foolib_2 ← … ← foolib_n, the overall cost is effectively the -[triangle sum](https://en.wikipedia.org/wiki/Triangular_number) 1 + 2 + … + n, -which is O(n^2). This cost is wasteful because the library rule’s behavior is -not actually affected by the transitive sources. - -Generally speaking, depsets should be used whenever you are accumulating more -and more information through your transitive dependencies. This helps ensure -that your build scales well as your target graph grows deeper. The exact -advantage will depend on how deep the target graph is and how many elements per -target are added. - -To actually get the performance advantage, it’s important to not retrieve the -contents of the depset unnecessarily in library rules. One call to `to_list()` -at the end in a binary rule is fine, since the overall cost is just O(n). It’s -when many non-terminal targets try to call `to_list()` that we start to get into -quadratic behavior. - -## Upcoming changes - -The API for depsets is being updated to be more consistent. Here are some recent -and/or upcoming changes. - -* The name “set” has been replaced by “depset”. Do not use the `set` - constructor in new code; it is deprecated and will be removed. The traversal - orders have undergone a similar renaming; their old names will be removed as - well. - -* Depset contents should be retrieved using `to_list()`, not by iterating over - the depset itself. Direct iteration over depsets is deprecated and will be - removed. - -* Depset elements currently must have the same type, e.g. all ints or all - strings. This restriction will be lifted. - -* The `|` operator is defined for depsets as a synonym for `+`. This will be - going away; use `+` instead. - -* (Pending approval) The `+` operator will be deprecated in favor of a new - syntax based on function calls. This avoids confusion regarding how `+` - treats direct elements vs children. diff --git a/site/versions/master/docs/skylark/errors/read-only-variable.md b/site/versions/master/docs/skylark/errors/read-only-variable.md deleted file mode 100644 index 5dc1eeebab..0000000000 --- a/site/versions/master/docs/skylark/errors/read-only-variable.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: documentation -title: Variable x is read only ---- -# Error: Variable x is read only - -A global variable cannot be reassigned. It will always point to the same object. -However, its content might change, if the value is mutable (for example, the -content of a list). Local variables don't have this restriction. - -```python -a = [1, 2] - -a[1] = 3 - -b = 3 - -b = 4 # forbidden -``` - -`ERROR: /path/ext.bzl:7:1: Variable b is read only` - -You will get a similar error if you try to redefine a function (function -overloading is not supported), for example: - -```python -def foo(x): return x + 1 - -def foo(x, y): return x + y # forbidden -``` diff --git a/site/versions/master/docs/skylark/index.md b/site/versions/master/docs/skylark/index.md deleted file mode 100644 index dc336c99da..0000000000 --- a/site/versions/master/docs/skylark/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -layout: documentation -title: Extensions ---- - -# Extensions -Skylark is the name of the extension mechanism in Bazel. It lets you add support -for new languages and tools by writing [custom build rules](rules.md). You can -also compose existing rules into [macros](macros.md). - -## Getting started - -Read the [concepts](concepts.md) behind Skylark and try the -[cookbook examples](cookbook.md). To go further, read about the -[standard library](lib/globals.html). ---> - diff --git a/site/versions/master/docs/skylark/language.md b/site/versions/master/docs/skylark/language.md deleted file mode 100644 index 583e4f7c0a..0000000000 --- a/site/versions/master/docs/skylark/language.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -layout: documentation -title: Extensions - Overview ---- -# Language - - -## Syntax - -The extension language, Skylark, is a superset of the -[Core Build Language](/docs/build-ref.html#core_build_language) -and its syntax is a subset of Python. -It is designed to be simple, thread-safe and integrated with the -BUILD language. It is not a general-purpose language and most Python -features are not included. - -The following constructs have been added to the Core Build Language: `if` -statements, `for` loops, and function definitions. They behave like in Python. -Here is an example to show the syntax: - -```python -def fizz_buzz(n): - """Print Fizz Buzz numbers from 1 to n.""" - for i in range(1, n + 1): - s = "" - if i % 3 == 0: - s += "Fizz" - if i % 5 == 0: - s += "Buzz" - print(s if s else i) - -fizz_buzz(20) -``` - -The following basic types are supported: [None](lib/globals.html#None), -[bool](lib/bool.html), [dict](lib/dict.html), function, [int](lib/int.html), -[list](lib/list.html), [string](lib/string.html). On top of that, two new -types are specific to Bazel: [depset](lib/depset.html) and -[struct](lib/struct.html). - -Skylark is syntactically a subset of both Python 2 and Python 3, and will remain -so through at least the 1.x release lifecycle. This ensures that Python-based -tooling can at least parse Skylark code. Although Skylark is not *semantically* -a subset of Python, behavioral differences are rare (excluding cases where -Skylark raises an error). - - -## Mutability - -Because evaluation of BUILD and .bzl files is performed in parallel, there are -some restrictions in order to guarantee thread-safety and determinism. Two -mutable data structures are available: [lists](lib/list.html) and -[dicts](lib/dict.html). - -In a build, there are many "evaluation contexts": each `.bzl` file and each -`BUILD` file is loaded in a different context. Each rule is also analyzed in a -separate context. We allow side-effects (e.g. appending a value to a list or -deleting an entry in a dictionary) only on objects created during the current -evaluation context. Once the code in that context is done executing, all of its -values are frozen. - -For example, here is the content of the file `foo.bzl`: - -```python -var = [] - -def fct(): - var.append(5) - -fct() -``` - -The variable `var` is created when `foo.bzl` is loaded. `fct()` is called during -the same context, so it is safe. At the end of the evaluation, the environment -contains an entry mapping the identifier `var` to a list `[5]`; this list is -then frozen. - -It is possible for multiple other files to load symbols from `foo.bzl` at the -same time. For this reason, the following code is not legal: - -```python -load(":foo.bzl", "var", "fct") - -var.append(6) # runtime error, the list stored in var is frozen - -fct() # runtime error, fct() attempts to modify a frozen list -``` - -Evaluation contexts are also created for the analysis of each custom rule. This -means that any values that are returned from the rule's analysis are frozen. -Note that by the time a custom rule's analysis begins, the .bzl file in which -it is defined has already been loaded, and so the global variables are already -frozen. - -## Differences with Python - -In addition to the mutability restrictions, there are also differences with -Python: - -* Global variables cannot be reassigned. - -* `for` statements are not allowed at the top-level; factor them into functions - instead. - -* Dictionaries have a deterministic order of iteration. - -* Recursion is not allowed. - -* Int type is limited to 32-bit signed integers. - -* Lists and other mutable types may be stored in dictionary - keys once they are frozen. - -* Modifying a collection during iteration is an error. You can avoid the error - by iterating over a copy of the collection, e.g. - `for x in list(my_list): ...`. You can still modify its deep contents - regardless. - -* Global (non-function) variables must be declared before they can be used in - a function, even if the function is not called until after the global variable - declaration. However, it is fine to define `f()` before `g()`, even if `f()` - calls `g()`. - -* The order comparison operators (<, <=, >=, >) are not defined across different - types of values, e.g., you can't compare `5 < 'foo'` (however you still can - compare them using == or !=). This is a difference with Python 2, but - consistent with Python 3. Note that this means you are unable to sort lists - that contain mixed types of values. - -* Tuple syntax is more restrictive. You may use a trailing comma only when the - tuple is between parentheses, e.g. write `(1,)` instead of `1,`. - -* Strings are represented with double-quotes (e.g. when you - call [repr](lib/globals.html#repr)). - -The following Python features are not supported: - -* implicit string concatenation (use explicit `+` operator) -* `class` (see [`struct`](lib/globals.html#struct) function) -* `import` (see [`load`](concepts.md#loading-an-extension) statement) -* `while`, `yield` -* float and set types -* generators and generator expressions -* `lambda` and nested functions -* `is` (use `==` instead) -* `try`, `raise`, `except`, `finally` (see [`fail`](lib/globals.html#fail) for - fatal errors) -* `global`, `nonlocal` -* most builtin functions, most methods diff --git a/site/versions/master/docs/skylark/macros.md b/site/versions/master/docs/skylark/macros.md deleted file mode 100644 index 7782198287..0000000000 --- a/site/versions/master/docs/skylark/macros.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -layout: documentation -title: Macros ---- -# Macros - -## Macro creation - -A macro is a function called from the BUILD file that can instantiate rules. -Macros don't give additional power, they are just used for encapsulation and -code reuse. By the end of the [loading phase](concepts.md#evaluation-model), -macros don't exist anymore, and Bazel sees only the set of rules they created. - -Native rules (i.e. rules that don't need a `load()` statement) can be -instantiated from the [native](lib/native.html) module, e.g. - -```python -def my_macro(name, visibility=None): - native.cc_library( - name = name, - srcs = ["main.cc"], - visibility = visibility, - ) -``` - -If you need to know the package name (i.e. which BUILD file is calling the -macro), use the constant [PACKAGE_NAME](lib/globals.html#PACKAGE_NAME). - -## Examples - -* [Macro creating rules](cookbook.md#macro). - -* [Macro creating native rules](cookbook.md#macro_native). - -* [Macro combining multiple rules](cookbook.md#macro_compound). - -## Debugging - -* `bazel query --output=build //my/path:all` will show you how the BUILD file - looks after evaluation. All macros, globs, loops are expanded. Known - limitation: `select` expressions are currently not shown in the output. - -* You may filter the output based on `generator_function` (which function - generated the rules) or `generator_name` (the name attribute of the macro), - e.g. - ```bash - $ bazel query --output=build 'attr(generator_function, my_macro, //my/path:all)' - ``` - -* To find out where exactly the rule `foo` is generated in a BUILD file, you - can try the following trick. Insert this line near the top of the BUILD - file: `cc_library(name = "foo")`. Run Bazel. You will get an exception when - the rule `foo` is created (due to a name conflict), which will show you the - full stack trace. - -* You can also use [print](lib/globals.html#print) for debugging. It displays - the message as a warning during the loading phase. Except in rare cases, - either remove `print` calls, or make them conditional under a `debugging` - parameter that defaults to `False` before submitting the code to the depot. - -## Errors - -If you want to throw an error, use the [fail](lib/globals.html#fail) function. -Explain clearly to the user what went wrong and how to fix their BUILD file. It -is not possible to catch an error. - -``` -def my_macro(name, deps, visibility=None): - if len(deps) < 2: - fail("Expected at least two values in deps") - # ... -``` - -## Conventions - -* All public functions (functions that don't start with underscore) that - instantiate rules must have a `name` argument. This argument should not be - optional (don't give a default value). - -* Public functions should use a docstring following [Python - conventions](https://www.python.org/dev/peps/pep-0257/#one-line-docstrings). - -* In BUILD files, the `name` argument of the macros must be a keyword argument - (not a positional argument). - -* The `name` attribute of rules generated by a macro should include the name - argument as a prefix. For example, `macro(name = "foo")` can generate a - `cc_library` `foo` and a genrule `foo_gen`. - -* In most cases, optional parameters should have a default value of `None`. - `None` can be passed directly to native rules, which treat it the same as if - you had not passed in any argument. Thus, there is no need to replace it - with `0`, `False`, or `[]` for this purpose. Instead, the macro should defer - to the rules it creates, as their defaults may be complex or may change over - time. Additionally, a parameter that is explicitly set to its default value - looks different than one that is never set (or set to `None`) when accessed - through the query language or build-system internals. - -* Macros should have an optional `visibility` argument. - -## Full example - -The typical use-case for a macro is when you want to reuse a genrule, e.g. - -``` -genrule( - name = "file", - outs = ["file.txt"], - cmd = "$(location generator) some_arg > $@", - tools = [":generator"], -) -``` - -If you want to generate another file with different arguments, you may want to -extract this code to a function. - -The BUILD file will become simply: - -``` -load("//path:generator.bzl", "file_generator") - -file_generator( - name = "file", - arg = "some_arg", -) -``` - -In order to keep BUILD files clean and declarative, you must put the function in -a separate `.bzl` file. For example, write the definition of the macro in -`path/generator.bzl`: - -``` -def file_generator(name, arg, visibility=None): - native.genrule( - name = name, - outs = [name + ".txt"], - cmd = "$(location generator) %s > $@" % arg, - tools = ["//test:generator"], - visibility = visibility, - ) -``` - -When you want to investigate what a macro does, use the following command to -see the expanded form: - -``` -$ bazel query --output=build :file -# /absolute/path/test/ext.bzl:42:3 -genrule( - name = "file", - tools = ["//test:generator"], - outs = ["//test:file.txt"], - cmd = "$(location generator) some_arg > $@", -) -``` - diff --git a/site/versions/master/docs/skylark/repository_rules.md b/site/versions/master/docs/skylark/repository_rules.md deleted file mode 100644 index c6890062ef..0000000000 --- a/site/versions/master/docs/skylark/repository_rules.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -layout: documentation -title: Repository Rules ---- -# Repository Rules - -**Status: Experimental**. We may make breaking changes to the API, but we will - announce them and help you update your code. - -An [external repository](/docs/external.md) is a rule that can be used only -in the `WORKSPACE` file and enable non-hermetic operation at the loading phase -of Bazel. Each external repository rule creates its own workspace, with its -own BUILD files and artifacts. They can be used to depend on third-party -libraries (such as Maven packaged libraries) but also to generate BUILD files -specific to the host Bazel is running on. - -## Repository Rule creation - -In a `.bzl` file, use the -[repository_rule](lib/globals.html#repository_rule) function to create a new -repository rule and store it in a global variable. - -A custom repository rule can be used just like a native repository rule. It -has a mandatory `name` attribute and every target present in its build files -can be referred as `@<name>//package:target` where `<name>` is the value of the -`name` attribute. - -The rule is loaded when you explicitly build it, or if it is a dependency of -the build. In this case, Bazel will execute its `implementation` function. This -function describe how to creates the repository, its content and BUILD files. - -## Attributes - -An attribute is a rule argument, such as `url` or `sha256`. You must list -the attributes and their types when you define a repository rule. - -```python -local_repository = repository_rule( - implementation=_impl, - local=True, - attrs={"path": attr.string(mandatory=True)}) -``` - -`name` attributes are implicitly defined for all `repository_rule`s. -To access an attribute, use `repository_ctx.attr.<attribute_name>`. -The name of a repository rule is accessible with `repository_ctx.name`. - -If an attribute name starts with `_` it is private and users cannot set it. - -## Implementation function - -Every repository rule requires an `implementation` function. It contains the -actual logic of the rule and is executed strictly in the Loading Phase. -The function has exactly one input parameter, `repository_ctx`, and should -always returns `None`. The input parameter `repository_ctx` can be used to -access attribute values, and non-hermetic functions (finding a binary, -executing a binary, creating a file in the repository or downloading a file -from the Internet). See [the library](lib/repository_ctx.html) for more -context. Example: - -```python -def _impl(repository_ctx): - repository_ctx.symlink(repository_ctx.attr.path, "") - -local_repository = repository_rule( - implementation=_impl, - ...) -``` - -## When is the implementation function executed? - -If the repository is declared as `local` then change in a dependency -in the dependency graph (including the WORKSPACE file itself) will -cause an execution of the implementation function. - -The implementation function can be _restarted_ if a dependency it -request is _missing_. The beginning of the implementation function -will be re-executed after the dependency has been resolved. - -File given as a label are declared as dependencies, so requesting it -might interrupt the function and restart it later, re-executing the -part up till there. - -Finally, for non-`local` repositories, only a change in the following -dependencies might cause a restart: - -- Skylark files needed to define the repository rule. -- Declaration of the repository rule in the `WORKSPACE` file. -- Value of any environment variable declared with the `environ` -attribute of the -[`repository_rule`](https://bazel.build/versions/master/docs/skylark/lib/globals.html#repository_rule) -function. The value of those environment variable can be enforced from -the command line with the -[`--action_env`](/docs/command-line-reference.html#flag--action_env) -flag (but this flag will invalidate every action of the build). -- Content of any file used and referred to by a label (e.g., - `//mypkg:label.txt` not `mypkg/label.txt`). - -## Examples - -- [C++ auto-configured toolchain](https://github.com/bazelbuild/bazel/blob/ac29b78000afdb95afc7e97efd2b1299ebea4dac/tools/cpp/cc_configure.bzl#L288): -it uses a repository rule to automatically create the -C++ configuration files for Bazel by looking for the local C++ compiler, the -environment and the flags the C++ compiler supports. -- - [Go repositories](https://github.com/bazelbuild/rules_go/blob/67bc217b6210a0922d76d252472b87e9a6118fdf/go/private/go_repositories.bzl#L195) - uses several `repository_rule` to defines the list of dependencies - needed to use the Go rules. -- - [maven_jar](https://github.com/bazelbuild/bazel/a110ac400190c90a45856f15482c8d0952c542f5/master/tools/build_defs/repo/maven_rules.bzl#L276) - is a reimplementation of the native `maven_jar` rule using the - `maven` tool. - diff --git a/site/versions/master/docs/skylark/rules.md b/site/versions/master/docs/skylark/rules.md deleted file mode 100644 index 47f27abb13..0000000000 --- a/site/versions/master/docs/skylark/rules.md +++ /dev/null @@ -1,596 +0,0 @@ ---- -layout: documentation -title: Rules ---- -# Rules - -**Status: Experimental**. We may make breaking changes to the API, but we will - help you update your code. - -A rule defines a series of [actions](#actions) that Bazel should perform on -inputs to get a set of outputs. For example, a C++ binary rule might take a set -of `.cpp` files (the inputs), run `g++` on them (the action), and return an -executable file (the output). - -Note that, from Bazel's perspective, `g++` and the standard C++ libraries are -also inputs to this rule. As a rule writer, you must consider not only the -user-provided inputs to a rule, but also all of the tools and libraries required -to execute the actions (called _implicit inputs_). - -Before creating or modifying any rule, make sure you are familiar with the -[extensibility model](concepts.md) (understand the three phases and the -differences between macros and rules). - -## Rule creation - -In a `.bzl` file, use the [rule](lib/globals.html#rule) -function to create a new rule and store it in a global variable: - -```python -my_rule = rule(...) -``` - -See [the cookbook](cookbook.md#empty) for examples. The rule can then be -loaded by BUILD files: - -```python -load('//some/pkg:whatever.bzl', 'my_rule') -``` - -A custom rule can be used just like a native rule. It has a mandatory `name` -attribute, you can refer to it with a label, and you can see it in -`bazel query`. - -The rule is analyzed when you explicitly build it, or if it is a dependency of -the build. In this case, Bazel will execute its `implementation` function. This -function decides what the outputs of the rule are and how to build them (using -[actions](#actions)). During the [analysis phase](concepts.md#evaluation-model), -no external command can be executed. Instead, actions are registered and -will be run in the execution phase, if their output is needed for the build. - -## Attributes - -An attribute is a rule argument, such as `srcs` or `deps`. You must list -the attributes and their types when you define a rule. - -```python -sum = rule( - implementation = _impl, - attrs = { - "number": attr.int(default = 1), - "deps": attr.label_list(), - }, -) -``` - -The following attributes are implicitly added to every rule: `deprecation`, -`features`, `name`, `tags`, `testonly`, `visibility`. Test rules also have the -following attributes: `args`, `flaky`, `local`, `shard_count`, `size`, -`timeout`. - -Labels listed in `attr` will be inputs to the rule. - -To access an attribute in a rule's implementation, use -`ctx.attr.<attribute_name>`. The name and the package of a rule are available -with `ctx.label.name` and `ctx.label.package`. - -See [an example](cookbook.md#attr) of using `attr` in a rule. - -### <a name="private-attributes"></a> Private Attributes - -In Python, we use one leading underscore(`_`) for non-public methods and -instance variables (see [PEP-8][1]). - -Similarly, if an attribute name starts with `_` it is private and users cannot -set it. -It is useful in particular for label attributes (your rule will have an -implicit dependency on this label). - -```python -metal_compile = rule( - implementation = _impl, - attrs = { - "srcs": attr.label_list(), - "_compiler": attr.label( - default = Label("//tools:metalc"), - allow_single_file = True, - executable = True, - ), - }, -) -``` - -## Implementation function - -Every rule requires an `implementation` function. It contains the actual logic -of the rule and is executed strictly in the -[analysis phase](concepts.md#evaluation-model). The function has exactly one -input parameter, `ctx`, and it may return the [runfiles](#runfiles) -and [providers](#providers) of the rule. The input parameter `ctx` can be used -to access attribute values, outputs and dependent targets, and files. It also -has some helper functions. See [the library](lib/ctx.html) for more context. -Example: - -```python -def _impl(ctx): - ... - return [DefaultInfo(runfiles=...), MyInfo(...)] - -my_rule = rule( - implementation = _impl, - ... -) -``` - -## Files - -There are two kinds of files: files stored in the file system and generated -files. For each generated file, there must be one and only one generating -action, and each action must generate one or more output files. Bazel will throw -an error otherwise. - -## Targets - -Every build rule corresponds to exactly one target. A target can create -[actions](#actions), can have dependencies (which can be files or -other build rules), [output files](#output-files) (generated by -its actions), and [providers](#providers). - -A target `y` depends on target `x` if `y` has a label or label list type -attribute where `x` is declared: - -```python -my_rule( - name = "x", -) - -my_rule( - name = "y", - deps = [":x"], -) -``` - -In the above case, it's possible to access targets declared in `my_rule.deps`: - -```python -def _impl(ctx): - for dep in ctx.attr.deps: - # Do something with dep - ... - -my_rule = rule( - implementation = _impl, - attrs = { - "deps": attr.label_list(), - }, - ... -) -``` - -## <a name="output-files"></a> Output files - -A target can declare output files, which must be generated by the target's -actions. There are three ways to create output files: - -* If the rule is marked `executable`, it creates an output file of the same name - as the rule's. [See example](cookbook.md#outputs-executable) - -* The rule can declare default `outputs`, which are always generated. - [See example](cookbook.md#outputs-default) - -* The rule can have output or output list type attributes. In that case the - output files come from the actual attribute values. - [See example](cookbook.md#outputs-custom) - -Each output file must have exactly one generating action. See the -[library](lib/ctx.html#outputs) for more context. - -## Default outputs - -Every rule has a set of default outputs. This is used: - -* When the user runs `bazel build` on your target. Bazel will build the default - outputs of the rule. - -* When the target is used as a dependency of another rule. A rule can access - the default outputs by using [target.files](lib/Target.html#files). - This is the case, for example, if you use a rule in the `srcs` attribute of a - `genrule`. - -Use the `files` provider to specify the default outputs of a rule. -If left unspecified, it will contain all the declared outputs. - -```python -def _impl(ctx): - # ... - return DefaultInfo(files=depset([file1, file2])) -``` - -This can be useful for exposing files generated with -[ctx.new_file](lib/ctx.html#new_file). You can also have "implicit -outputs", i.e., files that are declared in the rule, but not in the default -outputs (like `_deploy.jar` in `java_binary`). - -## Actions - -An action describes how to generate a set of outputs from a set of inputs, for -example "run gcc on hello.c and get hello.o". When an action is created, Bazel -doesn't run the command immediately. It registers it in a graph of dependencies, -because an action can depend on the output of another action (e.g. in C, -the linker must be called after compilation). In the execution phase, Bazel -decides which actions must be run and in which order. - -There are three ways to create actions: - -* [ctx.action](lib/ctx.html#action), to run a command. -* [ctx.file_action](lib/ctx.html#file_action), to write a string to a file. -* [ctx.template_action](lib/ctx.html#template_action), to generate a file from a template. - -Actions take a set (which can be empty) of input files and generate a (non-empty) -set of output files. -The set of input and output files must be known during the -[analysis phase](concepts.md#evaluation-model). It might depend on the value -of attributes and information from dependencies, but it cannot depend on the -result of the execution. For example, if your action runs the unzip command, you -must specify which files you expect to be inflated (before running unzip). - -Actions are comparable to pure functions: They should depend only on the -provided inputs, and avoid accessing computer information, username, clock, -network, or I/O devices (except for reading inputs and writing outputs). This is -important because the output will be cached and reused. - -**If an action generates a file that is not listed in its outputs**: This is -fine, but the file will be ignored and cannot be used by other rules. - -**If an action does not generate a file that is listed in its outputs**: This is -an execution error and the build will fail. This happens for instance when a -compilation fails. - -**If an action generates an unknown number of outputs and you want to keep them -all**, you must group them in a single file (e.g., a zip, tar, or other -archive format). This way, you will be able to deterministically declare your -outputs. - -**If an action does not list a file it uses as an input**, the action execution -will most likely result in an error. The file is not guaranteed to be available -to the action, so if it **is** there, it's due to coincidence or error. - -**If an action lists a file as an input, but does not use it**: This is fine. -However, it can affect action execution order, resulting in sub-optimal -performance. - -Dependencies are resolved by Bazel, which will decide which actions are -executed. It is an error if there is a cycle in the dependency graph. Creating -an action does not guarantee that it will be executed: It depends on whether -its outputs are needed for the build. - -## Configurations - -Imagine that you want to build a C++ binary and target a different architecture. -The build can be complex and involve multiple steps. Some of the intermediate -binaries, like the compilers and code generators, have to run on your machine -(the host); some of the binaries such the final output must be built for the -target architecture. - -For this reason, Bazel has a concept of "configurations" and transitions. The -topmost targets (the ones requested on the command line) are built in the -"target" configuration, while tools that should run locally on the host are -built in the "host" configuration. Rules may generate different actions based on -the configuration, for instance to change the cpu architecture that is passed to -the compiler. In some cases, the same library may be needed for different -configurations. If this happens, it will be analyzed and potentially built -multiple times. - -By default, Bazel builds the dependencies of a target in the same configuration -as the target itself, i.e. without transitioning. When a target depends on a -tool, the label attribute will specify a transition to the host configuration. -This causes the tool and all of its dependencies to be built for the host -machine, assuming those dependencies do not themselves have transitions. - -For each [label attribute](lib/attr.html#label), you can decide whether the -dependency should be built in the same configuration, or transition to the host -configuration (using `cfg`). If a label attribute has the flag -`executable=True`, the configuration must be set explicitly. -[See example](cookbook.html#execute-a-binary) - -In general, sources, dependent libraries, and executables that will be needed at -runtime can use the same configuration. - -Tools that are executed as part of the build (e.g., compilers, code generators) -should be built for the host configuration. In this case, specify `cfg="host"` -in the attribute. - -Otherwise, executables that are used at runtime (e.g. as part of a test) should -be built for the target configuration. In this case, specify `cfg="target"` in -the attribute. - -The configuration `"data"` is present for legacy reasons and should be used for -the `data` attributes. - -## <a name="fragments"></a> Configuration Fragments - -Rules may access [configuration fragments](lib/skylark-configuration-fragment.html) -such as `cpp`, `java` and `jvm`. However, all required fragments must be -declared in order to avoid access errors: - -```python -def _impl(ctx): - # Using ctx.fragments.cpp would lead to an error since it was not declared. - x = ctx.fragments.java - ... - -my_rule = rule( - implementation = _impl, - fragments = ["java"], # Required fragments of the target configuration - host_fragments = ["java"], # Required fragments of the host configuration - ... -) -``` - -`ctx.fragments` only provides configuration fragments for the target -configuration. If you want to access fragments for the host configuration, -use `ctx.host_fragments` instead. - -## Providers - -Providers are pieces of information that a rule exposes to other rules that -depend on it. This data can include output files, libraries, parameters to pass -on a tool's command line, or anything else the depending rule should know about. -Providers are the only mechanism to exchange data between rules, and can be -thought of as part of a rule's public interface (loosely analogous to a -function's return value). - -A rule can only see the providers of its direct dependencies. If there is a rule -`top` that depends on `middle`, and `middle` depends on `bottom`, then we say -that `middle` is a direct dependency of `top`, while `bottom` is a transitive -dependency of `top`. In this case, `top` can see the providers of `middle`. The -only way for `top` to see any information from `bottom` is if `middle` -re-exports this information in its own providers; this is how transitive -information can be accumulated from all dependencies. In such cases, consider -using [depsets](depsets.md) to hold the data more efficiently without excessive -copying. - -Providers can be declared using the [provider()](lib/globals.html#provider) function: - -```python -TransitiveDataInfo = provider() -``` - -Rule implementation function can then construct and return provider instances: - -```python -def rule_implementation(ctx): - ... - return [TransitiveDataInfo(value = ["a", "b", "c"])] -``` - -`TransitiveDataInfo` acts both as a constructor for provider instances and as a key to access them. -A [target](lib/Target.html) serves as a map from each provider that the target supports, to the -target's corresponding instance of that provider. -A rule can access the providers of its dependencies using the square bracket notation (`[]`): - -```python -def dependent_rule_implementation(ctx): - ... - s = depset() - for dep_target in ctx.attr.deps: - s += dep_target[TransitiveDataInfo].value - ... -``` - -All targets have a [`DefaultInfo`](lib/globals.html#DefaultInfo) provider that can be used to access -some information relevant to all targets. - -Providers are only available during the analysis phase. Examples of usage: - -* [mandatory providers](cookbook.md#mandatory-providers) -* [optional providers](cookbook.md#optional-providers) - -> *Note:* -> Historically, Bazel also supported provider instances that are identified by strings and -> accessed as fields on the `target` object instead of as keys. This style is deprecated -> but still supported. Return legacy providers as follows: -> -```python -def rule_implementation(ctx): - ... - modern_provider = TransitiveDataInfo(value = ["a", "b", "c"]) - # Legacy style. - return struct(legacy_provider = struct(...), - another_legacy_provider = struct(...), - # The `providers` field contains provider instances that can be accessed - # the "modern" way. - providers = [modern_provider]) -``` -> To access legacy providers, use the dot notation. -> Note that the same target can define both modern and legacy providers: -> -```python -def dependent_rule_implementation(ctx): - ... - s = depset() - for dep_target in ctx.attr.deps: - x = dep_target.legacy_provider # legacy style - s += dep_target[TransitiveDataInfo].value # modern style - ... -``` -> **We recommend using modern providers for all future code.** - -## Runfiles - -Runfiles are a set of files used by the (often executable) output of a rule -during runtime (as opposed to build time, i.e. when the binary itself is -generated). -During the [execution phase](concepts.md#evaluation-model), Bazel creates a -directory tree containing symlinks pointing to the runfiles. This stages the -environment for the binary so it can access the runfiles during runtime. - -Runfiles can be added manually during rule creation and/or collected -transitively from the rule's dependencies: - -```python -def _rule_implementation(ctx): - ... - transitive_runfiles = depset() - for dep in ctx.attr.special_dependencies: - transitive_runfiles += dep.transitive_runtime_files - - runfiles = ctx.runfiles( - # Add some files manually. - files = [ctx.file.some_data_file], - # Add transitive files from dependencies manually. - transitive_files = transitive_runfiles, - # Collect runfiles from the common locations: transitively from srcs, - # deps and data attributes. - collect_default = True, - ) - # Add a field named "runfiles" to the DefaultInfo provider in order to actually - # create the symlink tree. - return [DefaultInfo(runfiles=runfiles)] -``` - -Note that non-executable rule outputs can also have runfiles. For example, a -library might need some external files during runtime, and every dependent -binary should know about them. - -Also note that if an action uses an executable, the executable's runfiles can -be used when the action executes. - -Normally, the relative path of a file in the runfiles tree is the same as the -relative path of that file in the source tree or generated output tree. If these -need to be different for some reason, you can specify the `root_symlinks` or -`symlinks` arguments. The `root_symlinks` is a dictionary mapping paths to -files, where the paths are relative to the root of the runfiles directory. The -`symlinks` dictionary is the same, but paths are implicitly prefixed with the -name of the workspace. - -```python - ... - runfiles = ctx.runfiles( - root_symlinks = {"some/path/here.foo": ctx.file.some_data_file2} - symlinks = {"some/path/here.bar": ctx.file.some_data_file3} - ) - # Creates something like: - # sometarget.runfiles/ - # some/ - # path/ - # here.foo -> some_data_file2 - # <workspace_name>/ - # some/ - # path/ - # here.bar -> some_data_file3 -``` - -If `symlinks` or `root_symlinks` is used, be careful not to map two different -files to the same path in the runfiles tree. This will cause the build to fail -with an error describing the conflict. To fix, you will need to modify your -`ctx.runfiles` arguments to remove the collision. This checking will be done for -any targets using your rule, as well as targets of any kind that depend on those -targets. - -## Output groups - -By default Bazel builds a target's -[default outputs](#default-outputs). However, a rule can also create - other outputs that are not part of a typical build but might still be useful, - such as debug information files. The facility for this is _output groups_. - -A rule can declare that a certain file belongs to a certain output group by returning -the [OutputGroupInfo](lib/globals.html#OutputGroupInfo) provider. Fields of -that provider are output group names: - -```python -def _impl(ctx): - name = ... - binary = ctx.new_file(name) - debug_file = ctx.new_file(name + ".pdb") - # ... add actions to generate these files - return [DefaultInfo(files = depset([binary])), - OutputGroupInfo(debug_files = depset([debug_file]), - all_files = depset([binary, debug_file]))] -``` - -By default, only the `binary` file will be built. -The user can specify an [`--output_groups=debug_files`](../command-line-reference.html#build) -flag on the command line. In that case, only `debug_file` will be built. If the user -specifies `--output_groups=all_files`, both `binary` and `debug_file` will be build. - -> Note: [OutputGroupInfo](skylark/lib/globals.html#OutputGroupInfo) is a regular -> [provider](#providers), and dependencies of a target can examine it using -> the `target[OutputGroupInfo]` syntax. - -## Code coverage instrumentation - -A rule can use the `instrumented_files` provider to provide information about -which files should be measured when code coverage data collection is enabled: - -```python -def _rule_implementation(ctx): - ... - return struct(instrumented_files = struct( - # Optional: File extensions used to filter files from source_attributes. - # If not provided, then all files from source_attributes will be - # added to instrumented files, if an empty list is provided, then - # no files from source attributes will be added. - extensions = ["ext1", "ext2"], - # Optional: Attributes that contain source files for this rule. - source_attributes = ["srcs"], - # Optional: Attributes for dependencies that could include instrumented - # files. - dependency_attributes = ["data", "deps"])) -``` - -[ctx.config.coverage_enabled](lib/configuration.html#coverage_enabled) notes -whether coverage data collection is enabled for the current run in general -(but says nothing about which files specifically should be instrumented). -If a rule implementation needs to add coverage instrumentation at -compile-time, it can determine if its sources should be instrumented with -[ctx.coverage_instrumented](lib/ctx.html#coverage_instrumented): - -```python -# Are this rule's sources instrumented? -if ctx.coverage_instrumented(): - # Do something to turn on coverage for this compile action -``` - -Note that function will always return false if `ctx.config.coverage_enabled` is -false, so you don't need to check both. - -If the rule directly includes sources from its dependencies before compilation -(e.g. header files), it may also need to turn on compile-time instrumentation -if the dependencies' sources should be instrumented. In this case, it may -also be worth checking `ctx.config.coverage_enabled` so you can avoid looping -over dependencies unnecessarily: - -```python -# Are this rule's sources or any of the sources for its direct dependencies -# in deps instrumented? -if ctx.config.coverage_enabled: - if (ctx.coverage_instrumented() or - any(ctx.coverage_instrumented(dep) for dep in ctx.attr.deps): - # Do something to turn on coverage for this compile action -``` - -## Executable rules - -An executable rule is a rule that users can run using `bazel run`. - -To make a rule executable, set `executable=True` in the -[rule function](lib/globals.html#rule). The `implementation` function of the -rule must generate the output file `ctx.outputs.executable`. -[See example](cookbook.md#outputs-executable) - -## Test rules - -Test rules are run using `bazel test`. - -To create a test rule, set `test=True` in the -[rule function](lib/globals.html#rule). The name of the rule must -also end with `_test`. Test rules are implicitly executable, which means that -the `implementation` function of the rule must generate the output file -`ctx.outputs.executable`. - -Test rules inherit the following attributes: `args`, `flaky`, `local`, -`shard_count`, `size`, `timeout`. - -[1]: https://www.python.org/dev/peps/pep-0008/#id46 diff --git a/site/versions/master/docs/support.md b/site/versions/master/docs/support.md deleted file mode 100644 index 407cec8e0c..0000000000 --- a/site/versions/master/docs/support.md +++ /dev/null @@ -1,257 +0,0 @@ ---- -layout: documentation -title: Get Support ---- - -# Get Support - -* Ask questions on [Stack Overflow](http://stackoverflow.com/questions/tagged/bazel) using the -`bazel` tag. -* Discuss on the [User mailing list](https://groups.google.com/forum/#!forum/bazel-discuss). -* Report bugs or feature requests in our [GitHub issue tracker](https://github.com/bazelbuild/bazel/issues). -* Find other Bazel contributors on [IRC](http://webchat.freenode.net) -(irc.freenode.net#bazel). - -# Support Policy - -We generally avoid making backwards-incompatible changes. We have several years of experience with -supporting a huge code base that is concurrently worked on by thousands of engineers every day, -and have successfully made significant changes to the core as well as to the rules without missing -a beat. We run hundreds of thousands of tests at Google before every single release to ensure that -it stays that way. - -That said, we occasionally have to make incompatible changes in order to fix bugs, to make further -improvements to the system, such as improving performance or usability, or to lock down APIs that -are known to be brittle. - -This document gives an overview of features that are widely used and that we consider stable. By -stable, we mean that the changes we make will be backwards compatible, or that we will provide a -migration path. - -It also covers features that are unstable. Either they are not yet widely used, or we are already -planning to change them significantly, possibly in ways that are not backwards compatible. - -We cannot cover everything that might change, but you can reasonably expect that we provide -advance notice on the mailing list before a major change happens. We're also happy to provide more -details, just ask on [bazel-discuss](https://groups.google.com/forum/#!forum/bazel-discuss). - -All undocumented features (attributes, rules, "Make" variables, and flags) are subject to change -at any time without prior notice. Features that are documented but marked *experimental* are also -subject to change at any time without prior notice. - -Bazel's extension language Skylark (anything you write in a `.bzl` file) is still subject to change. -We are in the process of migrating Google to Skylark, and expect the language part to extend macros -to stabilize as part of that process. Adding rules with skylark is still somewhat experimental. - -Help keep us honest: report bugs and regressions in the -[GitHub bugtracker](https://github.com/bazelbuild/bazel/issues). We will make an effort to triage all -reported issues within 2 business days. - -## Releases - -We regularly publish [binary releases of Bazel](https://github.com/bazelbuild/bazel/releases). To -that end, we announce release candidates on -[bazel-discuss](https://groups.google.com/forum/#!forum/bazel-discuss); these are binaries that have -passed all of our unit tests. Over the next few days, we regression test all applicable build -targets at Google. If you have a critical project using Bazel, we recommend that you establish an -automated testing process that tracks the current release candidate, and report any regressions. - -If no regressions are discovered, we officially release the candidate after a week. However, -regressions can delay the release of a release candidate. If regressions are found, we apply -corresponding cherry-picks to the release candidate to fix those regressions. If no further -regressions are found for two business days, but not before a week has elapsed since the first -release candidate, we release it. - -### Release versioning - -Version 0.1 is our first release marking the start of our beta phase. Until version 1.0.0, we -increase the MINOR version every time we reach a [new milestone](http://bazel.build/roadmap.html). - -Version 1.0.0 marks the end of our beta phase; afterwards, we will label each release with a -version number of the form MAJOR.MINOR.PATCH according to the -[semantic version 2.0.0 document](http://semver.org). - -## Current Status - -### Built-In Rules and the Internal API For Rules ### -We are planning a number of changes to the APIs between the core of Bazel and the built-in rules, -in order to make it easier for us to develop openly. This has the added benefit of also making it -easier for users to maintain their own rules (if written in Java instead of Skylark), if they don't -want to or cannot check this code into our repository. However, it also means our internal API is -not stable yet. In the long term, we want to move to Skylark wholesale, so we encourage contributors -to use Skylark instead of Java when writing new rules. Rewriting all of our built-in rules is going -to be a lengthy process however. - -1. We will fix the friction points that we know about, as well as those that we discover every time - we make changes that span both the internal and external depots. -2. We will drive a number of pending API cleanups to completion, as well as run anticipated cleanups - to the APIs, such as disallowing access to the file system from rule implementations (because - it's not hermetic). -3. We will enumerate the internal rule APIs, and make sure that they are appropriately marked (for - example with annotations) and documented. Just collecting a list will likely give us good - suggestions for further improvements, as well as opportunities for a more principled API review - process. -4. We will automatically check rule implementations against an API whitelist, with the intention - that API changes are implicitly flagged during code review. -5. We will work on removing (legacy) Google-internal features to reduce the amount of differences - between the internal and external rule sets. -6. We will encourage our engineers to make changes in the external depot first, and migrate them to - to the internal one afterwards. -7. We will move more of our rule implementations into the open source repository (Android, Go, - Python, the remaining C++ rules), even if we don't consider the code to be *ready* or if they are - still missing tools to work properly. -8. In order to be able to accept external contributions, our highest priority item for Skylark is a - testing framework. We encourage to write new rules in Skylark rather than in Java. - - -### Stable -We expect the following rules and features to be stable. They are widely used within Google, so -our internal testing should ensure that there are no major breakages. - -<table class="table table-condensed table-striped table-bordered"> - <colgroup> - <col class="support-col-rules" /> - <col class="support-col-notes" /> - </colgroup> - <thead> - <tr> - <th>Rules</th> - <th>Notes</th> - </tr> - </thead> - <tbody> - <tr> - <td>C/C++ rules except <code>cc_toolchain</code> and <code>cc_toolchain_suite</code></td> - <td></td> - </tr> - <tr> - <td>Java rules except <code>java_toolchain</code></td> - <td></td> - </tr> - <tr> - <td>Android rules except <code>android_ndk_repository</code> and - <code>android_sdk_repository</code></td> - <td></td> - </tr> - <tr> - <td><code>genrule</code></td> - <td></td> - </tr> - <tr> - <td><code>genquery</code></td> - <td></td> - </tr> - <tr> - <td><code>test_suite</code></td> - <td></td> - </tr> - <tr> - <td><code>filegroup</code></td> - <td></td> - </tr> - <tr> - <td><code>config_setting</code></td> - <td> - <ul> - <li>This rule is used in <code>select()</code> expressions. We have hundreds of uses, so - we expect the basic functionality to be stable. That said, there are some common use - cases that are not covered yet, or that require workarounds. For example, it's not - easily possible to select on information specified in a CROSSTOOL file, such as the - target abi. Another example is that it's not possible to OR multiple conditions, - leading to duplicated entries in the select. - </li> - </ul> - </td> - </tr> - </tbody> -</table> - - -### Unstable -These rules and features have known limitations that we will likely address in future releases. - -<table class="table table-condensed table-striped table-bordered"> - <colgroup> - <col class="support-col-rules" /> - <col class="support-col-notes" /> - </colgroup> - <thead> - <tr> - <th>Feature</th> - <th>Notes</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>cc_toolchain</code> and <code>cc_toolchain_suite</code></td> - <td> - <ul> - <li>We intend to make significant changes to the way C/C++ toolchains are defined; we will - keep our published C/C++ toolchain definition(s) up to date, but we make no guarantees for - custom ones.</li> - </ul> - </td> - </tr> - <tr> - <td>iOS/Objective C rules</td> - <td> - <ul> - <li>We cannot vouch for changes made by Apple ® to the underlying tools and - infrastructure.</li> - <li>The rules are fairly new and still subject to change; we try to avoid breaking changes, - but this may not always be possible.</li> - <li>No testing support yet.</li> - </ul> - </td> - </tr> - <tr> - <td>Python rules</td> - <td> - <ul> - <li>The rules support neither Python 3, C/C++ extensions, nor packaging. - </li> - </ul> - </td> - </tr> - <tr> - <td>Extra actions (<code>extra_action</code>, <code>action_listener</code>)</td> - <td> - <ul> - <li>Extra actions expose information about Bazel that we consider to be implementation - details, such as the exact interface between Bazel and the tools we provide; as such, - users will need to keep up with changes to tools to avoid breakage.</li> - </ul> - </td> - </tr> - <tr> - <td><code>environment_group</code></td> - <td> - <ul> - <li>We're planning to use it more extensively, replacing several machine-enforceable - constraint mechanism, but there's only a handful of uses so far. We fully expect it to - work, but there's a small chance that we have to go back to the drawing board.</li> - </ul> - </td> - </tr> - <tr> - <td><code>android_ndk_repository</code> and <code>android_sdk_repository</code></td> - <td> - <ul> - <li>We don't support pre-release NDKs or SDKs at this time. Furthermore, we may still - make backwards-incompatible changes to the attributes or the semantics.</li> - </ul> - </td> - </tr> - <tr> - <td><code>Fileset</code></td> - <td> - <ul> - <li>There are vestiges of Fileset / FilesetEntry in the source code, but we do not intend to - support them in Bazel, ever.</li> - <li>They're still widely used internally, and are therefore unlikely to go away in the near - future.</li> - </ul> - </td> - </tbody> -</table> - diff --git a/site/versions/master/docs/test-encyclopedia.html b/site/versions/master/docs/test-encyclopedia.html deleted file mode 100644 index 76e326283b..0000000000 --- a/site/versions/master/docs/test-encyclopedia.html +++ /dev/null @@ -1,490 +0,0 @@ ---- -layout: documentation -title: Test Encyclopedia ---- -<h1>Writing tests</h1> - -<p class="lead">An Exhaustive Specification of the Test Execution Environment</p> - -<h2>Background</h2> - -<p>The Bazel BUILD language includes rules which can be used to define -automated test programs in many languages.</p> - -<p>Tests are run using <code><a href="bazel-user-manual.html#test">bazel test</a></code>. - -Users may also execute test binaries directly. This is allowed but not endorsed, as such -an invocation will not adhere to the mandates described below.</p> - -<p>Tests should be <i>hermetic</i>: that is, they ought to access only those -resources on which they have a declared dependency. If tests are not properly -hermetic then they do not give historically reproducible results. This could be a -significant problem for culprit finding (determining which change broke a test), -release engineering auditability, and resource isolation of tests (automated -testing frameworks ought not DDOS a server because some tests happen to -talk to it).<p> - -<h2>Objective</h2> - -<p>The goal of this document is to formally establish the runtime environment -for and expected behavior of Bazel tests. It will also impose requirements on -the test runner and the build system. - -Our intent is to help test authors avoid relying on unspecified -behavior, and thus give the testing infrastructure more freedom to make -implementation changes. We will also take the opportunity to tighten up some -holes which currently allow many tests to pass despite not being -properly hermetic, deterministic, and reentrant.</p> - -<p>This document is intended to be both normative and authoritative. If -this specification and the implemented behavior of test runner disagree, the -specification takes precedence.</p> - - -<h3>Purpose of Tests</h3> - -<p>The purpose of Bazel tests is to confirm some property of the source files -checked into the repository. (In this document, "source files" includes test data, -golden outputs, and anything else kept under version control.) One -user writes a test to assert an invariant which they expect to be maintained. -Other users execute the test later to check whether the invariant has been -broken. If the test depends on any variables other than source files -(non-hermetic), its value is diminished, because the later users cannot be sure -their changes are at fault when the test stops passing.</p> - -<p>Therefore the outcome of a test must depend only on:</p> -<ul> - <li>source files on which the test has a declared dependency</li> - <li>products of the build system on which the test has a declared dependency</li> - <li>resources whose behavior is guaranteed by the test runner to remain constant</li> -</ul> - -<p>Currently, such behavior is not enforced. However, test runners reserve the -right to add such enforcement in the future.</p> - -<h3>Role of the Build System</h3> - -<p>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 language-specific harness with the test code. Test rules must produce other -outputs as well. In addition to the primary test executable, the test runner -will need a manifest of <b>runfiles</b>, input files which should be made -available to the test at runtime, and it may need information about the type, -size, and tags of a test.</p> - -<p>The build system may use the runfiles to deliver code as well as data. (This -might be used as an optimization to make each test binary smaller by sharing -files across tests, e.g. through the use of dynamic linking.) The build system -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.</p> - -<h3>Role of the Test Runner</h3> - -<p>From the point of view of the test runner, each test is a program which can -be invoked with <code>execve()</code>. There may be other ways to execute -tests; for example, an IDE might allow the execution of Java tests in-process. -However, the result of running the test as a standalone process must be -considered authoritative. If a test process runs to completion and terminates -normally with an exit code of zero, the test has passed. Any other result is -considered a test failure. In particular, writing any of the strings -<code>PASS</code> or <code>FAIL</code> to stdout has no significance to the test -runner.</p> - -<p>If a test takes too long to execute, exceeds some resource limit, or the test -runner otherwise detects prohibited behavior, it may choose to kill the test -and treat the run as a failure. The runner must not report the test as passing -after sending a signal to the test process or any children thereof.</p> - -<p id="timeout">The whole test target (not individual methods or tests) is given a -limited amount of time to run to completion. The time limit for a test is based -on its timeout attribute according to the following table:</p> - -<table class="table table-bordered table-striped table-condensed"> - <thead> - <tr><th>timeout</th><th>Time Limit (sec.)</th></tr> - </thead> - <tbody> - <tr><td><code>short</code></td><td>60</td></tr> - <tr><td><code>moderate</code></td><td>300</td></tr> - <tr><td><code>long</code></td><td>900</td></tr> - <tr><td><code>eternal</code></td><td>3600</td></tr> - </tbody> -</table> - -<p id="size">Tests which do not explicitly specify a timeout have one implied based on the -test's <code>size</code> as follows:</p> - -<table class="table table-bordered table-striped table-condensed"> - <thead> - <tr><th>size</th><th>Implied timeout label</th></tr> - </thead> - <tbody> - <tr><td><code>small</code></td><td>short</td></tr> - <tr><td><code>medium</code></td><td>moderate</td></tr> - <tr><td><code>large</code></td><td>long</td></tr> - <tr><td><code>enormous</code></td><td>eternal</td></tr> - </tbody> -</table> -<p>For example a "large" test with no explicit timeout setting will be allotted -900 seconds to run. A "medium" test with a timeout of "short" will be allotted -60 seconds.</p> - -<p>All combinations of <code>size</code> and <code>timeout</code> labels are -legal, so an "enormous" test may be declared to have a timeout of "short". -Presumably it would do some really horrible things very quickly.</p> -<p>Tests may return arbitrarily fast regardless of timeout. A test is not -penalized for an overgenerous timeout, although a warning may be issued: you -should generally set your timeout as tight as you can without incurring any -flakiness.</p> - -<p>There is also a recommended lower bound for test timeouts as follows: </p> - -<table class="table table-bordered table-striped table-condensed"> - <thead> - <tr><th>size</th><th>Time minimum (sec.)</th></tr> - </thead> - <tbody> - <tr><td><code>short</code></td><td>0</td></tr> - <tr><td><code>moderate</code></td><td>30</td></tr> - <tr><td><code>long</code></td><td>300</td></tr> - <tr><td><code>eternal</code></td><td>900</td></tr> - </tbody> -</table> - -<p>For example, if a "moderate" test completes in 5.5s, consider setting -<code>timeout</code>="short" or <code>size</code>="small". Using the bazel -<code>--test_verbose_timeout_warnings</code> command line option will show the -tests whose specified size is too big.</p> - -<p>Test sizes and timeouts are specified in the BUILD file according to the specification -<a href="be/common-definitions.html#common-attributes-tests">here</a>. -Any test that does not specify a recognized size will default to being a medium -test.</p> - -<p>If the main process of a test exits, but some of its children are still -running, 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.</p> - -<p>When executing a test, the test runner must establish certain initial -conditions.</p> - -<h3>Initial Conditions</h3> - -<p>The test runner must invoke each test with the path to the test -executable in <code>argv[0]</code>. This path must be relative and -beneath the test's current directory (which is in the runfiles tree, -see below). -The test runner should not pass any other arguments to a -test unless the user explicitly requests it.</p> - -<p>The initial environment block shall be composed as follows:</p> - -<table class="table table-bordered table-striped table-condensed"> - <thead> - <tr><th>Variable</th><th>Value</th><th>Status</th></tr> - </thead> - <tbody> - - <tr><td><code>HOME</code></td><td>value of <code>$TEST_TMPDIR</code></td><td>recommended</td></tr> - <tr><td><code>LANG</code></td><td><i>unset</i></td><td>required</td></tr> - <tr><td><code>LANGUAGE</code></td><td><i>unset</i></td><td>required</td></tr> - <tr><td><code>LC_ALL</code></td><td><i>unset</i></td><td>required</td></tr> - <tr><td><code>LC_COLLATE</code></td><td><i>unset</i></td><td>required</td></tr> - <tr><td><code>LC_CTYPE</code></td><td><i>unset</i></td><td>required</td></tr> - <tr><td><code>LC_MESSAGES</code></td><td><i>unset</i></td><td>required</td></tr> - <tr><td><code>LC_MONETARY</code></td><td><i>unset</i></td><td>required</td></tr> - <tr><td><code>LC_NUMERIC</code></td><td><i>unset</i></td><td>required</td></tr> - <tr><td><code>LC_TIME</code></td><td><i>unset</i></td><td>required</td></tr> - <tr><td><code>LD_LIBRARY_PATH</code></td><td>colon-separated list of directories containing shared libraries</td><td>optional</td></tr> - <tr><td><code>JAVA_RUNFILES</code></td><td>value of <code>$TEST_SRCDIR</code></td><td>deprecated</td></tr> - - <tr><td><code>LOGNAME</code></td><td>value of <code>$USER</code></td><td>required</td></tr> - - <tr><td><code>PATH</code></td><td><code>/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin:.</code></td><td>recommended</td></tr> - <tr><td><code>PWD</code></td><td><code>$TEST_SRCDIR/<i>workspace-name</i></code></td><td>recommended</td></tr> - <tr><td><code>SHLVL</code></td><td><code>2</code></td><td>recommended</td></tr> - <tr><td><code>TEST_PREMATURE_EXIT_FILE</code></td><td>absolute path to a private file in a writable directory (used for catching calls to exit())</td><td>optional</td></tr> - <tr> - <td><code>TEST_RANDOM_SEED</code></td> - <td colspan="2">If the <code class='flag'>--runs_per_test</code> option is used, TEST_RANDOM_SEED - is set to the <var>run number</var> (starting with 1) for each individual test run.</td> - <td>optional</td> - </tr> - <tr><td><code>TEST_SIZE</code></td><td>The test <a href="#size"><code>size</code></a></td><td>optional</td></tr> - <tr><td><code>TEST_TIMEOUT</code></td><td>The test <a href="#timeout"><code>timeout</code></a></td><td>optional</td></tr> - <tr><td><code>TEST_SRCDIR</code></td><td>absolute path to the base of the runfiles tree</td><td>required</td></tr> - <tr><td><code>TEST_TMPDIR</code></td><td>absolute path to a private writable directory</td><td>required</td></tr> - <tr><td><code>TEST_UNDECLARED_OUTPUTS_DIR</code></td><td>absolute path to a private writable directory (used to write undeclared test outputs)</td><td>optional</td></tr> - <tr><td><code>TEST_UNDECLARED_OUTPUTS_ANNOTATIONS_DIR</code></td><td>absolute path to a private writable directory (used to write undeclared test output annotation .part files). - - </td><td>optional</td></tr> - <tr><td><code>TEST_WARNINGS_OUTPUT_FILE</code></td><td>absolute path to a private file in a writable directory (used to write test target warnings)</td><td>optional</td></tr> - - <tr><td><code>TZ</code></td><td><code>UTC</code></td><td>required</td></tr> - <tr><td><code>USER</code></td><td>value of <code>getpwuid(getuid())->pw_name</code></td><td>required</td></tr> - - <tr><td><code>XML_OUTPUT_FILE</code></td><td>Location of the <code>ANT</code>-like XML output file</td><td>optional</td></tr> - <tr><td><code>TEST_WORKSPACE</code></td><td>the local repository's workspace name</td><td>optional</td></tr> - </tbody> -</table> -<br> -<p>The environment may contain additional entries. Tests should not depend on the -presence, absence, or value of any environment variable not listed above.</p> - -<p>The initial working directory shall be <code>$TEST_SRCDIR/$TEST_WORKSPACE</code>.</p> -<p> The current process id, process group id, session id, and parent process -id are unspecified. The process may or may not be a process group leader or a -session leader. The process may or may not have a controlling terminal. The -process may have zero or more running or unreaped child processes. The process -should not have multiple threads when the test code gains control.</p> - -<p>File descriptor 0 (stdin) shall be open for reading, but what it is attached -to is unspecified. Tests must not read from it. File descriptors 1 (stdout) -and 2 (stderr) shall be open for writing, but what they are attached to is -unspecified. It could be a terminal, a pipe, a regular file, or anything else -to which characters can be written. They may share an entry in the open file -table (meaning that they cannot seek independently). Tests should not inherit -any other open file descriptors.</p> - -<p>The initial umask shall be 022 or 027.</p> - -<p>No alarm or interval timer shall be pending.</p> - -<p>The initial mask of blocked signals shall be empty. All signals shall be set -to their default action.</p> - -<p>The initial resource limits, both soft and hard, should be set as follows:</p> - -<table class="table table-bordered table-striped table-condensed"> - <thead> - <tr><th>Resource</th><th>Limit</th></tr> - </thead> - <tbody> - <tr><td>RLIMIT_AS</td><td>unlimited</td></tr> - <tr><td>RLIMIT_CORE</td><td>unspecified</td></tr> - <tr><td>RLIMIT_CPU</td><td>unlimited</td></tr> - <tr><td>RLIMIT_DATA</td><td>unlimited</td></tr> - <tr><td>RLIMIT_FSIZE</td><td>unlimited</td></tr> - <tr><td>RLIMIT_LOCKS</td><td>unlimited</td></tr> - <tr><td>RLIMIT_MEMLOCK</td><td>unlimited</td></tr> - <tr><td>RLIMIT_MSGQUEUE</td><td>unspecified</td></tr> - <tr><td>RLIMIT_NICE</td><td>unspecified</td></tr> - <tr><td>RLIMIT_NOFILE</td><td>at least 1024</td></tr> - <tr><td>RLIMIT_NPROC</td><td>unspecified</td></tr> - <tr><td>RLIMIT_RSS</td><td>unlimited</td></tr> - <tr><td>RLIMIT_RTPRIO</td><td>unspecified</td></tr> - <tr><td>RLIMIT_SIGPENDING</td><td>unspecified</td></tr> - <tr><td>RLIMIT_STACK</td><td>unlimited, or 2044KB <= rlim <= 8192KB</td></tr> - </tbody> -</table> - -<p>The initial process times (as returned by <code>times()</code>) and resource -utilization (as returned by <code>getrusage()</code>) are unspecified.</p> - -<p>The initial scheduling policy and priority are unspecified.</p> - -<h3>Role of the Host System</h3> - -<p>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.</p> - -<h4>Filesystem</h4> - -<p> -The root directory observed by a test may or may not be the real root directory.<br> -<code>/proc</code> shall be mounted.<br> -All build tools shall be present at the absolute paths under <code>/usr</code> used by a local installation.<br> -Paths starting with <code>/home</code> may not be available. Tests should not access any such paths.<br> -<code>/tmp</code> and <code>/export/hda3/tmp</code> shall be writable, but tests should avoid using these paths.<br> - -Tests must not assume that any constant path is available for their exclusive use.<br> -Tests must not assume that atimes are enabled for any mounted filesystem.<br> -</p> - -<h4>Users and groups</h4> - -<p>The users root, nobody, and unittest must exist. The groups root, nobody, -and eng must exist.</p> - -<p>Tests must be executed as a non-root user. The real and effective user ids -must be equal; likewise for group ids. Beyond this, the current user id, group -id, user name, and group name are unspecified. The set of supplementary group -ids is unspecified.</p> - -<p>The current user id and group id must have corresponding names which can be -retrieved with <code>getpwuid()</code> and <code>getgrgid()</code>. The same -may not be true for supplementary group ids.</p> - -<p>The current user must have a home directory. It may not be writable. Tests -must not attempt to write to it.</p> - -<h4>Networking</h4> - -<p>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.</p> - -<h4>Other resources</h4> - -<p>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 increase the reservation to a higher number of CPU cores by adding the -tag "cpu:n" (where n is a positive number) to a test rule. If a machine has -less total CPU cores than requested, Bazel will still run the test. If a test -uses sharding, each individual shard will reserve the number of CPU cores -specified here.</p> - -<p>Tests may create subprocesses, but not process groups or sessions.</p> - -<p>There is a limit on both the number of input files a test may consume, and -their aggregate size. Such limits are subject to change, but are currently in -the range of tens of thousands of inputs and several GB of aggregate size.</p> - -<h4>Time and date</h4> - -<p>The current time and date are unspecified. The system timezone is unspecified. - -</p> - -<p>X Windows may or may not be available. Tests that need an X server should -start Xvfb.</p> - -<h3>Test interaction with the filesystem</h3> -<p>All file paths specified in test environment variables point to -somewhere on the local filesystem, unless otherwise specified.</p> - -<p> -Tests should create files only within the directories specified by -<code>$TEST_TMPDIR</code> and <code>$TEST_UNDECLARED_OUTPUTS_DIR</code> -(if set).<br> -These directories will be initially empty.<br> -Tests must not attempt to remove, chmod, or otherwise alter these directories.<br> -These directories may be a symbolic links.<br> -The filesystem type of <code>$TEST_TMPDIR/.</code> remains unspecified.<br> -Tests may also write .part files to the <code>$TEST_UNDECLARED_OUTPUTS_ANNOTATIONS_DIR</code> -to annotate undeclared output files.</p> - -<p>Tests must access inputs through the <b>runfiles</b> mechanism, or other -parts of the execution environment which are specifically intended to make -input files available. - -Tests must not access other outputs of the -build system at paths inferred from the location of their own executable.</p> - -<p>It is unspecified whether the runfiles tree contains regular files, symbolic -links, or a mixture. The runfiles tree may contain symlinks to directories. -Tests should avoid using paths containing <code>..</code> components within the -runfiles tree.</p> - -<p>No directory, file, or symlink within the runfiles tree (including paths -which traverse symlinks) should be writable. (It follows that the initial -working directory should not be writable.) Tests must not assume that any part -of the runfiles is writable, or owned by the current user (i.e. chmod and chgrp -may fail).</p> - -<p>The runfiles tree (including paths which traverse symlinks) must not change -during test execution. Parent directories and filesystem mounts must not change -in any way which affects the result of resolving a path within the runfiles -tree.</p> - -<p>In order to catch early exit, a test may create a file at the path specified by -<code>TEST_PREMATURE_EXIT_FILE</code> upon start and remove it upon exit. If -Bazel sees the file when the test finishes, it will assume that the test exited -prematurely and mark it as having failed.</p> - -<h3>Tag conventions</h3> - -<p> - Some tags in the test rules have a special - meaning. -</p> - -<table class="table table-bordered table-striped table-condensed"> - <thead> - <tr><th>Tag</th><th>Meaning</th></tr> - </thead> - <tbody> - <tr> - <th><code>exclusive</code></th> - - <td>run no other test at the same time</td> - </tr> - <tr> - <th><code>external</code></th> - <td>test has an external dependency; disable test caching</td> - </tr> - <tr> - <th><code>large</code></th> - <td><code>test_suite</code> convention; suite of large tests<br/> - - </td> - </tr> - - <tr> - <th><code>manual</code></th> - - <td>don't include test target in wildcard target patterns like <code>:...</code>, <code>:*</code>, or <code>:all</code>)</td> - </tr> - <tr> - <th><code>medium</code></th> - - <td><code>test_suite</code> convention; suite of medium tests - </tr> - - <tr> - <th><code>small</code></th> - - <td><code>test_suite</code> convention; suite of small tests</td> - </tr> - - <tr> - <th><code>smoke</code></th> - - <td> - <code>test_suite</code> convention; means it should be run before committing code changes - into the version control system - </td> - </tr> - - </tbody> -</table> - -<h3>Runfiles</h3> - -<p>In the following, assume there is a *_binary() rule labeled <code>//foo/bar:unittest</code>, -with a run-time dependency on the rule labeled <code>//deps/server:server</code>.</p> - -<h4>Location</h4> -<p>The runfiles directory for a target <code>//foo/bar:unittest</code> is the directory -<code>$(WORKSPACE)/$(BINDIR)/foo/bar/unittest.runfiles</code>. This path is referred to as the -<code>runfiles_dir</code>.</p> - -<h4>Dependencies</h4> -<p>The runfiles directory is declared as a compile-time dependency of the *_binary() rule. -The runfiles directory itself depends on the set of BUILD 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.</p> - -<h4>Contents</h4> -<p>The runfiles directory contains the following:</p> -<ul> - <li><b>Symlinks to run-time dependencies</b>: each OutputFile and CommandRule that is a run-time -dependency of the *_binary() rule is represented by one symlink in the runfiles directory. -The name of the symlink is <code>$(WORKSPACE)/package_name/rule_name</code>. For example, the -symlink for server would be named <code>$(WORKSPACE)/deps/server/server</code>, and the full path -would be <code>$(WORKSPACE)/foo/bar/unittest.runfiles/$(WORKSPACE)/deps/server/server</code>. -The destination of the symlink is the OutputFileName() of the OutputFile or CommandRule, -expressed as an absolute path. Thus, the destination of the symlink might be -<code>$(WORKSPACE)/linux-dbg/deps/server/42/server</code>.</li> - <li><b>Symlinks to sub-runfiles</b>: for every *_binary() Z that is a run-time depdendency of -*_binary() C, there is a second link in the runfiles directory of C to the runfiles of Z. -The name of the symlink is <code>$(WORKSPACE)/package_name/rule_name.runfiles</code>. -The target of the symlink is the runfiles directory. I.e. all subprograms share a common -runfiles directory.</li> -</ul> - diff --git a/site/versions/master/docs/tutorial/android-app.md b/site/versions/master/docs/tutorial/android-app.md deleted file mode 100644 index f31736b9f9..0000000000 --- a/site/versions/master/docs/tutorial/android-app.md +++ /dev/null @@ -1,295 +0,0 @@ ---- -layout: documentation -title: Tutorial - Build an Android App ---- - -# Tutorial - Build an Android App - -The sample Android app in this tutorial is a very simple application that makes -an HTTP connection to the [backend server](backend-server.md) and displays the -resulting response. - -Here, you'll do the following: - -* Review the source files for the app -* Update the `WORKSPACE` file -* Create a `BUILD` file -* Run the build -* Find the build outputs -* Run the app - -## Review the source files - -Let's take a look at the source files for the app. These are located in -`$WORKSPACE/android/`. - -The key files and directories are: - -<table class="table table-condensed table-striped"> -<thead> -<tr> -<td>Name</td> -<td>Location</td> -</tr> -</thead> -<tbody> -<tr> -<td>Manifest file</td> -<td><code>src/main/java/com/google/bazel/example/android/AndroidManifest.xml</code></td> -</tr> -<tr> -<td>Activity source file</td> -<td><code>src/main/java/com/google/bazel/example/android/activities/MainActivity.java</code></td> -</tr> -<tr> -<td>Resource file directory</td> -<td><code>src/main/java/com/google/bazel/example/android/res/</code></td> -</tr> -</tbody> -</table> - -Note that you're just looking at these files now to become familiar with the -structure of the app. You don't have to edit any of the source files to complete -this tutorial. - -## Update the WORKSPACE file - -Bazel needs to run the Android SDK -[build tools](https://developer.android.com/tools/revisions/build-tools.html) -and uses the SDK libraries to build the app. This means that you need to add -some information to your `WORKSPACE` file so that Bazel knows where to find -them. Note that this step is not required when you build for other platforms. -For example, Bazel automatically detects the location of Java, C++ and -Objective-C compilers from settings in your environment. - -Add the following lines to your `WORKSPACE` file: - -```python -android_sdk_repository( - name = "androidsdk", - # Replace with your installed Android SDK API level - api_level = 25 -) -``` - -This will use the Android SDK specified referenced by the `ANDROID_HOME` -environment variable, and automatically detect the latest build tools -version installed within that location. - -Alternatively, you can explicitly specify the location of the Android -SDK and build tools version to use by including the `path` and -`build_tools_version` attributes: - -```python -android_sdk_repository( - name = "androidsdk", - path = "/path/to/Android/sdk", - api_level = 25, - build_tools_version = "25.0.1" -) -``` - -**Optional:** This is not required by this tutorial, but if you want to compile -native code into your Android app, you also need to download the -[Android NDK](https://developer.android.com/ndk/downloads/index.html) and -tell Bazel where to find it by adding the following rule to your `WORKSPACE` -file: - -```python -android_ndk_repository( - name = "androidndk", - # Replace with the Android NDK API level - api_level = 21 -) -``` - -`api_level` is the version of the Android API the SDK and the NDK target -(for example, 19 for Android K and 21 for Android L). It's not necessary to set -the API levels to the same value for the SDK and NDK. -[This web page](https://developer.android.com/ndk/guides/stable_apis.html) -contains a map from Android releases to NDK-supported API levels. - -Similar to `android_sdk_repository`, the path to the Android NDK is inferred from -the `ANDROID_NDK_HOME` environment variable by default. The path can also be -explicitly specified with a `path` attribute on `android_ndk_repository`. - -## Create a BUILD file - -A [`BUILD` file](/docs/build-ref.html#BUILD_files) is a text file that describes -the relationship between a set of build outputs -- for example, compiled -software libraries or executables -- and their dependencies. These dependencies -may be source files in your workspace or other build outputs. `BUILD` files are -written in the Bazel *build language*. - -`BUILD` files are part of concept in Bazel known as the *package hierarchy*. -The package hierarchy is a logical structure that overlays the directory -structure in your workspace. Each [package](/docs/build-ref.html#packages) is a -directory (and its subdirectories) that contains a related set of source files -and a `BUILD` file. The package also includes any subdirectories, excluding -those that contain their own `BUILD` file. The *package name* is the name of the -directory where the `BUILD` file is located. - -Note that this package hierarchy is distinct from, but coexists with, the Java -package hierarchy for your Android app. - -For the simple Android app in this tutorial, we'll consider all the source files -in `$WORKSPACE/android/` to comprise a single Bazel package. A more complex -project may have many nested packages. - -At a command-line prompt, open your new `BUILD` file for editing: - -```bash -vi $WORKSPACE/android/BUILD -``` - -### Add an android_library rule - -A `BUILD` file contains several different types of instructions for Bazel. The -most important type is the [build rule](/docs/build-ref.html#funcs), which tells -Bazel how to build an intermediate or final software output from a set of source -files or other dependencies. - -Bazel provides two build rules, `android_library` and `android_binary`, that you -can use to build an Android app. For this tutorial, you'll first use the -[`android_library`](/docs/be/android.html#android_library) rule to tell -Bazel how to build an -[Android library module](http://developer.android.com/tools/projects/index.html#LibraryProjects) -from the app source code and resource files. Then you'll use the -`android_binary` rule to tell it how to build the Android application package. - -Add the following to your `BUILD` file: - -```python -android_library( - name = "activities", - srcs = glob(["src/main/java/com/google/bazel/example/android/activities/*.java"]), - custom_package = "com.google.bazel.example.android.activities", - manifest = "src/main/java/com/google/bazel/example/android/activities/AndroidManifest.xml", - resource_files = glob(["src/main/java/com/google/bazel/example/android/activities/res/**"]), -) -``` - -As you can see, the `android_library` build rule contains a set of attributes -that specify the information that Bazel needs to build a library module from the -source files. Note also that the name of the rule is `activities`. You'll -reference the rule using this name as a dependency in the `android_binary` rule. - -### Add an android_binary rule - -The [`android_binary`](/docs/be/android.html#android_binary) rule builds -the Android application package (`.apk` file) for your app. - -Add the following to your build file: - -```python -android_binary( - name = "android", - custom_package = "com.google.bazel.example.android", - manifest = "src/main/java/com/google/bazel/example/android/AndroidManifest.xml", - resource_files = glob(["src/main/java/com/google/bazel/example/android/res/**"]), - deps = [":activities"], -) -``` - -Here, the `deps` attribute references the output of the `activities` rule you -added to the `BUILD` file above. This means that, when Bazel builds the output -of this rule, it checks first to see if the output of the `activities` library -rule has been built and is up-to-date. If not, it builds it and then uses that -output to build the application package file. - -Now, save and close the file. You can compare your `BUILD` file to the -[completed example](https://github.com/bazelbuild/examples/blob/master/tutorial/android/BUILD) -in the `master` branch of the GitHub repo. - -## Run the build - -You use the -[`bazel`](/docs/bazel-user-manual.html) command-line tool to run builds, execute -unit tests and perform other operations in Bazel. This tool is located in the -`output` subdirectory of the location where you installed Bazel. During -[installation](/docs/install.md), you probably added this location to your -path. - -Before you build the sample app, make sure that your current working directory -is inside your Bazel workspace: - -```bash -cd $WORKSPACE -``` - -Now, enter the following to build the sample app: - -```bash -bazel build //android:android -``` - -The [`build`](/docs/bazel-user-manual.html#build) subcommand instructs Bazel to -build the target that follows. The target is specified as the name of a build -rule inside a `BUILD` file, with along with the package path relative to -your workspace directory. Note that you can sometimes omit the package path -or target name, depending on your current working directory at the command -line and the name of the target. See [Labels](/docs/build-ref.html#labels) in -*Bazel Concepts and Terminology* page for more information about target labels -and paths. - -Bazel now launches and builds the sample app. During the build process, its -output will appear similar to the following: - -```bash -INFO: Found 1 target... -Target //android:android up-to-date: - bazel-bin/android/android_deploy.jar - bazel-bin/android/android_unsigned.apk - bazel-bin/android/android.apk -INFO: Elapsed time: 7.237s, Critical Path: 5.81s -``` - -## Find the build outputs - -Bazel stores the outputs of both intermediate and final build operations in -a set of per-user, per-workspace output directories. These directories are -symlinked from the following locations: - -* `$WORKSPACE/bazel-bin`, which stores binary executables and other runnable - build outputs -* `$WORKSPACE/bazel-genfiles`, which stores intermediary source files that are - generated by Bazel rules -* `$WORKSPACE/bazel-out`, which stores other types of build outputs - -Bazel stores the Android `.apk` file generated using the `android_binary` rule -in the `bazel-bin/android/` directory, where the subdirectory name `android` is -derived from the name of the Bazel package. - -At a command prompt, list the contents of this directory and find the -`android.apk` file: - -```bash -ls $WORKSPACE/bazel-bin/android -``` - -## Run the app - -You can now deploy the app to a connected Android device or emulator from the -command line using the -[`bazel mobile-install`](http://bazel.build/docs/bazel-user-manual.html#mobile-install) -command. This command uses the Android Debug Bridge (`adb`) to communicate with -the device. You must set up your device to use `adb` following the instructions -in -[Android Debug Bridge](http://developer.android.com/tools/help/adb.html) before -deployment. - -Enter the following: - -```bash -bazel mobile-install //android:android -``` - -Note that the `mobile-install` subcommand also supports the -[`--incremental`](http://bazel.build/docs/bazel-user-manual.html#mobile-install) -flag that can be used to deploy only those parts of the app that have changed -since the last deployment. - -## What's next - -Now that you've built a sample app for Android, it's time to do the same for -the [iOS app](ios-app.md). diff --git a/site/versions/master/docs/tutorial/app.md b/site/versions/master/docs/tutorial/app.md deleted file mode 100644 index b3b274c2d5..0000000000 --- a/site/versions/master/docs/tutorial/app.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -layout: documentation -title: Build Mobile Application ---- - -# Build Mobile Application - -You can use Bazel to build a variety of software outputs, including -Linux and macOS (OS X) applications written in Java, C++ and Objective-C. You can -also use Bazel to build software for other platforms or written in other -languages. - -This tutorial shows how to use Bazel to build the following: - -* An Android app -* An iOS app -* A mobile backend server running on App Engine - -In this tutorial, you'll learn how to: - -* Set up a Bazel workspace and create a `WORKSPACE` file -* Create `BUILD` files that contain the instructions used by Bazel to build - the software -* Run builds using the Bazel command line tool - -## Requirements - -You can follow the steps in this tutorial on either a Linux or Mac OS X system. -However, you can only build the iOS app if you are running Bazel on OS X. If -you are using Linux, you can skip the iOS instructions and still complete -the rest of the tutorial steps. - -## Sample project - -You don't have to write your own mobile apps and backend server to use this -tutorial. Instead, you'll use a sample project hosted on GitHub. The sample -project is hosted at the following location: - -[https://github.com/bazelbuild/examples/](https://github.com/bazelbuild/examples/) - -You'll grab the sample project files in the next step in this tutorial. - -## What's next - -Let's start off by [setting up](environment.md) the tutorial environment. diff --git a/site/versions/master/docs/tutorial/backend-server.md b/site/versions/master/docs/tutorial/backend-server.md deleted file mode 100644 index 00c61ac43d..0000000000 --- a/site/versions/master/docs/tutorial/backend-server.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -layout: documentation -title: Tutorial - Build the Backend Server ---- - -# Tutorial - Build the Backend Server - -The backend server is a simple web application that runs on Google App Engine -and responds to incoming HTTP requests from the sample Android and iOS apps. - -Here, you'll do the following: - -* Review the source files for the app -* Update the `WORKSPACE` file -* Create a `BUILD` file -* Run the build -* Find the build outputs -* Run the application on a local development server -* Deploy to Google App Engine - -Bazel provides a set of [App Engine build rules](https://github.com/bazelbuild/rules_appengine) -written using the [Skylark](/docs/skylark/index.html) framework. You'll use -these in the steps below to build the application. - -## Review the source files - -The source files for the backend server are located in `$WORKSPACE/backend/`. - -The key files and directories are: - -<table class="table table-condensed table-striped"> -<thead> -<tr> -<td>Name</td> -<td>Location</td> -</tr> -</thead> -<tbody> -<tr> -<td>Source file directory</td> -<td><code>src/main/java/com/google/bazel/example/app/</code></td> -</tr> -<tr> -<td>Web application metadata directory</td> -<td><code>webapp/WEB-INF/</code></td> -</tr> -</tbody> -</table> - -## Update the WORKSPACE file - -As with the Android app, you must add references to -[external dependencies](http://bazel.build/docs/external.html) to your `WORKSPACE` -file. For the backend server, these are references to the App Engine SDK, -the Java Servlet SDK and other libraries needed to build the App Engine -applications. - -### Add the App Engine rule - -When you built the Android app, you added a reference to the location on your -filesystem where you downloaded and installed the Android SDK. For the -backend server, however, you'll give Bazel instructions for downloading the -required App Engine SDK package from a remote server. This is optional. You -can also download and install the SDK manually on your filesystem and reference -it from that location as described in the -[App Engine rule documentation](https://github.com/bazelbuild/rules_appengine). - -Add the following to your `WORKSPACE` file: - -```python -http_archive( - name = "io_bazel_rules_appengine", - sha256 = "f4fb98f31248fca5822a9aec37dc362105e57bc28e17c5611a8b99f1d94b37a4", - strip_prefix = "rules_appengine-0.0.6", - url = "https://github.com/bazelbuild/rules_appengine/archive/0.0.6.tar.gz", -) -load("@io_bazel_rules_appengine//appengine:appengine.bzl", "appengine_repositories") -appengine_repositories() -``` - -[`http_archive`](/docs/be/workspace.html#http_archive) downloads the -AppEngine rules from a GitHub archive. We could also have used -[`git_repository`](/docs/be/workspace.html#git_repository) to fetch the rules -directly from the Git repository. -Then the next two lines use the `appengine_repositories` function defined in -these rules to download the libraries and SDK needed to build AppEngine -applications. - -Now, save and close the file. You can compare your `WORKSPACE` file to the -[completed example](https://github.com/bazelbuild/examples//blob/master/tutorial/WORKSPACE) -in the `master` branch of the GitHub repo. - -## Create a BUILD file - -Now that you have set up the external dependencies, you can go ahead and create -the `BUILD` file for the backend server, as you did previously for the sample -Android and iOS apps. - -Open your new `BUILD` file for editing: - -```bash -vi $WORKSPACE/backend/BUILD -``` - -### Add a java_binary rule - -Add the following to your `BUILD` file: - -```python -java_binary( - name = "app", - srcs = glob(["src/main/java/**/*.java"]), - main_class = "does.not.exist", - deps = [ - "@io_bazel_rules_appengine//appengine:javax.servlet.api", - ], -) -``` - -The [`java_binary`](/docs/be/java.html#java_binary) tells Bazel -how to build a Java `.jar` library for your application, plus a wrapper shell -script that launches the application code from the specified main class. Here, -we're using this rule instead of the -[`java_library`](/docs/be/java.html#java_library) because we need -the `.jar` file to contain all the dependencies required to build the final -App Engine `.war` file. For this reason, we specify a bogus class name -for the `main_class` attribute. - -### Add an appengine_war rule - -Add the following to your `BUILD` file: - -```python -load("@io_bazel_rules_appengine//appengine:appengine.bzl", "appengine_war") - -appengine_war( - name = "backend", - data = [":webapp"], - data_path = "/backend/webapp", - jars = [":app_deploy.jar"], -) - -filegroup( - name = "webapp", - srcs = glob(["webapp/**/*"]), -) -``` - -The [`appengine_war`](/docs/be/appengine.html#appengine_war) -rule builds the final App Engine `war` file from the library `.jar` file and web -application metadata files in the `webapp` directory. - -Save and close the file. Again, the -[completed example](https://github.com/google/bazel-examples/blob/master/tutorial/backend/BUILD) -is in the `master` branch of the GitHub repo. - -## Run the build - -Make sure that your current working directory is inside your Bazel workspace: - -```bash -cd $WORKSPACE -``` - -Now, enter the following to build the sample app: - -```bash -bazel build //backend:backend -``` - -Bazel now launches and builds the sample app. During the build process, its -output will appear similar to the following: - -```bash -INFO: Found 1 target... -Target //backend:backend up-to-date: - bazel-bin/backend/backend.war - bazel-bin/backend/backend.deploy - bazel-bin/backend/backend -INFO: Elapsed time: 56.867s, Critical Path: 2.72s -``` - -## Find the build outputs - -The `.war` file and other outputs are located in the -`$WORKSPACE/bazel-bin/backend` directory. - -In particular, the `appengine_war` rule generates scripts that you can use to -run your backend locally or deploy it to Google App Engine: - -## Run the application on a local development server - -Here, you'll start a local App Engine development server in your environment and -run your application on it. - -To run the application, enter the following: - -```bash -bazel-bin/backend/backend --port=12345 -``` - -Your application will be available at `http://localhost:12345` - -## Deploy to Google App Engine - -You can also deploy the application to the live App Engine serving -environment on Google Cloud Platform. For this scenario, you must first create -a new Cloud Platform project and App Engine application using the Google Cloud -Platform Console. -Follow [this link](https://console.cloud.google.com/projectselector/appengine/create?lang=java&st=true) -to perform these actions. - -Build the target that allows to deploy to App Engine: - -```bash -bazel build --java_toolchain=@io_bazel_rules_appengine//appengine:jdk7 //backend:backend.deploy -``` - -Then, to deploy the application, enter the following: - -```bash -bazel-bin/backend/backend.deploy <project-id> -``` - -The deployment script prompts you to authorize access to Google Cloud Platform. -After you have authorized access the first time, you can deploy the application -using the `bazel` command and the following rule target: - -```bash -bazel run //backend:backend.deploy <project-id> -``` - -Your application URL will be `http://<project-id>.appspot.com`. - -## What's next - -Now let's [review](review.md) the tutorial steps. diff --git a/site/versions/master/docs/tutorial/cpp.md b/site/versions/master/docs/tutorial/cpp.md deleted file mode 100644 index 23362010ef..0000000000 --- a/site/versions/master/docs/tutorial/cpp.md +++ /dev/null @@ -1,395 +0,0 @@ ---- -layout: documentation -title: Build C++ ---- - -Build C++ -========= - -You can use Bazel to build your C++ application. In this tutorial you'll learn how to: - -* Build your first C++ target -* Use external libraries -* Write and run C++ tests -* Use precompiled libraries - -## Setting up your workspace - -Suppose that you have an existing project in a directory, say, -`~/gitroot/my-project/`. Create an empty file at -`~/gitroot/my-project/WORKSPACE` to show Bazel where your project's root is. -We are going to create a small hello world project with the following directory structure: -{% highlight bash %} -└── my-project - ├── lib - │ ├── BUILD - │ ├── hello-greet.cc - │ └── hello-greet.h - ├── main - │ ├── BUILD - │ ├── hello-time.cc - │ ├── hello-time.h - │ └── hello-world.cc - └── WORKSPACE -{% endhighlight %} - -## Creating source files - -Using the following commands to create the necessary source files: -{% highlight bash %} -# If you're not already there, move to your workspace directory. -cd ~/gitroot/my-project -mkdir ./main -cat > main/hello-world.cc <<'EOF' - -#include "lib/hello-greet.h" -#include "main/hello-time.h" -#include <iostream> -#include <string> - -int main(int argc, char** argv) { - std::string who = "world"; - if (argc > 1) { - who = argv[1]; - } - std::cout << get_greet(who) <<std::endl; - print_localtime(); - return 0; -} -EOF - -cat > main/hello-time.h <<'EOF' - -#ifndef MAIN_HELLO_TIME_H_ -#define MAIN_HELLO_TIME_H_ - -void print_localtime(); - -#endif -EOF - -cat > main/hello-time.cc <<'EOF' - -#include "main/hello-time.h" -#include <ctime> -#include <iostream> - -void print_localtime() { - std::time_t result = std::time(nullptr); - std::cout << std::asctime(std::localtime(&result)); -} -EOF - -mkdir ./lib -cat > lib/hello-greet.h <<'EOF' - -#ifndef LIB_HELLO_GREET_H_ -#define LIB_HELLO_GREET_H_ - -#include <string> - -std::string get_greet(const std::string &thing); - -#endif -EOF - -cat > lib/hello-greet.cc <<'EOF' - -#include "lib/hello-greet.h" -#include <string> - -std::string get_greet(const std::string& who) { - return "Hello " + who; -} -EOF -{% endhighlight %} - -## Adding BUILD files - -As you can see from the source code, `main/hello-world.cc` needs to include both `lib/hello-greet.h` and `main/hello-time.h`. -First we create `lib/BUILD` for hello-greet.cc: - -{% highlight python %} -cc_library( - name = "hello-greet", - srcs = ["hello-greet.cc"], - hdrs = ["hello-greet.h"], - visibility = ["//main:__pkg__"], -) -{% endhighlight %} - -Note that `visibility = ["//main:__pkg__"]` indicates `hello-greet` is visible from `main/BUILD`. -Then we'd create the following `main/BUILD` file: - -{% highlight python %} -cc_library( - name = "hello-time", - srcs = ["hello-time.cc"], - hdrs = ["hello-time.h"], -) - -cc_binary( - name = "hello-world", - srcs = ["hello-world.cc"], - deps = [ - ":hello-time", - "//lib:hello-greet", - ], -) -{% endhighlight %} - -Note when depending on a target in the same package, we can just use `:hello-time`. -When the target is in other package, a full path from root should be used, like `//lib:hello-greet`. - -Now you are ready to build your hello world C++ binary: - -{% highlight bash %} -bazel build main:hello-world -{% endhighlight %} - -This produces the following output: - -{% highlight bash %} -INFO: Found 1 target... -Target //main:hello-world up-to-date: - bazel-bin/main/hello-world -INFO: Elapsed time: 2.869s, Critical Path: 1.00s -{% endhighlight %} - -{% highlight bash %} -./bazel-bin/main/hello-world -{% endhighlight %} - -This produces the following output: - -{% highlight bash %} -Hello world -Thu Jun 23 18:51:46 2016 -{% endhighlight %} - -{% highlight bash %} -./bazel-bin/main/hello-world Bazel -{% endhighlight %} - -This produces the following output: - -{% highlight bash %} -Hello Bazel -Thu Jun 23 18:52:10 2016 -{% endhighlight %} - -Congratulations, you've just built your first Bazel target! - -## Transitive includes - -If a file includes a header, then the file's rule should depend on that header's -library. Conversely, only direct dependencies need to be specified as -dependencies. For example, suppose `sandwich.h` includes `bread.h` and -`bread.h` includes `flour.h`. `sandwich.h` doesn't include `flour.h` (who wants -flour in their sandwich?), so the BUILD file would look like: - -```python -cc_library( - name = "sandwich", - srcs = ["sandwich.cc"], - hdrs = ["sandwich.h"], - deps = [":bread"], -) - -cc_library( - name = "bread", - srcs = ["bread.cc"], - hdrs = ["bread.h"], - deps = [":flour"], -) - -cc_library( - name = "flour", - srcs = ["flour.cc"], - hdrs = ["flour.h"], -) -``` - -Here, the `sandwich` library depends on the `bread` library, which depends -on the `flour` library. - -## Adding include paths - -Sometimes you cannot (or do not want to) base include paths at the workspace -root. Existing libraries might already have a include directory that doesn't -match its path in your workspace. For example, suppose you have the following -directory structure: - -``` -└── my-project - ├── third_party - │ └── some_lib - │ ├── BUILD - │ ├── include - │ │ └── some_lib.h - │ └── some_lib.cc - └── WORKSPACE -``` - -Bazel will expect `some_lib.h` to be included as -`third_party/some_lib/include/some_lib.h`, but suppose `some_lib.cc` includes -`"include/some_lib.h"`. To make that include path valid, -`third_party/some_lib/BUILD` will need to specify that the `some_lib/` -directory is an include directory: - -```python -cc_library( - name = "some_lib", - srcs = ["some_lib.cc"], - hdrs = ["some_lib.h"], - copts = ["-Ithird_party/some_lib"], -) -``` - -This is especially useful for external dependencies, as their header files -must otherwise be included with an `external/[repository-name]/` prefix. - -## Including external libraries - -Suppose you are using [Google Test](https://github.com/google/googletest). You -can use one of the `new_` repository functions in the `WORKSPACE` file to -download Google Test and make it available in your repository: - -```python -new_http_archive( - name = "gtest", - url = "https://github.com/google/googletest/archive/release-1.7.0.zip", - sha256 = "b58cb7547a28b2c718d1e38aee18a3659c9e3ff52440297e965f5edffe34b6d0", - build_file = "gtest.BUILD", -) -``` - -Then create `gtest.BUILD`, a BUILD file to use to compile Google Test. -Google Test has several "special" requirements that make its `cc_library` rule -more complicated: - -* `googletest-release-1.7.0/src/gtest-all.cc` `#include`s all of the other files in - `googletest-release-1.7.0/src/`, so we need to exclude it from the compile or we'll get - link errors for duplicate symbols. -* It uses header files that are relative to the `googletest-release-1.7.0/include/` directory - (`"gtest/gtest.h"`), so we must add that directory to the include paths. -* It needs to link in pthread, so we add that as a `linkopt`. - -The final rule looks like this: - -```python -cc_library( - name = "main", - srcs = glob( - ["googletest-release-1.7.0/src/*.cc"], - exclude = ["googletest-release-1.7.0/src/gtest-all.cc"] - ), - hdrs = glob([ - "googletest-release-1.7.0/include/**/*.h", - "googletest-release-1.7.0/src/*.h" - ]), - copts = [ - "-Iexternal/gtest/googletest-release-1.7.0/include" - ], - linkopts = ["-pthread"], - visibility = ["//visibility:public"], -) -``` - -This is somewhat messy: everything is prefixed with googletest-release-1.7.0 as a byproduct -of the archive's structure. You can make `new_http_archive` strip this prefix by -adding the `strip_prefix` attribute: - -```python -new_http_archive( - name = "gtest", - url = "https://github.com/google/googletest/archive/release-1.7.0.zip", - sha256 = "b58cb7547a28b2c718d1e38aee18a3659c9e3ff52440297e965f5edffe34b6d0", - build_file = "gtest.BUILD", - strip_prefix = "googletest-release-1.7.0", -) -``` - -Then `gtest.BUILD` would look like this: - -```python -cc_library( - name = "main", - srcs = glob( - ["src/*.cc"], - exclude = ["src/gtest-all.cc"] - ), - hdrs = glob([ - "include/**/*.h", - "src/*.h" - ]), - copts = ["-Iexternal/gtest/include"], - linkopts = ["-pthread"], - visibility = ["//visibility:public"], -) -``` - -Now `cc_` rules can depend on `@gtest//:main`. - -## Writing and running C++ tests - -For example, we could create a test `./test/hello-test.cc` such as: - -```cpp -#include "gtest/gtest.h" -#include "lib/hello-greet.h" - -TEST(HelloTest, GetGreet) { - EXPECT_EQ(get_greet("Bazel"), "Hello Bazel"); -} -``` - -Then create `./test/BUILD` file for your tests: - -```python -cc_test( - name = "hello-test", - srcs = ["hello-test.cc"], - copts = ["-Iexternal/gtest/include"], - deps = [ - "@gtest//:main", - "//lib:hello-greet", - ], -) -``` - -Note in order to make `hello-greet` visible to `hello-test`, we have to add `"//test:__pkg__",` to `visibility` attribute in `./lib/BUILD`. - -Now you can use `bazel test` to run the test. - -{% highlight bash %} -bazel test test:hello-test -{% endhighlight %} - -This produces the following output: - -{% highlight bash %} -INFO: Found 1 test target... -Target //test:hello-test up-to-date: - bazel-bin/test/hello-test -INFO: Elapsed time: 4.497s, Critical Path: 2.53s -//test:hello-test PASSED in 0.3s - -Executed 1 out of 1 tests: 1 test passes. -{% endhighlight %} - - -## Adding dependencies on precompiled libraries - -If you want to use a library that you only have a compiled version of (e.g., -headers and a .so) wrap it in a `cc_library` rule: - -```python -cc_library( - name = "mylib", - srcs = ["mylib.so"], - hdrs = ["mylib.h"], -) -``` - -Then other C++ targets in your workspace can depend on this rule. diff --git a/site/versions/master/docs/tutorial/environment.md b/site/versions/master/docs/tutorial/environment.md deleted file mode 100644 index 68548dfdfc..0000000000 --- a/site/versions/master/docs/tutorial/environment.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -layout: documentation -title: Tutorial - Set Up Your Environment ---- - -# Tutorial - Set Up Your Environment - -The first step in this tutorial is to set up your environment. - -Here, you'll do the following: - -* Install Bazel -* Install Android Studio and the Android SDK -* Install Xcode (macOS (OS X) only) -* Get the sample project from the GitHub repo - -## Install Bazel - -Follow the [installation instructions](/docs/install.md) to install Bazel and -its dependencies. - -## Install the Android SDK tools - -Do the following: - -1. Download and install the - [Android SDK Tools](https://developer.android.com/sdk/index.html#Other). - -2. Run the Android SDK Manager and install the following packages: - - <table class="table table-condensed table-striped"> - <thead> - <tr> - <td>Package</td> - <td>SDK directory</td> - </tr> - </thead> - <tbody> - <tr> - <td>Android SDK Platform Tools</td> - <td><code>platform-tools</code></td> - </tr> - <tr> - <td>Android SDK Build Tools</td> - <td><code>build-tools</code></td> - </tr> - <tr> - <td>Android SDK Platform</td> - <td><code>platform</code></td> - </tr> - </tbody> - </table> - - The SDK Manager is an executable named `android` located in the `tools` - directory. - -## Install Xcode (OS X only) - -If you are following the steps in this tutorial on Mac OS X, download and -install [Xcode](https://developer.apple.com/xcode/downloads/). The Xcode -download contains the iOS libraries, Objective-C compiler other tools -required by Bazel to build the iOS app. - -## Get the sample project - -You also need to get the sample project for the tutorial from GitHub: - -[https://github.com/bazelbuild/examples/](https://github.com/bazelbuild/examples/) - -The GitHub repo has two branches: `source-only` and `master`. The `source-only` -branch contains the source files for the project only. You'll use the files in -this branch in this tutorial. The `master` branch contains both the source files -and completed Bazel `WORKSPACE` and `BUILD` files. You can use the files in this -branch to check your work when you've completed the tutorial steps. - -Enter the following at the command line to get the files in the `source-only` -branch: - -```bash -cd $HOME -git clone -b source-only https://github.com/bazelbuild/examples -``` - -The `git clone` command creates a directory named `$HOME/examples/`. This -directory contains several sample projects for Bazel. The project files for this -tutorial are in `$HOME/examples/tutorial`. - -## What's next - -Now that you have set up your environment, you can -[set up a Bazel workspace](workspace.md). diff --git a/site/versions/master/docs/tutorial/ios-app.md b/site/versions/master/docs/tutorial/ios-app.md deleted file mode 100644 index abf49d27c4..0000000000 --- a/site/versions/master/docs/tutorial/ios-app.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -layout: documentation -title: Tutorial - Build an iOS App ---- - -# Tutorial - Build an iOS App - -Like the [Android app](android-app.md) you built in the previous step, the iOS -app is a simple mobile app that communicates with the -[backend server](backend-server.md). - -Here, you'll do the following: - -* Review the source files for the app -* Create a `BUILD` file -* Build the app for the simulator -* Find the build outputs -* Run/Debug the app on the simulator -* Build the app for a device -* Install the app on a device - -Note that, unlike with the Android app, you don't have to modify your -`WORKSPACE` file to add iOS-specific external dependencies. - -If you're following the steps in this tutorial on macOS (OS X), you can go ahead -and build the sample iOS app as described below. If you are on Linux, skip ahead -to the [next step](backend-server.md). - -## Review the source files - -Let's take a look at the source files for the app. These are located in -`$WORKSPACE/ios-app/UrlGet`. Again, you're just looking at these files now to -become familiar with the structure of the app. You don't have to edit any of the -source files to complete this tutorial. - -## Create a BUILD file - -At a command-line prompt, open your new `BUILD` file for editing: - -```bash -vi $WORKSPACE/ios-app/BUILD -``` - -## Add an objc_library rule - -Bazel provides several build rules that you can use to build an app for the -iOS platform. For this tutorial, you'll first use the -[`objc_library`](/docs/be/objective-c.html#objc_library) rule to tell Bazel -how to build an -[static library](https://developer.apple.com/library/ios/technotes/iOSStaticLibraries/Introduction.html) -from the app source code and Xib files. Then you'll use the -`objc_binary` rule to tell it how to bundle the iOS application. (Note that -this is a minimal use case of the Objective-C rules in Bazel. For example, you -have to use the `ios_application` rule to build multi-architecture iOS -apps.) - -Add the following to your `BUILD` file: - -```python -objc_library( - name = "UrlGetClasses", - srcs = [ - "UrlGet/AppDelegate.m", - "UrlGet/UrlGetViewController.m", - ], - hdrs = glob(["UrlGet/*.h"]), - xibs = ["UrlGet/UrlGetViewController.xib"], -) -``` - -Note the name of the rule, `UrlGetClasses`. - -## Add an objc_binary rule - -The [`objc_binary`](/docs/be/objective-c.html#objc_binary) rule creates a -binary to be bundled in the application. - -Add the following to your `BUILD` file: - -```python -objc_binary( - name = "ios-app-binary", - srcs = [ - "UrlGet/main.m", - ], - deps = [ - ":UrlGetClasses", - ], -) - -``` -Note how the `deps` attribute references the output of the -`UrlGetClasses` rule you added to the `BUILD` file above. - -## Add an ios_application rule - -The [`ios_application`](/docs/be/objective-c.html#ios_application) rule -creates the bundled `.ipa` archive file for the application and also generates -an Xcode project file. - -Add the following to your `BUILD` file: - -```python -ios_application( - name = "ios-app", - binary = ":ios-app-binary", - infoplist = "UrlGet/UrlGet-Info.plist", -) -``` - -Now, save and close the file. You can compare your `BUILD` file to the -[completed example](https://github.com/bazelbuild/examples/blob/master/tutorial/ios-app/BUILD) -in the `master` branch of the GitHub repo. - -## Build the app for the simulator - -Make sure that your current working directory is inside your Bazel workspace: - -```bash -cd $WORKSPACE -``` - -Now, enter the following to build the sample app: - -```bash -bazel build //ios-app:ios-app -``` - -Bazel now launches and builds the sample app. During the build process, its -output will appear similar to the following: - -```bash -INFO: Found 1 target... -Target //ios-app:ios-app up-to-date: - bazel-bin/ios-app/ios-app.ipa - bazel-bin/ios-app/ios-app.xcodeproj/project.pbxproj -INFO: Elapsed time: 3.765s, Critical Path: 3.44s -``` - -## Find the build outputs - -The `.ipa` file and other outputs are located in the -`$WORKSPACE/bazel-bin/ios-app` directory. - -## Run/Debug the app on the simulator - -You can now run the app from Xcode using the iOS Simulator. To run the app, -open the project directory `$WORKSPACE/bazel-bin/ios-app/ios-app.xcodeproj` in -Xcode, choose an iOS Simulator as the runtime scheme and then click the **Run** -button. - -**Note:** If you change anything about the project file set in Xcode (for -example, if you add or remove a file, or add or change a dependency), you must -rebuild the app using Bazel and then re-open the project. - -## Build the app for a device - -You need to set up bazel so that it can find the appropriate provisioning -profile for the device you want to build for. To set up the "default" -provisioning profile for all bazel builds: - - 1. Go to [Apple Profiles](https://developer.apple.com/account/ios/profile/profileList.action) - and download the appropriate provisioning profile for your device. - If this is confusing, please refer to [Apple's documentation](https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/MaintainingProfiles/MaintainingProfiles.html). - 1. Move your profile into `$WORKSPACE/tools/objc`. - 1. Optional - You may want to add your profile to your `.gitignore`. - 1. Edit `$WORKSPACE/tools/objc/BUILD` and add: - - ```python - filegroup( - name = "default_provisioning_profile", - srcs = ["<NAME OF YOUR PROFILE>.mobileprovision"], - ) - ``` - -Now you should be able to build the app for your device: - -```bash -bazel build //ios-app:ios-app --ios_multi_cpus=armv7,arm64 -``` - -This will build the app "fat". If you would prefer just to build for -your specific device architecture you can designate a single architecture. - -If you would like to select a specific Xcode version you can do so -with the `--xcode_version=7.2` option. If for some reason you need to specify -a specific SDK version you can use the `--ios_sdk_version=9.2` option, but the -`--xcode_version` should be sufficient in most circumstances. - -If you would like to specify a minimum version of iOS to run against, you can -do so with the `--ios_minimum_os=7.0` option. - -## Install the app on a device - -The easiest way to install the app on the device is to launch Xcode and use the -`Windows > Devices` command. Select your plugged in device from the list on the -left, and then add the app by clicking on the "plus" sign under installed apps -and selecting the `.ipa` that you built. - -If your app does not launch, please make sure that your device was on your -provisioning profile. The `View Device Logs` button on the `Devices` screen in -Xcode may provide other information as to what has gone wrong. - -## What's next - -The next step is to build a [backend server](backend-server.md) for the two -mobile apps you built in this tutorial. diff --git a/site/versions/master/docs/tutorial/java.md b/site/versions/master/docs/tutorial/java.md deleted file mode 100644 index a916aeb5be..0000000000 --- a/site/versions/master/docs/tutorial/java.md +++ /dev/null @@ -1,576 +0,0 @@ ---- -layout: documentation -title: Introduction to Bazel ---- - -Introduction to Bazel: Build Java -========== - -This tutorial is an introduction for anyone getting started with Bazel. It -focuses on the concepts, setup, and use of Bazel using a Java sample project. - -Estimated time: 30 min - -## What you will learn - -In this tutorial you'll learn how to: - -* Build a target from source files -* Produce a visual representation of the dependency graph -* Break a monolithic binary into smaller libraries -* Use multiple Bazel packages -* Control the visibility of a target between packages -* Use labels to reference a target -* Deploy your target - -## Before you begin - -* [Install Bazel](/docs/install.md) - -## Create the sample Java project - -The first step in this tutorial is to create a small Java project. Even though -the project is in Java, this tutorial will focus on concepts that are helpful -for using Bazel in any language. - -1. Create the directory `~/my-project/` - -2. Move to this directory: - - ``` - cd ~/my-project - ``` - -3. Create the following directories under `my-project`: - - ``` - mkdir -p src/main/java/com/example - ``` - - Note that path uses conventions specific to Java programs. Programs written - in other languages may have a different workspace path and directory - structure. - -4. In the directory you created, add a file called `Greeting.java` with the - following contents: - - ```java - package com.example; - - public class Greeting { - public static void sayHi() { - System.out.println("Hi!"); - } - } - ``` - -5. Add a second file `ProjectRunner.java` with the following contents: - - ```java - package com.example; - - public class ProjectRunner { - public static void main(String args[]) { - Greeting.sayHi(); - } - } - ``` - -You’ve now created a small Java project. It contains one file that will be -compiled into a library, and another which will be an executable that uses the -library. - -The rest of this tutorial focuses on setting up and using Bazel to build these -source files. - -## Build with Bazel - -### Set up the workspace - -Workspaces are directories that contain the source files for one or more -software projects, as well as a WORKSPACE file and BUILD files that contain -the instructions that Bazel uses to build the software. The workspace may also -contain symbolic links to output directories. - -To define the workspace, create an empty text file at the root of the project -and name it `WORKSPACE`. You now have: `~/my-project/WORKSPACE`. - -This directory and its subdirectories are now part of the same workspace. When -Bazel builds an output, all inputs and dependencies must be in the same -workspace. Anything in different workspaces are independent of each other, -though there are ways to link workspaces that are beyond the scope of this -introduction tutorial. - -If you also do the [C++ tutorial](/docs/tutorial/cpp.md), you’ll notice it uses -the same workspace. Bazel can understand multiple targets in multiple languages -in a single workspace. - -### Create a BUILD file - -Bazel looks for files named `BUILD` which describe how to build the project. - -1. In the `~/my-project` directory, create a file and name it BUILD. This BUILD - file is a sibling of the WORKSPACE file. - - In the BUILD file, you use a declarative language similar to Python to - create instances of Bazel rules. These instances are called *rule targets*. - In Bazel, *targets* are either files or rule targets and they are the - elements in a workspace that you can ask Bazel to build. - - For this project, you’ll use the built-in rule `java_binary`. Bazel's - built-in rules are all documented in the - [Build Encyclopedia](/docs/be/overview.html). You can also create your own - rules using the [Bazel rule extension framework](/docs/skylark/concepts.md). - -2. Add this text to the BUILD file: - - ``` - java_binary( - name = "my-runner", - srcs = glob(["src/main/java/com/example/*.java"]), - main_class = "com.example.ProjectRunner", - ) - ``` -As you can see, the text in the BUILD file doesn’t describe what Bazel does -when it executes this rule target. The rule’s implementation handles the -complexity of how it works (such as the compiler used). - -You can treat the rule as a black box, focusing on what inputs it needs, and -the outputs it produces. This rule builds a Java archive ("jar file") as well -as a wrapper shell script with the same name as the rule target. - -When you’re writing your own BUILD file, go to the -[Build Encyclopedia](/docs/be/overview.html) for a description of what a rule -does and for its list of possible attributes you can define. For example, -here’s the entry for the [java_binary](/docs/be/java.html#java_binary) rule in -the Build Encyclopedia. The Build Encyclopedia has information about all of the -rules that are compiled into Bazel. - -Let’s take a look at the rule target that you added to the BUILD file. - -Each rule instantiation in the BUILD file creates one rule target. Here, you’ve -instantiated the rule `java_binary`, creating the target `my-runner`. - -Different rules will require different attributes, though all must include a -“name” attribute. You use these attributes to explicitly list all of the -target’s dependencies and options. In the target above: - -* `my-runner` is the name of the rule target created - -* `glob(["src/main/java/com/example/*.java"])` includes every file in that - directory that ends with .java (see the Build Encyclopedia for more - information about [globbing](/docs/be/functions.html#glob)) - -* `"com.example.ProjectRunner"` specifies the class that contains the main - method. - -### Build with Bazel - -Now you’re ready to build the Java binary. To do so, you’ll use the command -`bazel build` with the target label `//:my-runner`. You reference targets by -using their label. Label syntax is described later in this tutorial. - -1. Build my-runner by using this command: - - ``` - bazel build //:my-runner - ``` - - You’ll see output similar to: - - ``` - INFO: Found 1 target... - Target //:my-runner up-to-date: - bazel-bin/my-runner.jar - bazel-bin/my-runner - INFO: Elapsed time: 1.021s, Critical Path: 0.83s - ``` - -2. Now execute the file by using this command: - - ``` - bazel-bin/my-runner - ``` - -Congratulations, you've built your first Bazel target! - -Let’s take a look at what you built. In `~/my-project`, Bazel created the -directory `bazel-bin` as well as other directories to store information about -the build. Open this directory to look at the files created during the build -process. These output directories keep the outputs separate from your source -tree. - -### Review the dependency graph - -Bazel requires build dependencies to be explicitly declared in BUILD -files. The build will fail if dependencies are missing, so when a build works -the declared dependencies are accurate. With this explicit information about -dependencies, Bazel creates a build graph and uses it to accurately perform -incremental builds. Our small Java project isn’t too exciting, but let’s check -out its build graph. - -The command `bazel query` retrieves information about the graph and the -relationships between targets. Let’s use it to produce a visual representation -of the build graph. - -1. From the root of the workspace (`my-project`), produce a text description - of the graph by using the command: - - ``` - bazel query --noimplicit_deps 'deps(//:my-runner)' --output graph - ``` - -2. Then, paste the output into Graphviz - ([http://www.webgraphviz.com/](http://www.webgraphviz.com/)) to see the - visual representation. - - The graph for the target my-runner will look like this: - -  - -You can see that `my-runner` depends on the two source files in your Java -project. - -You have now set up the workspace and BUILD file, and used Bazel to build your -project. You have also created a visual representation of the build graph to -see the structure of your build. - -## Refine your Bazel build - -### Add dependencies - -Creating one rule target to build your entire project may be sufficient for -small projects. As projects get larger it's important to break up the build -into self-contained libraries that can be assembled into a final product. -Self-contained libraries mean that everything doesn't need to be rebuilt after -small changes and that Bazel can parallelize more of the build steps. These -self-contained libraries also encourages good code hygiene. - -To break up a project, create a separate rule target for the each subcomponent -and then add the subcomponents as dependencies. For the project in this -tutorial, create a rule target to compile the library, and make the executable -depend on it. - -1. Replace the text in the BUILD file with the text below: - - ``` - java_binary( - name = "my-runner", - srcs = ["src/main/java/com/example/ProjectRunner.java"], - main_class = "com.example.ProjectRunner", - deps = [":greeter"], - ) - - java_library( - name = "greeter", - srcs = ["src/main/java/com/example/Greeting.java"], - ) - ``` - -The new `deps` attribute in `java_binary` tells Bazel that the `greeter` library -will be needed to compile the binary. Rules for many languages support the -`deps` attribute, though the exact semantics of the attribute will vary based -on the language and the type of target. The rule -[java_library](/docs/be/java.html#java_library) compiles sources into -a .jar file. Remember to go to the [Build Encyclopedia](/docs/be/overview.html) -for details about specific rules. - -This BUILD file builds the same files as before, but in a different way: now -Bazel will first build the `greeter` library and then build `my-runner`. - -2. Try building //:my-runner using the command: - - ``` - bazel build //:my-runner - ``` - - You’ll see output similar to: - - ``` - INFO: Found 1 target... - Target //:my-runner up-to-date: - bazel-bin/my-runner.jar - bazel-bin/my-runner - INFO: Elapsed time: 2.454s, Critical Path: 1.58s - ``` - - 3. Execute the file by using this command:: - - ``` - bazel-bin/my-runner - ``` - -If you now edit `ProjectRunner.java` and rebuild `my-runner`, the source file -`Greeting.java` will not be recompiled. When the BUILD file had only the one -target, both source files would be recompiled after any change. - -Looking at the dependency graph, you can see that `my-runner` depends on the -same inputs as it did before, but the structure of the build is different. - -The original dependency graph for `my-runner` looked link this: - - - -The dependency graph for `my-runner` after adding a dependency looks like this: - - - -### Use multiple packages - -For larger projects, you will often be dealing with several directories in your -workspace. You can organize your build process by adding a BUILD file to the -top directory of source files that you want to organize together. A directory -containing a BUILD file is called a package. - -Note that Bazel and Java both have the concept of a package. These are -unrelated to each other, though both are related to the structure of the -directories. - -Let’s build the java project using multiple packages. - -1. First, let’s make the Java project a bit more complex. - - 1. Add the following directory and file: - - ``` - mkdir -p src/main/java/com/example/cmdline - ``` - 2. In the directory cmdline, add the file Runner.java with the following - contents: - - ```java - package com.example.cmdline; - - import com.example.Greeting; - - public class Runner { - public static void main(String args[]) { - Greeting.sayHi(); - } - } - ``` - - Now you have a slightly larger Java project that you can organize with - multiple packages. - -2. In the directory `src/main/java/com/example/cmdline`, add an empty text - file and name it BUILD. The structure of the Java project is now: - - ``` - ├── BUILD - ├── src - │ └── main - │ └── java - │ └── com - │ └── example - │ ├── cmdline - │ │ ├── BUILD - │ │ └── Runner.java - │ ├── Greeting.java - │ └── ProjectRunner.java - └── WORKSPACE - ``` - - Each directory in the workspace can be part of only one package. The - workspace now has two BUILD files, and so has two packages: - - 1. The directory `my-project` and its subdirectories (but not including - subdirectories with their own BUILD file, such as `cmdline`), and - - 2. The directory `cmdline` and any subdirectories. - -3. In the new BUILD file, add the following text: - - ``` - java_binary( - name = "runner", - srcs = ["Runner.java"], - main_class = "com.example.cmdline.Runner", - deps = ["//:greeter"] - ) - ``` - - The file `Runner.java` depends on `com.example.Greeting`. In the BUILD file - this dependency is shown by listing the rule target `greeter` (with the - label `//:greeter`). - - Below is what the dependency graph for runner will look like. You can see - how `//:greeter` gives the dependency on `Greeting.java`. - -  - - -4. However, if you try to build runner right now you'll get a permissions - error. You can see the permission error by trying to build the target using - the command: - - ``` - bazel build //src/main/java/com/example/cmdline:runner - ``` - - By default, rule targets are private, which means that they can only be - depended on by targets in the same BUILD file. This privacy prevents - libraries that are implementation details from leaking into public APIs, - but it also means that you must explicitly allow `runner` to depend on - `//:greeter`. - - -5. Make a rule target visible to rule targets in other BUILD files by adding - a `visibility` attribute. To make the `greeter` rule target in - `~/my-project/BUILD` visible to any rule target in the new package, add the - following visibility attribute: - - ``` - java_library( - name = "greeter", - srcs = ["src/main/java/com/example/Greeting.java"], - visibility = ["//src/main/java/com/example/cmdline:__pkg__"], - ) - ``` - - The target `//:greeter` is now visible to any target in the - `//src/main/java/com/example/cmdline` package. - - See the Build Encyclopedia for more - [visibility options](/docs/be/common-definitions.html#common.visibility). - - -6. Now you can build the runner binary by using the command: - - ``` - bazel build //src/main/java/com/example/cmdline:runner - ``` - - You’ll see output similar to: - - ``` - INFO: Found 1 target... - Target //src/main/java/com/example/cmdline:runner up-to-date: - bazel-bin/src/main/java/com/example/cmdline/runner.jar - bazel-bin/src/main/java/com/example/cmdline/runner - INFO: Elapsed time: 1.576s, Critical Path: 0.81s - ``` - - -7. Execute the file by using this command: - - ``` - bazel-bin/src/main/java/com/example/cmdline/runner - ``` - -You’ve now refined your build so that it is broken down into smaller -self-contained libraries, and so that the explicit dependencies are more -granular. You’ve also built the Java project using multiple packages. - -## Use labels to reference targets - -In the BUILD files and in the command line, you have been using target labels -to reference targets. The label’s syntax is: `//path/to/package:target-name`, -where “`//`” is the workspace’s root, and “`:`” separates the package name and -the target name. If the target is a rule target and so defined in a BUILD file, -“`path/to/package`” would be the path of the BUILD file itself. “`Target-name`” -would be the same as the “`name`” attribute in the target in the BUILD file. - -The first BUILD file you created in this tutorial is in the same directory as -the WORKSPACE file. When referencing rule targets defined in that file, nothing -is needed for the path to the package because the workspace root and the package -root are the same directory. Here are the labels of the two targets defined -in that first BUILD file: - -``` -//:my-runner -//:greeter -``` - -The second BUILD file has a longer path from the workspace root to the package -root. The label for the target in that BUILD file is: - -``` -//src/main/java/com/example/cmdline:runner -``` - -Target labels can be shortened in a variety of ways. Within a BUILD file, if -you’re referencing a target from the same package, you can write the label -starting at “`:`”. For example, the rule target `greeter` can always be written -as `//:greeter`, and in the BUILD file where it’s defined, it can also be -written as `:greeter`. This shortened label in a BUILD file makes it immediately -clear which targets are in the current package. - -A rule target’s name will always be defined by its name attribute. A target’s -name is a bit more complex when it’s in a directory other than the root -of the package. In that case, the target’s label is: -`//path/to/package:path/to/file/file_name`. - -## Package a Java target for deployment - -To understand what you’ve built and what else can be built with Bazel, you need -to understand the capabilities of the rules used in your BUILD files. Always go -to the [Build Encyclopedia](/docs/be/overview.html) for this information. - -Let’s look at packaging a Java target for deployment, which requires you to -know the capabilities of the rule `java_binary`. - -You’re able to run the Java binaries you created in this tutorial, but you -can’t simply run it on a server, because it relies on the greeting library jar -to actually run. "Packaging an artifact so it can be run reliably outside the -development environment involves bundling it with all of its runtime -dependencies. Let's see now what’s needed to package the binaries. - -The rule [java_binary](/docs/be/java.html#java_binary) produces a Java archive -(“jar file”) and a wrapper shell script. The file `<target-name>_deploy.jar` -is suitable for deployment, but it’s only built by this rule if explicitly -requested. Let’s investigate. - -1. Look at the contents of the output `runner.jar` by using this command: - - ``` - jar tf bazel-bin/src/main/java/com/example/cmdline/runner.jar - ``` - - You’ll see output similar to: - - ``` - META-INF/ - META-INF/MANIFEST.MF - com/ - com/example/ - com/example/cmdline/ - com/example/cmdline/Runner.class - ``` - - You can see that `runner.jar` contains `Runner.class`, but not its - dependency `Greeting.class`. The `runner` script that Bazel generates adds - the greeter jar to the classpath, so running this program works locally. It - will not work if you want to copy `runner.jar` to another machine and use - it as a standalone binary. - - -2. The rule `java_binary` allows you to build a self-contained binary that can - be deployed. To create this binary, build `runner_deploy.jar` (or, more - generally, `<target-name>_deploy.jar`) by using this command: - - ``` - bazel build //src/main/java/com/example/cmdline:runner_deploy.jar - ``` - - You’ll see output similar to: - - ``` - INFO: Found 1 target... - Target //src/main/java/com/example/cmdline:runner_deploy.jar up-to-date: - bazel-bin/src/main/java/com/example/cmdline/runner_deploy.jar - INFO: Elapsed time: 1.700s, Critical Path: 0.23s - ``` - - The file runner_deploy.jar will contain all of its dependencies, and so can - be used as a standalone binary. - -You’ve now created a Java target that you can distribute and deploy. To do so, -you had to be aware of what outputs the Bazel Java rule `java_binary` is able to -produce. - -## Further topics - -* Try the tutorial [Build C++](/docs/tutorial/cpp.md). -* Try the tutorial [Build Mobile Application](/docs/tutorial/app.md). - diff --git a/site/versions/master/docs/tutorial/review.md b/site/versions/master/docs/tutorial/review.md deleted file mode 100644 index 62d4501ad4..0000000000 --- a/site/versions/master/docs/tutorial/review.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -layout: documentation -title: Tutorial - Review ---- - -# Tutorial - Review - -In this tutorial, you used Bazel to build an [Android app](android-app.md), -an [iOS app](ios-app.md) and a [backend server](backend-server.md) that runs on -Google App Engine. - -To build these software outputs, you: - -* Set up a Bazel [workspace](workspace.md) that contained the source code - for the components and a `WORKSPACE` that identifies the top level of the - workspace directory -* Created a `BUILD` file for each component -* Updated the `WORKSPACE` file to contain references to the required - external dependencies -* Ran Bazel to build the software components - -The built mobile apps and backend server application files are located in the -`$WORKSPACE/bazel-bin` directory. - -Note that completed `WORKSPACE` and `BUILD` files for this tutorial are located -in the -[master branch](https://github.com/bazelbuild/examples/tree/master/tutorial) -of the GitHub repo. You can compare your work to the completed files for -additional help or troubleshooting. diff --git a/site/versions/master/docs/tutorial/workspace.md b/site/versions/master/docs/tutorial/workspace.md deleted file mode 100644 index eee1b1a350..0000000000 --- a/site/versions/master/docs/tutorial/workspace.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -layout: documentation -title: Tutorial - Set Up a Workspace ---- - -# Tutorial - Set Up a Workspace - -A [workspace](/docs/build-ref.html#workspaces) is a directory that contains the -source files for one or more software projects, as well as a `WORKSPACE` file -and `BUILD` files that contain the instructions that Bazel uses to build -the software. The workspace may also contain symbolic links to output -directories. - -A workspace directory can be located anywhere on your filesystem. In this -tutorial, your workspace directory is `$HOME/examples/tutorial/`, which -contains the sample project files you cloned from the GitHub repo in the -previous step. - -Note that Bazel itself doesn't make any requirements about how you organize -source files in your workspace. The sample source files in this tutorial are -organized according to common conventions for Android apps, iOS apps and App -Engine applications. - -For your convenience, set the `$WORKSPACE` environment variable now to refer to -your workspace directory. At the command line, enter: - -```bash -export WORKSPACE=$HOME/examples/tutorial -``` - -## Create a WORKSPACE file - -Every workspace must have a text file named `WORKSPACE` located in the top-level -workspace directory. This file may be empty or it may contain references -to [external dependencies](/docs/external.html) required to build the -software. - -For now, you'll create an empty `WORKSPACE` file, which simply serves to -identify the workspace directory. In later steps, you'll update the file to add -external dependency information. - -Enter the following at the command line: - -```bash -touch $WORKSPACE/WORKSPACE -``` - -This creates the empty `WORKSPACE` file. - -## What's next - -Now that you've set up your workspace, you can -[build the Android app](android-app.md). diff --git a/site/versions/master/docs/windows.md b/site/versions/master/docs/windows.md deleted file mode 100644 index 5a0b6b51c4..0000000000 --- a/site/versions/master/docs/windows.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -layout: documentation -title: Windows ---- - -# Using Bazel on Windows - -Windows support is experimental. Known issues are [marked with label -"Windows"](https://github.com/bazelbuild/bazel/issues?q=is%3Aissue+is%3Aopen+label%3A%22category%3A+multi-platform+%3E+windows%22) -on github issues. - -We currently support only 64 bit Windows 7 or higher and we compile Bazel as a -msys2 binary. - -## <a name="install"></a>Installation - -See instructions on the [installation page](install-windows.md). - -## <a name="requirements"></a>Requirements - -Before you can compile or run Bazel, you will need to set some environment -variables: - -```bash -export JAVA_HOME="$(ls -d C:/Program\ Files/Java/jdk* | sort | tail -n 1)" -export BAZEL_SH=c:/tools/msys64/usr/bin/bash.exe -``` - -If you run outside of `bash`, ensure that ``msys-2.0.dll`` is in your ``PATH`` -(if you install msys2 to ``c:\tools\msys64``, just add -``c:\tools\msys64\usr\bin`` to ``PATH``). - -If you have another tool that vendors msys2 (such as msysgit), then -``c:\tools\msys64\usr\bin`` must appear in your ``PATH`` *before* entries for -those tools. - -Similarly, if you have [bash on Ubuntu on -Windows](https://msdn.microsoft.com/en-gb/commandline/wsl/about) installed, you -should make sure ``c:\tools\msys64\usr\bin`` appears in ``PATH`` *before* -``c:\windows\system32``, because otherwise Windows' ``bash.exe`` is used before -msys2's. - -Use ``where msys-2.0.dll`` to ensure your ``PATH`` is set up correctly. - -To **run** Bazel (even pre-built binaries), you will need: - -* Java JDK 8 or later -* [msys2 shell](https://msys2.github.io/) (need to be installed at - ``C:\tools\msys64\``). - * We build against version - [20160205](https://sourceforge.net/projects/msys2/files/Base/x86_64/msys2-x86_64-20160205.exe/download), - you will need this version in order to run the pre-built - [release Bazel binaries](https://github.com/bazelbuild/bazel/releases). - * You can also use newer versions or the - [latest version](https://sourceforge.net/projects/msys2/files/latest/download?source=files), - but then you will need to compile Bazel from the distribution archive (the - source zip file) so that it's linked against the right version of - ``msys-2.0.dll``. See also the - [known issues](install-compile-source.md#known-issues-when-compiling-from-source). -* Several msys2 packages. Use the ``pacman`` command to install them: - - ``` - pacman -Syuu gcc git curl zip unzip zlib-devel - ``` - -To **compile** Bazel, in addition to the above you will need: - -* [Visual C++ Build Tools](http://landinghub.visualstudio.com/visual-cpp-build-tools) - or the full [Visual C++](https://www.visualstudio.com/) (as part of Visual - Studio; Community Edition is fine) with Windows SDK installed. -* You may need to apply some patches/workarounds, see the - [known issues](install-compile-source.md#known-issues-when-compiling-from-source). - -## <a name="compiling"></a>Compiling Bazel on Windows - -Ensure you have the [requirements](#requirements). - -To build Bazel: - -* Open the msys2 shell. -* Clone the Bazel git repository as normal. -* Set the environment variables (see above) -* Run ``compile.sh`` in Bazel directory. -* If all works fine, bazel will be built at ``output\bazel.exe``. - - -## <a name="using"></a>Using Bazel on Windows - -Bazel now supports building C++, Java and Python targets on Windows. - -### Build C++ - -To build C++ targets, you will need: - -* [Visual Studio](https://www.visualstudio.com/) -<br/>We are using MSVC as the native C++ toolchain, so please ensure you have Visual -Studio installed with the `Visual C++ > Common Tools for Visual C++` and -`Visual C++ > Microsoft Foundation Classes for C++` features. -(which is NOT the default installation type of Visual Studio). -You can set `BAZEL_VS` environment variable to tell Bazel -where Visual Studio is, otherwise Bazel will try to find the latest version installed. -<br/>For example: `export BAZEL_VS="C:/Program Files (x86)/Microsoft Visual Studio 14.0"` - -* [Python](https://www.python.org/downloads/) -<br/>Both Python 2 and Python 3 are supported. -Currently, we use Python wrapper scripts to call the actual MSVC compiler, so -please make sure Python is installed and its location is added into PATH. -It's also a good idea to set `BAZEL_PYTHON` environment variable to tell Bazel -where Python is. -<br/>For example: `export BAZEL_PYTHON=C:/Python27/python.exe` - -Bazel will auto-configure the location of Visual Studio and Python at the first -time you build any target. -If you need to auto-configure again, just run `bazel clean` then build a target. - -If everything is set up, you can build C++ target now! - -```bash -bazel build examples/cpp:hello-world -./bazel-bin/examples/cpp/hello-world.exe -bazel run examples/cpp:hello-world -``` - -However, with Bazel version prior to 0.5.0, MSVC -toolchain is not default on Windows, you should use flag -`--cpu=x64_windows_msvc` to enable it like this: - -```bash -bazel build --cpu=x64_windows_msvc examples/cpp:hello-world -``` - -### Build Java - -Building Java targets works well on Windows, no special configuration is needed. -Just try: - -```bash -bazel build examples/java-native/src/main/java/com/example/myproject:hello-world -./bazel-bin/examples/java-native/src/main/java/com/example/myproject/hello-world -bazel run examples/java-native/src/main/java/com/example/myproject:hello-world -``` - -### Build Python - -On Windows, we build a self-extracting zip file for executable Python targets, you can even use -`python ./bazel-bin/path/to/target` to run it in native Windows command line (cmd.exe). -See more details in this [design doc](/designs/2016/09/05/build-python-on-windows.html). - -```bash -bazel build examples/py_native:bin -./bazel-bin/examples/py_native/bin -python ./bazel-bin/examples/py_native/bin # This works in both msys and cmd.exe -bazel run examples/py_native:bin -``` |
