diff options
| author |  David Chen <dzc@google.com> | 2016-08-29 08:56:37 +0000 |
|---|---|---|
| committer |  Klaus Aehlig <aehlig@google.com> | 2016-08-29 09:42:52 +0000 |
| commit | 15c09dd1b5dbd7e76fe42d193a79dab8bfc24abc (patch) | |
| tree | e6df9943f0f96c095a6f91240a8f4bc3a84708d9 /site | |
| parent | 6f2e6fb1eff1a7a265778abf1eb32a850765599e (diff) | |
Replace doc pages with redirects to versioned doc pages.
* Add a new `redirect` Jekyll layout.
* Replace all pages under docs/ with redirects to corresponding page under
versions/master/.
* Prepend links on Documentation sidebar, including generated navs for the
Skylark Library and Build Encyclopedia, with prefix for versioned directory.
* Add code to both the internal jekyll-config.sh and external jekyll-tree.sh
to add redirect pages for the Skylark Library and Build Encyclopedia.
* Bring the branched User Manual doc up to date with latest changes.
--
MOS_MIGRATED_REVID=131568800
Diffstat (limited to 'site')
47 files changed, 142 insertions, 12972 deletions
diff --git a/site/BUILD b/site/BUILD index 89cfc8996d..52f9da12be 100644 --- a/site/BUILD +++ b/site/BUILD @@ -2,7 +2,7 @@ load("@bazel_tools//tools/build_defs/pkg:pkg.bzl", "pkg_tar") exports_files( [ - "docs/bazel-user-manual.html", + "versions/master/docs/bazel-user-manual.html", "command-line-reference-prefix.html", "command-line-reference-suffix.html", ], diff --git a/site/_config.yml b/site/_config.yml index d6dccbaa8e..1caaaba15b 100644 --- a/site/_config.yml +++ b/site/_config.yml @@ -4,3 +4,4 @@ paginate: 10 highlighter: pygments sass: sass_dir: _sass +default_version: "master" diff --git a/site/_layouts/documentation.html b/site/_layouts/documentation.html index ec17b6a74c..a68b1a9aa8 100644 --- a/site/_layouts/documentation.html +++ b/site/_layouts/documentation.html @@ -1,5 +1,6 @@ --- nav: docs +version_prefix: /versions/master --- <!DOCTYPE html> @@ -24,8 +25,8 @@ nav: docs </a> <nav class="sidebar collapse" id="sidebar-nav"> <ul class="sidebar-nav"> - <li><a href="/docs/install.html">Installing</a></li> - <li><a href="/docs/getting-started.html">Getting Started</a></li> + <li><a href="{{ page.version_prefix }}/docs/install.html">Installing</a></li> + <li><a href="{{ page.version_prefix }}/docs/getting-started.html">Getting Started</a></li> <li> <a class="sidebar-nav-heading" data-toggle="collapse" href="#tutorial-menu" aria-expanded="false" @@ -33,48 +34,48 @@ nav: docs Tutorial <span class="caret"></span> </a> <ul class="collapse sidebar-nav sidebar-submenu" id="tutorial-menu"> - <li><a href="/docs/tutorial/java.html">Build Java</a></li> - <li><a href="/docs/tutorial/cpp.html">Build C++</a></li> + <li><a href="{{ page.version_prefix }}/docs/tutorial/java.html">Build Java</a></li> + <li><a href="{{ page.version_prefix }}/docs/tutorial/cpp.html">Build C++</a></li> <li> <a class="sidebar-nav-heading" href="#app-menu" data-toggle="collapse" aria-expanded="false" aria-controls="app-menu"> Build Mobile Application </a> <ul class="collapse sidebar-nav sidebar-submenu" id="app-menu"> - <li><a href="/docs/tutorial/app.html">Introduction</a></li> - <li><a href="/docs/tutorial/environment.html">Set Up Your Environment</a></li> - <li><a href="/docs/tutorial/workspace.html">Set Up a Workspace</a></li> - <li><a href="/docs/tutorial/android-app.html">Build an Android App</a></li> - <li><a href="/docs/tutorial/ios-app.html">Build an iOS App</a></li> - <li><a href="/docs/tutorial/backend-server.html">Build the Backend Server</a></li> - <li><a href="/docs/tutorial/review.html">Review</a></li> + <li><a href="{{ page.version_prefix }}/docs/tutorial/app.html">Introduction</a></li> + <li><a href="{{ page.version_prefix }}/docs/tutorial/environment.html">Set Up Your Environment</a></li> + <li><a href="{{ page.version_prefix }}/docs/tutorial/workspace.html">Set Up a Workspace</a></li> + <li><a href="{{ page.version_prefix }}/docs/tutorial/android-app.html">Build an Android App</a></li> + <li><a href="{{ page.version_prefix }}/docs/tutorial/ios-app.html">Build an iOS App</a></li> + <li><a href="{{ page.version_prefix }}/docs/tutorial/backend-server.html">Build the Backend Server</a></li> + <li><a href="{{ page.version_prefix }}/docs/tutorial/review.html">Review</a></li> </ul> </li> </ul> </li> - <li><a href="/docs/support.html">Get Support</a></li> + <li><a href="{{ page.version_prefix }}/docs/support.html">Get Support</a></li> </ul> <h3>Using Bazel</h3> <ul class="sidebar-nav"> - <li><a href="/docs/build-ref.html">BUILD files</a></li> - <li><a href="/docs/bazel-user-manual.html">User Manual</a></li> - <li><a href="/docs/test-encyclopedia.html">Writing Tests</a></li> - <li><a href="/docs/query.html">Query Language</a></li> - <li><a href="/docs/query-how-to.html">Query How-To</a></li> - <li><a href="/docs/mobile-install.html">mobile-install (Android)</a></li> - <li><a href="/docs/external.html">External Dependencies</a></li> - <li><a href="/docs/command-line-reference.html">Command-line Reference</a></li> - <li><a href="/docs/output_directories.html">Output Directories</a></li> + <li><a href="{{ page.version_prefix }}/docs/build-ref.html">BUILD files</a></li> + <li><a href="{{ page.version_prefix }}/docs/bazel-user-manual.html">User Manual</a></li> + <li><a href="{{ page.version_prefix }}/docs/test-encyclopedia.html">Writing Tests</a></li> + <li><a href="{{ page.version_prefix }}/docs/query.html">Query Language</a></li> + <li><a href="{{ page.version_prefix }}/docs/query-how-to.html">Query How-To</a></li> + <li><a href="{{ page.version_prefix }}/docs/mobile-install.html">mobile-install (Android)</a></li> + <li><a href="{{ page.version_prefix }}/docs/external.html">External Dependencies</a></li> + <li><a href="{{ page.version_prefix }}/docs/command-line-reference.html">Command-line Reference</a></li> + <li><a href="{{ page.version_prefix }}/docs/output_directories.html">Output Directories</a></li> </ul> {% include be-nav.html %} <h3>Extensions</h3> <ul class="sidebar-nav"> - <li><a href="/docs/skylark/concepts.html">Overview</a></li> - <li><a href="/docs/skylark/macros.html">Macros</a></li> - <li><a href="/docs/skylark/rules.html">Rules</a></li> - <li><a href="/docs/skylark/aspects.html">Aspects</a></li> - <li><a href="/docs/skylark/repository_rules.html">Repository rules</a></li> - <li><a href="/docs/rule-challenges.html">Challenges of writing rules</a></li> + <li><a href="{{ page.version_prefix }}/docs/skylark/concepts.html">Overview</a></li> + <li><a href="{{ page.version_prefix }}/docs/skylark/macros.html">Macros</a></li> + <li><a href="{{ page.version_prefix }}/docs/skylark/rules.html">Rules</a></li> + <li><a href="{{ page.version_prefix }}/docs/skylark/aspects.html">Aspects</a></li> + <li><a href="{{ page.version_prefix }}/docs/skylark/repository_rules.html">Repository rules</a></li> + <li><a href="{{ page.version_prefix }}/docs/rule-challenges.html">Challenges of writing rules</a></li> <li> <a class="sidebar-nav-heading" data-toggle="collapse" href="#skylark-lib-menu" aria-expanded="false" @@ -85,8 +86,8 @@ nav: docs {% include skylark-nav.html %} </ul> </li> - <li><a href="/docs/skylark/cookbook.html">Examples</a></li> - <li><a href="/docs/skylark/deploying.html">Packaging rules</a></li> + <li><a href="{{ page.version_prefix }}/docs/skylark/cookbook.html">Examples</a></li> + <li><a href="{{ page.version_prefix }}/docs/skylark/deploying.html">Packaging rules</a></li> </ul> </nav> </div> diff --git a/site/_layouts/redirect.html b/site/_layouts/redirect.html new file mode 100644 index 0000000000..85ae15edbf --- /dev/null +++ b/site/_layouts/redirect.html @@ -0,0 +1,7 @@ +<html> + <head> + <script> + window.location.replace("/versions/{{ site.default_version }}/{{ page.redirect }}"); + </script> + </head> +</html> diff --git a/site/docs/bazel-user-manual.html b/site/docs/bazel-user-manual.html deleted file mode 100644 index 3480529df0..0000000000 --- a/site/docs/bazel-user-manual.html +++ /dev/null @@ -1,3720 +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 path of the base workspace directory - and your userid, so if you build in multiple workspaces, you'll have - multiple Bazel server processes. Multiple users on the same - workstation can build concurrently in the same workspace. 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. -</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--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 also output - a <i>symbol counts</i> file (via the <code>--print-symbol-counts</code> gold - option) that logs the number of symbols from each .o input that were used in - the binary. This 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> - -<h4 id='flag--javawarn'><code class='flag'>--javawarn (all|cast|deprecation|empty|unchecked|fallthrough|path|rawtypes|serial|finally|overrides)</code></h4> -<p> - This option is used to enable Java warnings across an entire build. It takes - an argument which is a javac warning to be enabled, overriding any other Java - options that disable the given warning. The arguments to this option are - appended to the "-Xlint:" flag to javac, and must be exactly one of - the listed warnings. -</p> -<p> - For example: -</p> -<pre> - % bazel build --javawarn="deprecation" --javawarn="unchecked" //java/... -</pre> -<p> - Note that changing <code class='flag'>--javawarn</code> settings will force a recompilation - of all affected classes. -</p> - -<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--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--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--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--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 options set the label or the path of the base Java installation to use - for running JavaBuilder, SingleJar, and is also used for bazel run and inside - Java binaries built by <code>java_binary</code> rules. 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--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,--build-id=md5' '-Wl,--hash-style=gnu' -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 the test (not to the test runner). 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_blaze_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 BINMODE - -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. -</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. We are working to come up with a better - solution. -</p> -<h4 id='flag--adb'><code class='flag'>--adb</code></h4> -<p> - Indicates the <code>adb</code> binary to be used. When unspecified, the binary - in the repository is used. -</p> -<h4 id='flag--adb_arg'><code class='flag'>--adb_arg</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. - Example: -<pre>% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef -</pre> -will invoke <code>adb</code> as -<pre> -adb -s deadbeef install ... -</pre> - -</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> -</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. Note that it is currently - only possible to provide these options on the command line, not in the rc - files. Can be specified multiple times to add flags from several - config sections. -</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/docs/bazel-user-manual.md b/site/docs/bazel-user-manual.md new file mode 100644 index 0000000000..f9fea184a6 --- /dev/null +++ b/site/docs/bazel-user-manual.md @@ -0,0 +1,4 @@ +--- +layout: redirect +redirect: docs/bazel-user-manual.html +--- diff --git a/site/docs/build-ref.html b/site/docs/build-ref.html deleted file mode 100644 index ac2aa7b247..0000000000 --- a/site/docs/build-ref.html +++ /dev/null @@ -1,1195 +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'> -<svg width="582pt" height="188pt" - viewBox="0.00 0.00 581.89 188.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> -<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 184)"> -<title>G1</title> -<polygon fill="white" stroke="transparent" points="-4,4 -4,-184 577.888,-184 577.888,4 -4,4"/> -<!-- Target --> -<g id="node1" class="node"> -<title>Target</title> -<ellipse fill="none" stroke="black" cx="376.795" cy="-162" rx="40.0939" ry="18"/> -<text text-anchor="middle" x="376.795" y="-158.3" font-family="arial" font-size="14.00">Target</text> -</g> -<!-- Rule --> -<g id="node2" class="node"> -<title>Rule</title> -<ellipse fill="none" stroke="black" cx="241.795" cy="-90" rx="30.5947" ry="18"/> -<text text-anchor="middle" x="241.795" y="-86.3" font-family="arial" font-size="14.00">Rule</text> -</g> -<!-- Target->Rule --> -<g id="edge1" class="edge"> -<title>Target->Rule</title> -<path fill="none" stroke="black" d="M351.402,-147.834C329.151,-136.296 296.735,-119.487 272.926,-107.142"/> -<polygon fill="black" stroke="black" points="274.432,-103.98 263.943,-102.484 271.21,-110.195 274.432,-103.98"/> -</g> -<!-- File --> -<g id="node6" class="node"> -<title>File</title> -<ellipse fill="none" stroke="black" cx="376.795" cy="-90" rx="30.5947" ry="18"/> -<text text-anchor="middle" x="376.795" y="-86.3" font-family="arial" font-size="14.00">File</text> -</g> -<!-- Target->File --> -<g id="edge5" class="edge"> -<title>Target->File</title> -<path fill="none" stroke="black" d="M376.795,-143.697C376.795,-135.983 376.795,-126.712 376.795,-118.112"/> -<polygon fill="black" stroke="black" points="380.295,-118.104 376.795,-108.104 373.295,-118.104 380.295,-118.104"/> -</g> -<!-- Package group --> -<g id="node9" class="node"> -<title>Package group</title> -<ellipse fill="none" stroke="black" cx="499.795" cy="-90" rx="74.187" ry="18"/> -<text text-anchor="middle" x="499.795" y="-86.3" font-family="arial" font-size="14.00">Package group</text> -</g> -<!-- Target->Package group --> -<g id="edge8" class="edge"> -<title>Target->Package group</title> -<path fill="none" stroke="black" d="M400.802,-147.337C418.506,-137.262 442.911,-123.373 463.059,-111.906"/> -<polygon fill="black" stroke="black" points="465.018,-114.819 471.978,-106.831 461.555,-108.735 465.018,-114.819"/> -</g> -<!-- cc_library --> -<g id="node3" class="node"> -<title>cc_library</title> -<ellipse fill="none" stroke="black" cx="59.7947" cy="-18" rx="59.5901" ry="18"/> -<text text-anchor="middle" x="59.7947" y="-14.3" font-family="arial" font-size="14.00">cc_library</text> -</g> -<!-- Rule->cc_library --> -<g id="edge2" class="edge"> -<title>Rule->cc_library</title> -<path fill="none" stroke="black" d="M216.87,-79.4136C188.038,-68.3243 140.006,-49.8505 104.633,-36.2453"/> -<polygon fill="black" stroke="black" points="105.607,-32.8704 95.0176,-32.5473 103.095,-39.4038 105.607,-32.8704"/> -</g> -<!-- java_test --> -<g id="node4" class="node"> -<title>java_test</title> -<ellipse fill="none" stroke="black" cx="191.795" cy="-18" rx="54.6905" ry="18"/> -<text text-anchor="middle" x="191.795" y="-14.3" font-family="arial" font-size="14.00">java_test</text> -</g> -<!-- Rule->java_test --> -<g id="edge3" class="edge"> -<title>Rule->java_test</title> -<path fill="none" stroke="black" d="M230.449,-73.1159C224.298,-64.5051 216.557,-53.6674 209.621,-43.9567"/> -<polygon fill="black" stroke="black" points="212.453,-41.9004 203.793,-35.7973 206.757,-45.9691 212.453,-41.9004"/> -</g> -<!-- ... --> -<g id="node5" class="node"> -<title>...</title> -<ellipse fill="none" stroke="black" cx="291.795" cy="-18" rx="27" ry="18"/> -<text text-anchor="middle" x="291.795" y="-14.3" font-family="arial" font-size="14.00">...</text> -</g> -<!-- Rule->... --> -<g id="edge4" class="edge"> -<title>Rule->...</title> -<path fill="none" stroke="black" d="M253.14,-73.1159C259.469,-64.2555 267.482,-53.0373 274.57,-43.1152"/> -<polygon fill="black" stroke="black" points="277.529,-44.9929 280.494,-34.8212 271.833,-40.9242 277.529,-44.9929"/> -</g> -<!-- Source --> -<g id="node7" class="node"> -<title>Source</title> -<ellipse fill="none" stroke="black" cx="376.795" cy="-18" rx="40.0939" ry="18"/> -<text text-anchor="middle" x="376.795" y="-14.3" font-family="arial" font-size="14.00">Source</text> -</g> -<!-- File->Source --> -<g id="edge6" class="edge"> -<title>File->Source</title> -<path fill="none" stroke="black" d="M376.795,-71.6966C376.795,-63.9827 376.795,-54.7125 376.795,-46.1124"/> -<polygon fill="black" stroke="black" points="380.295,-46.1043 376.795,-36.1043 373.295,-46.1044 380.295,-46.1043"/> -</g> -<!-- Generated --> -<g id="node8" class="node"> -<title>Generated</title> -<ellipse fill="none" stroke="black" cx="489.795" cy="-18" rx="54.6905" ry="18"/> -<text text-anchor="middle" x="489.795" y="-14.3" font-family="arial" font-size="14.00">Generated</text> -</g> -<!-- File->Generated --> -<g id="edge7" class="edge"> -<title>File->Generated</title> -<path fill="none" stroke="black" d="M396.997,-76.4854C413.512,-66.2547 437.203,-51.579 456.513,-39.6169"/> -<polygon fill="black" stroke="black" points="458.378,-42.579 465.036,-34.3375 454.691,-36.6283 458.378,-42.579"/> -</g> -</g> -</svg> -<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 start with a lower-case ASCII letter - (<code>a</code>–<code>z</code>), - and must be composed entirely of characters drawn from the set - <code>a</code>–<code>z</code>, <code>0</code>–<code>9</code>, - '<code>_</code>', and '<code>/</code>'. -</p> - -<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"> -<svg width="157pt" height="246pt" - viewBox="0.00 0.00 156.50 246.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> -<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 242)"> -<title>G1</title> -<polygon fill="white" stroke="transparent" points="-4,4 -4,-242 152.5,-242 152.5,4 -4,4"/> -<!-- r1 --> -<g id="node1" class="node"> -<title>r1</title> -<polygon fill="none" stroke="black" points="88.5,-173 34.5,-173 34.5,-137 88.5,-137 88.5,-173"/> -<text text-anchor="middle" x="61.5" y="-152.5" font-family="arial" font-size="10.00" fill="#006000">rule</text> -</g> -<!-- s1 --> -<g id="node3" class="node"> -<title>s1</title> -<ellipse fill="none" stroke="black" cx="14.5" cy="-223.5" rx="14.5" ry="14.5"/> -<text text-anchor="middle" x="14.5" y="-221" font-family="arial" font-size="10.00" fill="#006000">in</text> -</g> -<!-- r1->s1 --> -<g id="edge1" class="edge"> -<title>r1->s1</title> -<path fill="none" stroke="black" d="M49.3963,-173.125C42.9655,-182.224 35.0324,-193.449 28.3559,-202.895"/> -<polygon fill="black" stroke="black" points="25.3432,-201.094 22.4297,-211.28 31.0596,-205.134 25.3432,-201.094"/> -</g> -<!-- s2 --> -<g id="node4" class="node"> -<title>s2</title> -<ellipse fill="none" stroke="black" cx="61.5" cy="-223.5" rx="14.5" ry="14.5"/> -<text text-anchor="middle" x="61.5" y="-221" font-family="arial" font-size="10.00" fill="#006000">in</text> -</g> -<!-- r1->s2 --> -<g id="edge2" class="edge"> -<title>r1->s2</title> -<path fill="none" stroke="black" d="M61.5,-173.125C61.5,-180.918 61.5,-190.27 61.5,-198.729"/> -<polygon fill="black" stroke="black" points="58.0001,-198.782 61.5,-208.782 65.0001,-198.782 58.0001,-198.782"/> -</g> -<!-- s3 --> -<g id="node5" class="node"> -<title>s3</title> -<ellipse fill="none" stroke="black" cx="108.5" cy="-223.5" rx="14.5" ry="14.5"/> -<text text-anchor="middle" x="108.5" y="-221" font-family="arial" font-size="10.00" fill="#006000">in</text> -</g> -<!-- r1->s3 --> -<g id="edge3" class="edge"> -<title>r1->s3</title> -<path fill="none" stroke="black" d="M73.6037,-173.125C80.0345,-182.224 87.9676,-193.449 94.6441,-202.895"/> -<polygon fill="black" stroke="black" points="91.9404,-205.134 100.57,-211.28 97.6568,-201.094 91.9404,-205.134"/> -</g> -<!-- r2 --> -<g id="node2" class="node"> -<title>r2</title> -<polygon fill="none" stroke="black" points="148.5,-101 94.5,-101 94.5,-65 148.5,-65 148.5,-101"/> -<text text-anchor="middle" x="121.5" y="-80.5" font-family="arial" font-size="10.00" fill="#006000">rule</text> -</g> -<!-- r2->r1 --> -<g id="edge5" class="edge"> -<title>r2->r1</title> -<path fill="none" stroke="black" d="M106.669,-101.303C99.4753,-109.695 90.7033,-119.93 82.8097,-129.139"/> -<polygon fill="black" stroke="black" points="80.0114,-127.025 76.1609,-136.896 85.3262,-131.581 80.0114,-127.025"/> -</g> -<!-- s4 --> -<g id="node6" class="node"> -<title>s4</title> -<ellipse fill="none" stroke="black" cx="121.5" cy="-155" rx="14.5" ry="14.5"/> -<text text-anchor="middle" x="121.5" y="-152.5" font-family="arial" font-size="10.00" fill="#006000">in</text> -</g> -<!-- r2->s4 --> -<g id="edge4" class="edge"> -<title>r2->s4</title> -<path fill="none" stroke="black" d="M121.5,-101.303C121.5,-110.01 121.5,-120.7 121.5,-130.171"/> -<polygon fill="black" stroke="black" points="118,-130.175 121.5,-140.175 125,-130.176 118,-130.175"/> -</g> -<!-- o1 --> -<g id="node7" class="node"> -<title>o1</title> -<ellipse fill="none" stroke="black" cx="61.5" cy="-83" rx="14.5" ry="14.5"/> -<text text-anchor="middle" x="61.5" y="-80.5" font-family="arial" font-size="10.00" fill="#006000">out</text> -</g> -<!-- o1->r1 --> -<g id="edge6" class="edge"> -<title>o1->r1</title> -<path fill="none" stroke="black" d="M61.5,-97.8297C61.5,-106.081 61.5,-116.847 61.5,-126.744"/> -<polygon fill="black" stroke="black" points="58.0001,-126.981 61.5,-136.981 65.0001,-126.981 58.0001,-126.981"/> -</g> -<!-- o2 --> -<g id="node8" class="node"> -<title>o2</title> -<ellipse fill="none" stroke="black" cx="121.5" cy="-14.5" rx="14.5" ry="14.5"/> -<text text-anchor="middle" x="121.5" y="-12" font-family="arial" font-size="10.00" fill="#006000">out</text> -</g> -<!-- o2->r2 --> -<g id="edge7" class="edge"> -<title>o2->r2</title> -<path fill="none" stroke="black" d="M121.5,-29.2788C121.5,-36.6355 121.5,-45.9556 121.5,-54.7067"/> -<polygon fill="black" stroke="black" points="118,-54.9286 121.5,-64.9286 125,-54.9286 118,-54.9286"/> -</g> -</g> -</svg> -<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/docs/build-ref.md b/site/docs/build-ref.md new file mode 100644 index 0000000000..e08473d1f5 --- /dev/null +++ b/site/docs/build-ref.md @@ -0,0 +1,4 @@ +--- +layout: redirect +redirect: docs/build-ref.html +--- diff --git a/site/docs/docs_style.css b/site/docs/docs_style.css deleted file mode 100644 index bb225e1fd9..0000000000 --- a/site/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/docs/external.md b/site/docs/external.md index 1bcdc683d7..ec45348162 100644 --- a/site/docs/external.md +++ b/site/docs/external.md @@ -1,201 +1,4 @@ --- -layout: documentation -title: External Dependencies +layout: redirect +redirect: docs/external.html --- - -# Working with external dependencies - -Bazel is designed to have absolutely everything needed for a build, from source -code to libraries to compilers, under one directory (the workspace directory). -This is impractical for some version control systems and goes against how many -existing projects are structured. Thus, Bazel has a system for pulling in -dependencies from outside of the workspace. - -External dependencies can be specified in a `WORKSPACE` file in the -[workspace directory](/docs/build-ref.html#workspaces). This `WORKSPACE` file -uses the same Python-like syntax of BUILD files, but allows a different set of -rules. See the full list of rules that are allowed in the -[Workspace](/docs/be/workspace.html) list of rules in the Build -Encyclopedia. - -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`. - -## 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.io/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. This -means that if your project (`A`) depends on another project (`B`) which list a -dependency on project `C` in its `WORKSPACE` file, you'll have to add both `B` -and `C` to your project's `WORKSPACE` file. This 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. - -Bazel provides a tool to help generate these expansive `WORKSPACE` files, called -`generate_workspace`. This 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 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", -) -``` - -This 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. - -# Types of external dependencies - -There are a few basic types of external dependencies that can be created. - -## Combining Bazel projects - -If you have a second Bazel project that you'd like to use targets from, you can -use -[`local_repository`](http://bazel.io/docs/be/workspace.html#local_repository) -or [`http_archive`](http://bazel.io/docs/be/workspace.html#http_archive) -to symlink it from the local filesystem 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`. - -## Depending on non-Bazel projects - -Rules prefixed with `new_` (e.g., -[`new_local_repository`](http://bazel.io/docs/be/workspace.html#new_local_repository) -and [`new_http_archive`](http://bazel.io/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. - -# Caching of external dependencies - -Bazel caches external dependencies and only re-downloads or updates them when -the `WORKSPACE` file changes. If the `WORKSPACE` file does not change, Bazel -assumes that the external dependencies have not changed, either. This can cause -unexpected results, especially with local repositories. - -For instance, in the example above, suppose that `my-project/` has a target that -depends on `@coworkers-project//:a`, which you build. Then you change to -`coworkers-project/` and pull the latest updates to their library, which changes -the behavior of `@coworkers-project//:a`. If you go back to `my-project/` and -build your target again, it will assume `@coworkers-project//:a` is already -up-to-date and reuse the cached library (instead of realizing that the sources -have changed and, thus, rebuilding). - -To avoid this situation, prefer remote repositories to local ones and do not -manually change the files in `[output_base]/external`. If you change a file -in `[output_base]/external`, rerun `bazel fetch ...` to update the cache. diff --git a/site/docs/getting-started.md b/site/docs/getting-started.md index 0e91dd3b13..1e69dce256 100644 --- a/site/docs/getting-started.md +++ b/site/docs/getting-started.md @@ -1,97 +1,4 @@ --- -layout: documentation -title: Getting Started +layout: redirect +redirect: docs/getting-started.html --- - -# 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/docs/install.md b/site/docs/install.md index 206226f282..1166fe133c 100644 --- a/site/docs/install.md +++ b/site/docs/install.md @@ -1,278 +1,4 @@ --- -layout: documentation -title: Installing Bazel +layout: redirect +redirect: docs/install.html --- - -# Installing Bazel - -Supported platforms: - -* [Ubuntu Linux (Wily 15.10 and Trusty 14.04 LTS)](#ubuntu) -* [Mac OS X](#mac-os-x) -* [Windows (highly experimental)](windows.md) - -For other platforms, you can try to [compile from source](#compiling-from-source). - -Required Java version: - -* Java JDK 8 or later ([JDK 7](#jdk7) is still supported - but deprecated). - -Extras: - -* [Bash completion](#bash) -* [zsh completion](#zsh) - -For more information on using Bazel, see [Getting -started](getting-started.html). - - -## <a name="ubuntu"></a>Ubuntu - -Install Bazel on Ubuntu using one of the following methods: - - * [Using our custom APT repostiory](#install-on-ubuntu) - * [Using binary installer](#install-with-installer-ubuntu) - * [Compiling Bazel from source](#compiling-from-source) - -### <a name="install-on-ubuntu"></a> Using Bazel custom API repository (recommended) - -#### 1. Install JDK 8 - -If you are running **Ubuntu Wily (15.10)**, you can skip this step. -But for **Ubuntu Trusty (14.04 LTS)** users, since OpenJDK 8 is not available on Trusty, please install Oracle JDK 8: - -``` -$ sudo add-apt-repository ppa:webupd8team/java -$ sudo apt-get update -$ sudo apt-get install oracle-java8-installer -``` - -Note: You might need to `sudo apt-get install software-properties-common` if you don't have the `add-apt-repository` command. See [here](http://manpages.ubuntu.com/manpages/wily/man1/add-apt-repository.1.html). - -#### 2. 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://storage.googleapis.com/bazel-apt/doc/apt-key.pub.gpg | sudo apt-key add - -``` - -If you want to use the JDK 7, please replace `jdk1.8` with `jdk1.7` and if you want to install the testing version of Bazel, replace `stable` with `testing`. - -#### 3. Update and install Bazel - -`$ sudo apt-get update && sudo apt-get install bazel` - -Once installed, you can upgrade to newer version of Bazel with: - -`$ sudo apt-get upgrade bazel` - -### <a name="install-with-installer-ubuntu"></a>Install with Installer - -We provide binary installers on our -<a href="https://github.com/bazelbuild/bazel/releases">GitHub releases page</a> - -The installer only contains Bazel binary, some additional libraries are required to be installed on the machine to work. - - -#### 1. Install JDK 8 - -**Ubuntu Trusty (14.04 LTS).** OpenJDK 8 is not available on Trusty. To -install Oracle JDK 8: - -``` -$ sudo add-apt-repository ppa:webupd8team/java -$ sudo apt-get update -$ sudo apt-get install oracle-java8-installer -``` - -Note: You might need to `sudo apt-get install software-properties-common` if you don't have the `add-apt-repository` command. See [here](http://manpages.ubuntu.com/manpages/wily/man1/add-apt-repository.1.html). - -**Ubuntu Wily (15.10).** To install OpenJDK 8: - -``` -$ sudo apt-get install openjdk-8-jdk -``` - -#### 2. Install other required packages - -``` -$ sudo apt-get install pkg-config zip g++ zlib1g-dev unzip -``` - -#### 3. Download Bazel - -Download the [Bazel installer](https://github.com/bazelbuild/bazel/releases) for -your operating system. - -#### 4. Run the installer - -Run the installer: - -<pre> -$ chmod +x bazel-<em>version</em>-installer-<em>os</em>.sh -$ ./bazel-<em>version</em>-installer-<em>os</em>.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. - -#### 5. 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. - - - -## <a name="mac-os-x"></a>Mac OS X - -Install Bazel on Mac OS X using one of the following methods: - - * [Using Homebrew](#install-on-mac-os-x-homebrew) - * [Using binary installer](#install-with-installer-mac-os-x) - * [Compiling Bazel from source](#compiling-from-source) - - -### <a name="install-on-mac-os-x-homebrew"></a>Using Homebrew - -#### 1. Install Homebrew on Mac OS X (one time setup) - -`$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"` - -#### 2. Install Bazel Homebrew Package - -`$ brew install bazel` - -Once installed, you can upgrade to newer version of Bazel with: - -`$ brew upgrade bazel` - - -### <a name="install-with-installer-mac-os-x"></a>Install with installer - -We provide binary installers on our -<a href="https://github.com/bazelbuild/bazel/releases">GitHub releases page</a> - -The installer only contains Bazel binary, some additional libraries are required to be installed on the machine to work. - -#### 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 x64" under "Java SE Development Kit". This will download a -DMG image with an install wizard. - -#### 2. Install XCode command line tools - -Xcode can be downloaded from the -[Apple Developer Site](https://developer.apple.com/xcode/downloads/), which will -redirect to the 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 -``` - -#### 3. Download Bazel - -Download the [Bazel installer](https://github.com/bazelbuild/bazel/releases) for -your operating system. - -#### 4. Run the installer - -Run the installer: - -<pre> -$ chmod +x bazel-<em>version</em>-installer-<em>os</em>.sh -$ ./bazel-<em>version</em>-installer-<em>os</em>.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. - -#### 5. 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. - -## <a name="compiling-from-source"></a>Compiling from source - -If you would like to build Bazel from source, clone the source from GitHub and -run `./compile.sh` to build it: - -``` -$ git clone https://github.com/bazelbuild/bazel.git -$ cd bazel -$ ./compile.sh -``` - -This will create a bazel binary in `bazel-bin/src/bazel`. This binary is -self-contained, so it can be copied to a directory on the PATH (e.g., -`/usr/local/bin`) or used in-place. - -Check our [continuous integration](http://ci.bazel.io) for the current status of -the build. - - -## <a name="jdk7"></a>Using Bazel with JDK 7 (deprecated) - -Bazel version _0.1.0_ runs without any change with JDK 7. However, future -version will stop supporting JDK 7 when our CI cannot build for it anymore. -The installer for JDK 7 for Bazel versions after _0.1.0_ is labeled -<pre> -./bazel-<em>version</em>-jdk7-installer-<em>os</em>.sh -</pre> -If you wish to use JDK 7, follow the same steps as for JDK 8 but with the _jdk7_ installer or using a different APT repository as described [here](#1-add-bazel-distribution-uri-as-a-package-source-one-time-setup). - -## <a name="bash"></a>Getting bash completion - -Bazel comes with a bash completion script. To install it: - -1. Build it with Bazel: `bazel build //scripts:bazel-complete.bash`. -2. Copy the script `bazel-bin/scripts/bazel-complete.bash` 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 simply insert `source /path/to/bazel-complete.bash` in your - `~/.bashrc` file (under OS X, put it in your `~/.bash_profile` file). - -## <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 - ``` - -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/docs/mobile-install.md b/site/docs/mobile-install.md index f273871d0d..b209f182e5 100644 --- a/site/docs/mobile-install.md +++ b/site/docs/mobile-install.md @@ -1,220 +1,4 @@ --- -layout: documentation -title: mobile-install +layout: redirect +redirect: docs/mobile-install.html --- - -# 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/docs/output_directories.md b/site/docs/output_directories.md index 9b5f391cf7..aa176bb43c 100644 --- a/site/docs/output_directories.md +++ b/site/docs/output_directories.md @@ -1,133 +1,4 @@ --- -layout: documentation -title: Output Directory Layout +layout: redirect +redirect: docs/output_directories.html --- - -# 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. - server.socket <== Socket file for the server. - server.log <== Server logs. - <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 `--partial` option to -`bazel clean` will clean a configuration-specific `outputDir`, and the -`--expunge` option will clean the entire outputBase. diff --git a/site/docs/query-how-to.html b/site/docs/query-how-to.html index 8920843812..26ba74e3c9 100644 --- a/site/docs/query-how-to.html +++ b/site/docs/query-how-to.html @@ -1,399 +1,4 @@ --- -layout: documentation -title: Query how-to +layout: redirect +redirect: docs/query-how-to.html --- -<h1><a name="_Bazel_Query_How_To"> </a>Bazel query how-to</h1> - -<p>This is a quick tutorial to get you started using Bazel's query language to trace dependencies in your code.<p/> - -<p>For a language details and <code>--output</code> flag details, please see the reference manual, <a href="query.html">Bazel query reference</a>. You can get help for Bazel query by typing <code>bazel help query</code>.<p/> - -<p>To execute a query while ignoring errors such as missing targets, use the <tt>--keep_going</tt> flag.</p> - -<h2><a name="_Contents"> </a> Contents </h2> - -<p /> -<ul> -<li> <a href="#Finding_the_Dependencies_of_a_Ru">Finding the Dependencies of a Rule</a> -</li> -<li> <a href="#Tracing_the_Dependency_Chain_bet">Tracing the Dependency Chain between Two Packages</a> -<ul> -<li> <a href="#Aside_implicit_dependencies">Aside: implicit dependencies</a> -</li> -</ul> -</li> -<li> <a href="#Reverse_Dependencies">Reverse Dependencies</a> -</li> -<li> <a href="#Miscellaneous_Uses">Miscellaneous Uses</a> -<ul> -<li> <a href="#What_exists_">What exists ...</a> -<ul> -<li> <a href="#What_packages_exist_beneath_foo_">What packages exist beneath <code>foo</code>?</a> -</li> -<li> <a href="#What_rules_are_defined_in_the_foo">What rules are defined in the <code>foo</code> package?</a> -</li> -<li> <a href="#What_files_are_generated_by_rule">What files are generated by rules in the <code>foo</code> package?</a> -</li> -<li> <a href="#What_s_the_set_of_BUILD_files_ne">What's the set of BUILD files needed to build <code>//foo</code>?</a> -</li> -<li> <a href="#What_are_the_individual_tests_th">What are the individual tests that a <code>test_suite</code> expands to?</a> -<ul> -<li> <a href="#Which_of_those_are_C_tests_">Which of those are C++ tests?</a> -</li> -<li> <a href="#Which_of_those_are_small_Medium_">Which of those are small? Medium? Large?</a> -</li> -</ul> -</li> -<li> <a href="#What_are_the_tests_beneath_foo_t">What are the tests beneath <code>foo</code> that match a pattern?</a> -</li> -<li> <a href="#What_package_contains_file_java_">What package contains file <code>src/main/java/com/example/cache/LRUCache.java</code>?</a> -</li> -<li> <a href="#What_is_the_build_label_for_java">What is the build label for <code>src/main/java/com/example/cache/LRUCache.java</code>?</a> -</li> -<li> <a href="#What_build_rule_contains_file_ja">What build rule contains file <code>src/main/java/com/example/cache/LRUCache.java</code> as a source?</a> -</li> -</ul> -</li> -<li> <a href="#What_package_dependencies_exist_">What package dependencies exist ...</a> -<ul> -<li> <a href="#What_packages_does_foo_depend_on">What packages does <code>foo</code> depend on? (What do I need to check out to build <code>foo</code>)</a> -</li> -<li> <a href="#What_packages_does_the_foo_">What packages does the <code>foo</code> tree depend on, excluding <code>foo/contrib</code>?</a> -</li> -</ul> -</li> -<li> <a href="#What_rule_dependencies_exist_">What rule dependencies exist ...</a> -<ul> -<li> <a href="#What_genproto_rules_does_bar_">What genproto rules does bar depend upon?</a> -</li> -<li> <a href="#Find_the_definition_of_some_JNI_">Find the definition of some JNI (C++) library that is transitively depended upon by a Java binary rule in the servlet tree.</a> -<ul> -<li> <a href="#_Now_find_the_definitions_of_all">...Now find the definitions of all the Java binaries that depend on them</a> -</li> -</ul> -</li> -</ul> -</li> -<li> <a href="#What_file_dependencies_exist_">What file dependencies exist ...</a> -<ul> -<li> <a href="#What_s_the_complete_set_of_Java_">What's the complete set of Java source files required to build QUX?</a> -</li> -<li> <a href="#What_is_the_complete_set_of_Java">What is the complete set of Java source files required to build QUX's tests?</a> -</li> -</ul> -</li> -<li> <a href="#What_differences_in_dependencies">What differences in dependencies between X and Y exist ...</a> -<ul> -<li> <a href="#What_targets_does_foo_depend_on_">What targets does <code>//foo</code> depend on that <code>//foo:foolib</code> does not?</a> -</li> -<li> <a href="#What_C_libraries_do_the_foo_test">What C++ libraries do the <code>foo</code> tests depend on that the <code>//foo</code> production binary does <em>not</em> depend on?</a> -</li> -</ul> -</li> -<li> <a href="#Why_does_this_dependency_exist_">Why does this dependency exist ...</a> -<ul> -<li> <a href="#Why_does_bar_depend_on_groups">Why does <code>bar</code> depend on <code>groups2</code>?</a> -</li> -<li> <a href="#Show_me_a_path_from_docker_updater">Show me a path from <code>docker/updater:updater_systest</code> (a <code>py_test</code>) to some <code>cc_library</code> that it depends upon:</a> -</li> -<li> <a href="#Why_does_library_photos_fronten">Why does library <code>//photos/frontend:lib</code> depend on two variants of the same library <code>//third_party/jpeglib</code> and <code>//third_party/jpeg</code>?</a> -</li> -</ul> -</li> -<li> <a href="#What_depends_on_">What depends on ...</a> -<ul> -<li> <a href="#What_rules_under_bar_depend_o">What rules under bar depend on Y?</a> -</li> -</ul> -</li> -<li> <a href="#How_do_I_break_a_dependency_">How do I break a dependency ...</a> -<ul> -<li> <a href="#What_dependency_paths_do_I_have_">What dependency paths do I have to break to make <code>bar</code> no longer depend on X?</a> -</li> -</ul> -</li> -<li> <a href="#Misc_">Misc ...</a> -<ul> -<li> <a href="#How_many_sequential_steps_are_th">How many sequential steps are there in the <code>ServletSmokeTests</code> build?</a> -</li> -</ul> -</li> -</ul> -</li> -</ul> -<p /> -<h2><a name="Finding_the_Dependencies_of_a_Ru"> </a> Finding the Dependencies of a Rule </h2> -<p /> -To see the dependencies of <code>//src/main/java/com/example/base:base</code>, use the <code><b>deps</b></code> function in bazel query: -<p /> -<pre> - $ <kbd>bazel query "deps(src/main/java/com/example/base:base)"</kbd> - //resources:translation.xml - //src/main/java/com/example/base:AbstractPublishedUri.java - <var>...</var> -</pre> -<p /> - This is the set of all targets required to build <code>//src/main/java/com/example/base:base</code>. -<p /> -<h2><a name="Tracing_the_Dependency_Chain_bet"> </a> Tracing the Dependency Chain between Two Packages </h2> -<p /> -The library <code><b>//third_party/zlib:zlibonly</b></code> isn't in the BUILD file for <code>//src/main/java/com/example/base</code>, but it is an indirect dependency. How can we trace this dependency path? There are two useful functions here: <code>allpaths</code> and <code>somepath</code> -<p /> -<pre class="prettyprint"> -$ <kbd>bazel query "somepath(src/main/java/com/example/base:base, third_party/zlib:zlibonly)"</kbd> -//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 -$ <kbd>bazel query "allpaths(src/main/java/com/example/common/base:base, third_party/...)"</kbd> - <var>...many errors detected in BUILD files...</var> -//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 -</pre> -<p /> -<h3><a name="Aside_implicit_dependencies"> </a> Aside: implicit dependencies </h3> -<div> -<p /> -The BUILD file for <code>src/main/java/com/example/common/base</code> never references <code>//translations/tools:aggregator</code>. So, where's the direct dependency? -<p /> -Certain rules include implicit dependencies on additional libraries or tools. For example, to build a <code>genproto</code> rule, you need first to build the Protocol Compiler, so every <code>genproto</code> 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 <a href="https://github.com/bazelbuild/bazel/tree/master/src/main/java/com/example/devtools/build/lib/packages/RuleClassProvider.java">RuleClassProvider</a>.) -</div> -<p /> -<h2><a name="Reverse_Dependencies"> </a> Reverse Dependencies </h2> -<p /> -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 <code>rdeps(u, x)</code> to find the reverse dependencies of the targets in <code>x</code> within the transitive closure of <code>u</code>. -<p /> -Unfortunately, invoking, e.g., -<code>rdeps(..., daffie/annotations2:constants-lib)</code> -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. -<p /> -<h2><a name="Miscellaneous_Uses"> </a> Miscellaneous Uses </h2> -<p /> -You can use <code>bazel query</code> to analyze many dependency relationships. -<p /> -<h3><a name="What_exists_"> </a> What exists ... </h3> -<p /> -<h4><a name="What_packages_exist_beneath_foo_"> </a> What packages exist beneath <code>foo</code>? </h4> -<div> - <code>bazel query 'foo/...' --output package</code> -</div> -<p /> -<h4><a name="What_rules_are_defined_in_the_gw"> </a> What rules are defined in the <code>foo</code> package? </h4> -<div> - <code>bazel query 'kind(rule, foo:all)' --output label_kind</code> -</div> -<p /> -<h4><a name="What_files_are_generated_by_rule"> </a> What files are generated by rules in the <code>foo</code> package? </h4> - <code>bazel query 'kind("generated file", //foo:*)'</code> -<p /> -<h4><a name="What_s_the_set_of_BUILD_files_ne"> </a> What's the set of BUILD files needed to build <code>//foo</code>? </h4> -<div> - <code>bazel query 'buildfiles(deps(//foo))' --output location | cut -f1 -d:</code> -</div> -<p /> -<h4><a name="What_are_the_individual_tests_th"> </a> What are the individual tests that a <code>test_suite</code> expands to? </h4> -<div> - <code>bazel query 'tests(//foo:smoke_tests)'</code> -</div> -<p /> -<h5><a name="Which_of_those_are_C_tests_"> </a> Which of those are C++ tests? </h5> -<div> - <code>bazel query 'kind(cc_.*, tests(//foo:smoke_tests))'</code> -</div> -<p /> -<h5><a name="Which_of_those_are_small_Medium_"> </a> Which of those are small? Medium? Large? </h5> -<div> - <code>bazel query 'attr(size, small, tests(//foo:smoke_tests))'</code> -<p /> - <code>bazel query 'attr(size, medium, tests(//foo:smoke_tests))'</code> -<p /> - <code>bazel query 'attr(size, large, tests(//foo:smoke_tests))'</code> -</div> -<p /> -<p /> -<h4><a name="What_are_the_tests_beneath_foo_t"> </a> What are the tests beneath <code>foo</code> that match a pattern? </h4> - <code>bazel query 'filter("pa?t", kind(".*_test rule", //foo/...))'</code> -The pattern is a regex and is applied to the full name of the rule. It's similar to doing - <code>bazel query 'kind(".*_test rule", //foo/...)' | grep -E 'pa?t'</code> -<p /> -<h4><a name="What_package_contains_file_java_"> </a> What package contains file <code>src/main/java/com/example/cache/LRUCache.java</code>? </h4> - <code>bazel query 'buildfiles(src/main/java/com/example/cache/LRUCache.java)' --output=package</code> -<p /> -<h4><a name="What_is_the_build_label_for_java"> </a> What is the build label for <code>src/main/java/com/example/cache/LRUCache.java</code>? </h4> - <code>bazel query src/main/java/com/example/cache/LRUCache.java</code> -<p /> -<h4><a name="What_build_rule_contains_file_ja"> </a> What build rule contains file <code>src/main/java/com/example/cache/LRUCache.java</code> as a source? </h4> -<div> -<pre> -fullname=$(bazel query src/main/java/com/example/cache/LRUCache.java) -bazel query "attr('srcs', $fullname, ${fullname//:*/}:*)" -</pre> -</div> -<p /> -<h3><a name="What_package_dependencies_exist_"> </a> What package dependencies exist ... </h3> -<p /> -<h4><a name="What_packages_does_foo_depend_on"> </a> What packages does <code>foo</code> depend on? (What do I need to check out to build <code>foo</code>) </h4> -<div> - <code>bazel query 'buildfiles(deps(//foo:foo))' --output package</code> -<p /> -Note, <code>buildfiles</code> is required in order to correctly obtain all files -referenced by <code>subinclude</code>; see the reference manual for details. -</div> -<p /> -<h4><a name="What_packages_does_the_foo_"> </a> What packages does the <code>foo</code> tree depend on, excluding <code>foo/contrib</code>? </h4> -<div> - <code>bazel query 'deps(foo/... except foo/contrib/...)' --output package</code> -</div> -<p /> -<h3><a name="What_rule_dependencies_exist_"> </a> What rule dependencies exist ... </h3> -<h4><a name="What_genproto_rules_does_bar_"> </a> What genproto rules does bar depend upon? </h4> -<div> - <code>bazel query 'kind(genproto, deps(bar/...))'</code> -</div> -<p /> -<h4><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. </h4> -<div> - <code>bazel query 'some(kind(cc_.*library, deps(kind(java_binary, src/main/java/com/example/frontend/...))))' --output location</code> -</div> -<p /> -<h5><a name="_Now_find_the_definitions_of_all"> </a> ...Now find the definitions of all the Java binaries that depend on them </h5> -<div> - <pre>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)'</pre> -</div> -<p /> -<p /> -<h3><a name="What_file_dependencies_exist_"> </a> What file dependencies exist ... </h3> -<h4><a name="What_s_the_complete_set_of_Java_"> </a> What's the complete set of Java source files required to build QUX? </h4> -<div> - Source files: <code>bazel query 'kind("source file", deps(src/main/java/com/example/qux/...))' | grep java$</code> -<p /> - Generated files: <code>bazel query 'kind("generated file", deps(src/main/java/com/example/qux/...))' | grep java$</code> -</div> -<p /> -<h4><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? </h4> -<div> - Source files: <code>bazel query 'kind("source file", deps(kind(".*_test rule", javatests/com/example/qux/...)))' | grep java$</code> -<p /> - Generated files: <code>bazel query 'kind("generated file", deps(kind(".*_test rule", javatests/com/example/qux/...)))' | grep java$</code> -</div> -<p /> -<p /> -<h3><a name="What_differences_in_dependencies"> </a> What differences in dependencies between X and Y exist ... </h3> -<h4><a name="What_targets_does_foo_depend_on_"> </a> What targets does <code>//foo</code> depend on that <code>//foo:foolib</code> does not? </h4> -<div> - <code>bazel query 'deps(//foo) except deps(//foo:foolib)'</code> -</div> -<p /> -<h4><a name="What_C_libraries_do_the_foo_test"> </a> What C++ libraries do the <code>foo</code> tests depend on that the <code>//foo</code> production binary does <em>not</em> depend on? </h4> -<div> - <code>bazel query 'kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo))'</code> -</div> -<p /> -<h3><a name="Why_does_this_dependency_exist_"> </a> Why does this dependency exist ... </h3> -<p /> -<h4><a name="Why_does_bar_depend_on_groups"> </a> Why does <code>bar</code> depend on <code>groups2</code>? </h4> -<div> -<p /> - <code>bazel query 'somepath(bar/...,groups2/...:*)'</code> -<p /> - 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 <code>bar</code>. The query can then - be further refined to: -</div> -<p /> -<h4><a name="Show_me_a_path_from_docker_updater"> </a> Show me a path from <code>docker/updater:updater_systest</code> (a <code>py_test</code>) to some <code>cc_library</code> that it depends upon: </h4> -<div> -<pre>bazel query 'let cc = kind(cc_library, deps(docker/updater:updater_systest)) in - somepath(docker/updater:updater_systest, $cc)'</pre> -</div> -<p /> -<h4><a name="Why_does_library_photos_fronten"> </a> Why does library <code>//photos/frontend:lib</code> depend on two variants of the same library <code>//third_party/jpeglib</code> and <code>//third_party/jpeg</code>? </h4> -<div> -This query boils down to: "show me the subgraph of -<code>//photos/frontend:lib</code> that depends on both libraries". When shown -in topological order, the last element of the result is the most -likely culprit. -<p /> -<pre> -% 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 -</pre> -</div> -<p /> -<h3><a name="What_depends_on_"> </a> What depends on ... </h3> -<h4><a name="What_rules_under_bar_depend_o"> </a> What rules under bar depend on Y? </h4> -<div> - <code>bazel query 'bar/... intersect allpaths(bar/..., Y)'</code> -<p /> - Note: <code>X intersect allpaths(X, Y)</code> 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 - <code>let</code> to avoid duplication. -</div> -<p /> -<h3><a name="How_do_I_break_a_dependency_"> </a> How do I break a dependency ... </h3> -<!-- TODO find a convincing value of X to plug in here --> -<h4><a name="What_dependency_paths_do_I_have_"> </a> What dependency paths do I have to break to make <code>bar</code> no longer depend on X? </h4> -<div> -To output the graph to a <code>png</code> file: -<p /> -<pre> -bazel query 'allpaths(bar/...,X)' --output graph | dot -Tpng > /tmp/dep.png -</pre> -</div> -<p /> -<h3><a name="Misc_"> </a> Misc ... </h3> -<h4><a name="How_many_sequential_steps_are_th"> </a> How many sequential steps are there in the <code>ServletSmokeTests</code> build? </h4> -<div> -Unfortunately, the query language can't currently give you the longest -path from x to y, but it can find the (or rather <i>a</i>) most -distant node from the starting point, or show you the <em>lengths</em> of the -longest path from x to every y that it depends on. Use <code>maxrank</code>: -<p /> -<pre> % bazel query 'deps(//src/test/java/com/example/servlet:ServletSmokeTests)' ---output maxrank | tail -1 -85 //third_party/zlib:zutil.c -</pre> -<p /> -The result indicates that there exist paths of length 85 that must -occur in order in this build. -</div> -<p /> -</table> -<p /> diff --git a/site/docs/query.html b/site/docs/query.html deleted file mode 100644 index 70bb492454..0000000000 --- a/site/docs/query.html +++ /dev/null @@ -1,1799 +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'> -<svg width="153pt" height="288pt" - viewBox="0.00 0.00 153.40 288.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> -<g id="graph0" class="graph" transform="scale(0.839179 0.839179) rotate(0) translate(4 339.193)"> -<title>somepath1</title> -<polygon fill="white" stroke="transparent" points="-4,4 -4,-339.193 178.798,-339.193 178.798,4 -4,4"/> -<!-- n1 --> -<g id="node1" class="node"> -<title>n1</title> -<ellipse fill="none" stroke="black" cx="40" cy="-314.394" rx="18" ry="18"/> -</g> -<!-- n2 --> -<g id="node2" class="node"> -<title>n2</title> -<ellipse fill="pink" stroke="black" cx="41" cy="-236.798" rx="18" ry="18"/> -</g> -<!-- n1->n2 --> -<g id="edge1" class="edge"> -<title>n1->n2</title> -<path fill="none" stroke="black" d="M40.2269,-296.24C40.3484,-287.058 40.5009,-275.531 40.6382,-265.147"/> -<polygon fill="black" stroke="black" points="44.1413,-264.93 40.774,-254.884 37.1419,-264.837 44.1413,-264.93"/> -</g> -<!-- n3 --> -<g id="node3" class="node"> -<title>n3</title> -<ellipse fill="pink" stroke="black" cx="18" cy="-162" rx="18" ry="18"/> -</g> -<!-- n2->n3 --> -<g id="edge2" class="edge"> -<title>n2->n3</title> -<path fill="none" stroke="black" d="M35.7809,-219.279C32.9579,-210.344 29.4064,-199.103 26.2211,-189.021"/> -<polygon fill="black" stroke="black" points="29.5485,-187.935 23.1984,-179.454 22.8737,-190.044 29.5485,-187.935"/> -</g> -<!-- n10 --> -<g id="node10" class="node"> -<title>n10</title> -<ellipse fill="pink" stroke="black" cx="37" cy="-90" rx="18" ry="18"/> -</g> -<!-- n2->n10 --> -<g id="edge9" class="edge"> -<title>n2->n10</title> -<path fill="none" stroke="black" d="M42.9371,-218.86C44.7656,-200.425 46.9578,-170.088 45,-144 44.3634,-135.518 43.1616,-126.336 41.8792,-118.036"/> -<polygon fill="black" stroke="black" points="45.3237,-117.412 40.2483,-108.112 38.4164,-118.547 45.3237,-117.412"/> -</g> -<!-- n3->n10 --> -<g id="edge10" class="edge"> -<title>n3->n10</title> -<path fill="none" stroke="black" d="M22.5027,-144.411C24.7033,-136.304 27.404,-126.354 29.8755,-117.248"/> -<polygon fill="black" stroke="black" points="33.2878,-118.038 32.5296,-107.47 26.5322,-116.204 33.2878,-118.038"/> -</g> -<!-- n4 --> -<g id="node4" class="node"> -<title>n4</title> -<ellipse fill="pink" stroke="black" cx="87" cy="-18" rx="18" ry="18"/> -<text text-anchor="middle" x="87" y="-14.3" font-family="arial" font-size="14.00">E</text> -</g> -<!-- n5 --> -<g id="node5" class="node"> -<title>n5</title> -<ellipse fill="none" stroke="black" cx="97" cy="-236.798" rx="18" ry="18"/> -</g> -<!-- n6 --> -<g id="node6" class="node"> -<title>n6</title> -<ellipse fill="none" stroke="black" cx="121" cy="-162" rx="18" ry="18"/> -</g> -<!-- n5->n6 --> -<g id="edge5" class="edge"> -<title>n5->n6</title> -<path fill="none" stroke="black" d="M102.446,-219.279C105.413,-210.281 109.15,-198.944 112.492,-188.808"/> -<polygon fill="black" stroke="black" points="115.851,-189.796 115.658,-179.203 109.203,-187.604 115.851,-189.796"/> -</g> -<!-- n6->n4 --> -<g id="edge6" class="edge"> -<title>n6->n4</title> -<path fill="none" stroke="black" d="M115.99,-144.365C112.931,-133.96 109.038,-120.252 106,-108 100.867,-87.3 95.8646,-63.6851 92.2822,-45.9844"/> -<polygon fill="black" stroke="black" points="95.6398,-44.9258 90.2466,-35.8064 88.7758,-46.2987 95.6398,-44.9258"/> -</g> -<!-- n9 --> -<g id="node9" class="node"> -<title>n9</title> -<ellipse fill="none" stroke="black" cx="133" cy="-90" rx="18" ry="18"/> -</g> -<!-- n6->n9 --> -<g id="edge8" class="edge"> -<title>n6->n9</title> -<path fill="none" stroke="black" d="M123.905,-144.055C125.261,-136.145 126.907,-126.54 128.425,-117.688"/> -<polygon fill="black" stroke="black" points="131.882,-118.237 130.122,-107.789 124.982,-117.054 131.882,-118.237"/> -</g> -<!-- n7 --> -<g id="node7" class="node"> -<title>n7</title> -<ellipse fill="pink" stroke="black" cx="97" cy="-314.394" rx="20.5982" ry="20.5982"/> -<text text-anchor="middle" x="97" y="-310.694" font-family="arial" font-size="14.00">S1</text> -</g> -<!-- n7->n2 --> -<g id="edge4" class="edge"> -<title>n7->n2</title> -<path fill="none" stroke="black" d="M84.8488,-296.991C76.7726,-286.089 66.0734,-271.646 57.2656,-259.756"/> -<polygon fill="black" stroke="black" points="60.0158,-257.588 51.2509,-251.636 54.391,-261.755 60.0158,-257.588"/> -</g> -<!-- n7->n5 --> -<g id="edge3" class="edge"> -<title>n7->n5</title> -<path fill="none" stroke="black" d="M97,-293.532C97,-284.887 97,-274.612 97,-265.254"/> -<polygon fill="black" stroke="black" points="100.5,-265.213 97,-255.213 93.5001,-265.213 100.5,-265.213"/> -</g> -<!-- n8 --> -<g id="node8" class="node"> -<title>n8</title> -<ellipse fill="none" stroke="black" cx="154" cy="-236.798" rx="20.5982" ry="20.5982"/> -<text text-anchor="middle" x="154" y="-233.098" font-family="arial" font-size="14.00">S2</text> -</g> -<!-- n8->n6 --> -<g id="edge7" class="edge"> -<title>n8->n6</title> -<path fill="none" stroke="black" d="M145.673,-217.428C141.606,-208.456 136.653,-197.53 132.254,-187.827"/> -<polygon fill="black" stroke="black" points="135.411,-186.313 128.095,-178.651 129.036,-189.204 135.411,-186.313"/> -</g> -<!-- n10->n4 --> -<g id="edge11" class="edge"> -<title>n10->n4</title> -<path fill="none" stroke="black" d="M47.1182,-74.8345C53.9632,-65.2515 63.1483,-52.3924 70.9784,-41.4303"/> -<polygon fill="black" stroke="black" points="73.9325,-43.3162 76.8968,-33.1445 68.2363,-39.2475 73.9325,-43.3162"/> -</g> -<!-- n11 --> -<g id="node11" class="node"> -<title>n11</title> -<ellipse fill="none" stroke="black" cx="33" cy="-18" rx="18" ry="18"/> -</g> -<!-- n10->n11 --> -<g id="edge12" class="edge"> -<title>n10->n11</title> -<path fill="none" stroke="black" d="M36.0112,-71.6966C35.5704,-63.9827 35.0407,-54.7125 34.5493,-46.1124"/> -<polygon fill="black" stroke="black" points="38.0423,-45.8883 33.9774,-36.1043 31.0537,-46.2878 38.0423,-45.8883"/> -</g> -</g> -</svg> -<p><code>somepath(S1 + S2, E)</code>,<br/>one possible result.</p> -</td> -<td style='padding: 40px; text-align: center'> -<svg width="153pt" height="288pt" - viewBox="0.00 0.00 153.40 288.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> -<g id="graph0" class="graph" transform="scale(0.839179 0.839179) rotate(0) translate(4 339.193)"> -<title>somepath2</title> -<polygon fill="white" stroke="transparent" points="-4,4 -4,-339.193 178.798,-339.193 178.798,4 -4,4"/> -<!-- n1 --> -<g id="node1" class="node"> -<title>n1</title> -<ellipse fill="none" stroke="black" cx="40" cy="-314.394" rx="18" ry="18"/> -</g> -<!-- n2 --> -<g id="node2" class="node"> -<title>n2</title> -<ellipse fill="none" stroke="black" cx="41" cy="-236.798" rx="18" ry="18"/> -</g> -<!-- n1->n2 --> -<g id="edge1" class="edge"> -<title>n1->n2</title> -<path fill="none" stroke="black" d="M40.2269,-296.24C40.3484,-287.058 40.5009,-275.531 40.6382,-265.147"/> -<polygon fill="black" stroke="black" points="44.1413,-264.93 40.774,-254.884 37.1419,-264.837 44.1413,-264.93"/> -</g> -<!-- n3 --> -<g id="node3" class="node"> -<title>n3</title> -<ellipse fill="none" stroke="black" cx="18" cy="-162" rx="18" ry="18"/> -</g> -<!-- n2->n3 --> -<g id="edge2" class="edge"> -<title>n2->n3</title> -<path fill="none" stroke="black" d="M35.7809,-219.279C32.9579,-210.344 29.4064,-199.103 26.2211,-189.021"/> -<polygon fill="black" stroke="black" points="29.5485,-187.935 23.1984,-179.454 22.8737,-190.044 29.5485,-187.935"/> -</g> -<!-- n10 --> -<g id="node10" class="node"> -<title>n10</title> -<ellipse fill="none" stroke="black" cx="37" cy="-90" rx="18" ry="18"/> -</g> -<!-- n2->n10 --> -<g id="edge9" class="edge"> -<title>n2->n10</title> -<path fill="none" stroke="black" d="M42.9371,-218.86C44.7656,-200.425 46.9578,-170.088 45,-144 44.3634,-135.518 43.1616,-126.336 41.8792,-118.036"/> -<polygon fill="black" stroke="black" points="45.3237,-117.412 40.2483,-108.112 38.4164,-118.547 45.3237,-117.412"/> -</g> -<!-- n3->n10 --> -<g id="edge10" class="edge"> -<title>n3->n10</title> -<path fill="none" stroke="black" d="M22.5027,-144.411C24.7033,-136.304 27.404,-126.354 29.8755,-117.248"/> -<polygon fill="black" stroke="black" points="33.2878,-118.038 32.5296,-107.47 26.5322,-116.204 33.2878,-118.038"/> -</g> -<!-- n4 --> -<g id="node4" class="node"> -<title>n4</title> -<ellipse fill="pink" stroke="black" cx="87" cy="-18" rx="18" ry="18"/> -<text text-anchor="middle" x="87" y="-14.3" font-family="arial" font-size="14.00">E</text> -</g> -<!-- n5 --> -<g id="node5" class="node"> -<title>n5</title> -<ellipse fill="none" stroke="black" cx="97" cy="-236.798" rx="18" ry="18"/> -</g> -<!-- n6 --> -<g id="node6" class="node"> -<title>n6</title> -<ellipse fill="pink" stroke="black" cx="121" cy="-162" rx="18" ry="18"/> -</g> -<!-- n5->n6 --> -<g id="edge5" class="edge"> -<title>n5->n6</title> -<path fill="none" stroke="black" d="M102.446,-219.279C105.413,-210.281 109.15,-198.944 112.492,-188.808"/> -<polygon fill="black" stroke="black" points="115.851,-189.796 115.658,-179.203 109.203,-187.604 115.851,-189.796"/> -</g> -<!-- n6->n4 --> -<g id="edge6" class="edge"> -<title>n6->n4</title> -<path fill="none" stroke="black" d="M115.99,-144.365C112.931,-133.96 109.038,-120.252 106,-108 100.867,-87.3 95.8646,-63.6851 92.2822,-45.9844"/> -<polygon fill="black" stroke="black" points="95.6398,-44.9258 90.2466,-35.8064 88.7758,-46.2987 95.6398,-44.9258"/> -</g> -<!-- n9 --> -<g id="node9" class="node"> -<title>n9</title> -<ellipse fill="none" stroke="black" cx="133" cy="-90" rx="18" ry="18"/> -</g> -<!-- n6->n9 --> -<g id="edge8" class="edge"> -<title>n6->n9</title> -<path fill="none" stroke="black" d="M123.905,-144.055C125.261,-136.145 126.907,-126.54 128.425,-117.688"/> -<polygon fill="black" stroke="black" points="131.882,-118.237 130.122,-107.789 124.982,-117.054 131.882,-118.237"/> -</g> -<!-- n7 --> -<g id="node7" class="node"> -<title>n7</title> -<ellipse fill="none" stroke="black" cx="97" cy="-314.394" rx="20.5982" ry="20.5982"/> -<text text-anchor="middle" x="97" y="-310.694" font-family="arial" font-size="14.00">S1</text> -</g> -<!-- n7->n2 --> -<g id="edge4" class="edge"> -<title>n7->n2</title> -<path fill="none" stroke="black" d="M84.8488,-296.991C76.7726,-286.089 66.0734,-271.646 57.2656,-259.756"/> -<polygon fill="black" stroke="black" points="60.0158,-257.588 51.2509,-251.636 54.391,-261.755 60.0158,-257.588"/> -</g> -<!-- n7->n5 --> -<g id="edge3" class="edge"> -<title>n7->n5</title> -<path fill="none" stroke="black" d="M97,-293.532C97,-284.887 97,-274.612 97,-265.254"/> -<polygon fill="black" stroke="black" points="100.5,-265.213 97,-255.213 93.5001,-265.213 100.5,-265.213"/> -</g> -<!-- n8 --> -<g id="node8" class="node"> -<title>n8</title> -<ellipse fill="pink" stroke="black" cx="154" cy="-236.798" rx="20.5982" ry="20.5982"/> -<text text-anchor="middle" x="154" y="-233.098" font-family="arial" font-size="14.00">S2</text> -</g> -<!-- n8->n6 --> -<g id="edge7" class="edge"> -<title>n8->n6</title> -<path fill="none" stroke="black" d="M145.673,-217.428C141.606,-208.456 136.653,-197.53 132.254,-187.827"/> -<polygon fill="black" stroke="black" points="135.411,-186.313 128.095,-178.651 129.036,-189.204 135.411,-186.313"/> -</g> -<!-- n10->n4 --> -<g id="edge11" class="edge"> -<title>n10->n4</title> -<path fill="none" stroke="black" d="M47.1182,-74.8345C53.9632,-65.2515 63.1483,-52.3924 70.9784,-41.4303"/> -<polygon fill="black" stroke="black" points="73.9325,-43.3162 76.8968,-33.1445 68.2363,-39.2475 73.9325,-43.3162"/> -</g> -<!-- n11 --> -<g id="node11" class="node"> -<title>n11</title> -<ellipse fill="none" stroke="black" cx="33" cy="-18" rx="18" ry="18"/> -</g> -<!-- n10->n11 --> -<g id="edge12" class="edge"> -<title>n10->n11</title> -<path fill="none" stroke="black" d="M36.0112,-71.6966C35.5704,-63.9827 35.0407,-54.7125 34.5493,-46.1124"/> -<polygon fill="black" stroke="black" points="38.0423,-45.8883 33.9774,-36.1043 31.0537,-46.2878 38.0423,-45.8883"/> -</g> -</g> -</svg> -<p><code>somepath(S1 + S2, E)</code>,<br/>another possible result.</p> -</td> -<td style='text-align: center'> -<svg width="153pt" height="288pt" - viewBox="0.00 0.00 153.40 288.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> -<g id="graph0" class="graph" transform="scale(0.839179 0.839179) rotate(0) translate(4 339.193)"> -<title>allpaths</title> -<polygon fill="white" stroke="transparent" points="-4,4 -4,-339.193 178.798,-339.193 178.798,4 -4,4"/> -<!-- n1 --> -<g id="node1" class="node"> -<title>n1</title> -<ellipse fill="none" stroke="black" cx="40" cy="-314.394" rx="18" ry="18"/> -</g> -<!-- n2 --> -<g id="node2" class="node"> -<title>n2</title> -<ellipse fill="pink" stroke="black" cx="41" cy="-236.798" rx="18" ry="18"/> -</g> -<!-- n1->n2 --> -<g id="edge1" class="edge"> -<title>n1->n2</title> -<path fill="none" stroke="black" d="M40.2269,-296.24C40.3484,-287.058 40.5009,-275.531 40.6382,-265.147"/> -<polygon fill="black" stroke="black" points="44.1413,-264.93 40.774,-254.884 37.1419,-264.837 44.1413,-264.93"/> -</g> -<!-- n3 --> -<g id="node3" class="node"> -<title>n3</title> -<ellipse fill="pink" stroke="black" cx="18" cy="-162" rx="18" ry="18"/> -</g> -<!-- n2->n3 --> -<g id="edge2" class="edge"> -<title>n2->n3</title> -<path fill="none" stroke="black" d="M35.7809,-219.279C32.9579,-210.344 29.4064,-199.103 26.2211,-189.021"/> -<polygon fill="black" stroke="black" points="29.5485,-187.935 23.1984,-179.454 22.8737,-190.044 29.5485,-187.935"/> -</g> -<!-- n10 --> -<g id="node10" class="node"> -<title>n10</title> -<ellipse fill="pink" stroke="black" cx="37" cy="-90" rx="18" ry="18"/> -</g> -<!-- n2->n10 --> -<g id="edge9" class="edge"> -<title>n2->n10</title> -<path fill="none" stroke="black" d="M42.9371,-218.86C44.7656,-200.425 46.9578,-170.088 45,-144 44.3634,-135.518 43.1616,-126.336 41.8792,-118.036"/> -<polygon fill="black" stroke="black" points="45.3237,-117.412 40.2483,-108.112 38.4164,-118.547 45.3237,-117.412"/> -</g> -<!-- n3->n10 --> -<g id="edge10" class="edge"> -<title>n3->n10</title> -<path fill="none" stroke="black" d="M22.5027,-144.411C24.7033,-136.304 27.404,-126.354 29.8755,-117.248"/> -<polygon fill="black" stroke="black" points="33.2878,-118.038 32.5296,-107.47 26.5322,-116.204 33.2878,-118.038"/> -</g> -<!-- n4 --> -<g id="node4" class="node"> -<title>n4</title> -<ellipse fill="pink" stroke="black" cx="87" cy="-18" rx="18" ry="18"/> -<text text-anchor="middle" x="87" y="-14.3" font-family="arial" font-size="14.00">E</text> -</g> -<!-- n5 --> -<g id="node5" class="node"> -<title>n5</title> -<ellipse fill="pink" stroke="black" cx="97" cy="-236.798" rx="18" ry="18"/> -</g> -<!-- n6 --> -<g id="node6" class="node"> -<title>n6</title> -<ellipse fill="pink" stroke="black" cx="121" cy="-162" rx="18" ry="18"/> -</g> -<!-- n5->n6 --> -<g id="edge5" class="edge"> -<title>n5->n6</title> -<path fill="none" stroke="black" d="M102.446,-219.279C105.413,-210.281 109.15,-198.944 112.492,-188.808"/> -<polygon fill="black" stroke="black" points="115.851,-189.796 115.658,-179.203 109.203,-187.604 115.851,-189.796"/> -</g> -<!-- n6->n4 --> -<g id="edge6" class="edge"> -<title>n6->n4</title> -<path fill="none" stroke="black" d="M115.99,-144.365C112.931,-133.96 109.038,-120.252 106,-108 100.867,-87.3 95.8646,-63.6851 92.2822,-45.9844"/> -<polygon fill="black" stroke="black" points="95.6398,-44.9258 90.2466,-35.8064 88.7758,-46.2987 95.6398,-44.9258"/> -</g> -<!-- n9 --> -<g id="node9" class="node"> -<title>n9</title> -<ellipse fill="none" stroke="black" cx="133" cy="-90" rx="18" ry="18"/> -</g> -<!-- n6->n9 --> -<g id="edge8" class="edge"> -<title>n6->n9</title> -<path fill="none" stroke="black" d="M123.905,-144.055C125.261,-136.145 126.907,-126.54 128.425,-117.688"/> -<polygon fill="black" stroke="black" points="131.882,-118.237 130.122,-107.789 124.982,-117.054 131.882,-118.237"/> -</g> -<!-- n7 --> -<g id="node7" class="node"> -<title>n7</title> -<ellipse fill="pink" stroke="black" cx="97" cy="-314.394" rx="20.5982" ry="20.5982"/> -<text text-anchor="middle" x="97" y="-310.694" font-family="arial" font-size="14.00">S1</text> -</g> -<!-- n7->n2 --> -<g id="edge4" class="edge"> -<title>n7->n2</title> -<path fill="none" stroke="black" d="M84.8488,-296.991C76.7726,-286.089 66.0734,-271.646 57.2656,-259.756"/> -<polygon fill="black" stroke="black" points="60.0158,-257.588 51.2509,-251.636 54.391,-261.755 60.0158,-257.588"/> -</g> -<!-- n7->n5 --> -<g id="edge3" class="edge"> -<title>n7->n5</title> -<path fill="none" stroke="black" d="M97,-293.532C97,-284.887 97,-274.612 97,-265.254"/> -<polygon fill="black" stroke="black" points="100.5,-265.213 97,-255.213 93.5001,-265.213 100.5,-265.213"/> -</g> -<!-- n8 --> -<g id="node8" class="node"> -<title>n8</title> -<ellipse fill="pink" stroke="black" cx="154" cy="-236.798" rx="20.5982" ry="20.5982"/> -<text text-anchor="middle" x="154" y="-233.098" font-family="arial" font-size="14.00">S2</text> -</g> -<!-- n8->n6 --> -<g id="edge7" class="edge"> -<title>n8->n6</title> -<path fill="none" stroke="black" d="M145.673,-217.428C141.606,-208.456 136.653,-197.53 132.254,-187.827"/> -<polygon fill="black" stroke="black" points="135.411,-186.313 128.095,-178.651 129.036,-189.204 135.411,-186.313"/> -</g> -<!-- n10->n4 --> -<g id="edge11" class="edge"> -<title>n10->n4</title> -<path fill="none" stroke="black" d="M47.1182,-74.8345C53.9632,-65.2515 63.1483,-52.3924 70.9784,-41.4303"/> -<polygon fill="black" stroke="black" points="73.9325,-43.3162 76.8968,-33.1445 68.2363,-39.2475 73.9325,-43.3162"/> -</g> -<!-- n11 --> -<g id="node11" class="node"> -<title>n11</title> -<ellipse fill="none" stroke="black" cx="33" cy="-18" rx="18" ry="18"/> -</g> -<!-- n10->n11 --> -<g id="edge12" class="edge"> -<title>n10->n11</title> -<path fill="none" stroke="black" d="M36.0112,-71.6966C35.5704,-63.9827 35.0407,-54.7125 34.5493,-46.1124"/> -<polygon fill="black" stroke="black" points="38.0423,-45.8883 33.9774,-36.1043 31.0537,-46.2878 38.0423,-45.8883"/> -</g> -</g> -</svg> -<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>minrank</code> or <code>maxrank</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> -<svg width="169pt" height="260pt" - viewBox="0.00 0.00 169.00 260.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> -<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 256)"> -<title>mygraph</title> -<polygon fill="white" stroke="transparent" points="-4,4 -4,-256 165,-256 165,4 -4,4"/> -<!-- //a:a --> -<g id="node1" class="node"> -<title>//a:a</title> -<polygon fill="none" stroke="black" points="65.5,-108 11.5,-108 11.5,-72 65.5,-72 65.5,-108"/> -<text text-anchor="middle" x="38.5" y="-86.3" font-family="arial" font-size="14.00">//a:a</text> -</g> -<!-- //a:a.cc --> -<g id="node2" class="node"> -<title>//a:a.cc</title> -<polygon fill="none" stroke="black" points="77,-36 0,-36 0,-0 77,-0 77,-36"/> -<text text-anchor="middle" x="38.5" y="-14.3" font-family="arial" font-size="14.00">//a:a.cc</text> -</g> -<!-- //a:a->//a:a.cc --> -<g id="edge1" class="edge"> -<title>//a:a->//a:a.cc</title> -<path fill="none" stroke="black" d="M38.5,-71.6966C38.5,-63.9827 38.5,-54.7125 38.5,-46.1124"/> -<polygon fill="black" stroke="black" points="42.0001,-46.1043 38.5,-36.1043 35.0001,-46.1044 42.0001,-46.1043"/> -</g> -<!-- //b:b --> -<g id="node3" class="node"> -<title>//b:b</title> -<polygon fill="none" stroke="black" points="120.5,-180 66.5,-180 66.5,-144 120.5,-144 120.5,-180"/> -<text text-anchor="middle" x="93.5" y="-158.3" font-family="arial" font-size="14.00">//b:b</text> -</g> -<!-- //b:b->//a:a --> -<g id="edge2" class="edge"> -<title>//b:b->//a:a</title> -<path fill="none" stroke="black" d="M79.9045,-143.697C73.3773,-135.389 65.432,-125.277 58.2534,-116.141"/> -<polygon fill="black" stroke="black" points="60.8695,-113.805 51.9391,-108.104 55.3653,-118.13 60.8695,-113.805"/> -</g> -<!-- //b:b.cc --> -<g id="node4" class="node"> -<title>//b:b.cc</title> -<polygon fill="none" stroke="black" points="161,-108 84,-108 84,-72 161,-72 161,-108"/> -<text text-anchor="middle" x="122.5" y="-86.3" font-family="arial" font-size="14.00">//b:b.cc</text> -</g> -<!-- //b:b->//b:b.cc --> -<g id="edge3" class="edge"> -<title>//b:b->//b:b.cc</title> -<path fill="none" stroke="black" d="M100.669,-143.697C103.935,-135.813 107.874,-126.304 111.502,-117.546"/> -<polygon fill="black" stroke="black" points="114.82,-118.683 115.414,-108.104 108.353,-116.003 114.82,-118.683"/> -</g> -<!-- //c:c --> -<g id="node5" class="node"> -<title>//c:c</title> -<polygon fill="none" stroke="black" points="92.5,-252 38.5,-252 38.5,-216 92.5,-216 92.5,-252"/> -<text text-anchor="middle" x="65.5" y="-230.3" font-family="arial" font-size="14.00">//c:c</text> -</g> -<!-- //c:c->//a:a --> -<g id="edge5" class="edge"> -<title>//c:c->//a:a</title> -<path fill="none" stroke="black" d="M62.2432,-215.871C57.6415,-191.67 49.188,-147.211 43.7086,-118.393"/> -<polygon fill="black" stroke="black" points="47.0748,-117.359 41.7684,-108.189 40.198,-118.667 47.0748,-117.359"/> -</g> -<!-- //c:c->//b:b --> -<g id="edge4" class="edge"> -<title>//c:c->//b:b</title> -<path fill="none" stroke="black" d="M72.4214,-215.697C75.5747,-207.813 79.3783,-198.304 82.8814,-189.546"/> -<polygon fill="black" stroke="black" points="86.194,-190.689 86.6583,-180.104 79.6946,-188.089 86.194,-190.689"/> -</g> -</g> -</svg> -</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 printed is the place in the BUILD file where the target is defined. -For rules, this is the first line of the definition of the rule in the BUILD -file, for output files, the first line of the definition of the rule that -outputs the file and for input files, the first line of the definition of a -rule that references this input file. -</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/docs/query.md b/site/docs/query.md new file mode 100644 index 0000000000..7a42ae7ea5 --- /dev/null +++ b/site/docs/query.md @@ -0,0 +1,4 @@ +--- +layout: redirect +redirect: docs/query.html +--- diff --git a/site/docs/rule-challenges.md b/site/docs/rule-challenges.md index 7b92655b91..88aa5cba13 100644 --- a/site/docs/rule-challenges.md +++ b/site/docs/rule-challenges.md @@ -1,214 +1,4 @@ --- -layout: documentation -title: Challenges of Writing Rules. +layout: redirect +redirect: docs/rule-challenges.html --- - -# 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.io/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/docs/skylark/aspects.md b/site/docs/skylark/aspects.md index 6bafa20b65..ba524f5cf6 100644 --- a/site/docs/skylark/aspects.md +++ b/site/docs/skylark/aspects.md @@ -1,191 +1,4 @@ --- -layout: documentation -title: Aspects +layout: redirect +redirect: docs/skylark/aspects.html --- -# 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 the aspect is being applied to. -* [`ctx`](lib/ctx.html): `ctx` 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.src - 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 = set(outputs) - for dep in ctx.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/docs/skylark/build-graph-aspect.svg b/site/docs/skylark/build-graph-aspect.svg deleted file mode 100644 index 508a916bd3..0000000000 --- a/site/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/docs/skylark/build-graph-aspects.png b/site/docs/skylark/build-graph-aspects.png Binary files differdeleted file mode 100644 index fb8042a5b7..0000000000 --- a/site/docs/skylark/build-graph-aspects.png +++ /dev/null diff --git a/site/docs/skylark/build-graph.png b/site/docs/skylark/build-graph.png Binary files differdeleted file mode 100644 index 2efd68ac59..0000000000 --- a/site/docs/skylark/build-graph.png +++ /dev/null diff --git a/site/docs/skylark/build-graph.svg b/site/docs/skylark/build-graph.svg deleted file mode 100644 index cbad06dcb2..0000000000 --- a/site/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/docs/skylark/build-style.md b/site/docs/skylark/build-style.md index 3cee2fc26e..5a47a30eda 100644 --- a/site/docs/skylark/build-style.md +++ b/site/docs/skylark/build-style.md @@ -1,110 +1,4 @@ - -# 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. - - * 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. +--- +layout: redirect +redirect: docs/skylark/build-style.html +--- diff --git a/site/docs/skylark/bzl-style.md b/site/docs/skylark/bzl-style.md index a88dfcad76..c17600796b 100644 --- a/site/docs/skylark/bzl-style.md +++ b/site/docs/skylark/bzl-style.md @@ -1,48 +1,4 @@ - -# .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. - +--- +layout: redirect +redirect: docs/skylark/bzl-style.html +--- diff --git a/site/docs/skylark/concepts.md b/site/docs/skylark/concepts.md index 7388ab7e87..a1e5028f15 100644 --- a/site/docs/skylark/concepts.md +++ b/site/docs/skylark/concepts.md @@ -1,190 +1,4 @@ --- -layout: documentation -title: Extensions - Overview +layout: redirect +redirect: docs/skylark/concepts.html --- -# 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 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("/path/to:my_rules.bzl", "some_rule", nice_alias = "some_other_rule") -``` - -Symbols starting with `_` are private and cannot be loaded from other files. -Visibility doesn't affect loading: 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. The -function is evaluated as soon as the BUILD file is read. 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, as it can access -Bazel internals and have full control over what is going on. It may for example -pass information to other rules. - -If a macro becomes complex, it is often a good idea to make it a rule. - -## 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. 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. - -* **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 run during this phase, as they are actions. - -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. - -## Syntax - -The extension language (sometimes referred as "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) -``` - -## 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). Unlike in Python, [sets](lib/set.html) are not mutable. - -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. - -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 definition -`var = [5]` is exported. Any other file can load it, and it is possible that -multiple files will load it at the same time. For this reason, the following -code is not legal: - -```python -load(":foo.bzl", "var", "fct") - -var.append(6) # not allowed - -fct() # not allowed -``` - -Since the call to `fct()` attempts to mutate the shared variable `var`, it will -fail. `fct()` can only be called during the evaluation of `foo.bzl`. It cannot -be called from another file. It is also forbidden to call it during the analysis -phase (i.e. when a custom rule is analyzed). - -## Differences with Python - -In addition to the mutability restrictions, there are also differences with -Python: - -* All global values are constant (they cannot be reassigned). - -* `x += y` is syntactic sugar for `x = x + y`. Even if `x` and `y` are lists, - dicts or sets, the original value is not mutated, so references to `x` - that were assigned before the operation will see the old value. This behavior - is temporary, and will follow Python semantics in the future. - -* The `+` operator is defined for dictionaries, returning an immutable - concatenated dictionary created from the entries of the original - dictionaries. In case of duplicate keys, we use values from the second - operand. If you need compatibility with Python, we suggest this syntax: - `dict(a.items() + b.items())`. - -* Dictionaries have deterministic order when iterating (sorted by key). - -* Sets use a custom order when iterating (see [documentation](lib/globals.html#set)). - -* Recursion is not allowed. - -* Loops iterate over a shallow copy of the collection. If the collection is a - list or dictionary that is modified during iteration, this will not affect - what values get bound to the loop variable or variables. The changes are - still visible if you directly access the collection. - -The following Python features are not supported: - -* `class` (see [`struct`](lib/globals.html#struct) function) -* `import` (see [`load`](#loading-a-skylark-extension) statement) -* `while`, `yield` -* `lambda` and nested functions -* `is` (use `==` instead) -* `try`, `raise`, `except`, `finally` (see [`fail`](lib/globals.html#fail) - for fatal errors). -* most builtin functions, most methods - - diff --git a/site/docs/skylark/cookbook.md b/site/docs/skylark/cookbook.md index a6950022d1..a4a4dadcbb 100644 --- a/site/docs/skylark/cookbook.md +++ b/site/docs/skylark/cookbook.md @@ -1,920 +1,4 @@ --- -layout: documentation -title: Extensions examples +layout: redirect +redirect: docs/skylark/cookbook.html --- -# 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 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) - -def _impl(ctx): - return struct([...], - # When instrumenting this rule, again hide implementation from - # users. - instrumented_files( - source_attributes = ["srcs", "csrcs"], - dependency_attributes = ["deps", "cdeps"])) - -_cc_and_something_else_binary = rule(implementation=_impl) -``` - - -## <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. - -```python -load("//pkg:extension.bzl", "system_test_suite") - -# Run all files through the 'fast' flavor. -system_test_suite("smoke", flavors=["fast"], glob(["*_test.py"])) - -# Run the basic test through all flavors. -system_test_suite("thorough", flavors=["fast", "debug", "opt"], ["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, 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>Define simple runfiles - -`execute.bzl`: - -```python -def _impl(ctx): - executable = ctx.outputs.executable - # Create the output executable file with command as its content. - ctx.file_action( - output=executable, - content=ctx.attr.command, - executable=True) - - return struct( - # 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 path to data.txt has to include the package directories as well. I.e. - # if the BUILD file is under foo/BUILD and the data file is foo/data.txt - # then it needs to be referred as foo/data.txt in the command. - command = "cat 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)) - -hash = 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", "hash") - -hash( - 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 -def _impl(ctx): - result = ctx.attr.number - for i in ctx.attr.deps: - result += i.number - ctx.file_action(output=ctx.outputs.out, content=str(result)) - - # Fields in the struct will be visible by other rules. - return struct(number=result) - -sum = rule( - implementation=_impl, - attrs={ - "number": attr.int(default=1), - # All deps must provide all listed providers. - "deps": attr.label_list(providers=["number"]), - }, - 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 -def _impl(ctx): - result = ctx.attr.number - for i in ctx.attr.deps: - if hasattr(i, "number"): - result += i.number - ctx.file_action(output=ctx.outputs.out, content=str(result)) - - # Fields in the struct will be visible by other rules. - return struct(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 = set() - files += ctx.attr.dep_rule_1.files - files += ctx.attr.dep_rule_2.files - return struct(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/docs/skylark/deploying.md b/site/docs/skylark/deploying.md index ad0831ccff..a56f7183ae 100644 --- a/site/docs/skylark/deploying.md +++ b/site/docs/skylark/deploying.md @@ -1,144 +1,4 @@ --- -layout: documentation -title: Deploying new Skylark rules +layout: redirect +redirect: docs/skylark/deploying.html --- -# 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.io](http://ci.bazel.io). - -## 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/docs/skylark/index.md b/site/docs/skylark/index.md index b7d46a56f4..541fcba640 100644 --- a/site/docs/skylark/index.md +++ b/site/docs/skylark/index.md @@ -1,16 +1,4 @@ --- -layout: documentation -title: Extensions +layout: redirect +redirect: docs/skylark/index.html --- - -# 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/docs/skylark/macros.md b/site/docs/skylark/macros.md index 6242af8d1a..b247e4b89f 100644 --- a/site/docs/skylark/macros.md +++ b/site/docs/skylark/macros.md @@ -1,140 +1,4 @@ --- -layout: documentation -title: Macros +layout: redirect +redirect: docs/skylark/macros.html --- -# 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, macros don't exist anymore, and -Bazel sees only the set of rules they created. - -Native rules can be instantiated from the `native` 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 like after evaluation. All macros, globs, loops are expanded. - -* 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, remove -your `print` calls 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://google-styleguide.googlecode.com/svn/trunk/pyguide.html?showone=Comments#Comments). - -* 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/docs/skylark/repository_rules.md b/site/docs/skylark/repository_rules.md index 2ee876b687..6af0109578 100644 --- a/site/docs/skylark/repository_rules.md +++ b/site/docs/skylark/repository_rules.md @@ -1,78 +1,4 @@ --- -layout: documentation -title: Repository Rules +layout: redirect +redirect: docs/skylark/repository_rules.html --- -# 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, - ...) -``` - -## Examples - -For now, we only have one full example of usage of the `repository_rule`: -[C++ auto-configured toolchain](https://github.com/bazelbuild/bazel/blob/9116b3e99af2fd31d92c9bb7c37905a1675456c1/tools/cpp/cc_configure.bzl#L288). - -This example 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. - diff --git a/site/docs/skylark/rules.md b/site/docs/skylark/rules.md index 809b8763da..22b62057eb 100644 --- a/site/docs/skylark/rules.md +++ b/site/docs/skylark/rules.md @@ -1,460 +1,4 @@ --- -layout: documentation -title: Rules +layout: redirect +redirect: docs/skylark/rules.html --- -# 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 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_). - -## 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`). During analysis, no external command can be executed: actions will -be run in the execution phase. - -## 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 - -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. 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 struct( - runfiles=..., - my_provider=..., - ... - ) - -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 struct(files=set([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 - -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. 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). - -**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 - -By default, a target is built in the target configuration. For each label -attribute, you can decide whether the dependency should be built in the same -configuration, or in the host configuration. - -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. - -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 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 used to access information from other rules. A rule depending on -another rule has access to the data the latter provides. These data can be e.g. -output files, the libraries the dependent rule is using to link or compile, or -anything the depending rule should know about. Using providers is the only way -to exchange data between rules. - -A rule can only access data provided by its direct dependencies, not that of -transitive dependencies: if rule `top` depends on `middle`, and `middle` depends -on `bottom`, then `middle` is a direct dependency of `top` and `bottom` is a -transitive dependency of `top`. In this scenario `top` can only access data -provided by `middle`. If `middle` also provides the data that `bottom` provided -to it, then and only then can `top` access it. - -The following data types can be passed using providers: - -* `bool` -* `integer` -* `string` -* `file` -* `label` -* `None` -* anything composed of these types and `lists`, `dicts`, `sets` or `structs` - -Providers are created from the return value of the rule implementation function: - -```python -def rule_implementation(ctx): - ... - return struct( - transitive_data=set(["a", "b", "c"]) - ) -``` - -A dependent rule might access these data as struct fields of the `target` being -depended upon: - -```python -def dependent_rule_implementation(ctx): - ... - s = set() - for dep_target in ctx.attr.deps: - # Use `print(dir(dep_target))` to see the list of providers. - s += dep_target.transitive_data - ... -``` - -Providers are only available during the analysis phase. Examples of usage: - -* [mandatory providers](cookbook.md#mandatory-providers) -* [optional providers](cookbook.md#optional-providers) - -## 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 execution, Bazel creates a directory tree containing symlinks pointing to -the runfiles, staging 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 = set() - 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 return struct in order to actually - # create the symlink tree. - return struct(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. - -## Instrumented files - -Instrumented files are a set of files used by the coverage command. A rule can -use the `instrumented_files` provider to provide information about which files -should be used for measuring coverage. - -```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"])) -``` - -## 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). During the analysis -phase, 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 they -must generate the output file `ctx.outputs.executable`. - -Test rules inherit the following attributes: `args`, `flaky`, `local`, -`shard_count`, `size`, `timeout`. diff --git a/site/docs/support.md b/site/docs/support.md index fae80aa227..0d1b8cdaa6 100644 --- a/site/docs/support.md +++ b/site/docs/support.md @@ -1,255 +1,4 @@ --- -layout: documentation -title: Get Support +layout: redirect +redirect: docs/support.html --- - -# Get Support - -* [User mailing list](https://groups.google.com/forum/#!forum/bazel-discuss) -* [Issue tracker](https://github.com/bazelbuild/bazel/issues) -* [Twitter](http://www.twitter.com/bazelbuild) -* [IRC](irc://irc.freenode.net/bazel) (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.io/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/docs/test-encyclopedia.html b/site/docs/test-encyclopedia.html deleted file mode 100644 index bdb7e787f6..0000000000 --- a/site/docs/test-encyclopedia.html +++ /dev/null @@ -1,483 +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>Inherited from the client environment. If <code class='flag'>--runs_per_test</code> option is used and client environment does not contain this variable, it 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_TIMEOUT</code></td><td><code>300</code></td><td>optional</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.</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/docs/test-encyclopedia.md b/site/docs/test-encyclopedia.md new file mode 100644 index 0000000000..b87cc71ac7 --- /dev/null +++ b/site/docs/test-encyclopedia.md @@ -0,0 +1,4 @@ +--- +layout: redirect +redirect: docs/test-encyclopedia.html +--- diff --git a/site/docs/tutorial/android-app.md b/site/docs/tutorial/android-app.md index 31e86475cc..ea52e3ef1d 100644 --- a/site/docs/tutorial/android-app.md +++ b/site/docs/tutorial/android-app.md @@ -1,280 +1,4 @@ --- -layout: documentation -title: Tutorial - Build an Android App +layout: redirect +redirect: docs/tutorial/android-app.html --- - -# 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 path to Android SDK on your system - path = "/Users/username/Library/Android/sdk", - # Replace with the Android SDK API level - api_level = 23, - # Replace with the version in sdk/build-tools/ - build_tools_version="23.0.0" -) -``` - -**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 path to Android NDK on your system - path = "/Users/username/Library/Android/ndk", - # 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. - -## 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.io/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.io/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/docs/tutorial/app.md b/site/docs/tutorial/app.md index fdc33c5f83..d3c2872f6f 100644 --- a/site/docs/tutorial/app.md +++ b/site/docs/tutorial/app.md @@ -1,45 +1,4 @@ --- -layout: documentation -title: Build Mobile Application +layout: redirect +redirect: docs/tutorial/app.html --- - -# Build Mobile Application - -You can use Bazel to build a variety of software outputs, including -Linux and Mac 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/docs/tutorial/backend-server.md b/site/docs/tutorial/backend-server.md index ad668a0d3b..150f9152ec 100644 --- a/site/docs/tutorial/backend-server.md +++ b/site/docs/tutorial/backend-server.md @@ -1,224 +1,4 @@ --- -layout: documentation -title: Tutorial - Build the Backend Server +layout: redirect +redirect: docs/tutorial/backend-server.html --- - -# 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 the `appengine.BUILD` file -* Create a `BUILD` file -* Run the build -* Find the build outputs -* Deploy to a local development server -* Deploy to Google App Engine - -Bazel provides a set of [App Engine build rules](/docs/be/appengine.html) -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.io/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 a new\_http\_archive 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](/docs/be/appengine.html). - -Add the following to your `WORKSPACE` file: - -```python -git_repository( - name = "io_bazel_rules_appengine", - remote = "https://github.com/bazelbuild/rules_appengine.git", - tag = "0.0.2", -) -load("@io_bazel_rules_appengine//appengine:appengine.bzl", "appengine_repositories") -appengine_repositories() -``` - -[`git_repository`](/docs/be/workspace.html#git_repository) downloads the -AppEngine rules from GitHub, 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. - -## Deploy to a local development server - -The `appengine_war` rule generates an upload script that you can use to deploy -your backend server on Google App Engine. Here, you'll start a local App Engine -development server in your environment and deploy your application there. - -To deploy the application, enter the following: - -```bash -$ bazel-bin/backend/backend --port=12345 -``` - -Your application URL will be `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 project in the -[Google Developers Console](https://console.developers.google.com). - -To deploy the application, enter the following: - -```bash -$ $WORKSPACE/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/docs/tutorial/cpp.md b/site/docs/tutorial/cpp.md index 3d6effbd68..6ec737f93d 100644 --- a/site/docs/tutorial/cpp.md +++ b/site/docs/tutorial/cpp.md @@ -1,360 +1,4 @@ --- -layout: documentation -title: Build C++ +layout: redirect +redirect: docs/tutorial/cpp.html --- - -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 -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 -$ ./bazel-bin/main/hello-world -Hello world -Thu Jun 23 18:51:46 2016 -$ ./bazel-bin/main/hello-world Bazel -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://code.google.com/p/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://googletest.googlecode.com/files/gtest-1.7.0.zip", - sha256 = "247ca18dd83f53deb1328be17e4b1be31514cedfc1e3424f672bf11fd7e0d60d", - 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: - -* `gtest-1.7.0/src/gtest-all.cc` `#include`s all of the other files in - `gtest-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 relative to the `gtest-1.7.0/include/` directory - (`"gtest/gtest.h"`), so we must add that directory 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( - ["gtest-1.7.0/src/*.cc"], - exclude = ["gtest-1.7.0/src/gtest-all.cc"] - ), - hdrs = glob([ - "gtest-1.7.0/include/**/*.h", - "gtest-1.7.0/src/*.h" - ]), - copts = [ - "-Iexternal/gtest/gtest-1.7.0/include" - ], - linkopts = ["-pthread"], - visibility = ["//visibility:public"], -) -``` - -This is somewhat messy: everything is prefixed with gtest-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://googletest.googlecode.com/files/gtest-1.7.0.zip", - sha256 = "247ca18dd83f53deb1328be17e4b1be31514cedfc1e3424f672bf11fd7e0d60d", - build_file = "gtest.BUILD", - strip_prefix = "gtest-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 `//external: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(FactorialTest, Negative) { - 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 -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/docs/tutorial/environment.md b/site/docs/tutorial/environment.md index 219060de7c..8ce35d68a2 100644 --- a/site/docs/tutorial/environment.md +++ b/site/docs/tutorial/environment.md @@ -1,91 +1,4 @@ --- -layout: documentation -title: Tutorial - Set Up Your Environment +layout: redirect +redirect: docs/tutorial/environment.html --- - -# 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 (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/docs/tutorial/ios-app.md b/site/docs/tutorial/ios-app.md index 51774e9312..e77b36907e 100644 --- a/site/docs/tutorial/ios-app.md +++ b/site/docs/tutorial/ios-app.md @@ -1,206 +1,4 @@ --- -layout: documentation -title: Tutorial - Build an iOS App +layout: redirect +redirect: docs/tutorial/ios-app.html --- - -# 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 Mac 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/SDK version you can do so -with the `--xcode_version=7.2 --ios_sdk_version=9.2` options. Make sure that -the Xcode version that you select has the appropriate SDK installed in it. - -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/docs/tutorial/java.md b/site/docs/tutorial/java.md index ce916667e1..aeeac5483a 100644 --- a/site/docs/tutorial/java.md +++ b/site/docs/tutorial/java.md @@ -1,245 +1,4 @@ --- -layout: documentation -title: Build Java +layout: redirect +redirect: docs/tutorial/java.html --- - -Build Java -========== - -You can use Bazel to build your Java application. In this tutorial you'll learn how to: - -* Build your first Java target -* Add dependencies to your target -* Use multiple packages -* Deploy your target - -## 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. - -## Creating Your Own Build File - -Use the following commands to make a small Java project for this example: - -{% highlight bash %} -$ # If you're not already there, move to your workspace directory. -$ cd ~/gitroot/my-project -$ mkdir -p src/main/java/com/example -$ cat > src/main/java/com/example/ProjectRunner.java <<'EOF' -package com.example; - -public class ProjectRunner { - public static void main(String args[]) { - Greeting.sayHi(); - } -} -EOF -$ cat > src/main/java/com/example/Greeting.java <<'EOF' -package com.example; - -public class Greeting { - public static void sayHi() { - System.out.println("Hi!"); - } -} -EOF -{% endhighlight %} - -Bazel figures out what to build by looking for files named `BUILD` in your -workspace, so we'll create a `BUILD` file in the `~/gitroot/my-project` -directory. Add the following lines to this BUILD file: - -{% highlight python %} -# ~/gitroot/my-project/BUILD -java_binary( - name = "my-runner", - srcs = glob(["**/*.java"]), - main_class = "com.example.ProjectRunner", -) -{% endhighlight %} - -`java_binary` is the type of thing this rule will build. -`glob(["**/*.java"])` is a handy shorthand for "recursively include every file -that ends with .java" (see the -[build encyclopedia](be/functions.html#glob) for more information about -globbing). `com.example.ProjectRunner` specifies the class that contains the -main method. - -Now you are ready to build your Java binary: - -{% highlight bash %} -$ cd ~/gitroot/my-project -$ bazel build //:my-runner -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 -$ bazel-bin/my-runner -Hi! -{% endhighlight %} - -Congratulations, you've just built your first Bazel target! - -## Adding Dependencies - -Creating one rule to build your entire project may be sufficient for small -projects, but as projects get larger it's important to break up the build into -self-contained libraries that can be assembled into a final product. This way -the entire world doesn't need to be rebuilt on small changes and Bazel can -parallelize more of the build steps. - -To break up a project, create separate rules for each subcomponent and then -make them depend on each other. For the example above, add the following rules -to the `BUILD` file: - -{% highlight python %} -java_binary( - name = "my-other-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"], -) -{% endhighlight %} - -This builds the same files as before, but in a different way: now Bazel will -build the `greeter` library first and then build `my-other-runner`. Try building -and running `//:my-other-runner`: - -{% highlight bash %} -$ bazel run //:my-other-runner -INFO: Found 1 target... -Target //:my-other-runner up-to-date: - bazel-bin/my-other-runner.jar - bazel-bin/my-other-runner -INFO: Elapsed time: 2.454s, Critical Path: 1.58s - -INFO: Running command line: bazel-bin/my-other-runner -Hi! -{% endhighlight %} - -Now if you edit `ProjectRunner.java` and rebuild `my-other-runner`, -`Greeting.java` will not need to be recompiled. - -## Using Multiple Packages - -For larger projects, you will often be dealing with several directories. You -can refer to targets defined in other BUILD files using the syntax -`//path/to/directory:target-name`. For example, suppose -`src/main/java/com/example/` has a `cmdline/` subdirectory with the following -file: - -{% highlight bash %} -$ mkdir -p src/main/java/com/example/cmdline -$ cat > src/main/java/com/example/cmdline/Runner.java <<'EOF' -package com.example.cmdline; - -import com.example.Greeting; - -public class Runner { - public static void main(String args[]) { - Greeting.sayHi(); - } -} -EOF -{% endhighlight %} - -`Runner.java` depends on `com.example.Greeting`, so we could add a `BUILD` file -at `src/main/java/com/example/cmdline/BUILD` that contained the following rule: - -{% highlight python %} -# ~/gitroot/my-project/src/main/java/com/example/cmdline/BUILD -java_binary( - name = "runner", - srcs = ["Runner.java"], - main_class = "com.example.cmdline.Runner", - deps = ["//:greeter"] -) -{% endhighlight %} - -However, by default, build rules are _private_. This means that they can only be -referred to by rules in the same BUILD file. This 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`. As is, if we -build `runner` we'll get a permissions error: - -{% highlight bash %} -$ bazel build //src/main/java/com/example/cmdline:runner -ERROR: /home/user/gitroot/my-project/src/main/java/com/example/cmdline/BUILD:2:1: - Target '//:greeter' is not visible from target '//src/main/java/com/example/cmdline:runner'. - Check the visibility declaration of the former target if you think the dependency is legitimate. -ERROR: Analysis of target '//src/main/java/com/example/cmdline:runner' failed; build aborted. -INFO: Elapsed time: 0.091s -{% endhighlight %} - -You can make a rule visible to rules in other BUILD files by adding a -`visibility = level` attribute. Change the `greeter` rule in -`~/gitroot/my-project/BUILD` to be visible to our new rule: - -{% highlight python %} -java_library( - name = "greeter", - srcs = ["src/main/java/com/example/Greeting.java"], - visibility = ["//src/main/java/com/example/cmdline:__pkg__"], -) -{% endhighlight %} - -This makes `//:greeter` visible to any rule in the -`//src/main/java/com/example/cmdline` package. Now we can build and -run the `runner` binary: - -{% highlight bash %} -$ bazel run //src/main/java/com/example/cmdline:runner -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 - -INFO: Running command line: bazel-bin/src/main/java/com/example/cmdline/runner -Hi! -{% endhighlight %} - -See the [build encyclopedia](be/common-definitions.html#common.visibility) for more -visibility options. - -## Deploying - -If you look at the contents of -_bazel-bin/src/main/java/com/example/cmdline/runner.jar_, you can see that it -only contains `Runner.class`, not its dependencies (`Greeting.class`): - -{% highlight bash %} -$ jar tf bazel-bin/src/main/java/com/example/cmdline/runner.jar -META-INF/ -META-INF/MANIFEST.MF -com/ -com/example/ -com/example/cmdline/ -com/example/cmdline/Runner.class -{% endhighlight %} - -This works for running locally (the `runner` script Bazel generates adds the -greeter jar to the classpath) but will not work if we want to copy `runner.jar` -to another machine and use it as a standalone binary. To build a self-contained -jar that can be deployed, build `runner_deploy.jar` (or, more generally, -`<target-name>_deploy.jar`): - -{% highlight bash %} -$ bazel build //src/main/java/com/example/cmdline:runner_deploy.jar -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 -{% endhighlight %} - -`runner_deploy.jar` will contain all of its dependencies. - - diff --git a/site/docs/tutorial/review.md b/site/docs/tutorial/review.md index 62d4501ad4..16557f7527 100644 --- a/site/docs/tutorial/review.md +++ b/site/docs/tutorial/review.md @@ -1,29 +1,4 @@ --- -layout: documentation -title: Tutorial - Review +layout: redirect +redirect: docs/tutorial/review.html --- - -# 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/docs/tutorial/workspace.md b/site/docs/tutorial/workspace.md index ff3f6da510..76a2a7cd14 100644 --- a/site/docs/tutorial/workspace.md +++ b/site/docs/tutorial/workspace.md @@ -1,53 +1,4 @@ --- -layout: documentation -title: Tutorial - Set Up a Workspace +layout: redirect +redirect: docs/tutorial/workspace.html --- - -# 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. It also contains symbolic links to output directories in the -Bazel home directory. - -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/docs/windows.md b/site/docs/windows.md index a63761179c..8bf61e0e3b 100644 --- a/site/docs/windows.md +++ b/site/docs/windows.md @@ -1,83 +1,4 @@ --- -layout: documentation -title: Windows +layout: redirect +redirect: docs/windows.html --- - -Building 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. - -To bootstrap Bazel on Windows, you will need: - -* Java JDK 8 or later -* [Visual Studio](https://www.visualstudio.com/) (Community Edition is okay) -* [msys2](https://msys2.github.io/) (need to be installed at - ``C:\tools\msys64\``). -* Several msys2 packages. Use the ``pacman`` command to install them: - ``pacman -S gcc git curl zip unzip zlib-devel`` - -To build Bazel: - -* Open the msys2 shell. -* Clone the Bazel git repository as normal. -* Set the 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 -``` - -* Run ``compile.sh`` in Bazel directory. -* If all works fine, bazel will be built at ``output\bazel.exe``. - -Using Bazel on Windows -====================== - -Bazel currently supports building C++ targets and Java 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++ components -(which is NOT the default installation type of Visual Studio). - -* [Python 2.7](https://www.python.org/downloads/) -<br/>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! However, since MSVC -toolchain is not default on Windows yet, you should use flag -`--cpu=x64_windows_msvc` to enable it like this: - -```bash -$ bazel build --cpu=x64_windows_msvc examples/cpp:hello-world -$ ./bazel-bin/examples/cpp/hello-world.exe -$ bazel run --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 -``` - diff --git a/site/jekyll-tree.sh b/site/jekyll-tree.sh index d077345fcb..a787963aaa 100755 --- a/site/jekyll-tree.sh +++ b/site/jekyll-tree.sh @@ -40,24 +40,48 @@ function setup { # Unpack the Build Encyclopedia into docs/be function unpack_build_encyclopedia { - local be_dir="$OUT_DIR/docs/be" + local be_dir="$OUT_DIR/versions/master/docs/be" mkdir -p "$be_dir" unzip -qq "$BE_ZIP" -d "$be_dir" mv "$be_dir/be-nav.html" "$OUT_DIR/_includes" + + # Create redirects to each page in the Build Encyclopedia. + mkdir -p "$OUT_DIR/docs/be" + for f in $(find "$OUT_DIR/versions/master/docs/be" -name "*.html"); do + local filename=$(basename "$f") + cat > "$TMPDIR/out/docs/be/${filename}" <<EOF +--- +layout: redirect +redirect: docs/be/${filename} +--- +EOF + done } # Unpack the Skylark Library into docs/skylark/lib function unpack_skylark_library { - local sl_dir="$OUT_DIR/docs/skylark/lib" + local sl_dir="$OUT_DIR/versions/master/docs/skylark/lib" mkdir -p "$sl_dir" unzip -qq "$SL_ZIP" -d "$sl_dir" mv "$sl_dir/skylark-nav.html" "$OUT_DIR/_includes" + + # Create redirects to each page in the Skylark Library + mkdir -p "$OUT_DIR/docs/skylark/lib" + for f in $(find "$OUT_DIR/versions/master/docs/skylark/lib" -name "*.html"); do + local filename=$(basename "$f") + cat > "$TMPDIR/out/docs/skylark/lib/${filename}" <<EOF +--- +layout: redirect +redirect: docs/skylark/lib/${filename} +--- +EOF + done } function copy_skylark_rule_doc { local rule_family=$1 local rule_family_name=$2 - local be_dir="$OUT_DIR/docs/be" + local be_dir="$OUT_DIR/versions/master/docs/be" ( cat <<EOF --- diff --git a/site/versions/master/docs/bazel-user-manual.html b/site/versions/master/docs/bazel-user-manual.html index 794497490c..3480529df0 100644 --- a/site/versions/master/docs/bazel-user-manual.html +++ b/site/versions/master/docs/bazel-user-manual.html @@ -684,7 +684,6 @@ $ bazel fetch //... <li>Use the same values of these options as specified in the request configuration: <code class='flag'>--compiler</code>, - <code class='flag'>--thin_archives</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 @@ -1892,20 +1891,6 @@ cores directly from system configuration and will assume 1.0 I/O resource. that were successfully analyzed. </p> -<h4 id='flag--thin_archives'><code class='flag'>--[no]thin_archives</code></h4> -<p> - This option enables use of <i>thin archives</i>, an optimization which avoids - duplicating the content of object files when they are placed in archive - libraries; the archive library references the object file by name, and the - linker follows this reference as needed. This may give a speedup for C++ - builds, especially when building a single large executable from clean. -</p> - -<p> - This option is enabled by default; - use <code class='flag'>--nothin_archives</code> to disable. -</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 |
