Split into multiple examples, one for hybrid Cargo + Buck projects

.github/workflows/build-and-test.yml

@@ -20,15 +20,36 @@ jobs:
       - run: cargo build --locked
       - run: cargo test
       - uses: dtolnay/install-buck2@latest
-      - name: Build example project (Ubuntu, macOS)
+      - name: Build example projects (Ubuntu, macOS)
         run: |-
-          cd example
-          reindeer --third-party-dir third-party buckify
+          pushd examples/01-intro
+          reindeer buckify
           buck2 run "//project:test"
+          popd
+
+          pushd examples/02-hybrid
+          reindeer buckify
+          buck2 run "//project:test"
+          cargo run -p project
+          popd
+
+          pushd examples/03-complex-fixups
+          reindeer buckify
+          buck2 run "//project:test"
+          popd
         if: matrix.os == 'ubuntu' || matrix.os == 'macos'
-      - name: Build example project (Windows)
+      - name: Build example projects (Windows)
         run: |-
-          cd example
-          & reindeer --third-party-dir third-party buckify
+          cd examples/01-intro
+          & reindeer buckify
+          & buck2 run "//project:test"
+
+          cd examples/02-hybrid
+          & reindeer buckify
+          & buck2 run "//project:test"
+          & cargo run -p project
+
+          cd examples/03-complex-fixups
+          & reindeer buckify
           & buck2 run "//project:test"
         if: matrix.os == 'windows'

docs/MANUAL.md

@@ -30,16 +30,19 @@ environment matches this.)
 
 ## An Example
 
-See the [example directory](../example/README.md) as a starting point. This has:
+See the [first example directory](../examples/01-intro/) as a starting point. 
+This has:
 
 - Your first-party code in "project" (though of course it can be anywhere and
   everywhere), and
-- A [third-party](../example/third-party) directory which is managed by Reindeer
-- A [`setup.sh`](../example/setup.sh) script to get you bootstrapped
+- A [third-party](../examples/01-intro/third-party) directory which is managed 
+  by Reindeer
+- A [`setup.sh`](../examples/01-intro/setup.sh) script to get you bootstrapped
 
 Running `setup.sh` will build Reindeer (using Cargo) and then use it to vendor
 the small number of third-party dependencies defined in
-[`third-party/Cargo.toml`](../third-party/Cargo.toml) and generate build rules
+[`third-party/Cargo.toml`](../examples/01-intro/third-party/Cargo.toml) and 
+generate build rules
 for them in `third-party/BUCK`.
 
 I recommend using this as a starting template for your own project, at least

examples/01-intro/.buckconfig

@@ -0,0 +1,24 @@
+[cells]
+  root = .
+  prelude = prelude
+  toolchains = toolchains
+  none = none
+
+[cell_aliases]
+  config = prelude
+  ovr_config = prelude
+  fbcode = none
+  fbsource = none
+  fbcode_macros = none
+  buck = none
+
+# Uses a copy of the prelude bundled with the buck2 binary. You can alternatively delete this
+# section and vendor a copy of the prelude to the `prelude` directory of your project.
+[external_cells]
+  prelude = bundled
+
+[parser]
+  target_platform_detector_spec = target:root//...->prelude//platforms:default
+
+[build]
+  execution_platforms = prelude//platforms:default

examples/01-intro/.gitignore

@@ -0,0 +1,2 @@
+/buck-out
+/target

examples/01-intro/BUCK

@@ -0,0 +1,7 @@
+# A list of available rules and their signatures can be found here: https://buck2.build/docs/prelude/globals/
+
+genrule(
+    name = "hello_world",
+    out = "out.txt",
+    cmd = "echo BUILT BY BUCK2> $OUT",
+)

example/README.md → examples/01-intro/README.md

@@ -8,42 +8,42 @@ generate a BUCK file of build rules for them.
 This will require a Rust installation (stable, but probably fairly recent), and
 Buck to actually make use of the generated files.
 
-You can learn more about Buck at [buck.build](https://buck.build). The
-[getting started](https://buck.build/setup/getting_started.html) page should
+You can learn more about Buck at [buck.build](https://buck2.build). The
+[getting started](https://buck2.build/docs/about/getting_started/) page should
 help with getting it installed.
 
 ## Buck and its Configuration
 
 The `.buckconfig` file both configures Buck and tells it where the top of the
-"cell" is (current working tree). This only contains some very minimal Rust
-configuration; most notable is overriding the default to Rust 2018.
-
-(`.buck-java11` won't generally be needed.)
+"cell" is (current working tree).
 
 ## Reindeer configuration
 
 The files and directories Reindeer cares about are under `third-party/`:
 
-- reindeer.toml - Reindeer's configuration. The directory containing this file
+- `reindeer.toml` - Reindeer's configuration. The directory containing this 
+  file
   is also the base for any relative paths mentioned in the file.
-- Cargo.toml - You edit this to specify which packages you want to import, along
+- `Cargo.toml` - You edit this to specify which packages you want to import, 
+  along
   with other settings like features, patches and so on, using the full syntax
   Cargo allows
-- Cargo.lock - The resolved dependencies
-- BUCK - The generated Buck build rules (once generated)
-- .gitignore - This is used to ignore various inconvenient files in vendored
+- `Cargo.lock` - The resolved dependencies
+- `BUCK` - The generated Buck build rules (once generated)
+- `.gitignore` - This is used to ignore various inconvenient files in vendored
   code. Reindeer itself will look at this to edit them out of the vendored
   checksum.json files so that Cargo doesn't get upset.
 
 In addition to these files, there are a few significant directories:
 
-- vendor/ - where all the vendored code goes
-- fixups/ - fixups tell Reindeer how to handle packages with build scripts and
+- `vendor/` - where all the vendored code goes
+- `fixups/` - fixups tell Reindeer how to handle packages with build scripts 
+  and
   other special cases; most packages won't need anything here
-- macros/ - Buck macros which map from the rules Reindeer generates to the
+- `macros/` - Buck macros which map from the rules Reindeer generates to the
   actual build environment. This directory is not hard-coded and could be
   anywhere. The macros included here are quite minimal.
-- top/ - Cargo needs a dummy package for the Cargo.toml (it doesn't allow a
+- `top/` - Cargo needs a dummy package for the Cargo.toml (it doesn't allow a
   package which is _all_ dependencies)
 
 ## Project

examples/01-intro/project/BUCK

@@ -0,0 +1,7 @@
+rust_binary(
+    name = "test",
+    srcs = ["src/main.rs"],
+    deps = [
+        "//third-party:once_cell",
+    ],
+)

examples/01-intro/project/src/main.rs

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+use once_cell::sync::Lazy;
+
+const MAGIC: &str = "this is a magic string";
+
+static SPECIAL: Lazy<String> = Lazy::new(|| MAGIC.to_string());
+
+fn main() {
+    println!("static {}", &*SPECIAL);
+}

examples/01-intro/reindeer.toml

@@ -0,0 +1,48 @@
+##
+## Reindeer Config
+##
+## This file sets all of Reindeer's basic configuration. This file also marks
+## the top of the reindeer-managed directory, as all other paths are relative to
+## this one (both paths mentioned in this file, and implicit).
+##
+## Reindeer is under active development, and the layout and options in this file
+## may change.
+
+# Write output to third-party/BUCK
+# This also sets the default input (manifest_path) to third-party/Cargo.toml
+third_party_dir = "third-party"
+
+# If a fixups.toml file is needed (eg, the package has a build.rs), then
+# generate a template fixups.toml to be edited.
+fixup_templates = true
+
+# Configuration for generated BUCK file
+[buck]
+# Name of the generated file
+file_name = "BUCK" # default
+
+# Rules used for various kinds of targets. These rules don't directly
+# correspond with BUCK rules - they have extra attributes such as
+# per-platform settings. The intent is that you provide a set of macro
+# definitions which resolve them to appropriate underlying rules
+# suitable for your environment. (This may also work for Buck-like
+# build systems such as Bazel.)
+rust_library = "cargo.rust_library"     # A plain Rust library
+rust_binary = "cargo.rust_binary"       # A Rust executable
+buildscript_genrule = "buildscript_run" # Rule for running a build script to produce rustc args and generated sources
+
+# Load the macros to which the rules above will resolve.
+buckfile_imports = """
+load("@prelude//rust:cargo_buildscript.bzl", "buildscript_run")
+load("@prelude//rust:cargo_package.bzl", "cargo")
+"""
+
+# Banner comment for the generated BUCK File.
+generated_file_header = """
+##
+## \u0040generated by reindeer
+## Do not edit by hand.
+##
+## See README.md for directions on how to update this.
+##
+"""

example/setup.sh → examples/01-intro/setup.sh

@@ -4,11 +4,11 @@
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 
-# Generate file 'example/third-party/BUCK'.
+# Generate file 'third-party/BUCK'.
 
 set -e
 
-(cd ..; cargo build)
+(cd ../..; cargo build)
 
 # Build a BUCK file to build third-party crates.
 #
@@ -19,4 +19,4 @@ set -e
 # typically commit these fixups and the generated third-party/BUCK in the same
 # commit as above.
 
-../target/debug/reindeer --third-party-dir third-party buckify
+../../target/debug/reindeer --third-party-dir third-party buckify

example/third-party/.gitignore → examples/01-intro/third-party/.gitignore

@@ -1,9 +1,6 @@
 # Ignore Cargo-related stuff
-.cargo/registry
-.cargo/git
-/registry
-/git
-.package-cache
+.cargo
+target
 
 # Various cruft in vendored packages
 vendor/*/target

examples/01-intro/third-party/BUCK

@@ -0,0 +1,38 @@
+##
+## @generated by reindeer
+## Do not edit by hand.
+##
+## See README.md for directions on how to update this.
+##
+
+load("@prelude//rust:cargo_buildscript.bzl", "buildscript_run")
+load("@prelude//rust:cargo_package.bzl", "cargo")
+
+alias(
+    name = "once_cell",
+    actual = ":once_cell-1.20.2",
+    visibility = ["PUBLIC"],
+)
+
+http_archive(
+    name = "once_cell-1.20.2.crate",
+    sha256 = "1261fe7e33c73b354eab43b1273a57c8f967d0391e80353e51f764ac02cf6775",
+    strip_prefix = "once_cell-1.20.2",
+    urls = ["https://static.crates.io/crates/once_cell/1.20.2/download"],
+    visibility = [],
+)
+
+cargo.rust_library(
+    name = "once_cell-1.20.2",
+    srcs = [":once_cell-1.20.2.crate"],
+    crate = "once_cell",
+    crate_root = "once_cell-1.20.2.crate/src/lib.rs",
+    edition = "2021",
+    features = [
+        "alloc",
+        "default",
+        "race",
+        "std",
+    ],
+    visibility = [],
+)

example/third-party/Cargo.toml → examples/01-intro/third-party/Cargo.toml

@@ -15,7 +15,6 @@ path = "top/main.rs"
 # List of packages to be imported, with version constraints, features
 # and all options Cargo supports.
 [dependencies]
-blake3 = { version = "0.1", features = ["c_avx512"] }
 once_cell = "1.4"
 
 # Local patches - typically git references

examples/01-intro/third-party/top/main.rs

@@ -0,0 +1 @@
+fn main() {}

examples/01-intro/toolchains/BUCK

@@ -0,0 +1,5 @@
+load("@prelude//toolchains:demo.bzl", "system_demo_toolchains")
+
+# All the default toolchains, suitable for a quick demo or early prototyping.
+# Most real projects should copy/paste the implementation to configure them.
+system_demo_toolchains()

examples/02-hybrid/.gitignore

@@ -0,0 +1,2 @@
+/buck-out
+/target

examples/02-hybrid/Cargo.toml

@@ -0,0 +1,7 @@
+[workspace]
+
+members = ["project"]
+resolver = "2"
+
+# Local patches - typically git references
+[patch.crates-io]