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.
})
+
+## Key Distinctions
+
+### Configured vs Unconfigured
+
+In the targets build graph, Buck2 operates with two main perspectives on build
+targets: unconfigured and configured. You can refer
+[execution model](../../../developers/architecture/buck2/#execution-model) to
+see these two phase in a buck2 build.
+
+**Unconfigured** components are configuration independent representations. Think
+of them as the blueprint of your targets. For example, `//buck2:buck2` is the
+representation of `buck2`'s unconfigured target label.
+
+**Configured** components, on the other hand, include all the platform-specific
+details and other configurations needed for actual building. They have the
+necessary information about how to build it for a specific platform or
+configuration. For example, `//buck2:buck2 (cfg:linux-x86_64-xxxxxx)` is the
+representation of `buck2`'s configured target label.
+
+### Labels vs Nodes
+
+**Labels** are identifiers that uniquely reference targets in your build graph.
+They're like addresses that tell Buck2 which target you're talking about. For
+example, `//buck2:buck2` is an unconfigured label that points to a specific
+target.
+
+**Nodes** contain the actual information about targets. They hold the data about
+what a target is, what it depends on, what attributes it has, etc.
+
+### Target Labels vs Provider Labels
+
+**Target labels** (both configured and unconfigured) identify complete build
+targets. For example, `//buck2:buck2` refers to an entire target.
+
+**Provider labels** (both configured and unconfigured) represents a specific
+part of a target. For example, `//buck2:buck2[llvm_ir]` represents `buck2`
+target's `llvm_ir` sub-target
+
+## Label and Nodes Conversion
+
+This diagram shows how different components transform to each other using api
+
+})
diff --git a/_src/bxl/faq.md b/_src/bxl/faq.md
new file mode 100644
index 0000000000000..02125bc6462a8
--- /dev/null
+++ b/_src/bxl/faq.md
@@ -0,0 +1,78 @@
+---
+id: faq
+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 `})
+
+## Part 0:
+
+In this part, we will use bxl to write a "Hello world" program. We show how to
+define a function that receives arguments from the CLI and how to run it.
+
+First, let's create a file named `hello_world.bxl` and open it.
+
+Then, we define a bxl function which can be called by `buck2 bxl`:
+
+```python
+main = bxl_main(
+ impl = _main,
+ cli_args = {},
+)
+```
+
+`bxl_main` takes 2 arguments:
+
+1. `impl` implementation of this bxl main function
+2. `cli_args` we can define the arguments here
+
+Lets run the bxl script to give it a try. The command is in the format
+`buck2 bxl [file_path_to_bxl_file]:[bxl_main_function_name]`. For this case it
+looks like this:
+
+```
+buck2 bxl hello_world.bxl:main
+```
+
+As expected, we get this error:
+
+```
+Error evaluating module: `root//hello_world.bxl`
+
+Caused by:
+ error: Variable `_main` not found, did you mean `main`?
+ --> hello_world.bxl:2:12
+ |
+ 2 | impl = _main,
+ | ^^^^^
+ |
+```
+
+This is because we haven't defined the implementation function `_main` here.
+Let's do that:
+
+```python
+def _main(ctx: bxl.Context):
+ ctx.output.print("Hello world!")
+
+main = bxl_main(
+ impl = _main,
+ cli_args = {},
+)
+```
+
+Now if we run `buck2 bxl hello_world.bxl:main`, we will see the `Hello world!`
+in the console.
+
+For this, function `_main` must be defined to accept the argument `ctx` with
+type [`bxl.Context`](../../api/bxl/Context/)
+
+We can also use [`cli_args`](../../api/bxl/cli_args/) to pass cli args to bxl.
+These args can be accesed in the main function via
+[`ctx.cli_args`](../../api/bxl/Context/#contextcli_args).
+
+Here is an example
+
+```python
+def _main(ctx: bxl.Context):
+ ctx.output.print("Hello " + ctx.cli_args.project_name + "!")
+
+main = bxl_main(
+ impl = _main,
+ cli_args = {
+ "project-name": cli_args.string(),
+ },
+)
+```
+
+We can call bxl like this:
+
+```shell
+buck2 bxl hello_world.bxl:main -- --project-name buck2
+```
+
+We will see `Hello buck2!` in the console.
+
+## Part 1:
+
+Imagine we're generating index data for a Language Server Protocol (LSP). In our
+example, this index data is available in the build graph and originates from the
+"index" [sub-target](../../concepts/glossary/#subtarget) of each "library" and
+"binary" target. We'll utilize BXL to aggregate all the index data from a given
+target's dependencies into a single dataset.
+
+})
+
+In this part, we will use bxl query and filter to get the targets that we want
+to be used for generating index data. Along the way, we will work with target
+universes and queries to get exactly the targets we need.
+
+Let's describe the problem we want to solve. We already have (per target graph
+above) different types of targets: binaries, libraries, and resources. We only
+want the targets that are of type "binary" or "library", since "resource"
+targets do not contain index data.
+
+First, create a new file called `generate_index.bxl` with this basic script:
+
+```python
+def _main(ctx: bxl.Context):
+ ctx.output.print(ctx.cli_args.target)
+
+main = bxl_main(
+ impl = _main,
+ cli_args = {
+ "target": cli_args.target_label(),
+ },
+)
+```
+
+We use this command to run our script:
+
+```shell
+buck2 bxl generate_index.bxl:main -- --target //:bin
+```
+
+We need to get all the deps of this target, we do that using the
+[target universe](../../concepts/glossary/#target-universe) for this target:
+
+```python
+universe = ctx.target_universe(ctx.cli_args.target)
+```
+
+This will return a [`TargetUniverse`](../../api/bxl/TargetUniverse/) type. Then
+we get the all the targets from target universe:
+
+```python
+all_targets = universe.universe_target_set()
+```
+
+We can print it by `ctx.output.print(pstr(all_targets))`. `pstr` here is used to
+prettify the string representation of an object. We can see all the declared
+targets, which correspond to the ones displayed in the target graph above:
+
+```
+[
+ root//:a (})
+
+:::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/string_parameter_macros.md b/_src/concepts/string_parameter_macros.md
new file mode 100644
index 0000000000000..412d4815add7c
--- /dev/null
+++ b/_src/concepts/string_parameter_macros.md
@@ -0,0 +1,144 @@
+---
+id: string_parameter_macros
+title: String parameter macros
+---
+
+# String parameter macros
+
+Many rule attributes (the ones with type `attrs.arg`) support expanding
+references to other rules using a mechanism called string parameter macros. All
+expanded build rules are automatically added as dependencies.
+
+Note that the paths returned by these macros are _relative_ paths. Using
+relative paths ensures that your builds are _hermetic_, that is, they are
+reproducible across different machine environments.
+
+## `$(location //path/to:target)`
+
+Expands to the location of the output of the specified build rule. This means
+that you can refer to the output without needing to be aware of how Buck is
+storing data on the disk mid-build.
+
+For example:
+
+```starlark
+cxx_test(
+ name = "my_test",
+ srcs = ["main.cpp"],
+ preprocessor_flags = ["-DTEST_DIR=$(location :test_dir)"],
+)
+
+filegroup(
+ name = "test_dir",
+ srcs = [
+ "test_files/foo.json",
+ "test_files/bar.toml",
+ ],
+)
+```
+
+## `$(source relative/path/to/source)`
+
+Expands to the location of the specified source. The difference with using
+`$(location path/to:export_file_target)` is that the path points to the file in
+the source tree, rather than a copy or symlink in `buck-out`.
+
+For example:
+
+```starlark
+cxx_test(
+ name = "my_test",
+ srcs = ["main.cpp"],
+ preprocessor_flags = ["-DMY_SOURCE_FILE=$(source path/to/my_source_file)"],
+)
+```
+
+## `$(exe //path/to:target)`
+
+Expands a build rule that results in an executable to the commands necessary to
+run that executable as part of the build.
+
+For example, a `java_binary()` might expand to a call to
+`java -jar path/to/target.jar`. Files that are executable (perhaps generated by
+a `genrule()`) are also expanded.
+
+If the build rule does not generate an executable output, then an exception is
+thrown and the build breaks.
+
+If the `$(exe my_dependency)` dependency should actually be built with the
+target platform, use `$(exe_target my_dependency)` instead, which will stick to
+the same platform as the target.
+
+## `$(exe_target //path/to:target)`
+
+Identical to `$(exe //path/to:target)`, except that the target is built using
+the target platform, rather than the execution platform.
+
+This is for example useful to get the paths to executables to be run as part of
+tests. For example:
+
+```starlark
+sh_test(
+ name = "my_test",
+ args = [
+ "$(exe_target //path/to:target_to_test)",
+ ],
+ # `my_test.sh` takes a single argument, which is the path to an executable
+ # to test.
+ test = "my_test.sh",
+ visibility = ["//risk/tap_enricher/..."],
+)
+```
+
+## `$(query_targets queryfunction(//path/to:target))`
+
+Runs a query on the given target and replaces the macro with the matching
+targets.
+
+For example:
+
+```starlark
+my_rule(
+ name = "example",
+ # Will be replaced by all dependencies of `some_target`.
+ foo = "$(query_targets deps(:some_target))"
+)
+```
+
+## `$(query_outputs queryfunction(//path/to:target))`
+
+Runs a query on the given target and replaces the macro with the outputs of the
+matching targets.
+
+For example:
+
+```starlark
+my_rule(
+ name = "example",
+ # Will be replaced by the outputs of all dependencies of `some_target`.
+ foo = "$(query_outputs deps(:some_target))"
+)
+```
+
+## `$(query_targets_and_outputs [separator] queryfunction(//path/to:target))`
+
+Runs a query on the given target and replaces the macro with matching targets
+and their outputs, which are separated by an optional `separator` (defaults to a
+space).
+
+For example:
+
+```starlark
+my_rule(
+ name = "example",
+ # Will be replaced by the space-separated dependencies of `some_target`, as
+ # well as their outputs.
+ foo = "$(query_targets_and_outputs deps(:some_target))"
+)
+```
+
+## `$(classpath //path/to:target)`
+
+Expands to the transitive classpath of the specified build rule, provided that
+the rule has a Java classpath. If the rule does not have (or contribute to) a
+classpath, then an exception is thrown and the build breaks.
diff --git a/_src/concepts/target_pattern.md b/_src/concepts/target_pattern.md
new file mode 100644
index 0000000000000..59fa79665b2cb
--- /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 0000000000000..39c01a02d94ff
--- /dev/null
+++ b/_src/concepts/visibility.md
@@ -0,0 +1,110 @@
+---
+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). (Note: `visibility` and
+`within_view` arguments may be defined using
+[package() rules](../../rule_authors/package_files/#package)):
+
+- `visibility` - determines which other targets can depend on a target.
+
+ This allows for controlling the products/features that may consume your code
+ or the clients which your team may choose to support.
+
+- `within_view` - determines which other targets a target can depend on.
+
+ On an individual target, this is very similar to `deps`. If any of the
+ target's `deps` are not `within_view`, the target cannot be built. For this
+ reason, on an individual target, `within_view` is less useful since for each
+ additional `dep`, you must consider updating the within_view entries.
+
+ However, the utility of within_view is expanded when used in conjunction with
+ [package() rules](../../rule_authors/package_files/#package) which allow
+ defining both `visibility` and `within_view` attributes for multiple targets
+ in a scalable manner.
+
+In general, if a target is not listed, then there may be no dependency
+relationships as both attributes act as allowlists. However, there are some
+exceptions:
+
+- _Empty or Unset `within_view` List_: If the `within_view` list is empty or
+ unset, it does not impose any restrictions on which targets the current target
+ can depend on.
+- _Empty or Unset `visibility` List_: If the `visibility` list is empty or
+ unset, then only targets defined in the same
+ [BUCK file](./glossary.md#buck-file) can depend upon the current target.
+- _Special Value: `'PUBLIC'`_: `visibility` can be set to a special value
+ `'PUBLIC'` which makes a build rule visible to all targets. (Example below)
+
+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:
+
+```python
+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:
+
+```python
+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`:
+
+```python
+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:
+
+```python
+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:
+
+```python
+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 0000000000000..0be074ccf367a
--- /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 0000000000000..b82120d3bf1de
--- /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 0000000000000..d89261731dcea
--- /dev/null
+++ b/_src/developers/architecture/buck2_telemetry.md
@@ -0,0 +1,10 @@
+---
+id: buck2_telemetry
+title: Buck2 Telemetry
+---
+
+:::note
+
+🚧 THIS PAGE IS UNDER CONSTRUCTION
+
+:::
diff --git a/_src/developers/options.md b/_src/developers/options.md
new file mode 100644
index 0000000000000..e8eada0f95efb
--- /dev/null
+++ b/_src/developers/options.md
@@ -0,0 +1,10 @@
+# Buck 2 specific options
+
+Buck 2 introduces some options that don't exist in v1 and are accessed in the
+root cell:
+
+- `project.watchman_merge_base`: defines the merge base to use for SCM-aware
+ queries to Watchman. This is read when the daemon starts and cannot be changed
+ later without a restart.
+- `test.v2_test_executor`: defines the program to invoke as the test executor in
+ `buck test`. This is read every time a test command executes.
diff --git a/_src/developers/request_for_comments.md b/_src/developers/request_for_comments.md
new file mode 100644
index 0000000000000..e707bfb292c16
--- /dev/null
+++ b/_src/developers/request_for_comments.md
@@ -0,0 +1,24 @@
+---
+id: request_for_comments
+title: Request for Comments
+---
+
+Following are Request for Comments (RFCs) at specific stages of the lifecycle.
+
+### Drafts
+
+- [@configuration syntax](rfcs/drafts/configuration-at-syntax.md)
+- [bxl actions and Build API](rfcs/drafts/bxl-actions.md)
+- [Digest Kinds](rfcs/drafts/digest-kinds.md)
+- [labels -> metadata attribute](rfcs/attr-metadata.md)
+
+### Accepted
+
+- [configured_alias](rfcs/configured-alias.md)
+- [Buck Extension Language (BXL)](rfcs/bxl.md)
+- [Bxl Support for performing analysis on targets](rfcs/bxl-analysis.md)
+- [Package-local values](rfcs/package-local-values.md)
+
+### Implemented
+
+- [ProviderCollection[]](rfcs/implemented/provider-collection-at.md)
diff --git a/_src/developers/what-ran.md b/_src/developers/what-ran.md
new file mode 100644
index 0000000000000..154fbcbb58ea3
--- /dev/null
+++ b/_src/developers/what-ran.md
@@ -0,0 +1,90 @@
+---
+id: what-ran
+title: Finding Commands That Buck2 Ran
+---
+
+import { FbInternalOnly, OssOnly } from
+'docusaurus-plugin-internaldocs-fb/internal';
+
+Buck2 logs all the commands it runs. So, after you've run a build, you can query
+Buck2 to get access to the exact command it used.
+
+To do so, do your build as normal, then run `buck2 log what-ran`.
+
+## What Ran output format
+
+This will output a table showing all the commands that were executed, and how
+they were executed.
+
+The structure is as follows:
+
+```sh
+REASON .buckconfig",id:"re-configuration-in-buckconfig",level:2},{value:"RE platform configuration",id:"re-platform-configuration",level:2}];function d(e){const n={a:"a",code:"code",h2:"h2",li:"li",p:"p",pre:"pre",ul:"ul",...(0,s.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsxs)(n.p,{children:["Buck2 can use services that expose\n",(0,t.jsx)(n.a,{href:"https://github.com/bazelbuild/remote-apis",children:"Bazel's remote execution API"})," in\norder to run actions remotely."]}),"\n",(0,t.jsxs)(n.p,{children:["Buck2 projects have been successfully tested for remote execution against\n",(0,t.jsx)(n.a,{href:"https://www.engflow.com/",children:"EngFlow"}),",\n",(0,t.jsx)(n.a,{href:"https://github.com/buildbarn/bb-remote-execution",children:"BuildBarn"})," and\n",(0,t.jsx)(n.a,{href:"https://www.buildbuddy.io",children:"BuildBuddy"}),". Sample project configurations for those\nproviders are available under\n",(0,t.jsx)(n.a,{href:"https://github.com/facebook/buck2/tree/main/examples/remote_execution",children:"examples/remote_execution"}),"."]}),"\n",(0,t.jsxs)(n.h2,{id:"re-configuration-in-buckconfig",children:["RE configuration in ",(0,t.jsx)(n.code,{children:".buckconfig"})]}),"\n",(0,t.jsxs)(n.p,{children:["Configuration for remote execution can be found under ",(0,t.jsx)(n.code,{children:"[buck2_re_client]"})," in\n",(0,t.jsx)(n.code,{children:".buckconfig"}),"."]}),"\n",(0,t.jsx)(n.p,{children:"Keys supported include:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"engine_address"})," - address to your RE's engine."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"action_cache_address"})," - address to your action cache endpoint."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"cas_address"})," - address to your content-addressable storage (CAS) endpoint."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"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."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"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."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"http_headers"})," - HTTP headers to inject in all requests to RE. This is a\ncomma-separated list of ",(0,t.jsx)(n.code,{children:"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."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"instance_name"})," - an instance name to pass on execution, action cache, and CAS\nrequests."]}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:["Buck2 uses ",(0,t.jsx)(n.code,{children:"SHA256"})," for all its hashing by default. If your RE engine requires\nsomething else, this can be configured in ",(0,t.jsx)(n.code,{children:".buckconfig"})," as follows:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-ini",children:"[buck2]\n# Accepts BLAKE3, SHA1, or SHA256\ndigest_algorithms = BLAKE3\n"})}),"\n",(0,t.jsx)(n.h2,{id:"re-platform-configuration",children:"RE platform configuration"}),"\n",(0,t.jsxs)(n.p,{children:["Next, your build will need an\n",(0,t.jsx)(n.a,{href:"https://buck2.build/docs/concepts/glossary/#execution-platform",children:"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,t.jsx)(n.a,{href:"https://github.com/facebook/buck2/blob/main/examples/remote_execution/engflow/platforms/defs.bzl",children:"EngFlow example"}),",\n",(0,t.jsx)(n.a,{href:"https://github.com/facebook/buck2/blob/main/examples/remote_execution/buildbarn/platforms/defs.bzl",children:"BuildBarn example"}),",\nor the\n",(0,t.jsx)(n.a,{href:"https://github.com/facebook/buck2/blob/main/examples/remote_execution/buildbuddy/platforms/defs.bzl",children:"BuildBuddy example"}),"."]}),"\n",(0,t.jsxs)(n.p,{children:["To enable remote execution, configure the following fields in\n",(0,t.jsx)(n.a,{href:"https://buck2.build/docs/api/build/globals/#commandexecutorconfig",children:"CommandExecutorConfig"}),"\nas follows:"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"remote_enabled"})," - set to ",(0,t.jsx)(n.code,{children:"True"}),"."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"local_enabled"})," - set to ",(0,t.jsx)(n.code,{children:"True"})," if you also want to run actions locally."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"use_limited_hybrid"})," - set to ",(0,t.jsx)(n.code,{children:"False"})," unless you want to exclusively run\nremotely when possible."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"remote_execution_properties"})," - other additional properties.","\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["If the RE engine requires a container image, this can be done by setting\n",(0,t.jsx)(n.code,{children:"container-image"})," to an image URL, as is done in the example above."]}),"\n"]}),"\n"]}),"\n"]})]})}function u(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(d,{...e})}):d(e)}},28453:(e,n,i)=>{i.d(n,{R:()=>r,x:()=>c});var t=i(96540);const s={},o=t.createContext(s);function r(e){const n=t.useContext(o);return t.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function c(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:r(e.components),t.createElement(o.Provider,{value:n},e.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/0d303d7c.b0946604.js b/assets/js/0d303d7c.b0946604.js
new file mode 100644
index 0000000000000..7a1732b2220dd
--- /dev/null
+++ b/assets/js/0d303d7c.b0946604.js
@@ -0,0 +1 @@
+"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[6365],{17589:(e,t,r)=>{r.r(t),r.d(t,{assets:()=>l,contentTitle:()=>o,default:()=>g,frontMatter:()=>a,metadata:()=>d,toc:()=>c});var n=r(74848),s=r(28453),i=r(28774);const a={},o="TargetUniverse",d={id:"api/bxl/TargetUniverse",title:"TargetUniverse",description:"Target universe in BXL. Used for looking up valid configured targets to use in cquery. This is not needed for uquery.",source:"@site/../docs/api/bxl/TargetUniverse.md",sourceDirName:"api/bxl",slug:"/api/bxl/TargetUniverse",permalink:"/docs/api/bxl/TargetUniverse",draft:!1,unlisted:!1,tags:[],version:"current",frontMatter:{},sidebar:"apiSidebar",previous:{title:"SelectDict",permalink:"/docs/api/bxl/SelectDict"},next:{title:"UnconfiguredTargetNode",permalink:"/docs/api/bxl/UnconfiguredTargetNode"}},l={},c=[{value:"TargetUniverse.lookup",id:"targetuniverselookup",level:2},{value:"TargetUniverse.target_set",id:"targetuniversetarget_set",level:2},{value:"TargetUniverse.universe_target_set",id:"targetuniverseuniverse_target_set",level:2}];function u(e){const t={h1:"h1",h2:"h2",header:"header",hr:"hr",p:"p",...(0,s.R)(),...e.components};return(0,n.jsxs)(n.Fragment,{children:[(0,n.jsx)(t.header,{children:(0,n.jsx)(t.h1,{id:"targetuniverse",children:"TargetUniverse"})}),"\n",(0,n.jsx)(t.p,{children:"Target universe in BXL. Used for looking up valid configured targets to use in cquery. This is not needed for uquery."}),"\n",(0,n.jsx)(t.h2,{id:"targetuniverselookup",children:"TargetUniverse.lookup"}),"\n",(0,n.jsx)("pre",{class:"language-python",children:(0,n.jsxs)("code",{children:["def TargetUniverse.lookup(\ntargets: ",(0,n.jsx)(i.default,{to:"/docs/api/bxl/UnconfiguredTargetNode",children:"bxl.UnconfiguredTargetNode"})," | ",(0,n.jsx)(i.default,{to:"/docs/api/starlark/str",children:"str"})," | ",(0,n.jsx)(i.default,{to:"/docs/api/build/TargetLabel",children:"target_label"})," | ",(0,n.jsx)(i.default,{to:"/docs/api/bxl/UnconfiguredTargetSet",children:"target_set"})," | list[",(0,n.jsx)(i.default,{to:"/docs/api/bxl/UnconfiguredTargetNode",children:"bxl.UnconfiguredTargetNode"})," | ",(0,n.jsx)(i.default,{to:"/docs/api/starlark/str",children:"str"})," | ",(0,n.jsx)(i.default,{to:"/docs/api/build/TargetLabel",children:"target_label"}),"],\n) -> ",(0,n.jsx)(i.default,{to:"/docs/api/bxl/ConfiguredTargetSet",children:"target_set"})]})}),"\n",(0,n.jsx)(t.p,{children:"Looks up valid configured target nodes within the universe. The targets passed in are either string literals, unconfigured target nodes, or unconfigured target labels."}),"\n",(0,n.jsx)(t.hr,{}),"\n",(0,n.jsx)(t.h2,{id:"targetuniversetarget_set",children:"TargetUniverse.target_set"}),"\n",(0,n.jsx)("pre",{class:"language-python",children:(0,n.jsxs)("code",{children:["def TargetUniverse.target_set(\n) -> ",(0,n.jsx)(i.default,{to:"/docs/api/bxl/ConfiguredTargetSet",children:"target_set"})]})}),"\n",(0,n.jsx)(t.p,{children:"The target set of the nodes used to construct the target universe."}),"\n",(0,n.jsx)(t.hr,{}),"\n",(0,n.jsx)(t.h2,{id:"targetuniverseuniverse_target_set",children:"TargetUniverse.universe_target_set"}),"\n",(0,n.jsx)("pre",{class:"language-python",children:(0,n.jsxs)("code",{children:["def TargetUniverse.universe_target_set(\n) -> ",(0,n.jsx)(i.default,{to:"/docs/api/bxl/ConfiguredTargetSet",children:"target_set"})]})}),"\n",(0,n.jsx)(t.p,{children:"The target set of the entire target universe."})]})}function g(e={}){const{wrapper:t}={...(0,s.R)(),...e.components};return t?(0,n.jsx)(t,{...e,children:(0,n.jsx)(u,{...e})}):u(e)}},28453:(e,t,r)=>{r.d(t,{R:()=>a,x:()=>o});var n=r(96540);const s={},i=n.createContext(s);function a(e){const t=n.useContext(i);return n.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function o(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:a(e.components),n.createElement(i.Provider,{value:t},e.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/0f079156.9b6eb93e.js b/assets/js/0f079156.9b6eb93e.js
new file mode 100644
index 0000000000000..309b4ff283371
--- /dev/null
+++ b/assets/js/0f079156.9b6eb93e.js
@@ -0,0 +1 @@
+"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[9713],{6619:(t,e,n)=>{n.r(e),n.d(e,{assets:()=>f,contentTitle:()=>c,default:()=>u,frontMatter:()=>o,metadata:()=>a,toc:()=>i});var s=n(74848),r=n(28453);const o={},c="RFC: TestInfo v2",a={id:"rfcs/drafts/test-info-v2",title:"RFC: TestInfo v2",description:"A stub RFC for TestInfo v2 to track lessons learned about TestInfo v1. The stack",source:"@site/../docs/rfcs/drafts/test-info-v2.md",sourceDirName:"rfcs/drafts",slug:"/rfcs/drafts/test-info-v2",permalink:"/docs/rfcs/drafts/test-info-v2",draft:!1,unlisted:!1,tags:[],version:"current",frontMatter:{}},f={},i=[];function d(t){const e={a:"a",h1:"h1",header:"header",p:"p",...(0,r.R)(),...t.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(e.header,{children:(0,s.jsx)(e.h1,{id:"rfc-testinfo-v2",children:"RFC: TestInfo v2"})}),"\n",(0,s.jsxs)(e.p,{children:["A stub RFC for TestInfo v2 to track lessons learned about TestInfo v1. The stack\nstarting"," ",(0,s.jsx)(e.a,{href:"https://internalfb.com/D36339960",children:"D36339960"})," ","contains the original code for the TestInfo and templated\ntest API experiment."]})]})}function u(t={}){const{wrapper:e}={...(0,r.R)(),...t.components};return e?(0,s.jsx)(e,{...t,children:(0,s.jsx)(d,{...t})}):d(t)}},28453:(t,e,n)=>{n.d(e,{R:()=>c,x:()=>a});var s=n(96540);const r={},o=s.createContext(r);function c(t){const e=s.useContext(o);return s.useMemo((function(){return"function"==typeof t?t(e):{...e,...t}}),[e,t])}function a(t){let e;return e=t.disableParentContext?"function"==typeof t.components?t.components(r):t.components||r:c(t.components),s.createElement(o.Provider,{value:e},t.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/0fa06060.7d265d4c.js b/assets/js/0fa06060.7d265d4c.js
new file mode 100644
index 0000000000000..2afc8715453da
--- /dev/null
+++ b/assets/js/0fa06060.7d265d4c.js
@@ -0,0 +1 @@
+"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[1502],{75768:(e,i,n)=>{n.r(i),n.d(i,{assets:()=>d,contentTitle:()=>t,default:()=>u,frontMatter:()=>l,metadata:()=>a,toc:()=>c});var s=n(74848),r=n(28453);const l={id:"build_rule",title:"Build Rule"},t="Build Rule",a={id:"concepts/build_rule",title:"Build Rule",description:"A build rule is a procedure for producing output files from a set of input",source:"@site/../docs/concepts/build_rule.md",sourceDirName:"concepts",slug:"/concepts/build_rule",permalink:"/docs/concepts/build_rule",draft:!1,unlisted:!1,tags:[],version:"current",frontMatter:{id:"build_rule",title:"Build Rule"},sidebar:"main",previous:{title:"Concept Map",permalink:"/docs/concepts/concept_map"},next:{title:"Build File",permalink:"/docs/concepts/build_file"}},d={},c=[{value:"Buck2's collection of build rules",id:"buck2s-collection-of-build-rules",level:2},{value:"Source files as inputs to build rules",id:"source-files-as-inputs-to-build-rules",level:2},{value:"Package boundaries and access to source files",id:"package-boundaries-and-access-to-source-files",level:3},{value:"Symlinks: Use with caution if at all",id:"symlinks-use-with-caution-if-at-all",level:5},{value:"Dependencies: Output from one rule as input to another rule",id:"dependencies-output-from-one-rule-as-input-to-another-rule",level:2},{value:"Required dependencies are always built first",id:"required-dependencies-are-always-built-first",level:3},{value:"Visibility",id:"visibility",level:3},{value:"Dependencies define a graph",id:"dependencies-define-a-graph",level:3},{value:"How to handle special cases: genrules and macros",id:"how-to-handle-special-cases-genrules-and-macros",level:2},{value:"Multiple output files with genrules",id:"multiple-output-files-with-genrules",level:3},{value:"Macros",id:"macros",level:3},{value:"String parameter macros",id:"string-parameter-macros",level:2}];function o(e){const i={a:"a",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",h5:"h5",header:"header",li:"li",p:"p",strong:"strong",ul:"ul",...(0,r.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(i.header,{children:(0,s.jsx)(i.h1,{id:"build-rule",children:"Build Rule"})}),"\n",(0,s.jsxs)(i.p,{children:["A ",(0,s.jsx)(i.em,{children:"build rule"})," is a procedure for producing output files from a set of input\nfiles in the context of a specified build configuration. Build rules are\nspecified in ",(0,s.jsx)(i.a,{href:"/docs/concepts/build_file",children:"build file"}),"s\u2014typically named BUCK. ",(0,s.jsx)(i.strong,{children:"Note:"})," A\nbuild rule must explicitly specify, in its arguments, all of its required inputs\nin order for Buck2 to be able to build the rule's output in a way that is\ndeterministic and reproducible."]}),"\n",(0,s.jsx)(i.h2,{id:"buck2s-collection-of-build-rules",children:"Buck2's collection of build rules"}),"\n",(0,s.jsxs)(i.p,{children:["Buck2 comes with a collection of built-in build rules for many common build\nprocedures. For example, compiling Java code against the Android SDK is a common\nprocedure, so Buck2 provides the build rule\n",(0,s.jsx)(i.a,{href:"../../prelude/globals#android_library",children:(0,s.jsx)(i.code,{children:"android_library"})})," to do that.\nSimilarly, the final product of most Android development is an APK, so you can\nuse the build rule ",(0,s.jsx)(i.a,{href:"../../prelude/globals#android_binary",children:(0,s.jsx)(i.code,{children:"android_binary"})})," to\ncreate an APK."]}),"\n",(0,s.jsx)(i.h2,{id:"source-files-as-inputs-to-build-rules",children:"Source files as inputs to build rules"}),"\n",(0,s.jsxs)(i.p,{children:["Most build rules specify source files as inputs. For example, a\n",(0,s.jsx)(i.a,{href:"../../prelude/globals#cxx_library",children:(0,s.jsx)(i.code,{children:"cxx_library"})})," rule would specify ",(0,s.jsx)(i.code,{children:".cpp"}),"\nfiles as inputs. To support specifying these files, a ",(0,s.jsx)(i.code,{children:"cxx_library"})," rule\nprovides the ",(0,s.jsx)(i.code,{children:"srcs"})," argument. Some languages, such as C++, use header files as\nwell. To specify these, ",(0,s.jsx)(i.code,{children:"cxx_library"})," provides a ",(0,s.jsx)(i.code,{children:"headers"})," argument. In addition\nto ",(0,s.jsx)(i.code,{children:"srcs"})," and ",(0,s.jsx)(i.code,{children:"headers"}),", some rules provide variants of these arguments, such as\n",(0,s.jsx)(i.code,{children:"platform_srcs"})," and ",(0,s.jsx)(i.code,{children:"platform_headers"}),". These arguments support groups of source\nfiles that should be used as inputs only when building for specific platforms."]}),"\n",(0,s.jsx)(i.h3,{id:"package-boundaries-and-access-to-source-files",children:"Package boundaries and access to source files"}),"\n",(0,s.jsxs)(i.p,{children:["In Buck2, a BUCK file defines a ",(0,s.jsx)(i.em,{children:"package"}),", which corresponds ",(0,s.jsx)(i.em,{children:"roughly"})," to the\ndirectory that contains the BUCK file and those subdirectories that do not\nthemselves contain BUCK files. (To learn more, see the\n",(0,s.jsx)(i.a,{href:"/docs/concepts/key_concepts",children:"Key Concepts"})," topic.) A rule in a BUCK file cannot specify a\nsource file as an input unless that source file is in that BUCK file's package.\nAn exception to this restriction exists for header files, but only if a rule in\nthe package that contains the header file ",(0,s.jsx)(i.em,{children:"exports"})," that header file using the\n",(0,s.jsx)(i.code,{children:"exported_headers"})," argument. For more details, see the description for\n",(0,s.jsx)(i.code,{children:"exported_headers"})," in, for example, the\n",(0,s.jsx)(i.a,{href:"../../prelude/globals#cxx_library",children:(0,s.jsx)(i.code,{children:"cxx_library"})})," topic. More commonly though,\nthe package for a BUCK file contains all the source files required for the rules\ndefined in that BUCK file. Functionality in source files from other packages is\nmade available through the artifacts produced by the rules in the BUCK files for\nthose packages. For example, a ",(0,s.jsx)(i.a,{href:"../../prelude/globals/#cxx_binary",children:(0,s.jsx)(i.code,{children:"cxx_binary"})}),"\nmight use the functionality in a ",(0,s.jsx)(i.code,{children:"cxx_library"})," that is defined in another\npackage. To access that functionality, the ",(0,s.jsx)(i.code,{children:"cxx_binary"})," would take that\n",(0,s.jsx)(i.code,{children:"cxx_library"})," as a ",(0,s.jsx)(i.em,{children:"dependency"}),"."]}),"\n",(0,s.jsx)(i.h5,{id:"symlinks-use-with-caution-if-at-all",children:"Symlinks: Use with caution if at all"}),"\n",(0,s.jsxs)(i.p,{children:["We recommend that you do ",(0,s.jsx)(i.em,{children:"not"})," use symlinks\u2014either absolute or relative\u2014to\nspecify input files to build rules. Although using symlinks in this context does\nsometimes work, it can lead to unexpected behavior and errors."]}),"\n",(0,s.jsx)(i.h2,{id:"dependencies-output-from-one-rule-as-input-to-another-rule",children:"Dependencies: Output from one rule as input to another rule"}),"\n",(0,s.jsxs)(i.p,{children:["A build rule can use the output from another build rule as one of its inputs by\nspecifying that rule as a ",(0,s.jsx)(i.em,{children:"dependency"}),". Typically, a build rule specifies its\ndependencies as a list of ",(0,s.jsx)(i.a,{href:"/docs/concepts/build_target",children:"build target"}),"s in its ",(0,s.jsx)(i.code,{children:"deps"}),"\nargument. However, the rule can also specify dependencies\u2014as build targets\u2014in\nother arguments, such as ",(0,s.jsx)(i.code,{children:"srcs"}),". ",(0,s.jsx)(i.strong,{children:"Example:"})," The output of a\n",(0,s.jsx)(i.a,{href:"../../prelude/globals/#java_library",children:(0,s.jsx)(i.code,{children:"java_library"})})," rule is a JAR file. If a\n",(0,s.jsx)(i.code,{children:"java_library"})," rule specifies another ",(0,s.jsx)(i.code,{children:"java_library"})," rule as a dependency, the\nJAR file produced by the specified rule is added to the classpath for the\n",(0,s.jsx)(i.code,{children:"java_library"})," that depends on it. ",(0,s.jsx)(i.strong,{children:"Example:"})," If a\n",(0,s.jsx)(i.a,{href:"../../prelude/globals/#java_binary",children:(0,s.jsx)(i.code,{children:"java_binary"})})," rule specifies a\n",(0,s.jsx)(i.code,{children:"java_library"})," rule as a dependency, the JAR file for the specified\n",(0,s.jsx)(i.code,{children:"java_library"})," is available on the classpath for the ",(0,s.jsx)(i.code,{children:"java_binary"}),". In addition,\nin the case of ",(0,s.jsx)(i.code,{children:"java_binary"}),", the JAR files for any dependencies of the\n",(0,s.jsx)(i.code,{children:"java_library"})," rule ",(0,s.jsx)(i.em,{children:"are also"})," made available to the ",(0,s.jsx)(i.code,{children:"java_binary"})," rule\u2014and if\nthose dependencies have dependencies of their own, they are added as well. This\nexhaustive cascade of dependencies is referred to as the rule's ",(0,s.jsx)(i.em,{children:"transitive\nclosure"}),"."]}),"\n",(0,s.jsx)(i.h3,{id:"required-dependencies-are-always-built-first",children:"Required dependencies are always built first"}),"\n",(0,s.jsxs)(i.p,{children:["Buck2 guarantees that any dependencies that a rule lists that are required in\norder to build that rule are built successfully ",(0,s.jsx)(i.em,{children:"before"})," Buck2 builds the rule\nitself. Note though that there can be special cases\u2014such as\n",(0,s.jsx)(i.a,{href:"../../prelude/globals/#apple_bundle",children:(0,s.jsx)(i.code,{children:"apple_bundle"})}),"\u2014where a rule's listed\ndependencies do not actually need to be built before the rule."]}),"\n",(0,s.jsx)(i.h3,{id:"visibility",children:"Visibility"}),"\n",(0,s.jsxs)(i.p,{children:["In order for a build rule to take a dependency on another build rule, the build\nrule on which the dependency is taken must be ",(0,s.jsx)(i.em,{children:"visible"})," to the build rule taking\nthe dependency. A build rule's ",(0,s.jsx)(i.code,{children:"visibility"})," argument is a list of\n",(0,s.jsx)(i.a,{href:"/docs/concepts/target_pattern",children:"build target pattern"}),"s that specify the rules that can take\nthat rule as a dependency. For more information about the concept of visibility\nin Buck2, see the ",(0,s.jsx)(i.a,{href:"/docs/concepts/visibility",children:"Visibility"})," topic."]}),"\n",(0,s.jsx)(i.h3,{id:"dependencies-define-a-graph",children:"Dependencies define a graph"}),"\n",(0,s.jsx)(i.p,{children:"Build rules and their dependencies define a directed acyclic graph (DAG). Buck2\nrequires this graph to be acyclic to make it possible to build independent\nsubgraphs in parallel."}),"\n",(0,s.jsx)(i.h2,{id:"how-to-handle-special-cases-genrules-and-macros",children:"How to handle special cases: genrules and macros"}),"\n",(0,s.jsxs)(i.p,{children:['Although Buck2 provides a rich set of built-in build rules for developers, it is\nnot able to address all possible needs. As an "escape hatch," Buck2 provides a\ncategory of generic build rules called ',(0,s.jsx)(i.em,{children:"genrules"}),". With genrules, you can\nperform arbitrary operations using shell scripts. The genrules supported by\nBuck2 are:"]}),"\n",(0,s.jsxs)(i.ul,{children:["\n",(0,s.jsx)(i.li,{children:(0,s.jsx)(i.a,{href:"../../prelude/globals/#genrule",children:(0,s.jsx)(i.code,{children:"genrule"})})}),"\n",(0,s.jsx)(i.li,{children:(0,s.jsx)(i.a,{href:"../../prelude/globals/#apk_genrule",children:(0,s.jsx)(i.code,{children:"apk_genrule"})})}),"\n",(0,s.jsx)(i.li,{children:(0,s.jsx)(i.a,{href:"../../prelude/globals/#cxx_genrule",children:(0,s.jsx)(i.code,{children:"cxx_genrule"})})}),"\n"]}),"\n",(0,s.jsx)(i.h3,{id:"multiple-output-files-with-genrules",children:"Multiple output files with genrules"}),"\n",(0,s.jsxs)(i.p,{children:["In most cases, a build rule produces exactly one output file. However, with\ngenrules, you can specify an output ",(0,s.jsx)(i.em,{children:"directory"})," and write arbitrary files to\nthat directory."]}),"\n",(0,s.jsx)(i.h3,{id:"macros",children:"Macros"}),"\n",(0,s.jsx)(i.p,{children:"Finally, note that you can define functions that generate build rules. In\ngeneral, this should not be something that you need to do, but taking advantage\nof this option might help you add needed functionality to Buck2's without\nediting its source code."}),"\n",(0,s.jsx)(i.h2,{id:"string-parameter-macros",children:"String parameter macros"}),"\n",(0,s.jsxs)(i.p,{children:["It is also possible to expand references to other rules within the ",(0,s.jsx)(i.code,{children:"cmd"}),", using\nthe builtin ",(0,s.jsx)(i.a,{href:"/docs/concepts/string_parameter_macros",children:(0,s.jsx)(i.code,{children:"string parameter macros"})}),". All build\nrules expanded in the command are automatically considered to be dependencies of\nthe ",(0,s.jsx)(i.code,{children:"genrule()"}),"."]})]})}function u(e={}){const{wrapper:i}={...(0,r.R)(),...e.components};return i?(0,s.jsx)(i,{...e,children:(0,s.jsx)(o,{...e})}):o(e)}},28453:(e,i,n)=>{n.d(i,{R:()=>t,x:()=>a});var s=n(96540);const r={},l=s.createContext(r);function t(e){const i=s.useContext(l);return s.useMemo((function(){return"function"==typeof e?e(i):{...i,...e}}),[i,e])}function a(e){let i;return i=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:t(e.components),s.createElement(l.Provider,{value:i},e.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/104.af22fbcf.js b/assets/js/104.af22fbcf.js
new file mode 100644
index 0000000000000..a6bf05c481197
--- /dev/null
+++ b/assets/js/104.af22fbcf.js
@@ -0,0 +1,14887 @@
+exports.id = 104;
+exports.ids = [104];
+exports.modules = {
+
+/***/ 62954:
+/***/ ((module) => {
+
+(function(f){if(true){module.exports=f()}else { var g; }})(function(){var define,module,exports;return (function(){function r(e,n,t){function o(i,f){if(!n[i]){if(!e[i]){var c=undefined;if(!f&&c)return require(i,!0);if(u)return u(i,!0);var a=new Error("Cannot find module '"+i+"'");throw a.code="MODULE_NOT_FOUND",a}var p=n[i]={exports:{}};e[i][0].call(p.exports,function(r){var n=e[i][1][r];return o(n||r)},p,p.exports,r,e,n,t)}return n[i].exports}for(var u=undefined,i=0;i