1# Chapter 20: cargo-gen, a Cargo workspace written from the buck graph
2
3This repository is built by buck2, and buck's `BUCK` files are the one
4place a crate's dependencies are written. But most Rust tools, and most
5Rust people, expect Cargo: a `Cargo.toml` per crate and one at the root.
6Keeping both by hand would mean two lists of every dependency, which agree
7on the day they are written and never again.
8
9So the Cargo files are generated. Each `first_party_*` macro in
10`build/defs.bzl` quietly emits a small JSON file beside its target, naming
11its kind, its crate root and its dependencies. This tool reads all of those,
12plus the version, edition and supported majors from `build/defs.bzl` and the
13version requirements from `third-party/Cargo.toml`, and writes the root
14`Cargo.toml`, one manifest per package, and the extension's
15`src/bin/pgrx_embed.rs`.
16
17```mermaid
18flowchart LR
19  D["build/defs.bzl: VERSION, RUST_EDITION, PG_MAJORS"] --> G
20  M["each target's -cargo JSON"] --> G
21  T["third-party/Cargo.toml: version requirements"] --> G
22  G["cargo-gen generate"] --> O[":manifests"]
23  O -->|"drift test compares"| C["the committed Cargo.toml files"]
24  O -->|"buck2 run :update"| C
25```
26
27Every crate that reaches pgrx gets a `pgNN` feature for each supported
28major, the newest as the default, which is how cargo users pick a major
29(`--no-default-features --features pg17`). Every manifest says `MIT OR
30Apache-2.0` and "The postjevsql Authors", and none names a repository. The
31integration tests stay buck-only: they need buck to tell them where the
32built extension is.
33
34> **Try it.** After changing a dependency in a `BUCK` file, run
35> `nix develop -c buck2 run //tools/cargo-gen:update` and look at
36> `git diff`: the manifests have caught up. Skip it, and
37> `//tools/cargo-gen:drift` fails until you do.
38
39## For the people who maintain it
40
41| Path | What |
42| --- | --- |
43| [src/](src/) | The tool. Chapter 21. |
44| [BUCK](BUCK) | `:cargo-gen`; `PACKAGES`, the one hand-kept list of first-party packages; `:manifests` (what the BUCK files imply), `:committed` (what is in the checkout), `:drift` and `:update`. |
45| [drift.rs](drift.rs) | The drift test: fails, naming the file, when a committed manifest differs from the generated one. |
46| [Cargo.toml](Cargo.toml) | Its own manifest, generated by itself. |
47
48← Previous: [Chapter 19, pgrx-schema/src/](../pgrx-schema/src/) · Up: [tools](../) · Next: [Chapter 21, cargo-gen/src/](src/) →