1# Chapter 17: tools, the helpers that write files so nobody has to
2
3Four small Rust programs, none of which ships to anyone who installs the
4extension. Each exists because a file in this repository would otherwise
5have to be kept by hand, and anything kept by hand eventually lies.
6
7```mermaid
8flowchart LR
9  so["the built postjevsql.so"] --> PS["pgrx-schema"] --> sql["postjevsql--0.0.1.sql"]
10  bk["the BUCK files"] --> CG["cargo-gen"] --> cargo["every Cargo.toml"]
11  ar["the crate archives buck fetched"] --> TN["third-party-notices"] --> tp["THIRD-PARTY, THIRD-PARTY-sidecar"]
12  gs["the release gates"] --> RG["record-gates"] --> fx["tests/fixtures/*.json"]
13```
14
15Two of them follow one pattern, worth knowing once. The tool generates
16the file inside the buck build, a `drift` test compares that with the copy
17committed in the repository and fails when they differ, and `buck2 run
18//tools/<tool>:update` writes the generated copy back into the checkout. So
19the committed file can be stale for exactly as long as it takes the next
20test run to notice. The other two differ on purpose: pgrx-schema's output
21is never committed, only built, and record-gates writes its fixtures once and
22refuses to overwrite them unless told to (`--rerecord`).
23
24> **Aside.** Why commit generated files at all? Because they are for people
25> who do not run buck. The Cargo workspace lets anyone `cargo build` or
26> `cargo pgrx install` from a plain clone, and the licence notices are there
27> for anyone reading the code, as well as installed beside the binaries.
28> Generating them keeps them true; committing them makes them useful.
29
30> **Try it.** `nix develop -c buck2 test //tools/...` runs both drift tests
31> and the tools' lint tests. Change a dependency in a `BUCK` file without
32> running the update, and `//tools/cargo-gen:drift` tells you which manifest
33> is now stale.
34
35## For the people who maintain it
36
37| Tool | What |
38| --- | --- |
39| [pgrx-schema/](pgrx-schema/) | Writes the install SQL from the schema entities pgrx embeds in the built `.so`. Chapter 18. |
40| [cargo-gen/](cargo-gen/) | Writes the Cargo workspace (the root `Cargo.toml`, one manifest per package, the extension's `src/bin/pgrx_embed.rs`) from the buck targets. Chapter 20. |
41| [third-party-notices/](third-party-notices/) | Writes `THIRD-PARTY` and `THIRD-PARTY-sidecar`: the licence of every crate linked into the extension and into the sidecar CLI. Chapter 22. |
42| [record-gates/](record-gates/) | Prices the release gates' recording runs before anything is spent, and with `--send` records them as `tests/fixtures/`. Chapter 24. |
43
44← Previous: [Chapter 16, nix/](../nix/) · Up: [postjevsql](../) · Next: [Chapter 18, pgrx-schema/](pgrx-schema/) →