Transpile PostgreSQL C macros into Rust macro_rules!

[eeeebbbbrrrr]

This adds pgrx-c-macros, a library and clap CLI that follows cargo-pgrx’s PostgreSQL selection rules to discover and transpile function-style server macros with header and line-span provenance, supported by an architecture guide and extension book chapter.

cargo run -p pgrx-c-macros -- list pg18
cargo run -p pgrx-c-macros -- analyze pg18 --format json
cargo run -p pgrx-c-macros -- emit pg18 --name TYPEALIGN

• During pgrx-pg-sys builds, libclang and a compatible Clang executable establish the active definitions, declarations and recorded C profile alongside fresh bindgen output, while tracked inputs trigger regeneration and optional inspection/native failures preserve ordinary bindings through an unavailable report and classifier; PGRX_C_MACROS=0 opts out explicitly.
• The runtime admits compiler-verified LP64, LLP64 and ILP32 profiles, including unsigned-char Linux AArch64, Windows and either byte order and uses generated capability traits to preserve C promotions, rank, signedness, overflow, qualifiers, repeated evaluation and unevaluated operands, with caller-authored Rust unsafe operations and original C pointer, resource and thread obligations remaining explicit.
• Supported forms include scalar expressions, qualified pointers, record/union fields, packed and volatile access, bitfields, mutation, function/callback calls, static inline functions, sizeof, alignment, offsetof, return adapters, supported statement blocks, compiler-verified byte swaps/branch hints and closed token pastes, with native access and ABI adapters compiled into a verified static archive.
• Formatted cmacros/pgNN/ modules follow source-header paths, preserve parameter and verified literal/symbol/type-alias spellings, document the original C definitions and safety/panic domains, and expose macros through pgrx with public cmacros::c operand tags and if_c_macro! availability checks.
• Demand-driven support has stable member/signature identities, complete input-byte verification avoids unoptimized repeated compression work, and release generation refreshes all documentation snapshots while the published package includes only the PG15 snapshot selected by docs.rs.
• The dependency graph propagates binding disagreements and unavailable callees into structured skips in OUT_DIR/pgNN_macro_report.json, diagnostics require PGRX_MACRO_DEBUG=1, explanatory comments mark uncertain expansion fallbacks, and ordinary cargo tests compare generated Rust with original C for configured PostgreSQL installations.

[GijungKim]

approved

[eeeebbbbrrrr]

Static review of 5d0fc41. I didn't build or run anything. I read the hand-written code in pgrx-c-macros, pgrx-bindgen and the pgrx-pg-sys runtime, and sampled the pg15–19 snapshots.

What looks right

• Runtime: I found no path from safe code to UB. Every memory-touching entry point is an unsafe fn, and the traits it trusts are unsafe or sealed. The generated unsafe {} blocks that actually run never contain caller tokens. Native calls go through pg_guard_ffi_boundary.
• C typing: integer promotions, the usual arithmetic conversions, literal typing, shifts and ?: match the C rules for LP64.

What blocks this

• Builds that now fail: macro inspection errors fail the pgrx-pg-sys build, with no opt-out. Three configurations that build on develop fail here:
  • RPM/Arch CFLAGS containing -Wp,;
  • the cross-compile recipe used in CI and the book;
  • hosts without a Clang driver that matches libclang.
• Builds that silently lose every macro: Linux aarch64, and any profile with an unmodeled -f flag. They compile, but export zero macros and print no warning.

Inline comments are tagged P0 (breaks a currently supported build), P1 (risk under specific conditions) or P2 (hardening or quality). "Latent" means the current PG15–19 output doesn't hit it. Three top-level comments cover the larger changes: failing soft, public API stability, and size and build cost.

The PR description should mention the new Clang-driver requirement and the change that passes CFLAGS to bindgen, since both affect existing users.

[eeeebbbbrrrr]

Larger change 1: make macro generation unable to break or silently empty a pgrx-pg-sys build

On develop, a pgrx-pg-sys build needs libclang and pg_config --cppflags. With this PR, every non-Windows build also needs:

• a Clang driver whose major version matches libclang;
• a CFLAGS profile that the analyzer accepts;
• successful native compilation.

Any failure in those steps fails the build (build.rs:1326). Separately, bindgen now receives the full --cflags even when macros end up unavailable (build.rs:1176).

Configurations that build on develop and fail here, from reading the code (not run):

• -Wp, in CFLAGS: RPM and Arch packages set -Wp,-D_FORTIFY_SOURCE=… (frontend.rs:2225).
• The cross-compile recipe in CI and the book: -ccc-gcc-name is parsed as an extra input (frontend.rs:2190).
• Missing driver: hosts with libclang but no clang-N/clang of the same major.
• Driver config files: a driver that loads one (frontend.rs:2144).
• Unsupported targets: ppc64le, s390x and FreeBSD still run the full inspection, even though the runtime gate can never emit for them.

Configurations that build but export no macros, with no output unless PGRX_MACRO_DEBUG=1:

• Linux aarch64: plain char is unsigned there (support_generation.rs:113).
• Common packaging flags: any profile with -fexceptions, -fno-plt, -ffile-prefix-map=, -fprofile-arcs, or another -f flag outside the allowlist (analysis.rs:550).

Suggested shape:

1. Keep bindings independent of macros. Generate bindings with the pre-PR arguments, and treat macro generation as an add-on that consumes them.
2. Fail soft. Map every inspection or native-build error to MacroOutput::unavailable(reason), plus one unconditional cargo:warning naming the reason and the report path.
3. Check the target first. Gate inspection on the runtime-supported target set before running any compiler.
4. Add an explicit opt-out, such as PGRX_C_MACROS=0 or a cargo feature. Consider making generation opt-in for 0.20 until the platform matrix has CI coverage: Linux x86_64/aarch64 with distro PostgreSQL packages, macOS with Xcode and Homebrew LLVM, and a cross build.
5. Never go silent. Warn unconditionally whenever a whole profile is rejected or zero macros are emitted.

Once the cross-compile job on this PR finishes, it should confirm or refute the -ccc-gcc-name failure.

[eeeebbbbrrrr]

Larger change 2: the public macro API varies by host; give users a way to deal with that

Which pgrx::NAME! macros exist depends on several things besides the PostgreSQL major version:

• configure options. Assert is emitted only without USE_ASSERT_CHECKING, since the cassert form uses stringification and is skipped. gettext/dgettext/ngettext are emitted only without ENABLE_NLS.
• the target. Linux aarch64 gets none.
• the compiler flags.
• whether bindgen and Clang agree on each referenced constant.

An extension that compiles against a pgrx-managed install can therefore fail against a distro or cassert build with only "cannot find macro X in crate pgrx". The PR's own backend tests already have to work around this with the internal __pgrx_c_classify! { @if_available … } (pgrx-unit-tests/src/tests/generated_c_macro_tests.rs:28).

Suggestions:

• Stubs for skipped names. For every function-like macro that is skipped, emit macro_rules! NAME { ($($t:tt)*) => { compile_error!("pgrx: NAME was not generated: <reason>; see pgNN_macro_report.json") } }. This turns a missing-name error into an actionable one at no runtime cost.
• A documented availability check. Offer a supported availability macro, such as pgrx::if_c_macro!(NAME { … }), in place of the hidden one.
• A public home for the helper types. CValue and the C markers are required by the book's examples but live in #[doc(hidden)] pg_sys::__pgrx_c_macros.
• Input typing.
  • pg_sys integer constants keep bindgen's u32 (e.g. BLCKSZ), which gives different results from C when mixed with signed operands. See the inline comment on expression.rs:407.
  • usize, i64 and u64 are rejected with raw trait errors.
• Overlap with the hand-written ports. About 36 hand-written functions share names with generated macros (MAXALIGN, TYPEALIGN, GETSTRUCT, TransactionIdIsNormal, …). Their signatures differ: the functions take usize, and the macros reject it. Documenting which one is canonical would help, along with whether the ports are expected to go away.
• Guarded calls to trivial helpers (predicted cost, not measured). Static inline helpers such as DatumGetPointer are called through guarded FFI. PG_GETARG_POINTER! therefore pays a sigsetjmp per argument fetch, which the existing hand-written paths don't. This is worth measuring before the book recommends these macros on hot paths.

[eeeebbbbrrrr]

Larger change 3: package size, generated code volume, and rebuild cost

Measured or counted locally on 5d0fc41 unless noted.

Package size

• pgrx-pg-sys/Cargo.toml has include = ["src/**/*", …], so the 179 MB of src/include/cmacros/pg15..pg19 snapshots are packaged.
• A tar czf of the package inputs is about 9.76 MB. The merge base was about 1.78 MB, and crates.io's limit is 10 MiB.
• The next major's snapshot will probably push it over the limit, and every user unpacks about 180 MB into ~/.cargo/registry.
• docs.rs builds only pg15 ([package.metadata.docs.rs]). Shipping only that snapshot, by excluding cmacros/pg1[6-9], would fix both problems.

Code compiled on every build

• The pg18 snapshot tree is about 690k lines, close to the 686k lines/39 MB a normal build writes to OUT_DIR. That is about 549k lines of macro_rules! plus about 137k lines of support items: roughly 9.6k impls and 9k const _ asserts.
• For comparison, pg18.rs is about 2.4 MB.
• Every pgrx user compiles this whether or not they call a macro.
• Local build directories from earlier commits on this branch also hold a 36–51 MB pretty-printed pgNN_macro_report.json, rewritten on every build.

Build-script and rebuild cost (predicted, not measured)

• Hashing: several verify passes per build SHA-256 every input, including the clang executable and libclang. In downstream build scripts that runs at opt-level 0 (see the inline note on Cargo.toml:90).
• Watched directories: each PATH directory searched, libclang's directory, and SDK roots become recursive rerun-if-changed watches. A local build output here has 987 directives, including /Library/Developer/CommandLineTools/usr/lib.
• Environment triggers: PATH and HOME are rerun-if-env-changed inputs.

Snapshot churn

• The Inline_*, Address_* and __pgrx_inline_* names hash PATH, HOME, cwd and absolute paths.
• Signature_* hashes the OS-versioned triple.
• Field<N> is a global rank over all field names.
• So snapshots differ per maintainer, and one new header field renumbers thousands of lines.

Per-call expansion

• In pg18, the median macro's value arm is about 370 tokens and 11 generic runtime calls.
• VARSIZE_ANY is about 3,600 tokens and 115 calls; att_addlength_datum is about 6,000 tokens and 169 calls.
• expression.rs has a single #[inline], so debug builds execute all of these calls.

Before merging, I'd like to see:

• cargo build --timings for pgrx-pg-sys and a small extension, plus a no-op rebuild, compared against develop;
• the actual output of cargo package -p pgrx-pg-sys;
• the predicted vs. measured numbers, per AGENTS.md.

[eeeebbbbrrrr]

The Windows PG15 failure came from the test assuming that likely and unlikely always return C long: PostgreSQL's MSVC fallback returns int, while the GNU builtin returns long. Commit d9d3f89 now compares the generated result with the original PostgreSQL headers under the verified compiler profile, checking exact rank, signedness, width, value and separate operand evaluation counts.

I also reproduced a generation refusal with Apple Clang 21 and the current macOS SDK. Clang's header witness writer prepends explicit dependency entries such as SDKSettings.json before actual C inclusions; b9ee9d8 verifies that ordered prefix against the effective compiler arguments and fingerprints those dependencies while preserving exact agreement for C headers.

All 222 affected compiler/oracle tests and nine original-header integration tests passed locally, as did workspace formatting and strict compiler-crate Clippy. Broader integration linting still reports three existing library warnings in libpq and panic handling; the changed test fixtures have no lint warnings, and eba7ebc removes the duplicate binding-namespace documentation found during that check.