Workspace Cargo.toml support + overhaul examples (#54)

Summary:
Fixes #51 by

- Running cargo commands in current dir & prefixing `vendor` with third-party/...
- Adding --manifest-path flag
- Adding `manifest_path = "..."` + `third_party_dir = "..."` to reindeer.toml, allowing it to live at your workspace root and just point to where the output should go.
    - (This always bugged me about reindeer, the only real way to use it was with a wrapper script. No longer.)
- Remaining compatible with the old CLI ways, hopefully.
- Now that you can run on a workspace toml, filter out workspace members from the BUCK file by default; `include_workspace_members = false` (default false) because you often want to write your own BUCK files for those instead of having them mixed into a huge generated BUCK file.
- **Overhauls the example, now it's 3 examples with much more documentation.** Browse the tree at <https://github.com/cormacrelf/reindeer/tree/workspace_cargo_toml/examples> to see how it looks.

Altogether you get `reindeer --manifest-path ./Cargo.toml --third-party-dir subdirectory buckify`, and because this is not something I expect people will want to type, the new config parameters get that down to just `reindeer buckify`. The layout is as as below.

```sh
; cat reindeer.toml

manifest_path = "Cargo.toml"
third_party_dir = "third-party/rust"
...

; reindeer buckify
.
├── Cargo.lock
├── Cargo.toml
├── reindeer.toml
└── third-party
    └── rust
        ├── .cargo/...
        ├── BUCK
        └── vendor
```

Includes a cargo fmt, let me know if this is wrong, maybe there is configuration drift between this repo & others at meta.

Pull Request resolved: #54

Differential Revision: D72935124

Pulled By: dtolnay

fbshipit-source-id: fa4e831c4b91a9657c4d168d6bed7fad2fb1140e

Author: cormacrelf

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

@@ -20,17 +20,39 @@ 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)
+        if: matrix.os == 'ubuntu' || matrix.os == 'macos'
         run: |-
-          cd example
-          reindeer --third-party-dir third-party buckify
-          buck2 init --git
+          pushd examples/01-intro
+          reindeer buckify
           buck2 run "//project:test"
-        if: matrix.os == 'ubuntu' || matrix.os == 'macos'
-      - name: Build example project (Windows)
+          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
+      - name: Build example projects (Windows)
+        if: matrix.os == 'windows'
         run: |-
-          cd example
-          & reindeer --third-party-dir third-party buckify
-          & buck2 init --git
+          cd examples/01-intro
+          & reindeer buckify
           & buck2 run "//project:test"
-        if: matrix.os == 'windows'
+          cd ../..
+
+          cd examples/02-hybrid
+          & reindeer buckify
+          & buck2 run "//project:test"
+          & cargo run -p project
+          cd ../..
+
+          cd examples/03-complex-fixups
+          & reindeer buckify
+          & buck2 run "//project:test"
+          cd ../..

docs/MANUAL.md

@@ -30,17 +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
-for them in `third-party/BUCK`.
+[`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
 until you're familiar enough with how everything works to do it yourself.

example/third-party/macros/rust_third_party.bzl

@@ -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/.buckconfig

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

example/toolchains/.buckconfig renamed to examples/01-intro/.buckroot

@@ -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",
+)

examples/01-intro/.gitignore

@@ -8,42 +8,39 @@ 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
-  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.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
   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/BUCK

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

example/README.md renamed to examples/01-intro/README.md

@@ -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);
+}