Deploying to gh-pages from @ e925605 🚀

facebook · Jun 19, 2024 · b06546e · b06546e
commit b06546e
Show file tree

Hide file tree

Showing 485 changed files with 17,753 additions and 0 deletions.
diff --git a/.nojekyll b/.nojekyll
diff --git a/404.html b/404.html
@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en" dir="ltr" class="plugin-native plugin-id-default">
+<head>
+<meta charset="UTF-8">
+<meta name="generator" content="Docusaurus v2.3.1">
+<title data-rh="true">Page Not Found | Buck2</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:url" content="https://buck2.build/404.html"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docusaurus_tag" content="default"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docsearch:docusaurus_tag" content="default"><meta data-rh="true" property="og:title" content="Page Not Found | Buck2"><link data-rh="true" rel="icon" href="/img/logo.png"><link data-rh="true" rel="canonical" href="https://buck2.build/404.html"><link data-rh="true" rel="alternate" href="https://buck2.build/404.html" hreflang="en"><link data-rh="true" rel="alternate" href="https://buck2.build/404.html" hreflang="x-default"><link rel="preconnect" href="https://www.google-analytics.com">
+<link rel="preconnect" href="https://www.googletagmanager.com">
+<script async src="https://www.googletagmanager.com/gtag/js?id=G-GEGGHE39PE"></script>
+<script>function gtag(){dataLayer.push(arguments)}window.dataLayer=window.dataLayer||[],gtag("js",new Date),gtag("config","G-GEGGHE39PE",{anonymize_ip:!0})</script><link rel="stylesheet" href="/assets/css/styles.96950b1b.css">
+<link rel="preload" href="/assets/js/runtime~main.464ab9e8.js" as="script">
+<link rel="preload" href="/assets/js/main.725d093a.js" as="script">
+</head>
+<body class="navigation-with-keyboard">
+<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"light")}()</script>
+<div style="display: none; text-align: center; background-color: white; color: black;" id="internaldocs-banner"></div><div id="__docusaurus">
+<div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/logo.svg" alt="My Site Logo" class="themedImage_ToTc themedImage--light_HNdA"><img src="/img/logo.svg" alt="My Site Logo" class="themedImage_ToTc themedImage--dark_i4oU"></div><b class="navbar__title text--truncate">Buck2</b></a><a class="navbar__item navbar__link" href="/docs/">Docs</a><a class="navbar__item navbar__link" href="/docs/api/rules/">Rules</a><a class="navbar__item navbar__link" href="/docs/api/">API</a></div><div class="navbar__items navbar__items--right"><a href="https://github.com/facebook/buck2" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type="button" disabled="" title="Switch between dark and light mode (currently light mode)" aria-label="Switch between dark and light mode (currently light mode)" aria-live="polite"><svg viewBox="0 0 24 24" width="24" height="24" class="lightToggleIcon_pyhR"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" class="darkToggleIcon_wfgR"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg></button></div><div class="searchBox_ZlJk"><div class="navbar__search"><span aria-label="expand searchbar" role="button" class="search-icon" tabindex="0"></span><input type="search" id="search_input_react" placeholder="Loading..." aria-label="Search" class="navbar__search-input search-bar" disabled=""></div></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="docusaurus_skipToContent_fallback" class="main-wrapper mainWrapper_z2l0"><main class="container margin-vert--xl"><div class="row"><div class="col col--6 col--offset-3"><h1 class="hero__title">Page Not Found</h1><p>We could not find what you were looking for.</p><p>Please contact the owner of the site that linked you to the original URL and let them know their link is broken.</p></div></div></main></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="col footer__col"><div class="footer__title">Docs</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/docs/">User guide</a></li></ul></div><div class="col footer__col"><div class="footer__title">Community</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://github.com/facebook/buck2/issues" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub issues<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div><div class="col footer__col"><div class="footer__title">More</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://github.com/facebook/buck2" target="_blank" rel="noopener noreferrer" class="footer__link-item">Code<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://opensource.fb.com/legal/terms" target="_blank" rel="noopener noreferrer" class="footer__link-item">Terms of Use<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://opensource.fb.com/legal/privacy" target="_blank" rel="noopener noreferrer" class="footer__link-item">Privacy Policy<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div></div><div class="footer__bottom text--center"><div class="footer__copyright">Copyright © 2024 Meta Platforms, Inc. Built with Docusaurus.</div></div></div></footer></div>
+<script src="/assets/js/runtime~main.464ab9e8.js"></script>
+<script src="/assets/js/main.725d093a.js"></script>
+</body>
+</html>
diff --git a/CNAME b/CNAME
@@ -0,0 +1 @@
+buck2.build
diff --git a/_src/.gitignore b/_src/.gitignore
@@ -0,0 +1,2 @@
+/generated/
+*.generated.md
diff --git a/_src/api.md b/_src/api.md
@@ -0,0 +1,16 @@
+# APIs
+
+A lot of Buck2 is driven by Starlark APIs. While there is a
+[Starlark specification](https://github.com/bazelbuild/starlark/blob/master/spec.md),
+for most purposes it can be considered a subset of Python. There are three main
+places you can write Starlark in Buck2:
+
+- In `BUCK` files, where you can define the rules. The most interesting
+  functions are [the rules themselves](rules), but you will often use the
+  [builtin Starlark functions](starlark/globals) (most of which are the same as
+  in Python), and a few of the [build functions](build/globals) (e.g. `glob`).
+- In rule definitions, where you can use the same Starlark standard functions,
+  but will heavily be using the [build functions](build/globals) (e.g. `rule`
+  and `attrs`).
+- In [BXL](../developers/bxl), where the [context type](bxl/bxl_ctx) is one of
+  the more important ones.
diff --git a/_src/benefits.md b/_src/benefits.md
@@ -0,0 +1,150 @@
+---
+id: benefits
+title: Benefits When Compared to Buck1
+---
+
+<FbInternalOnly>
+
+For reports from real users, see the [Testimonials](testimonials.fb.md), which
+include Workplace posts and their full context.
+
+</FbInternalOnly>
+
+## Benefits for end users
+
+> _"`buck2 build SOME_TARGET_I_ALREADY_BUILT_BEFORE` is basically instantaneous
+> and is a super delightful experience. 🙂"_ - End user experience
+> <FbInternalOnly>
+> ([source](https://fb.prod.workplace.com/groups/buck2users/posts/3030704467185914))</FbInternalOnly>
+
+> _"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<FbInternalOnly>
+> ([source](https://fb.prod.workplace.com/groups/devx.ci.bffs/posts/616830502778501))</FbInternalOnly>
+
+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 build` when 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.
+- **Correctness** - in Buck2, rules are hermetic by default. Missing
+  dependencies are errors. These restrictions apply to both the user-written
+  `BUCK` files 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.
+- **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 <FbInternalOnly>
+> ([source](https://fb.prod.workplace.com/groups/333784157210625/posts/928214407767594))</FbInternalOnly>
+
+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 uquery` and
+  `cquery`. In Buck2, these commands are **faster** and use **less memory**.
+  - For example, on CI target determination (a bunch of targets/queries), Buck2
+    is 25% faster at P50 (moving to 40% faster at P95) with 25% less memory
+    (saving over 20Gb, and crossing below the 64Gb threshold).
+- **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.
+
+<FbInternalOnly>
+
+- **Eden friendly** - Buck2 is tuned for the Eden architecture, performing fewer
+  disk operations with greater parallelism.
+  - For example, the slowdown caused by using Eden for `targets` on `fbandroid`
+    is
+    [reduced from 300s to 80s](https://fb.workplace.com/groups/132499338763090/posts/132580122088345).
+- **Better observability** - Buck2 populates many Scuba tables with information
+  about
+  [loading](https://www.internalfb.com/intern/scuba/query/?dataset=buck2_loads),
+  [analysis](https://www.internalfb.com/intern/scuba/query/?dataset=buck2_analyses),
+  [builds](https://www.internalfb.com/intern/scuba/query/?dataset=buck2_builds)
+  and
+  [errors](https://www.internalfb.com/intern/scuba/query/?dataset=buck2_action_errors),
+  and more. The architecture of Buck2 ensures that all important information can
+  be recorded in a uniform manner, enabling sensible trade-offs to be made about
+  what to store vs for how long.
+
+</FbInternalOnly>
+
+## 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!
+
+<FbInternalOnly>
+
+- **Buck2 Web UI** - there isn’t yet a working Web UI equivalent to the one
+  provided by Buck1. But we’re working on it and hope to share an initial
+  version shortly.
+
+</FbInternalOnly>
diff --git a/_src/bootstrapping.md b/_src/bootstrapping.md
@@ -0,0 +1,32 @@
+---
+id: bootstrapping
+title: Bootstrapping Buck2
+---
+
+# Bootstrapping Buck2
+
+To generate `BUCK` files for `buck2`'s dependencies, we use
+[reindeer](https://github.com/facebookincubator/reindeer).
+
+Note that the resulting binary will be compiled without optimisations or
+[jemalloc](https://github.com/jemalloc/jemalloc), so we recommend using the
+Cargo-produced binary in further development.
+
+First, install `reindeer` with `Cargo`:
+
+```sh
+cargo install --locked --git https://github.com/facebookincubator/reindeer reindeer
+```
+
+Next, run the following to buckify dependencies:
+
+```sh
+cd buck2/
+reindeer --third-party-dir shim/third-party/rust buckify
+```
+
+Build `buck2` with `buck2`:
+
+```sh
+buck2 build //:buck2
+```
diff --git a/_src/concepts/buck_out.md b/_src/concepts/buck_out.md
@@ -0,0 +1,22 @@
+---
+id: buck_out
+title: buck-out
+---
+
+# buck-out
+
+Buck2 stores build artifacts in a directory named `buck-out` in the root of your
+[project](glossary.md#project). You should not make assumptions about where
+Buck2 places your build artifacts within the directory structure beneath
+`buck-out` as these locations depend on Buck2's implementation and could
+potentially change over time. Instead, to obtain the location of the build
+artifact for a particular target, you can use one of the `--show-*-output`
+options with the [`buck2 build`](../../users/commands/build) or
+[`buck2 targets`](../../users/commands/targets) commands, most commonly
+`--show-output`. For the full list of ways to show the output location, you can
+run `buck2 build --help` or `buck2 targets --help`.
+
+```
+buck2 targets --show-output <target>
+buck2 build --show-output <target>
+```