diff options
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 -``` |
