cargo-pgrx: inject -Wl,--no-gc-sections to keep .pgrxsc sections on aarch64 Linux (pgcentralfoundation#2280)

Closes pgcentralfoundation#2279 
(hopefully)

Background
----------
The "one compile" schema pipeline embeds SQL entity metadata in a
`.pgrxsc` ELF section made of `#[used]` statics scattered across every
codegen unit. Rust lowers `#[used]` to `@llvm.used`, which is supposed
to translate to `SHF_GNU_RETAIN` so `ld --gc-sections` (which rustc
passes by default on ELF cdylibs) leaves the section alone. That
contract has three load-bearing links: LLVM must emit the flag, binutils
must honor it, and LTO must not mask the difference.

The chain breaks on aarch64 Linux under non-LTO release builds. When it
breaks, every `.pgrxsc` input section is dropped, the output section
vanishes, and `cargo pgrx schema` fails with:

    no embedded pgrx schema section found; expected `.pgrxsc` on ELF/PE
    or `__DATA,__pgrxsc` on Mach-O

pglinter 0.18.0 hit exactly this on their arm64 `release-lto-off` build
while their amd64 `release` (lto = "fat") build kept working — fat LTO
preserves `@llvm.used` globals via the linker plugin, sidestepping the
`SHF_GNU_RETAIN` path entirely. The asymmetry is profile-driven, not
architecture-driven; arm64 just happens to be where we see it first.

Fix
---
cargo-pgrx now injects a top-level cargo `--config` on every cargo
invocation it spawns:

    target.'cfg(all(target_family = "unix",
                    not(target_os = "macos")))'.rustflags =
        ["-C", "link-arg=-Wl,--no-gc-sections"]

That disables section GC for the cdylib link step on Linux/BSDs (where
the retention contract is fragile) and leaves macOS (Mach-O, `ld64`,
uses `-dead_strip` and doesn't speak `-Wl,...`) and Windows MSVC
(`link.exe`, also doesn't speak `-Wl,...`) alone. The injection is wired
into the `cargo()` helper in `cargo-pgrx/src/cargo.rs`, which is the
single chokepoint that every cargo subprocess in the crate goes through
— both `Cargo::into_command()` (schema, test, run, pgrx_target) and the
hand-rolled `Command` in `install.rs::build_extension`.

The cost is a few KB of unreferenced code surviving in the final .so,
which is a trade we'll happily make for reliable schema generation
across the whole LLVM/binutils matrix.

Users who set `RUSTFLAGS`/`CARGO_ENCODED_RUSTFLAGS` continue to override
per cargo's rustflags precedence. A new env var
`CARGO_PGRX_DISABLE_GC_SECTIONS_WORKAROUND` provides an explicit escape
hatch.

Why inject instead of touch `pgrx`'s own build.rs
-------------------------------------------------
`cargo:rustc-link-arg-cdylib` from a build script only affects the
package the build script belongs to — it doesn't propagate to
dependents. `pgrx` is an rlib, so emitting link args from its build.rs
is effectively a no-op at extension-link time. Injecting from cargo-pgrx
at the cargo invocation boundary is the one place where we can fix this
for every extension without requiring a source change in each one.

CI regression coverage
----------------------
New `pgrx_tests_arm64` job in `.github/workflows/tests.yml` runs on
`ubuntu-24.04-arm` (free native arm64 runner, same as pglinter uses) and
executes:

    cd pgrx-unit-tests && cargo pgrx schema pg17 --release

with `CARGO_PROFILE_RELEASE_LTO=false` and
`CARGO_PROFILE_RELEASE_CODEGEN_UNITS=16` pinned so the regression test
stays faithful to the pglinter failure shape even if the workspace
`[profile.release]` is edited later. pgrx-unit-tests has dozens of
`#[pg_extern]` / `#[pg_trigger]` / `#[pg_aggregate]` / etc. entries, so
every schema entity kind contributes to `.pgrxsc` and the test exercises
every producer path.

If the `--no-gc-sections` injection ever regresses, this job fails
loudly with the exact error string users would see.

Changes
-------
- cargo-pgrx/src/cargo.rs: `pgrx_injected_config_args()` helper + unit
test guarding the `--no-gc-sections` and non-macOS scope
- cargo-pgrx/README.md: document
`CARGO_PGRX_DISABLE_GC_SECTIONS_WORKAROUND` alongside existing `PGRX_*`
env vars
- .github/workflows/tests.yml: `pgrx_tests_arm64` job pinned to the
non-LTO release profile shape

Author: eeeebbbbrrrr

.github/workflows/tests.yml

@@ -302,6 +302,114 @@ jobs:
       - name: Stop sccache server
         run: sccache --stop-server || true
 
+  pgrx_tests_arm64:
+    name: Linux arm64 native tests
+    needs: lintck
+    runs-on: ubuntu-24.04-arm
+    if: "!contains(github.event.head_commit.message, 'nogha')"
+    env:
+      PG_VER: ${{ matrix.postgres }}
+      RUST_TOOLCHAIN: 'stable'
+
+    # Regression coverage for the `.pgrxsc` ELF-section retention contract on
+    # aarch64 Linux. The bug this is guarding against: without LTO, `#[used]`
+    # statics in `.pgrxsc` rely on `SHF_GNU_RETAIN` surviving through LLVM →
+    # binutils → `ld --gc-sections`. That chain has broken in the wild on
+    # aarch64 (see pglinter 0.18.0 failure), dropping the whole section and
+    # producing "no embedded pgrx schema section found" at schema-generation
+    # time. Running `cargo pgrx schema --release` against pgrx-unit-tests on
+    # a native aarch64 runner directly exercises the broken path.
+    strategy:
+      matrix:
+        postgres: [ 17 ]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up prerequisites and environment
+        run: |
+          sudo apt-get update -y -qq --fix-missing
+
+          echo "----- Remove old postgres / clang / llvm (best effort) -----"
+          # Each regex can legitimately match zero packages on the arm64
+          # runner image (e.g. no pre-installed `mono-llvm*`), so we treat
+          # every removal as best-effort rather than failing the whole job.
+          for pattern in \
+            '^postgres.*' \
+            '^libpq.*' \
+            '^clang.*' \
+            '^llvm.*' \
+            '^libclang.*' \
+            '^libllvm.*' \
+            '^mono-llvm.*'; do
+            sudo apt remove -y "$pattern" || true
+          done
+
+          echo "----- Install system dependencies -----"
+          sudo apt-get install -y \
+            build-essential \
+            clang \
+            libclang-dev \
+            llvm-dev \
+            gcc \
+            libssl-dev \
+            libz-dev \
+            make \
+            pkg-config \
+            zlib1g-dev
+
+          "$TOOL_DIR"/rustup.sh
+
+          echo "----- Print env -----"
+          env
+          echo ""
+
+      - name: Setup release Postgres apt repo
+        run: |
+          sudo apt-get install -y wget gnupg
+          sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
+          wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
+          sudo apt-get update -y -qq --fix-missing
+
+      - name: Install Postgres
+        run: |
+          sudo apt-get install -y \
+            postgresql-$PG_VER \
+            postgresql-server-dev-$PG_VER
+
+      - name: Set up PostgreSQL permissions
+        run: sudo chmod a+rwx `/usr/lib/postgresql/$PG_VER/bin/pg_config --pkglibdir` `/usr/lib/postgresql/$PG_VER/bin/pg_config --sharedir`/extension /var/run/postgresql/
+
+      - name: Cache cargo registry
+        uses: actions/cache@v4
+        continue-on-error: false
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+          key: pgrx-arm64-cargo-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/Cargo.lock', '.github/workflows/tests.yml') }}
+
+      - name: Install cargo-pgrx
+        run: cargo install --path cargo-pgrx/ --debug --force
+
+      - name: Run 'cargo pgrx init' against system-level ${{ matrix.postgres }}
+        run: cargo pgrx init --pg$PG_VER /usr/lib/postgresql/$PG_VER/bin/pg_config
+
+      # Reproduces the pglinter 0.18.0 failure mode: release build with LTO
+      # off and many codegen units, where `.pgrxsc` retention depends on
+      # `SHF_GNU_RETAIN` surviving the whole LLVM → binutils → `ld
+      # --gc-sections` chain. The env vars below pin the profile shape so
+      # this regression test keeps exercising the broken path even if
+      # someone later edits `[profile.release]` in the workspace Cargo.toml.
+      # pgrx-unit-tests has a large, diverse set of schema entries, so if
+      # the injected `--no-gc-sections` workaround ever regresses, this step
+      # fails with "no embedded pgrx schema section found".
+      - name: Exercise cargo pgrx schema --release against pgrx-unit-tests
+        env:
+          CARGO_PROFILE_RELEASE_LTO: "false"
+          CARGO_PROFILE_RELEASE_CODEGEN_UNITS: "16"
+        run: cd pgrx-unit-tests && cargo pgrx schema pg$PG_VER --release
+
   cargo_pgrx_init:
     name: cargo pgrx init
     runs-on: ubuntu-22.04

cargo-pgrx/README.md

@@ -61,6 +61,7 @@ Options:
 - `PGRX_BUILD_VERBOSE` - Set to true to enable verbose "build.rs" output -- useful for debugging build issues
 - `HTTPS_PROXY` - If set during `cargo pgrx init`, it will download the Postgres sources using these proxy settings. For more details refer to the [env_proxy crate documentation](https://docs.rs/env_proxy/*/env_proxy/fn.for_url.html).
 - `PGRX_IGNORE_RUST_VERSIONS` - Set to true to disable the `rustc` version check we have when performing schema generation (schema generation requires the same version of `rustc` be used to build `cargo-pgrx` as the crate in question).
+- `CARGO_PGRX_DISABLE_GC_SECTIONS_WORKAROUND` - Set to any value to stop `cargo-pgrx` from injecting `-C link-arg=-Wl,--no-gc-sections` on non-macOS Unix cdylib builds. By default, `cargo-pgrx` passes this flag (scoped to `cfg(all(target_family = "unix", not(target_os = "macos")))`) to cargo as `--config target.<cfg>.rustflags=[...]` only for cdylib-producing invocations — `cargo pgrx install`, `cargo pgrx package`, and the non-`--test` path of `cargo pgrx schema`. This prevents GNU `ld --gc-sections` from dropping the `.pgrxsc` section where the embedded SQL schema metadata lives — a problem that surfaces on non-LTO builds (notably aarch64 Linux) as `no embedded pgrx schema section found`. The workaround is intentionally not applied to `cargo pgrx test` / `cargo pgrx schema --test` because those also link a test binary whose undefined Postgres `extern "C"` references are expected to be GC'd away. Disable this only if you are explicitly managing `rustflags` yourself and understand the retention contract.
 
 ## First Time Initialization
 

cargo-pgrx/src/cargo.rs

@@ -24,6 +24,10 @@ pub struct Cargo {
     profile: CargoProfile,
     // use a BTreeMap for deterministic order of iteration
     more_args: BTreeMap<String, Vec<String>>,
+    // Top-level cargo args placed before the subcommand (e.g. `--config ...`).
+    // Kept separate so callers can opt into cdylib-only tweaks without touching
+    // subcommand-specific arg ordering.
+    top_level_args: Vec<String>,
 }
 
 impl Cargo {
@@ -73,11 +77,26 @@ impl Cargo {
         self
     }
 
+    /// Apply the `.pgrxsc` retention workaround for cdylib-producing
+    /// invocations. See `pgrx_cdylib_config_args` for why this is only safe
+    /// to use when the subcommand only links a cdylib (never for `test`,
+    /// which also links a test binary that needs normal `--gc-sections` to
+    /// prune undefined Postgres `extern "C"` references).
+    pub fn with_pgrx_cdylib_workaround(mut self) -> Self {
+        self.top_level_args.extend(pgrx_cdylib_config_args());
+        self
+    }
+
     #[track_caller]
     pub fn into_command(self) -> process::Command {
         let mut cmd = cargo();
 
-        // subcommand *must* go first
+        // top-level cargo args (e.g. `--config ...`) go before the subcommand.
+        for arg in &self.top_level_args {
+            cmd.arg(arg);
+        }
+
+        // subcommand *must* go first among subcommand-relative args
         if self.subcmd != "" {
             cmd.arg(&self.subcmd);
         } else {
@@ -94,6 +113,7 @@ impl Cargo {
             package,
             subcmd: _,
             more_args,
+            top_level_args: _,
         } = self;
 
         // set most-interesting flags first, like profile, target, and manifest-path
@@ -178,6 +198,54 @@ pub(crate) fn cargo() -> std::process::Command {
     std::process::Command::new(cargo)
 }
 
+/// Cargo top-level `--config` arguments that force the linker to retain the
+/// `.pgrxsc` section when building the extension cdylib.
+///
+/// The schema metadata that drives `cargo pgrx schema` lives in a `.pgrxsc`
+/// ELF section composed of `#[used]` statics scattered across every CGU. Rust
+/// lowers `#[used]` to `@llvm.used`, which on ELF is supposed to mark the
+/// containing section with `SHF_GNU_RETAIN` so the linker's default
+/// `--gc-sections` pass leaves it alone. That contract is fragile in the wild:
+/// it depends on LLVM emitting the flag, binutils honoring it, and LTO not
+/// masking the difference. When it breaks, every `.pgrxsc` contribution is
+/// dropped and `cargo pgrx schema` fails with "no embedded pgrx schema section
+/// found" — which is exactly what we've seen on non-LTO aarch64 Linux builds.
+///
+/// Passing `-Wl,--no-gc-sections` as a link-arg on non-macOS Unix sidesteps the
+/// whole retention contract. The cost is a few KB of unreferenced code surviving
+/// in the final cdylib, which is a trade we'll happily make.
+///
+/// Critically, these args are only injected for cdylib-producing invocations
+/// (`cargo build --lib` inside cargo-pgrx install/package/schema paths). They
+/// MUST NOT be injected for `cargo test` invocations: rustc uses `--gc-sections`
+/// on test binaries to prune the many unreachable `extern "C"` references to
+/// Postgres symbols that pgrx-pg-sys declares. Keeping all those call sites
+/// retained makes the linker refuse to produce the test executable with a
+/// wall of "undefined symbol: CurrentMemoryContext" errors. The test-harness
+/// flow (`cargo pgrx test`) still picks up the workaround because the harness
+/// re-invokes `cargo-pgrx install` internally, and that path goes through
+/// `build_extension` which does apply the workaround.
+///
+/// This is scoped via a `cfg(...)` target predicate so it only fires when
+/// building for a GNU-ld-ish target; macOS (Mach-O, `ld64`, uses `-dead_strip`
+/// and doesn't understand this flag) and Windows (MSVC `link.exe`, doesn't
+/// speak `-Wl,...`) are excluded.
+///
+/// Users who set `RUSTFLAGS` or `CARGO_ENCODED_RUSTFLAGS` override this per
+/// cargo's rustflags precedence rules. Setting
+/// `CARGO_PGRX_DISABLE_GC_SECTIONS_WORKAROUND=1` in the environment also
+/// suppresses the injection entirely.
+pub(crate) fn pgrx_cdylib_config_args() -> Vec<String> {
+    if std::env::var_os("CARGO_PGRX_DISABLE_GC_SECTIONS_WORKAROUND").is_some() {
+        return Vec::new();
+    }
+    vec![
+        "--config".to_string(),
+        r#"target.'cfg(all(target_family = "unix", not(target_os = "macos")))'.rustflags = ["-C", "link-arg=-Wl,--no-gc-sections"]"#
+            .to_string(),
+    ]
+}
+
 /// Set some environment variables for use downstream (in `pgrx-test` for
 /// example). Does nothing if already set.
 pub(crate) fn initialize() {
@@ -256,3 +324,25 @@ impl CargoProfile {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::pgrx_cdylib_config_args;
+
+    #[test]
+    fn cdylib_config_args_carry_no_gc_sections_workaround() {
+        let args = pgrx_cdylib_config_args();
+        assert_eq!(args.len(), 2, "expected `--config <value>` pair, got {args:?}");
+        assert_eq!(args[0], "--config");
+        assert!(
+            args[1].contains("--no-gc-sections"),
+            "cdylib --config should disable section GC on non-macOS Unix: {}",
+            args[1]
+        );
+        assert!(
+            args[1].contains("not(target_os = \"macos\")"),
+            "cdylib --config must exclude macOS: {}",
+            args[1]
+        );
+    }
+}

cargo-pgrx/src/command/install.rs

@@ -305,6 +305,13 @@ pub(crate) fn build_extension(
     let flags = std::env::var("PGRX_BUILD_FLAGS").unwrap_or_default();
 
     let mut command = crate::cargo::cargo();
+    // These `--config` args go before the subcommand. They retain `.pgrxsc`
+    // on non-macOS Unix cdylib links so schema generation can find it; safe
+    // here because this path only ever builds the cdylib (`--lib`). See
+    // `pgrx_cdylib_config_args` for the full rationale.
+    for arg in crate::cargo::pgrx_cdylib_config_args() {
+        command.arg(arg);
+    }
     command.arg("build");
     command.arg("--lib");
 

cargo-pgrx/src/command/schema.rs

@@ -310,7 +310,16 @@ fn first_build(
         cargo.subcommand("build").flag("--lib")
     };
 
-    let cargo = cargo.profile(profile.clone()).target(target.map(|t| t.to_owned()));
+    let mut cargo = cargo.profile(profile.clone()).target(target.map(|t| t.to_owned()));
+
+    // `cargo build --lib` only ever links the cdylib, so it's safe to apply
+    // the `.pgrxsc` retention workaround. `cargo test --no-run` also links
+    // the test binary, which rustc needs `--gc-sections` to prune undefined
+    // Postgres `extern "C"` references from; applying the workaround there
+    // surfaces those as linker errors. See `pgrx_cdylib_config_args`.
+    if !is_test {
+        cargo = cargo.with_pgrx_cdylib_workaround();
+    }
 
     let mut command = cargo.into_command();