Page Not Found
We could not find what you were looking for.
Please contact the owner of the site that linked you to the original URL and let them know their link is broken.
})
+
+
+:::note
+The Concept Map is for reference only and is not intended to be 100%
+accurate nor complete.
+
+})
+
+### Buck2's dependency graph
+
+Every build rule can have zero or more dependencies. You can specify these
+dependencies using, for example, the `deps` argument to the build rule. For more
+information about specifying dependencies, consult the reference page for the
+build rule you are using. These dependencies form a directed graph, called the
+_target graph_. Buck2 requires the graph to be acyclic. When building the output
+of a build rule, all of the rule's transitive dependencies are built first. This
+means that the graph is built in a "bottom-up" fashion. A build rule knows only
+which rules it depends on, not which rules depend on it. This makes the graph
+easier to reason about and enables Buck2 to identify independent subgraphs that
+can be built in parallel. It also enables Buck2 to determine the minimal set of
+build targets that need to be rebuilt.
+
+### Multiple Buck2 projects in a single repository
+
+Buck2 is designed to build multiple deliverables from a single repository—that
+is, a _monorepo_—rather than from multiple repositories. Support for the
+monorepo design motivated Buck2's support for cells and projects. It is
+Facebook's experience that maintaining all dependencies in the same repository
+makes it easier to ensure that all developers have the correct version of the
+code and simplifies the process of making atomic commits.
+
+### See also
+
+Take a look at the [Concept Map](concept_map.md) for a visualization of how
+Buck2 concepts interact with each other. Also see the [Glossary](glossary.md).
diff --git a/_src/concepts/target_pattern.md b/_src/concepts/target_pattern.md
new file mode 100644
index 000000000000..59fa79665b2c
--- /dev/null
+++ b/_src/concepts/target_pattern.md
@@ -0,0 +1,88 @@
+---
+id: target_pattern
+title: Target Pattern
+---
+
+A _target pattern_ is a string that resolves to a set of
+[targets](./glossary.md#target). A target pattern can be used as arguments to
+commands, such as `buck2 build` and `buck uquery`. You can also use build target
+patterns in the [visibility](./glossary.md#visibility) argument of your build
+[rules](./glossary.md#rule).
+
+The simplest build target pattern matches the build target of the same name:
+
+```bash
+#
+# Matches //apps/myapp:app
+#
+//apps/myapp:app
+```
+
+A build target pattern that ends with a colon matches all build targets in the
+build file at the preceding directory path. For example, suppose that the build
+file:
+
+```sh
+apps/myapp/BUCK
+```
+
+defines the rules: `app_v1` and `app_v2`, then the following build target
+pattern would match both of those rules:
+
+```bash
+#
+# Matches //apps/myapp:app_v1 and //apps/myapp:app_v2
+#
+//apps/myapp:
+```
+
+A build target pattern that ends with an ellipsis (`/...`) matches all build
+targets in the build file in the directory that precedes the ellipsis and also
+_all build targets in build files in subdirectories_. For example, suppose that
+you have the following build files:
+
+```bash
+apps/BUCK
+apps/myapp/BUCK
+```
+
+then the following pattern would match all build targets in both of those files:
+
+```bash
+#
+# Matches (for example) //apps:common and //apps/myapp:app
+#
+//apps/...
+```
+
+A target pattern that does not include a `:` separator matches the target with
+the same name as the last element of the path:
+
+```bash
+#
+# Matches //apps/myapp:myapp
+#
+//apps/myapp
+```
+
+Finally, target patterns can be relative to your current directory. For example:
+
+```bash
+#
+# If your current working directory is `apps`, matches //apps/myapp:myapp
+#
+myapp:myapp
+```
+
+### Build target patterns are not allowed in the deps argument
+
+Build target patterns cannot be used with the `deps` argument of a build rule.
+Buck requires that you specify all dependencies explicitly as either
+fully-qualified or relative build targets.
+
+### Target aliases
+
+Buck supports the ability to define _aliases_ for build targets; using aliases
+can improve brevity when specifying targets on the Buck command line.
+
+To see which aliases exist, use `buck2 audit config alias`.
diff --git a/_src/concepts/visibility.md b/_src/concepts/visibility.md
new file mode 100644
index 000000000000..70e3bcc28414
--- /dev/null
+++ b/_src/concepts/visibility.md
@@ -0,0 +1,90 @@
+---
+id: visibility
+title: Visibility
+---
+
+Visibility determines whether a [target](./glossary.md#target) can reference
+another target in its [attributes](./glossary.md#attribute). In a large project,
+you may want to prevent developers from 'reaching across' the project and
+pulling in additional code. Reducing the visibility of targets can help prevent
+that type of behavior.
+
+There are two types of visibility attributes available (each of which takes a
+list of [target patterns](./glossary.md#target-pattern)):
+
+- `visibility` - determines which other targets can depend on a target.
+- `within_view` - determines which other targets a target can depend on.
+
+Both attributes act as allowlists, with some exceptions. In general, if a target
+is not listed, there may be no dependency relationship. If the `within_view`
+list is empty or unset, however, its check is bypassed. Similarly, targets
+defined in the same [BUCK file](./glossary.md#buck-file) always act as if they
+were members of their siblings' `visibility` lists.
+
+There is also a special value for `visibility` attribute: `'PUBLIC'`, which
+makes a build rule visible to all targets.
+
+In case of logically-conflicting lists, `within_view` takes precedence over
+`visibility`. If `//foo:bar` defines `//hello:world` in its `visibility` list,
+but `//hello:world` does not define `//foo:bar` in its `within_view` list, then
+`//hello:world` may not depend on `//foo:bar`.
+
+## Examples
+
+A common library like Guava should be able to be included by any build rule:
+
+```java
+prebuilt_jar(
+ name = 'guava',
+ binary_jar = 'guava-14.0.1.jar',
+ visibility = ['PUBLIC']
+)
+```
+
+It is common to restrict the visibility of Android resources to the Java code
+that uses it:
+
+```java
+android_resource(
+ name = 'ui_res',
+ res = 'res',
+ package = 'com.example',
+ visibility = ['//java/com/example/ui:ui']
+)
+```
+
+Or it may be simpler to make it visible to the entire directory in case
+additional build rules are added to `java/com/example/ui/BUCK`:
+
+```java
+android_resource(
+ name = 'ui_res',
+ res = 'res',
+ package = 'com.example',
+ visibility = ['//java/com/example/ui:']
+)
+```
+
+Also, it is common to limit code for testing to be visible only to tests. If you
+define all of your Java unit tests in a folder named `javatests/` in the root of
+your project, then you could define the following rule to ensure that only build
+rules under `javatests/` can depend on JUnit:
+
+```java
+prebuilt_jar(
+ name = 'junit',
+ binary_jar = 'junit-4.11.jar',
+ visibility = ['//javatests/...']
+)
+```
+
+Finally, restricting the view of a target can be useful for preventing
+dependency creep:
+
+```java
+java_library(
+ name = 'example',
+ visibility = ['PUBLIC',],
+ within_view = ['//foo:bar','//hello:world']
+)
+```
diff --git a/_src/developers/architecture/buck1_vs_buck2.md b/_src/developers/architecture/buck1_vs_buck2.md
new file mode 100644
index 000000000000..3129d9fc3a61
--- /dev/null
+++ b/_src/developers/architecture/buck1_vs_buck2.md
@@ -0,0 +1,175 @@
+---
+id: buck1_vs_buck2
+title: Buck1 vs Buck2
+---
+
+## At a glance
+
+The following table provides an at-a-glance comparison of Buck1 and Buck2.
+
+| Buck1 | Buck2 |
+| :---------------------------------------------- | :-------------------------------------------- |
+| Build files in Starlark | Build files in Starlark |
+| Macros in Starlark | Macros in Starlark |
+| Rules in Java | Rules in Starlark |
+| Rules and Macros are logically similar | Rules and Macros are logically similar |
+| Rules and Core are not well abstracted | Rules and Core are strongly separated |
+| Core in Java | Core in Rust |
+| Remote Execution (RE) not well supported | All rules support remote execution by default |
+| Varying degrees of incrementality / parallelism | Unified incrementality / parallelism |
+
+## Top-down vs Bottom-up - understanding the implications of the difference in execution models between Buck1 and Buck2
+
+It is often said that Buck1 does 'top down' and Buck2 does 'bottom up' building.
+This results in cases where some topics that seem conceptually trivial in Buck1
+are hard problems in Buck2, or vice versa.
+
+### What are the differences?
+
+**Scenario**: Imagine you are building A, which depends on both B and C, but
+where neither B nor C have any dependencies.
+
+For the sake of simplicity, imagine B and C are C++ compilations (that produce
+object files), and A is a link (that consumes them and produces a shared
+library).
+
+#### Building A with Buck1
+
+Following is an oversimplified view of what happens:
+
+- Buck1 computes the 'rulekey' for B.
+ - This consists of mixing together the hashes of the C++ file being compiled,
+ as well as all C++ compiler flags, and so on.
+- Buck1 then does the same for C.
+- Buck1 then computes the rulekey for A.
+ - This consist of mixing together the rulekeys of B and C, as well as linker
+ flags used by A. for example.
+- Buck1 then looks up the rulekey for A in the cache.
+ - If there's a hit, then Buck1 downloads the output and its job done.
+ - If there's a cache miss, continue.
+- Buck1 then queries the cache for the rulekeys of B and C:
+ - If there's a hit, then the output is downloaded.
+ - If there's a miss, then Buck1 runs the commands needed to produce the object
+ file that was missed. Regardless of whether those commands run locally or on
+ RE, Buck1 downloads the output of B and C.
+- Buck1 then runs the command for A to produce the shared library.
+ - At this point, Buck1 may actually do another cache lookup with a different
+ rulekey, which is called an _input based rulekey_. This rulekey is derived
+ from the inputs of the action that needs executing, which at this point of
+ the build are known (since they were just built)!
+
+#### Building A with Buck2
+
+In contrast, if you ask Buck2 to build A, here is what happens:
+
+- Buck2 produce the action to compile B and computes the hash of the action.
+ - This is the 'action digest', which consists of mixing the hashes of all the
+ inputs (such as the C++ file), as well as the command line (so, implicitly,
+ the compiler flags).
+- Buck2 queries the action cache for the action digest hash.
+ - If there's a hit, Buck2 obtains the hash of the resulting object file (that
+ is, the output of B).
+ - If there's a miss, Buck2 runs the action on RE (or potentially locally) and
+ obtains the hash of the object file. If the action runs remotely, Buck2 will
+ not download the output.
+- Buck2 does the same thing for C.
+- Buck2 produces the action to link A.
+ - This consists of mixing together all the hashes of the input files (which
+ were retrieved earlier) and the command line to produce an action digest,
+ then querying the cache and potentially running the action.
+- Once Buck2 produces A (again, on RE), then, since this output was requested by
+ the user (unlike the intermediary outputs B and C), Buck2 downloads A.
+
+### Some implications
+
+#### Rulekeys vs Action digests
+
+The closest thing to Buck1’s rulekey in Buck2 is the action digest, but they are
+very different!
+
+Since it’s a product of the (transitive) inputs of an action, the (default)
+rulekey can be computed without running anything or querying any caches.
+However, the action digest cannot: it requires the actual inputs of an action,
+which means you need to build all the dependencies first.
+
+This means that:
+
+- In Buck1, you can ask for rulekeys for a target.
+- In Buck2, you’d have to run the build first then ask for the action digests
+ (this is what the `buck2 log what-ran` would show you).
+
+#### Buck2 queries many more caches
+
+- Buck1 will not descend further down a tree of dependency when it gets a cache
+ hit.
+- Buck2 will always walk up all your dependencies, regardless of whether you get
+ cache hits or not.
+
+#### Materialization
+
+- When Buck1 gets a cache miss, it downloads the outputs.
+- Buck2, by contract, does not download outputs as part of a build (this is
+ called 'deferred materialization').
+ - Note that Buck2 does download the outputs if the user asked for them (that
+ is, they were the targets the user put on the command line).
+
+### Second-order implications
+
+#### Non-determinism
+
+Non-determinism in a build affects Buck2 and Buck1 differently. One scenario
+that often works fine in Buck1 but can work catastrophically bad in Buck2 is a
+codegen step, driven by a Python binary.
+
+In certain configurations/modes, Python binaries are non-deterministic, because
+they are
+(XARs)[https://engineering.fb.com/2018/07/13/data-infrastructure/xars-a-more-efficient-open-source-system-for-self-contained-executables/]
+(eXecutable ARchives) and that is always non-deterministic, which is bad!
+
+- In Buck1, that doesn’t really matter, because you can get a cache hit on the
+ codegen output without ever visiting the XAR (as long as the input files
+ haven’t changed).
+- In Buck2, you need the XAR to check the action cache for the codegen step.
+ - However, binaries are often not cached in certain configurations/modes, so
+ your XAR isn’t cached.
+ - Therefore, since your XAR build is non-deterministic, you’ll always miss in
+ the action cache and the codegen step will always have to run in every
+ build.
+
+It can get worse! If the Python binary produces non-deterministic codegen, then
+the entire build might become uncacheable.
+
+#### Cache misses don’t necessarily propagate
+
+Say that, in Buck2, you’re trying to build a chain of actions like codegen ->
+compile -> link.
+
+Even if your codegen step isn’t cached (say, because its action inputs are
+non-deterministic as mentioned above), as long as the codegen output is
+deterministic, you can still get cache hits from compile and link steps.
+
+#### Hybrid execution
+
+If you squint, you’ll note that Buck1’s build could be viewed as 'local first',
+whereas Buck2’s would be better viewed as 'remote first':
+
+- When Buck1 builds something remotely or gets a cache hit, the outputs are
+ always downloaded.
+- When Buck2 builds something remotely or gets a cache hit, the outputs are
+ never downloaded.
+
+In turn, this has some important implications:
+
+- When Buck1 builds something locally, the inputs are always already present.
+- When Buck2 builds something locally, the inputs have to be downloaded, unless
+ they were built locally (which if you’re doing any RE, is usually not the
+ case), or if another command caused them to be downloaded.
+
+This means that, in Buck1, running something locally when you have spare
+resources is usually a no-brainer, because it’s always ready to go, and you’ll
+save on not having to download the output from RE (though you might have to
+upload the output if you need to run actions depending on it later).
+
+On the flip side, with Buck2, that’s not necessarily the case. To run an action
+locally, you need to download inputs that you might otherwise not have needed,
+which will tax your network connection.
diff --git a/_src/developers/architecture/buck2.md b/_src/developers/architecture/buck2.md
new file mode 100644
index 000000000000..90438a76590e
--- /dev/null
+++ b/_src/developers/architecture/buck2.md
@@ -0,0 +1,190 @@
+---
+id: buck2
+title: Architectural Model
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+## High-level Overview
+
+Buck2 is a build system whose core is written in Rust. Starlark, which is a
+deterministic, immutable version of Python, is used to extend the Buck2 build
+system, enabling Buck2 to be language-agnostic.
+
+The high-level flow starts with a user creating a build file (a `BUCK` file)
+containing one or more targets, which is specified by the target label, its
+inputs (sources, attributes, configurations, and dependencies), and the type of
+macro or rule to use.
+
+Briefly, a macro is a wrapper around a rule, which runs necessary commands to
+generate what’s needed for a target (for example, for a `cxx_binary` target,
+generate the header map and run necessary `clang` commands). Macros can be used
+to reduce boilerplate code for users (such as to supply the same set of
+attributes for a rule for all targets). Macros and rules are both written in
+Starlark and are specified by input sources, attributes, and the implementation
+function.
+
+If the target type is a macro, then the macro will fill in some details (for
+example, for a `cxx_binary` target, these are the compilation, debug flags to
+use, this is the `clang` to use). If the target type is a rule, then the macro
+layer is skipped altogether.
+
+This is all orchestrated by the core, which performs operations such as
+executing Buck2 CLI args, generating/updating the dependency graph (which
+contains the configured target nodes, unconfigured target nodes, action nodes,
+among other types of nodes that all allow for incrementality and execution), and
+materializing the artifacts. The core is written in Rust.
+
+The following diagram shows the high-level overview.
+
+})
+
+The Buck2 CLI runs in a client process, which sends commands to the Buck2 daemon
+via gRPC. The daemon goes through several phases after receiving a request from
+the client: **evaluation, configuration, analysis, execution, and
+materialization** (see [Execution Model](#execution-model), below). When using
+`buck2 test`, there is a final stage for **testing**. Note that these are the
+phases that a build goes through, but they are not always sequential.
+
+After finishing all phases, the daemon will send the response back to the client
+via gRPC.
+
+## Execution Model
+
+The following diagram shows the Execution Model, which consists of 5 phases and
+states.
+
+})
+
+Each of the phases and states shown in the Execution Model, are detailed in the
+following sub-sections.
+
+### State 0 - Build Files
+
+Build files (commonly referred to as `BUCK` files, their default name) are the
+main input to Buck2 and are syntactically Python.
+
+Each build file is uniquely identified by the directory in which it's located.
+Since all build files have the same name, there cannot be two build files in the
+same directory. This is usually represented as the relative path from the root
+of the project (the directory where the .buckconfig file is).
+
+Each build file has a set of targets. These describe the things the user wants
+Buck2 to know about. Each target has a type and a set of named attributes,
+including at least a name (also known as the label) identifying it. Additional
+attributes depend on the type of the target.
+
+### Phase A: Evaluation
+
+First, Buck2 evaluates a build file, and then constructs an unconfigured target
+graph.
+
+Buck2 performs directory listings to discover packages, then evaluates the build
+files that were found, expands any macros detected into their underlying rules,
+and then will take rule attributes and convert them from Starlark to Rust types
+to construct a target node, and insert it into the unconfigured target graph,
+which is a smaller portion of Buck2’s larger dependency graph. The target node
+consists of a reference to rule implementation, and the set of attributes and
+sources.
+
+The result of evaluation is a list of targets read from the build file mapped to
+a target node in Buck2 unconfigured target graph.
+
+### State 1 - Unconfigured Target Graph is generated
+
+At this point, the unconfigured target graph is available for the next stage of
+transformation, which is to configure the target nodes within the graph.
+
+### Phase B: Configuration
+
+At the end of evaluation, the target nodes are not yet configured. Configuration
+means applying a list of constraints (such as resolving selects to specify the
+right CPU) to make sure the target can be run where it needs to. This is also
+known as target platform resolution, and can be configured within the target,
+the buckconfig, propagated from dependencies, or passed into the CLI. After
+applying configurations, the target nodes are transformed into configured target
+nodes within the Buck2 configured target graph, which is a smaller portion of
+Buck2’s larger dependency graph.
+
+### State 2 - Configured Target Graph is generated
+
+At this point, the configured target graph is available for the analysis stage
+to generate the action graph.
+
+### Phase C: Analysis
+
+In the analysis phase, Buck2 constructs a context object (ctx) which contains
+relevant information (such as attributes pulled from the configuration stage),
+all converted into Starlark types and made available to the rule. For example,
+the target’s dependencies are turned into a `ProviderCollection`, source files
+are converted into `StarlarkArtifacts`, and String attributes are turned into a
+`StarlarkString`. This ctx object is backed by Buck2’s dependency graph for
+computation and rules use it to tell Buck2 to run actions, create dynamic
+actions, or create new files.
+
+The rule will return a list of providers, which is data that the rule wants to
+expose to its dependents (that is, can flow through the dependency graph), such
+as output artifact information (such as file paths and file hashes). Providers
+could be actions, source files, or attributes. Within the returned list,
+DefaultInfo always needs to be returned, which indicates what the default
+outputs are. Some other common built-in providers include RunInfo, TestInfo, and
+InstallInfo.
+
+The end result is a list of providers and actions (inserted into the action
+graph) that Buck2 needs to execute to produce the desired outputs, known as
+'bound artifacts'.
+
+### State 3 - Action Graph and Providers are generated
+
+At this point, the action graph and providers are available to be processed by
+the execution stage.
+
+### Phase D: Execute
+
+Execution is where Buck2 takes all the providers (input files from the targets,
+args from the command line), runs the actions, and then outputs the computed
+results. The critical path is the theoretical lower bound for the duration of a
+build, which are the slowest set of actions.
+
+Buck2 can be run locally or on remote execution, or in a hybrid manner.
+
+For each action, a digest is created which is a hash of an action's command and
+all its inputs. Buck2 then checks if there is a result cached within RE for an
+action with a given digest.
+
+If there is a cache hit, Buck2 does not need to run the command for the action.
+Instead, the RE returns the output action digest. This digest can be used to
+download the actual output artifacts at a later time. This is known as the **RE
+action cache**.
+
+If there is a cache miss, the action needs to be run either remotely or locally.
+If Buck2 decides to run the action remotely, it will first upload all of the
+action's inputs that are missing from the RE's content addressable storage. If
+Buck2 decides to run the action locally, it will first download and materialize
+in `buck-out` all of the action's inputs. These inputs might be outputs of other
+actions and are stored in RE's content addressable storage but are missing on
+the local machine.Only after those steps will Buck2 schedule the action for
+actual execution.
+
+Buck2 can also decide to run local and remote execution simultaneously (a
+process known as racing), and use the result of whichever action finishes first
+to speed up performance. This strategy is known as **hybrid execution**."
+
+Materialization of action outputs (which involves downloading and placing them
+in the correct location in `buck-out`) can be done immediately after the action
+has finished executing. Alternatively, it can be deferred until it is actually
+needed for the local execution of another action. There are various
+configurations that a user can set to control how this materialization is
+handled.
+
+### State 4 - Build outputs are generated
+
+At this point, the build is complete.
+
+If a user ran `buck2 test`, then there is a final transformation for Buck2 to
+construct a command for TPX to execute the actual test.
+
+### Phase E: Execute tests
+
+For more detail on testing, review
+[Test Execution](/docs/rule_authors/test_execution).
diff --git a/_src/developers/architecture/buck2_telemetry.md b/_src/developers/architecture/buck2_telemetry.md
new file mode 100644
index 000000000000..9cb33beaff20
--- /dev/null
+++ b/_src/developers/architecture/buck2_telemetry.md
@@ -0,0 +1,11 @@
+---
+id: buck2_telemetry
+title: Buck2 Telemetry
+---
+
+
+:::note
+🚧 THIS PAGE IS UNDER CONSTRUCTION
+
+
+:::
diff --git a/_src/developers/bxl.md b/_src/developers/bxl.md
new file mode 100644
index 000000000000..ce850e20bfe9
--- /dev/null
+++ b/_src/developers/bxl.md
@@ -0,0 +1,117 @@
+---
+id: bxl
+title: Why BXL
+---
+
+## Buck2 Extension Language (BXL)
+
+BXL is a Starlark-based script that enables integrators to inspect and interact
+with the Buck2 graph.
+
+Integrators are able to:
+
+- Write Starlark code that queries, analyzes, and builds on the Buck2 graph.
+- Introspect and interact with the Buck2 graph structures natively, via
+ Starlark, in a safe, controlled manner.
+
+Introspection of the Buck2 graph can occur at the unconfigured, configured,
+providers, and action stages. There are also APIs offered to allow BXL to accept
+custom command line argument, output artifacts, and print results to stdout.
+
+BXL leverages Buck2 core's incremental
+[caching](bxl_faq.md#when-is-my-bxl-script-cached). It also has support for
+[running actions](bxl_common_how_tos.md#running-actions),
+[dynamic outputs](bxl_dynamic_output.md), and
+[anonymous targets](bxl_anon_target.md). In addition, BXL has
+[profiling](bxl_common_how_tos.md#profiling-testing-and-debugging-a-bxl-script)
+capabilities, and allows users to add their own [telemetry](bxl_telemetry.md)
+directly within the BXL scripts.
+
+BXL is considered to be mostly stable, with a bit more active development here
+and there.
+
+## When should I use BXL over Buck2 API/CLI?
+
+There are many overlaps between BXL and Buck2 (for example, both can run cquery
+and both can build targets). It’s possible that one use case could be handled by
+both BXL and Buck2.
+
+Following are some specific recommendations to help decide when to use BXL over
+regular Buck2:
+
+- **Use/inspect resolved attributes that are not exposed/accessible to users via
+ normal Buck2 operations.**
+ - This includes introspecting the Starlark object of providers, analyzing the
+ Starlark object of a rule’s attr before and after coercing and resolution,
+ and introspecting intermediate query results.
+- **Reduce/eliminate the need to make several Buck2 calls within your program,
+ such as running several subprocesses to call `cquery` several times.**
+ - With BXL, you can just call the BXL script once in a subprocess, potentially
+ reducing the amount of code you need to write in your program. For example,
+ if you need to call cquery and build several times, you can put that all
+ within a single BXL script and run `buck2 bxl` once, rather than running
+ `buck2 cquery` and `buck2 build` several times.
+- **Reduce/eliminate the need to manually parse Buck2 output format within your
+ program, and any bugs that may come with manual parsing**.
+ - Some languages are more verbose than others when it comes to string parsing.
+ - BXL scripts are written in Starlark, which is basically a deterministic,
+ immutable Python, and are able to directly introspect Starlark objects (such
+ as rules and target nodes, and so on) and call methods on these objects
+ instead of parsing them over Buck2’s output.
+
+## Example Use Cases
+
+### Generate a project for IDE
+
+IDE project generation is roughly as follows:
+
+- Form the target graph for the project target
+- Perform some filtering on the graph targets if needed. This depends on the
+ target's configuration.
+- For each target, generate the project target metadata, including:
+- compiler flags
+- linker flags
+- paths to generated files
+- inputs and outputs for each targets
+- the paths relative to some `PATH`
+- Write a single file translating this metadata into a format understood by the
+ IDE
+
+An example BXL flow for generating a project for IDE might be:
+
+- Add some command line arguments to accept a target (or subtarget) to generate
+ the project
+- Run analysis on the project target with a specific configuration to filter the
+ graph targets
+- For each resulting target, inspect the providers and attributes to extract the
+ required metadata information. BXL has filesystem operations handle paths
+ within the project
+- Run actions based on the linker/compiler flags, and build artifacts as needed
+ to generate a project
+- Write a single file containing the metadata obtained from previous steps
+
+### Build an LSP
+
+A compilation database is a database containing information about which compile
+options are used to build the files in a project. Language Server Protocols
+(LSPs) uses the compilation database to provide language features like auto
+complete, go to definition, and find all references for the user within an
+IDE/editor.
+
+An example BXL flow for building a C++ LSP might be:
+
+- Add a command line argument to accept a file
+- Run owners cquery in BXL to get the owning target of the file
+- Run analysis on the owning target to get the desired clang flags
+- Use BXL to write the clang flags to the disk in compilation database format
+
+### Perform graph analysis
+
+Some example graph analysis functionalities might be:
+
+- Run an analysis in BXL on a set of targets, and then inspect their providers,
+ and build some subtargets
+- Run a uquery on some set of targets, and inspect the resulting nodes' coerced
+ attributes
+- Run a cquery on some set of targets with a specific configuration, and inspect
+ the resulting nodes' attributes before and after resolution
diff --git a/_src/developers/bxl_anon_target.md b/_src/developers/bxl_anon_target.md
new file mode 100644
index 000000000000..4e0757099abc
--- /dev/null
+++ b/_src/developers/bxl_anon_target.md
@@ -0,0 +1,144 @@
+---
+id: anon_targets
+title: BXL and Anonymous Targets
+---
+
+## Anonymous targets
+
+[Anonymous targets](../rule_authors/anon_targets.md) are supported in BXL.
+Anonymous targets are keyed by the attributes, and allow you to share/cache work
+more effectively.
+
+You might want to use anonymous targets if there is some heavy Starlark
+evaluation which can be cached, or if you want to cache local actions.
+
+**Note**: The context object within the anon target rule is **not** a BXL
+context, but a normal rule analysis context.
+
+### APIs
+
+The `actions` object returned from `ctx.bxl_actions().actions` (equivalent of
+`ctx.actions` in normal rules) has the following functions for anonymous
+targets:
+
+- `anon_target(rule: "rule", attrs: Dict[str, Any]) -> "promise"`: generates a
+ single anonymous target. Return type is an unresolved `promise`.
+- `anon_targets(rules: [("rule", Dict[str, Any])]) -> "promise"`: generates a
+ list of anonymous targets. Return type is an unresolved `promise` representing
+ the list of anonymous targets.
+- `artifact_promise(promise: "promise") -> "promise_artifact"`: turns an
+ unresolved promise into a kind of artifact. See
+ [Convert promise to artifact](../rule_authors/anon_targets.md#convert-promise-to-artifact)
+ for more info on why you might want to use this.
+
+The resulting promise also has `map()` and `join()` functions. `map()` applies a
+function to the promise's results, and `join()` turns multiple promises into a
+single promise.
+
+To resolve promises in BXL, `bxl_ctx` has a `resolve()` function, which takes in
+the analysis actions instance (`actions` object returned from
+`ctx.bxl_actions().actions`) and a single promise and returns an optional
+promise value, if there is one. If you intend to create multiple promises, using
+`join()` to produce a single promise will allow you to resolve them concurently
+with a single `resolve()` call.
+
+Small example:
+
+```python
+def _my_impl(ctx):
+ bxl_actions = ctx.bxl_actions() # pass in relevant params to configure the execution platform resolution
+ actions = bxl_actions.actions
+
+ promise1 = actions.anon_target(my_anon_rule1, my_attrs1).promise
+ promise2 = actions.anon_target(my_anon_rule2, my_attrs2).promise.map(my_map_function)
+
+ joined = promise1.join(promise2)
+
+ resolved = ctx.resolve(actions, joined)
+
+ # do some more stuff ...
+```
+
+### Complete Example
+
+```python
+## anon_bxl_rules.bzl ############
+
+# Define an anonymous rule.
+
+MirrorInfo = provider(fields = ["mirrored_attrs"])
+
+# Anonymous rule which writes some silly output, and also mirrors all attributes received
+def _mirror_impl(ctx: "context") -> ["provider"]:
+ out = ctx.actions.declare_output("my_output")
+ ctx.actions.write(out, "my_content")
+ return [DefaultInfo(default_outputs = [out]), MirrorInfo(mirrored_attrs = ctx.attrs)]
+
+my_mirror_rule = rule(impl = _mirror_impl, attrs = {
+ "false": attrs.bool(),
+ "int": attrs.int(),
+ "list_string": attrs.list(attrs.string()),
+ "string": attrs.string(),
+ "true": attrs.bool(),
+})
+
+# Will be used in a map function in my_script.bxl below
+StringInfo = provider(fields = ["my_string"])
+
+## my_script.bxl ############
+
+load(":anon_bxl_rules.bzl", "MirrorInfo", "StringInfo", "my_mirror_rule")
+
+def _anon_target_example(ctx):
+ bxl_actions = ctx.bxl_actions()
+ actions = bxl_actions.actions
+
+ # Attrs to pass into the anonymous target. An anonymous target is defined by the hash of its attributes
+ my_attrs = {
+ "false": False,
+ "int": 42,
+ "list_string": ["a", "b", "c"],
+ "string": "foo-bar-string",
+ "true": True,
+ }
+
+ # A function to be applied to the promise (result of anon target), producing a promise with the resulting value.
+ def my_function(providers):
+ # Do something with the attrs. In this example, we are validating that the attrs are what we expect.
+ mirrored_fields = providers[MirrorInfo].mirrored_attrs
+ assert_eq(mirrored_fields.true, True)
+ assert_eq(mirrored_fields.false, False)
+ assert_eq(mirrored_fields.int, 42)
+ assert_eq(mirrored_fields.string, "foo-bar-string")
+ assert_eq(mirrored_fields.list_string, ["a", "b", "c"])
+
+ outputs = providers[DefaultInfo].default_outputs
+ # These are the providers this target returns
+ return [DefaultInfo(default_outputs = outputs), StringInfo(my_string = "map function succeeded!")]
+
+ # Create an anonymous target by passing in "my_attrs" into "my_mirror_rule", and returns providers.
+ # Specifically, it returns "DefaultInfo" and "MirrorInfo", as defined in "my_mirror_rule"
+ # Then, we map the result to "my_function", which does some validation
+ promise = actions.anon_target(my_mirror_rule, my_attrs).promise.map(my_function)
+
+ # Resolving the promise returns a "provider_collection", which was defined by "my_function" above.
+ # `DefaultInfo` is at index 0, `StringInfo` is at index 1
+ promise_result = ctx.resolve(actions, promise)
+
+ ensured = ctx.output.ensure(promise_result[0].default_outputs[0])
+ # should print out location of the output, which contains the "my_content" string as defined in anon_bxl_rules.bzl above
+ ctx.output.print(ensured)
+
+ # should print out "map function succeeded!"
+ ctx.output.print(promise_result[1].my_string)
+
+def assert_eq(a, b):
+ if a != b:
+ fail("Expected {} == {}".format(a, b))
+
+anon_target_example = bxl_main(
+ impl = _anon_target_example,
+ cli_args = {
+ },
+)
+```
diff --git a/_src/developers/bxl_basics.md b/_src/developers/bxl_basics.md
new file mode 100644
index 000000000000..ffe0358b6d08
--- /dev/null
+++ b/_src/developers/bxl_basics.md
@@ -0,0 +1,107 @@
+---
+id: bxl_basics
+title: BXL Basics
+---
+
+This page is a primer on common BXL functionalities and data types. Ramping up
+in BXL may be challenging without much prior knowledge of Buck2 building blocks
+(ex: targets, configurations, queries), so please take a look at the
+[Concepts](../concepts/concept_map.md) documentation before reading on.
+
+## Common BXL functionalities
+
+### Build
+
+You can build targets within BXL with
+[`ctx.build()`](../../api/bxl/bxl_ctx/#bxl_ctxbuild). The result is a
+[`bxl_build_result`](../../api/bxl/bxl_build_result), which has `artifacts()`
+and `failures()` functions that provide iterators to the artifacts or failures,
+respectively. You can pass in a single target or target pattern to build.
+
+### Analysis
+
+You can run analysis on targets within BXL via
+[`ctx.analysis()`](../../api/bxl/bxl_ctx/#bxl_ctxanalysis). Analysis means to
+evaluate the underlying rule implementation for the inputted targets, and
+produce the providers that the rule defined for the target. A common workflow is
+to inspect the resulting providers, and perhaps ensure parts of these providers
+or run actions using information from the providers (see [Actions](#actions)
+below).
+
+### Query
+
+Buck2 supports a couple different query types: querying the unconfigured graph
+(`buck2 uquery`), the configured graph (`buck2 cquery`), or the action graph
+(`buck2 aquery`). These queries are all available in BXL as well:
+
+- `ctx.uquery()` returns a [`uqueryctx`](../../api/bxl/uqueryctx)
+- `ctx.cquery()` returns a [`cqueryctx`](../../api/bxl/cqueryctx)
+- `ctx.aquery()` returns a [`aqueryctx`](../../api/bxl/aqueryctx)
+
+You can read more about the individual queries in the API docs. There are many
+queries that are common between uquery, cquery, and aquery, but cquery and
+aquery will have extra queries unique to the configured graph or the action
+graph. One more thing to call out is the `eval()` query, which is a special
+query that takes in the entire query as a string literal. A common use for
+`eval()` is to migrate a complex query from Buck2 CLI to BXL by dropping the
+entire query string directly into `eval()`.
+
+The query results are target sets (iterable container) of
+[`unconfigured_target_node`s](../../api/bxl/unconfigured_target_node) for
+uquery, [`target_node`s](../../api/bxl/target_node) for cquery, and
+[`action_query_node`s](../../api/bxl/action_query_node) for aquery. Each of
+these node types have accessors on their attributes. A common workflow is to run
+some query in BXL, and iterate through the resulting nodes to inspect their
+attributes, and use those attributes to inform further computations in BXL.
+
+#### Uquery
+
+Querying the unconfigured graph means that no configurations (such as platforms
+and transitions) have been applied to the target graph yet. This means that it's
+very possible that some parts of the target graph is broken due to lack of
+configurations. Generally to avoid this problem, cquery may be preferred
+instead.
+
+#### Cquery
+
+Querying the configured graph means that configurations have been applied to the
+target graph. For cquery, we require that users use a
+[target universe](../developers/bxl_target_universe.md) for their query inputs.
+
+#### Aquery
+
+Aquery is a quite different from uquery and cquery. It is used to query the
+action graph, which is constructed after Buck2 runs analysis on the targets and
+produces the list of providers and actions needed to build the target.
+
+### Actions
+
+You can create actions directly within the BXL API. The available action APIs
+are equivalent to the ones found on the [`actions`](../../api/bxl/actions) type
+for normal rules, with the caveat that
+[dynamic actions](./bxl_dynamic_output.md) use the
+[`bxl_ctx`](../../api/bxl/bxl_ctx) (which provides richer functionalities).
+
+A common workflow would be to run analysis on a target, and use some interesting
+bits found in the analysis result to construct an augmented
+[`cmd_args`](../../api/bxl/cmd_args) to run, and then ensure the action's output
+(see below for ensuring). Also see
+[Running actions](./bxl_common_how_tos.md#running-actions).
+
+### Ensure
+
+Ensuring an artifact means that you want the artifact to be materialized
+(meaning, downloaded to your machine) at the end of the BXL execution. There are
+two APIs for ensuring: `ctx.output.ensure()` and `ctx.output.ensure_multiple()`
+(see [`bxl_output_stream`](../../api/bxl/bxl_output_stream)). As the naming
+indicates, the former is for ensuring a single artifact, and the latter is for
+ensuring multiple artifact-like inputs. Artifact-like inputs include
+[`cmd_args`](../../api/bxl/cmd_args) (can be found when inspecting providers),
+[`bxl_build_result`](../../api/bxl/bxl_build_result) (produced when building
+something in BXL), or [`artifact`](../../api/bxl/artifact) (can be found when
+inspecting providers, or creating your own actions).
+
+A common workflow is to ensure an artifact that you created via some custom
+actions defined in your script, or ensuring some artifacts found in the
+providers after running analysis. Also see
+[What do I need to know about ensured artifacts](./bxl_faq.md#what-do-i-need-to-know-about-ensured-artifacts).
diff --git a/_src/developers/bxl_common_how_tos.md b/_src/developers/bxl_common_how_tos.md
new file mode 100644
index 000000000000..4bc69ce1be54
--- /dev/null
+++ b/_src/developers/bxl_common_how_tos.md
@@ -0,0 +1,234 @@
+---
+id: bxl_how_tos
+title: Common How-Tos
+---
+
+## Passing in and using CLI args
+
+A BXL function can accept a `cli_args` attribute where args names and types are
+specified to use within your script, as shown in the following example:
+
+Example:
+
+```python
+def _impl_example(ctx):
+ # ...
+ pass
+
+example = bxl_main(
+ impl = _impl_example,
+ cli_args = {
+ # cli args that you want to receive from the command line
+ "bool_arg": cli_args.bool(),
+ "list_type": cli_args.list(cli_args.int()),
+ "optional": cli_args.option(cli_args.string()),
+ "target": cli_args.target_label(),
+ },
+)
+```
+
+On the command line, you can invoke the arguments as follows:
+
+```sh
+buck2 bxl //myscript.bxl:example -- --bool_arg true --list_type 1 --list_type 2 --target //foo:bar
+```
+
+For BXL functions, to read the arguments, use them as attributes from the
+`cli_args` attribute on the BXL `ctx` object, as follows:
+
+```python
+def _impl_example(ctx):
+ my_bool_arg = ctx.cli_args.bool_arg
+```
+
+## Running actions
+
+You can create actions within BXL via the `actions_factory`. This is called once
+globally then used on demand:
+
+```python
+def _impl_example(ctx):
+ actions = ctx.bxl_actions().actions # call once, reuse wherever needed
+ output = actions.write("my_output", "out")
+```
+
+You will need to have
+[execution platforms](../rule_authors/configurations.md#execution-platforms)
+enabled for your project, or else you will get an error. You can specify the
+execution platform resolution by setting named parameters when instantiating
+`bxl_actions`:
+
+- `exec_deps` - These are dependencies you wish to access as executables for
+ creating the action. This is usually the same set of targets one would pass to
+ rule's `attr.exec_dep`. Accepts a list of strings, subtarget labels, target
+ labels, or target nodes.
+- `toolchains` - The set of toolchains needed for the actions you intend to
+ create. Accepts a list of strings, subtarget labels, target labels, or target
+ nodes.
+- `target_platform` - The intended target platform for your toolchains. Accepts
+ a string or target label.
+- `exec_compatible_with` - Explicit list of configuration nodes (like platforms
+ or constraints) that these actions are compatible with. This is the
+ `exec_compatible_with` attribute of a target. Accepts a list of strings,
+ target labels, or target nodes.
+
+If you specify `exec_deps` or `toolchains`, you can access the resolved
+`dependency` objects on the `bxl_actions` object. The `bxl_actions` object will
+have `exec_deps` and `toolchains` attributes, which are `dict`s where the keys
+are the unconfigured subtarget labels, and the values are the
+configured/resolved `dependency` objects.
+
+Note that the keys of `exec_deps` and `toolchains` must be unconfigured
+subtarget labels (`StarlarkProvidersLabel`), and not unconfigured target labels.
+You can use `ctx.unconfigured_sub_targets(...)` or `with_sub_target()` on
+`target_label` to create the label.
+
+```python
+def _impl_example(ctx):
+ my_exec_dep = ctx.unconfigured_sub_targets("foo//bar:baz") # has some provider that you would use in the action
+ bxl_actions = ctx.bxl_actions(exec_deps = [my_exec_dep]) # call once, reuse wherever needed
+ output = bxl_actions.actions.run(
+ [
+ "python3",
+ bxl_actions.exec_deps[my_exec_dep][RunInfo], # access resolved exec_deps on the `bxl_actions`
+ out.as_output(),
+ ],
+ category = "command",
+ local_only = True,
+ )
+ ctx.output.ensure(output)
+```
+
+## Getting providers from an analysis
+
+After calling `analysis()`, you can get the providers collection from
+`providers()`:
+
+```python
+def _impl_example(ctx):
+ my_providers = ctx.analysis(my_target).providers()
+```
+
+## Get a specific provider from an analysis
+
+After calling `analysis()`, you can also get the providers collection from
+`providers()` then grab whatever specific provider you need:
+
+```python
+def _impl_example(ctx):
+ default_info = ctx.analysis(my_target).providers()[DefaultInfo]
+ ctx.output.print(default_info)
+```
+
+## Get a specific subtarget from an analysis
+
+Once you have a provider, you can get its subtargets by using the `sub_targets`
+attribute on the struct to get a dict of provider labels to provider
+collections:
+
+```python
+def _impl_example(ctx):
+ subtarget = ctx.analysis(my_target).providers()[DefaultInfo].sub_targets["my_subtarget"]
+ ctx.output.print(subtarget)
+```
+
+## Building a subtarget
+
+You can use `analysis()` to get a specific subtarget from an analysis, or you
+can pass in the subtarget literal directly into `ctx.build()`:
+
+```python
+def _impl_example(ctx):
+ outputs = ctx.build("cell//path/to/my:target[my_subtarget]")
+ ctx.output.ensure_multiple(outputs)
+```
+
+## Getting attributes or resolved attributes efficiently on a configured target node
+
+If you need to use all of the attrs/resolved_attrs, then initializing the eager
+variant once would be best. If you only need a few of the attrs, then
+initializing the lazy variant is better. There’s not really a hard line, it
+depends on the target node, and which attrs you are looking for. If performance
+is key to your BXL script, the best way to determine this is to use the BXL
+profiler.
+
+Regardless, if you use eager or lazy versions of getting attributes, you should
+cache the attrs object:
+
+```python
+def _impl_example(ctx):
+ my_configured_node = ctx.configured_targets(":foo")
+
+ # call once and resue, ideally when you need most/all attrs
+ eager = my_configured_node.attrs_eager()
+
+ # call once and reuse, ideally when you only need a few attrs
+ lazy = my_configured_node.attrs_lazy()
+
+ # call once and reuse, ideally when you need most/all resolved attrs
+ resolved_eager = my_configured_node.resolved_attrs_eager(ctx)
+
+ # call once and reuse, ideally when you only need a few resolved attrs
+ resolved_lazy = my_configured_node.resolved_attrs_lazy(ctx)
+```
+
+## Inspecting a struct
+
+You can use `dir(my_struct)` to inspect a struct. You can also use
+`getattr(my_struct, "my_attr")` to grab individual attributes, which is
+equivalent to `my_struct.my_attr`.
+
+These are available as part of the
+[Starlark language spec](https://github.com/bazelbuild/starlark/blob/master/spec.md#dir).
+
+## Set addition/subtraction on a `target_set`
+
+There are a few BXL actions that return a `target_set` (such as a cquery
+`eval()`). The `target_set` supports set subtraction and addition (you can use
+`-` and `+` directly in Starlark).
+
+## Profiling, Testing, and Debugging a BXL script
+
+You can use `buck2 bxl profiler`, with various measurements, to determine where
+the script is least efficient.
+
+To time individual pieces of the script, you can use BXL’s timestamp methods:
+
+```python
+def _impl_example(_ctx):
+ start = now() # call once and reuse wherever is necessary
+ # do something time intensive here
+ end1 = start.elapsed_millis()
+ # do something else time intensive here
+ end2 = start.elapsed_millis()
+```
+
+BXL does not have a debugger available nor a robust testing framework for
+mocking.
+
+- **Debug** - the main method to debug a BXL script is with print statements
+ (`print()` and `ctx.output.print()`).
+- **Test** - the main method to test a BXL script is to actually invoke it with
+ required inputs then verify the outputs.
+
+## Getting the path of an artifact as a string
+
+The starlark `artifact` type encapsulates source artifacts, declared artifacts,
+and build artifacts. It can be dangerous to access paths and use them in further
+BXL computations. For example, if you are trying to use absolute paths for
+something and end up passing it into a remotely executed action, the absolute
+path may not exist on the remote machine. Or, if you are working with paths and
+expecting the artifact to already have been materialized in further BXL
+computations, that would also result in errors.
+
+However, if you are not making any assumptions about the existence of these
+artifacts, you can use use
+[`get_path_without_materialization()`](../../api/bxl/globals#get_path_without_materialization),
+which accepts source, declared, or build aritfacts. It does _not_ accept ensured
+artifacts (also see
+[What do I need to know about ensured artifacts](./bxl_faq.md#what-do-i-need-to-know-about-ensured-artifacts)).
+
+For getting paths of `cmd_args()` inputs, you can use
+[`get_paths_without_materialization()`](../../api/bxl/globals#get_paths_without_materialization),
+but note this is risky because the inputs could contain tsets, which, when
+expanded, could be very large. Use these methods at your own risk.
diff --git a/_src/developers/bxl_dynamic_output.md b/_src/developers/bxl_dynamic_output.md
new file mode 100644
index 000000000000..979b01c68552
--- /dev/null
+++ b/_src/developers/bxl_dynamic_output.md
@@ -0,0 +1,79 @@
+---
+id: dynamic_output
+title: BXL and Dynamic Outputs
+---
+
+## Dynamic output
+
+When declaring [dynamic outputs](../rule_authors/dynamic_dependencies.md) within
+a BXL script, the dynamic lambda for is created with a `bxl_ctx`, which means
+that you can do things like run analysis or queries to inspect the build graph
+from within the dynamic lambda.
+
+You may declare multiple dynamic outputs within a single BXL script, or declare
+nested dynamic outputs. Dynamic outputs are run asynchronously after the BXL
+evaluation.
+
+### Limitations
+
+- `ctx.output` is not available from a dynamic lambda. This means you can’t
+ ensure artifacts or print cached outputs within a dynamic lambda.
+- Error messages from skipping incompatible targets are only emitted to the
+ console, and not cached in the stderr
+- `build()` is not available from a dynamic lambda
+- `bxl_actions` in a dynamic lambda always inherits the execution platform
+ resolution of the root/parent BXL.
+ - The expected usage of `bxl_actions` from within a dynamic lambda is to
+ instantiate it without any named parameters, but the `exec_deps` and
+ `toolchains` of the execution platform resolution are accessible, and return
+ the same values as the root/parent BXL
+- Profiling is not hooked up to dynamic BXL context
+
+### Silly example
+
+This is a silly example of creating a dynamic output which reads some
+`query_params` input, calls some BXL functions like `uquery`,
+`configured_targets` to get the resolved attributes of a target node, and then
+writes the attributes to an output file.
+
+```python
+def _impl_dynamic_output(ctx):
+ actions = ctx.bxl_actions().actions
+
+ # Declare some input here to read within the lambda
+ query_params = actions.write_json("query_params", {"rule_type": "apple_bundle", "universe": "fbcode//buck2/tests/..."})
+
+ # Dynamic lambda's output artifact
+ resolved_attrs = actions.declare_output("resolved_attrs")
+
+ # Dynamic lambda function to be used in the dynamic_output
+ def my_deferred(ctx, artifacts, outputs):
+
+ # Read the input, then do some BXL things here
+
+ params = artifacts[query_params].read_json()
+ target = ctx.uquery().kind(params["rule_type"], params["universe"])[0]
+ node = ctx.configured_targets(target.label)
+ eager_attrs = node.resolved_attrs_eager(ctx)
+
+ # Dynamic BXL context's `bxl_actions` does not take in named parameters because it inherits the exec platform resolution from the root/parent BXL. If the root BXL's `bxl_actions` were created with exec deps/toolchains, you can access them using `exec_deps` and `toolchains` attributes here
+
+ ctx.bxl_actions().actions.write(outputs[resolved_attrs], str(eager_attrs))
+
+ actions.dynamic_output(
+ dynamic = [query_params],
+ inputs = [],
+ outputs = [
+ resolved_attrs,
+ ],
+ f = my_deferred,
+ )
+
+ ctx.output.print(ctx.output.ensure(resolved_attrs).abs_path())
+
+dynamic_output_example = bxl_main(
+ impl = _impl_dynamic_output,
+ cli_args = {
+ },
+)
+```
diff --git a/_src/developers/bxl_faq.md b/_src/developers/bxl_faq.md
new file mode 100644
index 000000000000..15f1d40bec2a
--- /dev/null
+++ b/_src/developers/bxl_faq.md
@@ -0,0 +1,78 @@
+---
+id: bxl_faqs
+title: FAQs
+---
+
+## When is my BXL script cached?
+
+The entire BXL script is represented as a single node on the DICE graph (Buck2’s
+internal dependency graph). When the script’s input changes, the entire node is
+invalidated and needs to be recomputed. For example, if a BXL function calls
+uquery, then uses the result to do a cquery and then a build, if Buck2 detects
+that any of the recorded calls to uquery, cquery, and build changes, then the
+entire BXL script will be reran. The computations themselves (uquery, cquery,
+and build) will still be incrementally evaluated via DICE, so we are not
+rerunning _every_ computation entirely within the BXL.
+
+When the BXL script creates artifacts and ensures them, those artifacts are
+cached separately in an action outside of the BXL execution. This means that the
+artifacts produced by BXL are cached separately from the BXL script itself, much
+like the computations within a BXL.
+
+During 2023, there is a plan to add finer grain incrementality to make better
+use of DICE’s existing incrementality support.
+
+## What’s the difference between `ctx.output.print()` and `print()`?
+
+- `ctx.output.print()` writes items to stdout by buck2 even when the script is
+ cached. Items written to the output stream are considered to be the results of
+ a BXL script, which will be displayed to stdout by buck2 even when the script
+ is cached.
+- `print()` is offered by Starlark via the stdlib. This prints anything you want
+ but won’t be provided to stdout at the end of a BXL script. These can be used
+ to print to stderr. NOTE: `print()` statements don't show up if the script has
+ been cached.
+
+## What do I need to know about ensured artifacts
+
+An `ensured_artifact` prints out the relative or absolute path via
+`ctx.output.print()`, depending on if called with `abs_path()` or `rel_path`(),
+but will print out `.buckconfig",id:"re-configuration-in-buckconfig",level:2},{value:"RE platform configuration",id:"re-platform-configuration",level:2}],m={toc:u};function c(e){let{components:n,...t}=e;return(0,a.mdx)("wrapper",(0,r.Z)({},m,t,{components:n,mdxType:"MDXLayout"}),(0,a.mdx)("p",null,"Buck2 can use services that expose\n",(0,a.mdx)("a",{parentName:"p",href:"https://github.com/bazelbuild/remote-apis"},"Bazel's remote execution API")," in\norder to run actions remotely."),(0,a.mdx)("p",null,"Buck2 projects have been successfully tested for remote execution against\n",(0,a.mdx)("a",{parentName:"p",href:"https://www.engflow.com/"},"EngFlow"),",\n",(0,a.mdx)("a",{parentName:"p",href:"https://github.com/buildbarn/bb-remote-execution"},"BuildBarn")," and\n",(0,a.mdx)("a",{parentName:"p",href:"https://www.buildbuddy.io"},"BuildBuddy"),". Sample project configurations for those\nproviders are available under\n",(0,a.mdx)("a",{parentName:"p",href:"https://github.com/facebook/buck2/tree/main/examples/remote_execution"},"examples/remote_execution"),"."),(0,a.mdx)("h2",{id:"re-configuration-in-buckconfig"},"RE configuration in ",(0,a.mdx)("inlineCode",{parentName:"h2"},".buckconfig")),(0,a.mdx)("p",null,"Configuration for remote execution can be found under ",(0,a.mdx)("inlineCode",{parentName:"p"},"[buck2_re_client]")," in\n",(0,a.mdx)("inlineCode",{parentName:"p"},".buckconfig"),"."),(0,a.mdx)("p",null,"Keys supported include:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"engine_address")," - address to your RE's engine."),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"action_cache_address")," - address to your action cache endpoint."),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"cas_address")," - address to your content-addressable storage (CAS) endpoint."),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"tls_ca_certs")," - path to a CA certificates bundle. This must be PEM-encoded.\nIf none is set, a default bundle will be used. This path contains environment\nvariables using shell interpolation syntax (i.e. $VAR). They will be\nsubstituted before reading the file."),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"tls_client_cert")," - path to a client certificate (and intermediate chain), as\nwell as its associated private key. This must be PEM-encoded. This path can\ncontain environment variables using shell interpolation syntax (i.e. $VAR).\nThey will be substituted before reading the file."),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"http_headers")," - HTTP headers to inject in all requests to RE. This is a\ncomma-separated list of ",(0,a.mdx)("inlineCode",{parentName:"li"},"Header: Value")," pairs. Minimal validation of those\nheaders is done here. This can contain environment variables using shell\ninterpolation syntax ($VAR). They will be substituted before reading the file."),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"instance_name")," - an instance name to pass on execution, action cache, and CAS\nrequests.")),(0,a.mdx)("p",null,"Buck2 uses ",(0,a.mdx)("inlineCode",{parentName:"p"},"SHA256")," for all its hashing by default. If your RE engine requires\nsomething else, this can be configured in ",(0,a.mdx)("inlineCode",{parentName:"p"},".buckconfig")," as follows:"),(0,a.mdx)("pre",null,(0,a.mdx)("code",{parentName:"pre",className:"language-ini"},"[buck2]\n# Accepts BLAKE3, SHA1, or SHA256\ndigest_algorithms = BLAKE3\n")),(0,a.mdx)("h2",{id:"re-platform-configuration"},"RE platform configuration"),(0,a.mdx)("p",null,"Next, your build will need an\n",(0,a.mdx)("a",{parentName:"p",href:"https://buck2.build/docs/concepts/glossary/#execution-platform"},"execution platform"),"\nthat specifies how and where actions should be executed. For a sample platform\ndefinition that sets up an execution platform to utilize RE, take a look at the\n",(0,a.mdx)("a",{parentName:"p",href:"https://github.com/facebook/buck2/blob/main/examples/remote_execution/engflow/platforms/defs.bzl"},"EngFlow example"),",\n",(0,a.mdx)("a",{parentName:"p",href:"https://github.com/facebook/buck2/blob/main/examples/remote_execution/buildbarn/platforms/defs.bzl"},"BuildBarn example"),",\nor the\n",(0,a.mdx)("a",{parentName:"p",href:"https://github.com/facebook/buck2/blob/main/examples/remote_execution/buildbuddy/platforms/defs.bzl"},"BuildBuddy example"),"."),(0,a.mdx)("p",null,"To enable remote execution, configure the following fields in\n",(0,a.mdx)("a",{parentName:"p",href:"https://buck2.build/docs/api/build/globals/#commandexecutorconfig"},"CommandExecutorConfig"),"\nas follows:"),(0,a.mdx)("ul",null,(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"remote_enabled")," - set to ",(0,a.mdx)("inlineCode",{parentName:"li"},"True"),"."),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"local_enabled")," - set to ",(0,a.mdx)("inlineCode",{parentName:"li"},"True")," if you also want to run actions locally."),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"use_limited_hybrid")," - set to ",(0,a.mdx)("inlineCode",{parentName:"li"},"False")," unless you want to exclusively run\nremotely when possible."),(0,a.mdx)("li",{parentName:"ul"},(0,a.mdx)("inlineCode",{parentName:"li"},"remote_execution_properties")," - other additional properties.",(0,a.mdx)("ul",{parentName:"li"},(0,a.mdx)("li",{parentName:"ul"},"If the RE engine requires a container image, this can be done by setting\n",(0,a.mdx)("inlineCode",{parentName:"li"},"container-image")," to an image URL, as is done in the example above.")))))}c.isMDXComponent=!0}}]);
\ No newline at end of file
diff --git a/assets/js/0c7aced5.696b97dc.js b/assets/js/0c7aced5.696b97dc.js
new file mode 100644
index 000000000000..9ed7011725e6
--- /dev/null
+++ b/assets/js/0c7aced5.696b97dc.js
@@ -0,0 +1 @@
+"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[2247],{3905:(e,t,a)=>{a.r(t),a.d(t,{MDXContext:()=>d,MDXProvider:()=>_,mdx:()=>x,useMDXComponents:()=>p,withMDXComponents:()=>m});var i=a(67294);function n(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function r(){return r=Object.assign||function(e){for(var t=1;tpriv/ directory",id:"with-priv-directory",level:4},{value:"Using OTP applications and mod field",id:"using-otp-applications-and-mod-field",level:4},{value:"Using Yecc and Leex",id:"using-yecc-and-leex",level:4},{value:"erlang_app_includes",id:"erlang_app_includes",level:2},{value:"Parameters",id:"parameters-47",level:4},{value:"erlang_escript",id:"erlang_escript",level:2},{value:"Parameters",id:"parameters-48",level:4},{value:"Details",id:"details-31",level:4},{value:"erlang_otp_binaries",id:"erlang_otp_binaries",level:2},{value:"Parameters",id:"parameters-49",level:4},{value:"Details",id:"details-32",level:4},{value:"erlang_release",id:"erlang_release",level:2},{value:"Parameters",id:"parameters-50",level:4},{value:"Details",id:"details-33",level:4},{value:"erlang_test",id:"erlang_test",level:2},{value:"Parameters",id:"parameters-51",level:4},{value:"Details",id:"details-34",level:4},{value:"export_file",id:"export_file",level:2},{value:"Parameters",id:"parameters-52",level:4},{value:"Details",id:"details-35",level:4},{value:"external_test_runner",id:"external_test_runner",level:2},{value:"Parameters",id:"parameters-53",level:4},{value:"filegroup",id:"filegroup",level:2},{value:"Parameters",id:"parameters-54",level:4},{value:"Details",id:"details-36",level:4},{value:"gen_aidl",id:"gen_aidl",level:2},{value:"Parameters",id:"parameters-55",level:4},{value:"Details",id:"details-37",level:4},{value:"genrule",id:"genrule",level:2},{value:"Parameters",id:"parameters-56",level:4},{value:"Details",id:"details-38",level:4},{value:"git_fetch",id:"git_fetch",level:2},{value:"Parameters",id:"parameters-57",level:4},{value:"Details",id:"details-39",level:4},{value:"go_binary",id:"go_binary",level:2},{value:"Parameters",id:"parameters-58",level:4},{value:"Details",id:"details-40",level:4},{value:"go_exported_library",id:"go_exported_library",level:2},{value:"Parameters",id:"parameters-59",level:4},{value:"Details",id:"details-41",level:4},{value:"go_library",id:"go_library",level:2},{value:"Parameters",id:"parameters-60",level:4},{value:"Details",id:"details-42",level:4},{value:"go_stdlib",id:"go_stdlib",level:2},{value:"Parameters",id:"parameters-61",level:4},{value:"go_test",id:"go_test",level:2},{value:"Parameters",id:"parameters-62",level:4},{value:"Details",id:"details-43",level:4},{value:"go_test_runner",id:"go_test_runner",level:2},{value:"Parameters",id:"parameters-63",level:4},{value:"groovy_library",id:"groovy_library",level:2},{value:"Parameters",id:"parameters-64",level:4},{value:"Details",id:"details-44",level:4},{value:"groovy_test",id:"groovy_test",level:2},{value:"Parameters",id:"parameters-65",level:4},{value:"gwt_binary",id:"gwt_binary",level:2},{value:"Parameters",id:"parameters-66",level:4},{value:"halide_library",id:"halide_library",level:2},{value:"Parameters",id:"parameters-67",level:4},{value:"Details",id:"details-45",level:4},{value:"haskell_binary",id:"haskell_binary",level:2},{value:"Parameters",id:"parameters-68",level:4},{value:"Details",id:"details-46",level:4},{value:"haskell_ghci",id:"haskell_ghci",level:2},{value:"Parameters",id:"parameters-69",level:4},{value:"haskell_haddock",id:"haskell_haddock",level:2},{value:"Parameters",id:"parameters-70",level:4},{value:"haskell_ide",id:"haskell_ide",level:2},{value:"Parameters",id:"parameters-71",level:4},{value:"haskell_library",id:"haskell_library",level:2},{value:"Parameters",id:"parameters-72",level:4},{value:"Details",id:"details-47",level:4},{value:"haskell_prebuilt_library",id:"haskell_prebuilt_library",level:2},{value:"Parameters",id:"parameters-73",level:4},{value:"Details",id:"details-48",level:4},{value:"http_archive",id:"http_archive",level:2},{value:"Parameters",id:"parameters-74",level:4},{value:"Details",id:"details-49",level:4},{value:"http_file",id:"http_file",level:2},{value:"Parameters",id:"parameters-75",level:4},{value:"Details",id:"details-50",level:4},{value:"jar_genrule",id:"jar_genrule",level:2},{value:"Parameters",id:"parameters-76",level:4},{value:"java_annotation_processor",id:"java_annotation_processor",level:2},{value:"Parameters",id:"parameters-77",level:4},{value:"java_binary",id:"java_binary",level:2},{value:"Parameters",id:"parameters-78",level:4},{value:"java_library",id:"java_library",level:2},{value:"Parameters",id:"parameters-79",level:4},{value:"Details",id:"details-51",level:4},{value:"java_plugin",id:"java_plugin",level:2},{value:"Parameters",id:"parameters-80",level:4},{value:"java_test",id:"java_test",level:2},{value:"Parameters",id:"parameters-81",level:4},{value:"java_test_runner",id:"java_test_runner",level:2},{value:"Parameters",id:"parameters-82",level:4},{value:"js_bundle",id:"js_bundle",level:2},{value:"Parameters",id:"parameters-83",level:4},{value:"js_bundle_genrule",id:"js_bundle_genrule",level:2},{value:"Parameters",id:"parameters-84",level:4},{value:"js_library",id:"js_library",level:2},{value:"Parameters",id:"parameters-85",level:4},{value:"julia_binary",id:"julia_binary",level:2},{value:"Parameters",id:"parameters-86",level:4},{value:"julia_jll_library",id:"julia_jll_library",level:2},{value:"Parameters",id:"parameters-87",level:4},{value:"julia_library",id:"julia_library",level:2},{value:"Parameters",id:"parameters-88",level:4},{value:"julia_test",id:"julia_test",level:2},{value:"Parameters",id:"parameters-89",level:4},{value:"keystore",id:"keystore",level:2},{value:"Parameters",id:"parameters-90",level:4},{value:"kotlin_library",id:"kotlin_library",level:2},{value:"Parameters",id:"parameters-91",level:4},{value:"Details",id:"details-52",level:4},{value:"kotlin_test",id:"kotlin_test",level:2},{value:"Parameters",id:"parameters-92",level:4},{value:"legacy_toolchain",id:"legacy_toolchain",level:2},{value:"Parameters",id:"parameters-93",level:4},{value:"llvm_link_bitcode",id:"llvm_link_bitcode",level:2},{value:"Parameters",id:"parameters-94",level:4},{value:"Details",id:"details-53",level:4},{value:"lua_binary",id:"lua_binary",level:2},{value:"Parameters",id:"parameters-95",level:4},{value:"Details",id:"details-54",level:4},{value:"lua_library",id:"lua_library",level:2},{value:"Parameters",id:"parameters-96",level:4},{value:"Details",id:"details-55",level:4},{value:"matlab_program",id:"matlab_program",level:2},{value:"Parameters",id:"parameters-97",level:4},{value:"ndk_library",id:"ndk_library",level:2},{value:"Parameters",id:"parameters-98",level:4},{value:"Details",id:"details-56",level:4},{value:"ndk_toolchain",id:"ndk_toolchain",level:2},{value:"Parameters",id:"parameters-99",level:4},{value:"ocaml_binary",id:"ocaml_binary",level:2},{value:"Parameters",id:"parameters-100",level:4},{value:"Details",id:"details-57",level:4},{value:"ocaml_library",id:"ocaml_library",level:2},{value:"Parameters",id:"parameters-101",level:4},{value:"Details",id:"details-58",level:4},{value:"ocaml_object",id:"ocaml_object",level:2},{value:"Parameters",id:"parameters-102",level:4},{value:"ocaml_shared",id:"ocaml_shared",level:2},{value:"Parameters",id:"parameters-103",level:4},{value:"platform",id:"platform",level:2},{value:"Parameters",id:"parameters-104",level:4},{value:"prebuilt_apple_framework",id:"prebuilt_apple_framework",level:2},{value:"Parameters",id:"parameters-105",level:4},{value:"Details",id:"details-59",level:4},{value:"prebuilt_cxx_library",id:"prebuilt_cxx_library",level:2},{value:"Parameters",id:"parameters-106",level:4},{value:"Details",id:"details-60",level:4},{value:"prebuilt_cxx_library_group",id:"prebuilt_cxx_library_group",level:2},{value:"Parameters",id:"parameters-107",level:4},{value:"Details",id:"details-61",level:4},{value:"prebuilt_dotnet_library",id:"prebuilt_dotnet_library",level:2},{value:"Parameters",id:"parameters-108",level:4},{value:"Details",id:"details-62",level:4},{value:"prebuilt_go_library",id:"prebuilt_go_library",level:2},{value:"Parameters",id:"parameters-109",level:4},{value:"Details",id:"details-63",level:4},{value:"prebuilt_jar",id:"prebuilt_jar",level:2},{value:"Parameters",id:"parameters-110",level:4},{value:"Details",id:"details-64",level:4},{value:"prebuilt_native_library",id:"prebuilt_native_library",level:2},{value:"Parameters",id:"parameters-111",level:4},{value:"Details",id:"details-65",level:4},{value:"prebuilt_ocaml_library",id:"prebuilt_ocaml_library",level:2},{value:"Parameters",id:"parameters-112",level:4},{value:"prebuilt_python_library",id:"prebuilt_python_library",level:2},{value:"Parameters",id:"parameters-113",level:4},{value:"Details",id:"details-66",level:4},{value:"python_binary",id:"python_binary",level:2},{value:"Parameters",id:"parameters-114",level:4},{value:"Details",id:"details-67",level:4},{value:"python_bootstrap_binary",id:"python_bootstrap_binary",level:2},{value:"Parameters",id:"parameters-115",level:4},{value:"python_bootstrap_library",id:"python_bootstrap_library",level:2},{value:"Parameters",id:"parameters-116",level:4},{value:"python_library",id:"python_library",level:2},{value:"Parameters",id:"parameters-117",level:4},{value:"Details",id:"details-68",level:4},{value:"python_needed_coverage_test",id:"python_needed_coverage_test",level:2},{value:"Parameters",id:"parameters-118",level:4},{value:"python_test",id:"python_test",level:2},{value:"Parameters",id:"parameters-119",level:4},{value:"Details",id:"details-69",level:4},{value:"python_test_runner",id:"python_test_runner",level:2},{value:"Parameters",id:"parameters-120",level:4},{value:"remote_file",id:"remote_file",level:2},{value:"Parameters",id:"parameters-121",level:4},{value:"Details",id:"details-70",level:4},{value:"robolectric_test",id:"robolectric_test",level:2},{value:"Parameters",id:"parameters-122",level:4},{value:"rust_binary",id:"rust_binary",level:2},{value:"Parameters",id:"parameters-123",level:4},{value:"Details",id:"details-71",level:4},{value:"rust_library",id:"rust_library",level:2},{value:"Parameters",id:"parameters-124",level:4},{value:"Details",id:"details-72",level:4},{value:"rust_test",id:"rust_test",level:2},{value:"Parameters",id:"parameters-125",level:4},{value:"Details",id:"details-73",level:4},{value:"scala_library",id:"scala_library",level:2},{value:"Parameters",id:"parameters-126",level:4},{value:"scala_test",id:"scala_test",level:2},{value:"Parameters",id:"parameters-127",level:4},{value:"scene_kit_assets",id:"scene_kit_assets",level:2},{value:"Parameters",id:"parameters-128",level:4},{value:"sh_binary",id:"sh_binary",level:2},{value:"Parameters",id:"parameters-129",level:4},{value:"Details",id:"details-74",level:4},{value:"sh_test",id:"sh_test",level:2},{value:"Parameters",id:"parameters-130",level:4},{value:"Details",id:"details-75",level:4},{value:"supermodule_target_graph",id:"supermodule_target_graph",level:2},{value:"Parameters",id:"parameters-131",level:4},{value:"swift_library",id:"swift_library",level:2},{value:"Parameters",id:"parameters-132",level:4},{value:"swift_toolchain",id:"swift_toolchain",level:2},{value:"Parameters",id:"parameters-133",level:4},{value:"test_suite",id:"test_suite",level:2},{value:"Parameters",id:"parameters-134",level:4},{value:"Details",id:"details-76",level:4},{value:"toolchain_alias",id:"toolchain_alias",level:2},{value:"Parameters",id:"parameters-135",level:4},{value:"Details",id:"details-77",level:4},{value:"versioned_alias",id:"versioned_alias",level:2},{value:"Parameters",id:"parameters-136",level:4},{value:"windows_resource",id:"windows_resource",level:2},{value:"Parameters",id:"parameters-137",level:4},{value:"Details",id:"details-78",level:4},{value:"worker_tool",id:"worker_tool",level:2},{value:"Parameters",id:"parameters-138",level:4},{value:"Details",id:"details-79",level:4},{value:"zip_file",id:"zip_file",level:2},{value:"Parameters",id:"parameters-139",level:4},{value:"Details",id:"details-80",level:4}],m={toc:d};function p(e){let{components:t,...a}=e;return(0,n.mdx)("wrapper",(0,i.Z)({},m,a,{components:t,mdxType:"MDXLayout"}),(0,n.mdx)("h1",{id:"rules"},"Rules"),(0,n.mdx)("p",null,"These rules are available as standard in Buck2."),(0,n.mdx)("pre",null,(0,n.mdx)("code",{parentName:"pre",className:"language-python"},"def alias(\n *,\n name: str,\n default_target_platform: None | str = _,\n target_compatible_with: list[str] = _,\n compatible_with: list[str] = _,\n exec_compatible_with: list[str] = _,\n visibility: list[str] = _,\n within_view: list[str] = _,\n metadata: opaque_metadata = _,\n tests: list[str] = _,\n _apple_platforms: dict[str, str] = _,\n actual: str,\n buck2_compatibility: str = _,\n contacts: list[str] = _,\n default_host_platform: None | str = _,\n labels: list[str] = _,\n licenses: list[str] = _\n) -> None\n")),(0,n.mdx)("h4",{id:"parameters"},"Parameters"),(0,n.mdx)("ul",null,(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"name"),": name of the target"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"default_target_platform"),": specifies the default target platform, used when no platforms are specified on the command line"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"target_compatible_with"),": a list of constraints that are required to be satisfied for this target to be compatible with a configuration"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"compatible_with"),": a list of constraints that are required to be satisfied for this target to be compatible with a configuration"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"exec_compatible_with"),": a list of constraints that are required to be satisfied for this target to be compatible with an execution platform"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"visibility"),": a list of visibility patterns restricting what targets can depend on this one"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"within_view"),": a list of visibility patterns restricting what this target can depend on"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"metadata"),": a key-value map of metadata associated with this target"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"tests"),": a list of targets that provide tests for this one")),(0,n.mdx)("hr",null),(0,n.mdx)("h2",{id:"android_aar"},"android","_","aar"),(0,n.mdx)("pre",null,(0,n.mdx)("code",{parentName:"pre",className:"language-python"},"def android_aar(\n *,\n name: str,\n default_target_platform: None | str = _,\n target_compatible_with: list[str] = _,\n compatible_with: list[str] = _,\n exec_compatible_with: list[str] = _,\n visibility: list[str] = _,\n within_view: list[str] = _,\n metadata: opaque_metadata = _,\n tests: list[str] = _,\n _android_toolchain: str = _,\n _apple_platforms: dict[str, str] = _,\n _cxx_toolchain: str = _,\n _is_building_android_binary: bool = _,\n _is_force_single_cpu: bool = _,\n _is_force_single_default_cpu: bool = _,\n _java_toolchain: str = _,\n _wip_java_plugin_arguments: dict[str, list[str]] = _,\n abi_generation_mode: None | str = _,\n annotation_processing_tool: None | str = _,\n annotation_processor_deps: list[str] = _,\n annotation_processor_params: list[str] = _,\n annotation_processors: list[str] = _,\n buck2_compatibility: str = _,\n build_config_values: list[str] = _,\n build_config_values_file: None | str = _,\n compress_asset_libraries: bool = _,\n contacts: list[str] = _,\n cpu_filters: list[str] = _,\n default_host_platform: None | str = _,\n deps: list[str] = _,\n enable_relinker: bool = _,\n excluded_java_deps: list[str] = _,\n extra_arguments: list[str] = _,\n extra_kotlinc_arguments: list[str] = _,\n friend_paths: list[str] = _,\n include_build_config_class: bool = _,\n java_version: None | str = _,\n javac: None | str = _,\n kotlin_compiler_plugins: dict[str, dict[str, str]] = _,\n labels: list[str] = _,\n language: None | str = _,\n licenses: list[str] = _,\n manifest: None | str = _,\n manifest_file: None | str = _,\n manifest_skeleton: str,\n maven_coords: None | str = _,\n min_sdk_version: None | int = _,\n native_library_merge_code_generator: None | str = _,\n native_library_merge_glue: None | str = _,\n native_library_merge_linker_args: None | dict[str, list[str]] = _,\n native_library_merge_localized_symbols: None | list[str] = _,\n native_library_merge_map: None | dict[str, list[str]] = _,\n native_library_merge_sequence: None | list[typing.Any] = _,\n native_library_merge_sequence_blocklist: None | list[str] = _,\n never_mark_as_unused_dependency: None | bool = _,\n on_unused_dependencies: None | str = _,\n package_asset_libraries: bool = _,\n plugins: list[str] = _,\n proguard_config: None | str = _,\n relinker_whitelist: list[str] = _,\n remove_classes: list[str] = _,\n required_for_source_only_abi: bool = _,\n resource_union_package: None | str = _,\n resources: list[str] = _,\n resources_root: None | str = _,\n runtime_deps: list[str] = _,\n source: None | str = _,\n source_abi_verification_mode: None | str = _,\n source_only_abi_deps: list[str] = _,\n srcs: list[str] = _,\n strip_libraries: bool = _,\n target: None | str = _,\n use_jvm_abi_gen: None | bool = _\n) -> None\n")),(0,n.mdx)("p",null,"An ",(0,n.mdx)("inlineCode",{parentName:"p"},"android_aar()")," rule is used to generate an Android AAR."),(0,n.mdx)("h4",{id:"parameters-1"},"Parameters"),(0,n.mdx)("ul",null,(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"name"),": name of the target"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"default_target_platform"),": specifies the default target platform, used when no platforms are specified on the command line"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"target_compatible_with"),": a list of constraints that are required to be satisfied for this target to be compatible with a configuration"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"compatible_with"),": a list of constraints that are required to be satisfied for this target to be compatible with a configuration"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"exec_compatible_with"),": a list of constraints that are required to be satisfied for this target to be compatible with an execution platform"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"visibility"),": a list of visibility patterns restricting what targets can depend on this one"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"within_view"),": a list of visibility patterns restricting what this target can depend on"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"metadata"),": a key-value map of metadata associated with this target"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"tests"),": a list of targets that provide tests for this one"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"build_config_values"),": See the documentation on the values argument for ",(0,n.mdx)("inlineCode",{parentName:"li"},"android\\_build\\_config()"),"."),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"include_build_config_class"),": Whether to include the ",(0,n.mdx)("inlineCode",{parentName:"li"},"BuildConfig")," class files in the final .aar file. Needs to be set to ",(0,n.mdx)("inlineCode",{parentName:"li"},"True")," if any build","_","config","_","values are specified. This is normally only needed if the build tool that is consuming the .aar file does not generate ",(0,n.mdx)("inlineCode",{parentName:"li"},"BuildConfig")," classes. Note: the AAR format does not specify a way to pass defaults that should be injected into the final ",(0,n.mdx)("inlineCode",{parentName:"li"},"BuildConfig")," class, therefore that information might need to be replicated manually in the build that's consuming the .aar file."),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"manifest_skeleton"),": The skeleton manifest file used to generate the final ",(0,n.mdx)("inlineCode",{parentName:"li"},"AndroidManifest.xml")," . May either be a file or a ",(0,n.mdx)("inlineCode",{parentName:"li"},"android\\_manifest()"),"target."),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"remove_classes"),": List of classes to remove from the output aar. It removes classes from the target's own sources, and its dependencies.")),(0,n.mdx)("h4",{id:"details"},"Details"),(0,n.mdx)("p",null,"See the ",(0,n.mdx)("a",{parentName:"p",href:"https://developer.android.com/studio/projects/android-library#aar-contents"},"official Android documentation")," for details about the ",(0,n.mdx)("inlineCode",{parentName:"p"},".aar")," format."),(0,n.mdx)("p",null,"Examples:"),(0,n.mdx)("pre",null,(0,n.mdx)("code",{parentName:"pre"},"\nandroid_resource(\n name = 'res',\n res = 'res',\n assets = 'assets',\n package = 'com.example',\n)\n\nandroid_library(\n name = 'lib',\n srcs = glob(['**/*.java']),\n)\n\nandroid_aar(\n name = 'app',\n manifest_skeleton = 'AndroidManifestSkeleton.xml',\n deps = [\n ':res',\n ':lib',\n ],\n)\n\n")),(0,n.mdx)("hr",null),(0,n.mdx)("h2",{id:"android_app_modularity"},"android","_","app","_","modularity"),(0,n.mdx)("pre",null,(0,n.mdx)("code",{parentName:"pre",className:"language-python"},"def android_app_modularity(\n *,\n name: str,\n default_target_platform: None | str = _,\n target_compatible_with: list[str] = _,\n compatible_with: list[str] = _,\n exec_compatible_with: list[str] = _,\n visibility: list[str] = _,\n within_view: list[str] = _,\n metadata: opaque_metadata = _,\n tests: list[str] = _,\n _android_toolchain: str = _,\n _apple_platforms: dict[str, str] = _,\n _build_only_native_code: bool = _,\n application_module_blacklist: None | list[str] = _,\n application_module_configs: dict[str, list[str]] = _,\n application_module_dependencies: None | dict[str, list[str]] = _,\n buck2_compatibility: str = _,\n contacts: list[str] = _,\n default_host_platform: None | str = _,\n deps: list[str] = _,\n labels: list[str] = _,\n licenses: list[str] = _,\n no_dx: list[str] = _,\n should_include_classes: bool = _,\n should_include_libraries: bool = _\n) -> None\n")),(0,n.mdx)("h4",{id:"parameters-2"},"Parameters"),(0,n.mdx)("ul",null,(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"name"),": name of the target"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"default_target_platform"),": specifies the default target platform, used when no platforms are specified on the command line"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"target_compatible_with"),": a list of constraints that are required to be satisfied for this target to be compatible with a configuration"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"compatible_with"),": a list of constraints that are required to be satisfied for this target to be compatible with a configuration"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"exec_compatible_with"),": a list of constraints that are required to be satisfied for this target to be compatible with an execution platform"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"visibility"),": a list of visibility patterns restricting what targets can depend on this one"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"within_view"),": a list of visibility patterns restricting what this target can depend on"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"metadata"),": a key-value map of metadata associated with this target"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"tests"),": a list of targets that provide tests for this one")),(0,n.mdx)("hr",null),(0,n.mdx)("h2",{id:"android_binary"},"android","_","binary"),(0,n.mdx)("pre",null,(0,n.mdx)("code",{parentName:"pre",className:"language-python"},"def android_binary(\n *,\n name: str,\n default_target_platform: None | str = _,\n target_compatible_with: list[str] = _,\n compatible_with: list[str] = _,\n exec_compatible_with: list[str] = _,\n visibility: list[str] = _,\n within_view: list[str] = _,\n metadata: opaque_metadata = _,\n tests: list[str] = _,\n _android_toolchain: str = _,\n _apple_platforms: dict[str, str] = _,\n _cxx_toolchain: str = _,\n _dex_toolchain: str = _,\n _exec_os_type: str = _,\n _is_building_android_binary: bool = _,\n _is_force_single_cpu: bool = _,\n _is_force_single_default_cpu: bool = _,\n _java_toolchain: str = _,\n aapt2_keep_raw_values: bool = _,\n aapt2_locale_filtering: bool = _,\n aapt2_preferred_density: None | str = _,\n aapt_mode: str = _,\n additional_aapt_params: list[str] = _,\n allow_r_dot_java_in_secondary_dex: bool = _,\n allowed_duplicate_resource_types: list[str] = _,\n android_sdk_proguard_config: None | str = _,\n application_module_blacklist: None | list[str] = _,\n application_module_configs: dict[str, list[str]] = _,\n application_module_dependencies: None | dict[str, list[str]] = _,\n asset_compression_algorithm: None | str = _,\n banned_duplicate_resource_types: list[str] = _,\n buck2_compatibility: str = _,\n build_config_values: list[str] = _,\n build_config_values_file: None | str = _,\n build_string_source_map: bool = _,\n compress_asset_libraries: bool = _,\n constraint_overrides: list[str] = _,\n contacts: list[str] = _,\n cpu_filters: list[str] = _,\n default_host_platform: None | str = _,\n deps: list[str] = _,\n dex_compression: None | str = _,\n dex_group_lib_limit: int = _,\n dex_tool: str = _,\n disable_pre_dex: bool = _,\n duplicate_resource_behavior: str = _,\n duplicate_resource_whitelist: None | str = _,\n enable_relinker: bool = _,\n exopackage_modes: list[str] = _,\n extra_filtered_resources: list[str] = _,\n extra_no_compress_asset_extensions: list[str] = _,\n field_ref_count_buffer_space: int = _,\n ignore_aapt_proguard_config: bool = _,\n includes_vector_drawables: bool = _,\n is_cacheable: bool = _,\n is_voltron_language_pack_enabled: bool = _,\n keystore: str,\n labels: list[str] = _,\n licenses: list[str] = _,\n linear_alloc_hard_limit: int = _,\n locales: list[str] = _,\n manifest: None | str = _,\n manifest_entries: dict[str, typing.Any] = _,\n manifest_skeleton: None | str = _,\n method_ref_count_buffer_space: int = _,\n min_sdk_version: None | int = _,\n minimize_primary_dex_size: bool = _,\n module_manifest_skeleton: None | str = _,\n native_library_merge_code_generator: None | str = _,\n native_library_merge_glue: None | str = _,\n native_library_merge_linker_args: None | dict[str, list[str]] = _,\n native_library_merge_localized_symbols: None | list[str] = _,\n native_library_merge_map: None | dict[str, list[str]] = _,\n native_library_merge_sequence: None | list[typing.Any] = _,\n native_library_merge_sequence_blocklist: None | list[str] = _,\n no_auto_add_overlay_resources: bool = _,\n no_auto_version_resources: bool = _,\n no_dx: list[str] = _,\n no_version_transitions_resources: bool = _,\n optimization_passes: int = _,\n package_asset_libraries: bool = _,\n package_type: str = _,\n packaged_locales: list[str] = _,\n packaging_options: dict[str, list[str]] = _,\n post_filter_resources_cmd: None | str = _,\n preprocess_java_classes_bash: None | str = _,\n preprocess_java_classes_cmd: None | str = _,\n preprocess_java_classes_deps: list[str] = _,\n primary_dex_patterns: list[str] = _,\n proguard_config: None | str = _,\n proguard_jvm_args: list[str] = _,\n relinker_whitelist: list[str] = _,\n resource_compression: str = _,\n resource_filter: list[str] = _,\n resource_stable_ids: None | str = _,\n resource_union_package: None | str = _,\n secondary_dex_weight_limit: None | int = _,\n skip_crunch_pngs: None | bool = _,\n skip_proguard: bool = _,\n strip_libraries: bool = _,\n trim_resource_ids: bool = _,\n use_split_dex: bool = _,\n validation_deps: list[str] = _,\n xz_compression_level: int = _\n) -> None\n")),(0,n.mdx)("h4",{id:"parameters-3"},"Parameters"),(0,n.mdx)("ul",null,(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"name"),": name of the target"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"default_target_platform"),": specifies the default target platform, used when no platforms are specified on the command line"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"target_compatible_with"),": a list of constraints that are required to be satisfied for this target to be compatible with a configuration"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"compatible_with"),": a list of constraints that are required to be satisfied for this target to be compatible with a configuration"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"exec_compatible_with"),": a list of constraints that are required to be satisfied for this target to be compatible with an execution platform"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"visibility"),": a list of visibility patterns restricting what targets can depend on this one"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"within_view"),": a list of visibility patterns restricting what this target can depend on"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"metadata"),": a key-value map of metadata associated with this target"),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("inlineCode",{parentName:"li"},"tests"),": a list of targets that provide tests for this one")),(0,n.mdx)("hr",null),(0,n.mdx)("h2",{id:"android_build_config"},"android","_","build","_","config"),(0,n.mdx)("pre",null,(0,n.mdx)("code",{parentName:"pre",className:"language-python"},"def android_build_config(\n *,\n name: str,\n default_target_platform: None | str = _,\n target_compatible_with: list[str] = _,\n compatible_with: list[str] = _,\n exec_compatible_with: list[str] = _,\n visibility: list[str] = _,\n within_view: list[str] = _,\n metadata: opaque_metadata = _,\n tests: list[str] = _,\n _android_toolchain: str = _,\n _apple_platforms: dict[str, str] = _,\n _build_only_native_code: bool = _,\n _is_building_android_binary: bool = _,\n _java_toolchain: str = _,\n buck2_compatibility: str = _,\n contacts: list[str] = _,\n default_host_platform: None | str = _,\n labels: list[str] = _,\n licenses: list[str] = _,\n package: str = _,\n values: list[str] = _,\n values_file: None | str = _\n) -> None\n")),(0,n.mdx)("p",null,"An ",(0,n.mdx)("inlineCode",{parentName:"p"},"android_build_config()")," rule is used to generate a ",(0,n.mdx)("inlineCode",{parentName:"p"},"BuildConfig")," class with global configuration variables that other ",(0,n.mdx)("inlineCode",{parentName:"p"},"android\\_library()"),"rules can compile against. Currently, the only variable exposed by ",(0,n.mdx)("inlineCode",{parentName:"p"},"BuildConfig")," is a global ",(0,n.mdx)("inlineCode",{parentName:"p"},"boolean")," named ",(0,n.mdx)("inlineCode",{parentName:"p"},"DEBUG"),", much like the ",(0,n.mdx)("inlineCode",{parentName:"p"},"BuildConfig.java")," generated by the official Android build tools based on Gradle."),(0,n.mdx)("h4",{id:"parameters-4"},"Parameters"),(0,n.mdx)("ul",null,(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("p",{parentName:"li"},(0,n.mdx)("inlineCode",{parentName:"p"},"name"),": name of the target")),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("p",{parentName:"li"},(0,n.mdx)("inlineCode",{parentName:"p"},"default_target_platform"),": specifies the default target platform, used when no platforms are specified on the command line")),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("p",{parentName:"li"},(0,n.mdx)("inlineCode",{parentName:"p"},"target_compatible_with"),": a list of constraints that are required to be satisfied for this target to be compatible with a configuration")),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("p",{parentName:"li"},(0,n.mdx)("inlineCode",{parentName:"p"},"compatible_with"),": a list of constraints that are required to be satisfied for this target to be compatible with a configuration")),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("p",{parentName:"li"},(0,n.mdx)("inlineCode",{parentName:"p"},"exec_compatible_with"),": a list of constraints that are required to be satisfied for this target to be compatible with an execution platform")),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("p",{parentName:"li"},(0,n.mdx)("inlineCode",{parentName:"p"},"visibility"),": a list of visibility patterns restricting what targets can depend on this one")),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("p",{parentName:"li"},(0,n.mdx)("inlineCode",{parentName:"p"},"within_view"),": a list of visibility patterns restricting what this target can depend on")),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("p",{parentName:"li"},(0,n.mdx)("inlineCode",{parentName:"p"},"metadata"),": a key-value map of metadata associated with this target")),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("p",{parentName:"li"},(0,n.mdx)("inlineCode",{parentName:"p"},"tests"),": a list of targets that provide tests for this one")),(0,n.mdx)("li",{parentName:"ul"},(0,n.mdx)("p",{parentName:"li"},(0,n.mdx)("inlineCode",{parentName:"p"},"package"),": Name of the Java package to use in the generated ",(0,n.mdx)("inlineCode",{parentName:"p"},"BuildConfig.java")," file. Most developers set this to the application id declared in the manifest via ",(0,n.mdx)("inlineCode",{parentName:"p"},'