From 61393e24961e00a0c7f4b9696e1222a6743d072b Mon Sep 17 00:00:00 2001 From: Laurent Le Brun Date: Tue, 21 Feb 2017 18:07:16 +0000 Subject: Add even more links to rules/macros documentation. -- PiperOrigin-RevId: 148109339 MOS_MIGRATED_REVID=148109339 --- site/versions/master/docs/skylark/macros.md | 7 +-- site/versions/master/docs/skylark/rules.md | 77 ++++++++++++++++++++--------- 2 files changed, 58 insertions(+), 26 deletions(-) (limited to 'site/versions/master') diff --git a/site/versions/master/docs/skylark/macros.md b/site/versions/master/docs/skylark/macros.md index 4babef0f1c..01a0bef695 100644 --- a/site/versions/master/docs/skylark/macros.md +++ b/site/versions/master/docs/skylark/macros.md @@ -8,10 +8,11 @@ title: Macros 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. +code reuse. By the end of the [loading phase](concepts.html#evaluation-model), +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. +Native rules (i.e. rules that don't need a `load()` statement) can be +instantiated from the [native](lib/native.html) module, e.g. ```python def my_macro(name, visibility=None): diff --git a/site/versions/master/docs/skylark/rules.md b/site/versions/master/docs/skylark/rules.md index f82c5a38ca..6e8023d2e5 100644 --- a/site/versions/master/docs/skylark/rules.md +++ b/site/versions/master/docs/skylark/rules.md @@ -213,6 +213,13 @@ outputs (like `_deploy.jar` in `java_binary`). ## Actions +An action describes how to generate a set of outputs from a set of inputs, for +example "run gcc on hello.c and get hello.o". When an action is created, Bazel +doesn't run the command immediately. It registers it in a graph of dependencies, +because an action can depend on the output of another action (e.g. in C, +the linker must be called after compilation). In the execution phase, Bazel +decides which actions must be run and in which order. + There are three ways to create actions: * [ctx.action](lib/ctx.html#action), to run a command. @@ -259,10 +266,32 @@ 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. If `executable=True`, configuration -setting is required. +Imagine that you want to build a C++ binary and target a different architecture. +The build can be complex and involve multiple steps. Some of the intermediate +binaries, like the compilers and code generators, have to run on your machine +(the host); some of the binaries such the final output must be built for the +target architecture. + +For this reason, Bazel has a concept of "configurations" and transitions. The +topmost targets (the ones requested on the command line) are built in the +"target" configuration, while tools that should run locally on the host are +built in the "host" configuration. Rules may generate different actions based on +the configuration, for instance to change the cpu architecture that is passed to +the compiler. In some cases, the same library may be needed for different +configurations. If this happens, it will be analyzed and potentially built +multiple times. + +By default, Bazel builds the dependencies of a target in the same configuration +as the target itself, i.e. without transitioning. When a target depends on a +tool, the label attribute will specify a transition to the host configuration. +This causes the tool and all of its dependencies to be built for the host +machine, assuming those dependencies do not themselves have transitions. + +For each [label attribute](lib/attr.html#label), you can decide whether the +dependency should be built in the same configuration, or transition to the host +configuration (using `cfg`). If a label attribute has the flag +`executable=True`, the configuration must be set explictly. +[See example](cookbook.html#execute-a-binary) In general, sources, dependent libraries, and executables that will be needed at runtime can use the same configuration. @@ -274,12 +303,11 @@ in the attribute. The configuration `"data"` is present for legacy reasons and should be used for the `data` attributes. - ## 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: +Rules may access [configuration fragments](lib/skylark-configuration-fragment.html) +such as `cpp`, `java` and `jvm`. However, all required fragments must be +declared in order to avoid access errors: ```python def impl(ctx): @@ -316,13 +344,15 @@ 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` +* [bool](lib/bool.html) +* [integer](lib/int.html) +* [string](lib/string.html) +* [file](lib/File.html) +* [label](lib/Label.html) +* [None](lib/globals.html#None) +* anything composed of these types and [lists](lib/list.html), + [dicts](lib/dict.html), [depsets](lib/depset.html) or + [structs](lib/struct.html). Providers are created from the return value of the rule implementation function: @@ -357,9 +387,9 @@ Providers are only available during the analysis phase. Examples of usage: 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. +During the [execution phase](concepts.md#evaluation-model), Bazel creates a +directory tree containing symlinks pointing to the runfiles. This stages the +environment for the binary so it can access the runfiles during runtime. Runfiles can be added manually during rule creation and/or collected transitively from the rule's dependencies: @@ -445,11 +475,12 @@ def rule_implementation(ctx): dependency_attributes=["data", "deps"])) ``` -`ctx.config.coverage_enabled` notes whether coverage data collection is enabled -for the current run in general (but says nothing about which files specifically -should be instrumented). If a rule implementation needs to add coverage -instrumentation at compile-time, it can determine if its sources should be -instrumented with: +[ctx.config.coverage_enabled](lib/configuration.html#coverage_enabled) notes +whether coverage data collection is enabled for the current run in general +(but says nothing about which files specifically should be instrumented). +If a rule implementation needs to add coverage instrumentation at +compile-time, it can determine if its sources should be instrumented with +[ctx.coverage_instrumented](lib/ctx.html#coverage_instrumented): ```python # Are this rule's sources instrumented? -- cgit v1.2.3