1# Chapter 27: platforms, one build graph for every Postgres major
2
3An extension is compiled against one Postgres major's headers, and a
4library built for 18 will not load into 17. The usual answer is to build
5twice, with a setting flipped in between. buck has a better one: make the
6major part of the *configuration*, so one graph holds every major at once,
7and `buck2 test //...` builds and tests them all in a single run.
8
9This folder defines that configuration. A *constraint* named `pg_major`
10has one value per supported major, and a *platform* `pgNN` is the host's
11own platform plus that value. Anything that differs by major branches on it
12with `pg_major_select` (from `build/defs.bzl`): pgrx's `pgNN` feature,
13bindgen's `pg_config`, the server a test starts.
14
15```mermaid
16flowchart TD
17  D["build/defs.bzl: PG_MAJORS = 17, 18"] --> C["constraint pg_major: pg_major_17, pg_major_18"]
18  C --> P17["platform pg17"]
19  C --> P18["platform pg18"]
20  P17 --> T17["tests:happy_path-pg17"]
21  P18 -. "the default, newest" .-> T18["tests:happy_path"]
22  P17 --> N["nix/package.nix: --target-platforms //platforms:pg17"]
23```
24
25Every test gets a twin per older major (`first_party_test` emits
26`<name>-pg17` with that platform as its default), and the nix package builds
27one major at a time with `--target-platforms //platforms:pgNN`. Anything
28built without the constraint gets the newest.
29
30The other half of this folder is the *execution* platform: where buck runs
31its actions. It is the prelude's own default (local, on the host's CPU and
32OS) with one addition, an opt-in remote cache, off unless the machine's own
33buck configuration turns it on. Anywhere else, it is exactly the default,
34and the repository never needs the cache or its credentials to build.
35
36> **Try it.** `nix develop -c buck2 build //crates/postjevsql:ext
37> --target-platforms //platforms:pg17` builds the extension for 17.
38
39## For the people who maintain it
40
41| File | What |
42| --- | --- |
43| [BUCK](BUCK) | The `pg_major` constraint, its values and the `pgNN` platforms from `PG_MAJORS`, and `:execution`, the platform `.buckconfig` names. |
44| [execution.bzl](execution.bzl) | `cached_execution_platform`: the prelude default with `remote_cache` exposed, read from `[buildbuddy] cache`. Actions always run locally; the cache is checked first and local results uploaded. |
45
46← Previous: [Chapter 26, toolchains/](../toolchains/) · Up: [postjevsql](../) · Next: [Chapter 28, third-party/](../third-party/) →