})
+
+
+:::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 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..70e3bcc284144
--- /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 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..90438a76590ef
--- /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..9cb33beaff202
--- /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 0000000000000..0b21f9daa2a43
--- /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. BXL is 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 uses filesystem operations to 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 0000000000000..4e0757099abc0
--- /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 0000000000000..b143201df4049
--- /dev/null
+++ b/_src/developers/bxl_basics.md
@@ -0,0 +1,112 @@
+---
+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.Context/#bxl_ctxbuild). The result is a
+[`bxl.BuildResult`](../../api/bxl/bxl.BuildResult), 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.Context/#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
+ [`bxl.UqueryContext`](../../api/bxl/bxl.UqueryContext)
+- `ctx.cquery()` returns a
+ [`bxl.CqueryContext`](../../api/bxl/bxl.CqueryContext)
+- `ctx.aquery()` returns a
+ [`bxl.AqueryContext`](../../api/bxl/bxl.AqueryContext)
+
+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
+[`bxl.UnconfiguredTargetNode`s](../../api/bxl/bxl.UnconfiguredTargetNode) for
+uquery, [`bxl.ConfiguredTargetNode`s](../../api/bxl/bxl.ConfiguredTargetNode)
+for cquery, and [`bxl.ActionQueryNode`s](../../api/bxl/bxl.ActionQueryNode) 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.Context`](../../api/bxl/bxl.Context) (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.OutputStream`](../../api/bxl/bxl.OutputStream)). 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.BuildResult`](../../api/bxl/bxl.BuildResult) (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 0000000000000..96ad13578f66d
--- /dev/null
+++ b/_src/developers/bxl_common_how_tos.md
@@ -0,0 +1,258 @@
+---
+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 target/subtarget without blocking
+
+`ctx.build` is synchronous and should only be used when the result of the build
+is needed inline during the bxl execution. To execute builds without blocking
+the script, retrieve the `DefaultInfo` from the target's providers and use the
+`ctx.output.ensure_multiple` api.
+
+Example:
+
+```python
+ctx.output.ensure_multiple(ctx.analysis(label).providers()[DefaultInfo])
+```
+
+## 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).
+
+## Initializing configured/unconfigured `target_set`
+
+You can use following apis to initialize `target_set`
+
+```python
+def bxl.utarget_set(nodes: None | list[bxl.UnconfiguredTargetNode]) -> bxl.UnconfiguredTargetSet
+```
+
+```python
+def bxl.ctarget_set(nodes: None | list[bxl.ConfiguredTargetNode]) -> bxl.ConfiguredTargetSet
+```
+
+## 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()
+```
+
+- **Debug** - the common way to debug a BXL script is with print statements
+ (`print()`, `pprint()` and `ctx.output.print()`).
+
+Benefits When Compared to Buck1
Benefits for end users
"
buck2 build SOME_TARGET_I_ALREADY_BUILT_BEFOREis basically instantaneous +and is a super delightful experience. 🙂" - End user experience
"Buck2 is largely faster and more memory efficient than buck1, and where I’ve +seen counter-examples, the buck2 team quickly optimizes and fixes that.🙂" - +Software Engineer feedback
For people who use Buck on a daily basis (such as using Buck build as part of +their development inner loop), switching to Buck2 provides the following +benefits:
- Performance - the performance of Buck2 is better in four ways:
- Fast things are fast - in Buck1, simply typing
buck buildwhen there +is nothing to do can be expensive (23 seconds in some benchmarks). In Buck2, +the same build action takes 0.1 seconds. Actions that should be fast are +fast, which enables developers to use Buck more freely, without trying to +work around the build system. - Slow things are faster - when there is real work to do, Buck2 is +significantly closer to the critical path. Benchmarks range from 5%/10s +faster for changing a header file (lots of parallel C++ computations, Buck1 +already nearly at the critical path) to 42%/145s faster (changing a Thrift +file in a large project).
- Users contribute to the shared cache - with Buck1, only trusted CI +builds write to the network cache, while with Buck2 everyone writes to the +cache through sandboxed remote execution. This increases the chance of cache +hits, saving capacity and time.
- CI builds go faster - these numbers vary day by day, but most projects +are 2-4x faster. This means spending less time waiting for CI and saving +some capacity at the same time.
- Fast things are fast - in Buck1, simply typing
- Correctness - in Buck2, rules are hermetic by default. Missing
+dependencies are errors. These restrictions apply to both the user-written
+
BUCKfiles and the language rules.- During the process of migrating to Buck2, a huge number of missing +dependencies have been fixed. However, during the same process, several +Buck1 issues were identified that are not going to be fixed in Buck1 (such +as missing headers, genrules without dependencies, and OCaml rules don’t +track all deps). The end result is that Buck2 gives the right answer more +often, cutting down on user surprises.
- Rule features - the rules in Buck2, especially for less commonly used
+languages (such as Haskell, OCaml, and Rust) support features above and beyond
+those in Buck1.
- Examples: dependencies can be given as arguments to
+
prebuilt_ocaml_library, Haskell enables the use of stub headers from C++, +and Rust has experimental pipelining support.
- Examples: dependencies can be given as arguments to
+
- Actively developed - the Meta build team is putting all its efforts behind +Buck2; it's vastly easier to develop than Buck1. While Buck2 is already ahead +of Buck1 in many important aspects, the difference is only going to grow with +several improvements in the pipeline.
- Support - Meta can provide much better support to those having +difficulties with Buck2 than to those using Buck1.
Benefits for Rule Authors
If you write language-specific rules, then Buck2 is in a different league to +Buck1.
"This is all rather fun! Buck2 rules are so much more hackable than +Buck1." - Software Engineer feedback
There are a number of reasons why Buck2 excels for Rule Authors:
- Faster developer cycle - in Buck1, the time from changing a rule to seeing +the impact is many minutes: you first have to compile Buck1, invalidate the +dependency cache (and so on), and perhaps work between multiple OSs. With +Buck2, it takes seconds, you don’t even need to restart the daemon.
- Simple API - Buck2 rules use a small and documented Starlark API, which is +dependency-correct by construction. In Buck1, the rules must obey a lot of +subtle side conditions with a much larger API.
- Easier deployment - for Buck2, deployment is just checking the rules in, +with an atomic commit changing associated macros (when required). For Buck1, +you have to make the repo work with the old and new rules and wait for a Buck +version bump to ship your changes, perhaps a few days later.
- Low barrier to entry - writing rules in Buck2 is vastly easier than Buck1, +significantly increasing the developer pool. This means that writing rules is +now accessible to language experts, not just Buck experts.
Benefits for Integrators
For those people who integrate Buck2 into larger systems, in addition to many of +the above benefits apply, Buck2 provides the following benefits:
- Faster queries - many integrators make extensive use of
buck uqueryand +cquery. In Buck2, these commands are faster and use less memory. - Profiling - Buck2 already ships with five types of profiling for both +loading and analysis (flame graphs, statement breakdown, heap profiles etc). +With Buck2, these tools are much more easily accessible to people not on the +Build Infra team.
The downside
While there are many benefits, it would be remiss not to include a small list of +temporary issues:
- Stability - Buck2 is under active development, which means the risk of +regression is correspondingly higher. There may be issues, but they will be +fixed as quickly as possible (and lessons learned) through the through Meta's +SEV-review process.
- Corner cases - Buck1 has been battle-tested for nearly a decade, which has +included attention to events such as error messages in unlikely corner cases. +Only time and user feedback will enable Meta to bring Buck2 to the same level. +Please share all such feedback!