From f005e16c5d8eabbc27109a166e73eeaebc773a28 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Wed, 7 Oct 2026 15:39:18 -0500 Subject: [PATCH 1/5] Rename _CHECK_TEST_INSTALL_ERROR_STOP_SCRIPT to _PGXNTOOL_CHECK_TEST_INSTALL_ERROR_STOP_SCRIPT Internal plumbing variables are named _PGXNTOOL_*, so the name itself marks them as outside the user-facing surface while staying namespaced. This one is new in the current unreleased cycle, so no HISTORY.asc entry. Co-Authored-By: Claude Opus 5.5 --- base.mk | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/base.mk b/base.mk index 8802012..4fb62fd 100644 --- a/base.mk +++ b/base.mk @@ -272,7 +272,7 @@ else PGXNTOOL_ENABLE_TEST_INSTALL_ERROR_STOP_CHECK = yes endif -_CHECK_TEST_INSTALL_ERROR_STOP_SCRIPT ?= $(PGXNTOOL_DIR)/test/bin/check-test-install-error-stop.sh +_PGXNTOOL_CHECK_TEST_INSTALL_ERROR_STOP_SCRIPT ?= $(PGXNTOOL_DIR)/test/bin/check-test-install-error-stop.sh # ------------------------------------------------------------------------------ # verify-results: Safeguard for make results @@ -492,7 +492,7 @@ ifeq ($(PGXNTOOL_ENABLE_TEST_INSTALL),yes) ifeq ($(PGXNTOOL_ENABLE_TEST_INSTALL_ERROR_STOP_CHECK),yes) .PHONY: check-test-install-error-stop check-test-install-error-stop: - @$(_CHECK_TEST_INSTALL_ERROR_STOP_SCRIPT) $(TESTDIR) + @$(_PGXNTOOL_CHECK_TEST_INSTALL_ERROR_STOP_SCRIPT) $(TESTDIR) TEST_DEPS += check-test-install-error-stop endif endif From 9b5a39a8549b85c294a942dcba16a979242da3fd Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Wed, 7 Oct 2026 16:12:14 -0500 Subject: [PATCH 2/5] Prefix internal test-gate targets with _ and document naming convention check-stale-expected and check-test-install-error-stop are wired into TEST_DEPS and never meant to be invoked directly, so rename them to _check-stale-expected and _check-test-install-error-stop. The _ prefix also keeps them out of `make list`. .claude/CLAUDE.md now spells out the naming convention: PGXNTOOL_ is a user-facing override point, _PGXNTOOL_ (and _-prefixed targets) is internal-only, and the older unprefixed internal variables stay as they are because consumers may reference them. Co-Authored-By: Claude Opus 5.5 --- .claude/CLAUDE.md | 19 +++++++++++++++++++ HISTORY.asc | 3 ++- README.asc | 6 +++--- base.mk | 38 +++++++++++++++++++------------------- 4 files changed, 43 insertions(+), 23 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index ffaef1f..f05f312 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -25,6 +25,25 @@ Addition specific to this paired repo, on top of the general convention in `../../ai/CLAUDE.md`: if you pushed to both pgxntool and pgxntool-test, start a background task for each — do not monitor them sequentially. +## Naming: `PGXNTOOL_` Is API, `_PGXNTOOL_` Is Internal + +- `PGXNTOOL_*` variables are user-facing override points: document them in + README.asc and treat any change as an API change. +- `_PGXNTOOL_*` variables (and `_pgxntool_*` functions) are internal-only, + including seams that exist so pgxntool-test can stub a script. Internal + make targets likewise start with `_` (e.g. `_check-stale-expected`), which + also keeps them out of `make list`. +- Older unprefixed internal variables (`TEST_DEPS`, `TEST_SQL_FILES`, + `TEST_BUILD_*`, `REGRESS_DBNAME`, `MAJORVER`, `GE91`, `PGXNTOOL_DIR`, + `PGXNTOOL_distclean`, ...) stay as they are, since consumers may + reference them. Don't rename them; give every new internal variable the + `_PGXNTOOL_` prefix. + +pgxntool-test's `test/standard/make-variables.bats` checks every variable +base.mk defines against the classified list in its +`test/lib/pgxntool-variables.txt`, so adding a variable means classifying +it there. + ## HISTORY.asc: Sorted Issue Numbers The "Issues fixed in this release:" line in HISTORY.asc must list issue diff --git a/HISTORY.asc b/HISTORY.asc index 2e99b76..8d8e22e 100644 --- a/HISTORY.asc +++ b/HISTORY.asc @@ -61,7 +61,8 @@ same `_PGXNTOOL_` consistency): `PGXNTOOL_BASE_MK_INCLUDED` -> `_CHECK_STALE_EXPECTED_SCRIPT` -> `_PGXNTOOL_CHECK_STALE_EXPECTED_SCRIPT`. None of these are documented anywhere as override points, but if you happened to reference one directly (unsupported, but possible), update to the new -name. +name. The internal `check-stale-expected` target is likewise renamed to +`_check-stale-expected`; `make test` runs it as before. == Add `make results-build` Refreshes `test/build/expected/*.out` from the last `test-build` run's diff --git a/README.asc b/README.asc index 012943c..cefc07b 100644 --- a/README.asc +++ b/README.asc @@ -202,7 +202,7 @@ Without `test/install`, each test file typically needs to run `CREATE EXTENSION` **Key detail:** Install files and regular tests run in a single `pg_regress` invocation. This means the database is NOT dropped between install and test phases — state created by install files persists into the main test suite. -WARNING: **`+test/install/*.out+` is never actually compared against anything.** Unlike every other test type pgxntool supports, the `test/install` directory's actual output is written to the exact same file as its expected output, so there is no diff — a wrong or changed result will never fail the build, no matter how much it changes. The *only* thing that still fails the build is a hard SQL error, and only if the file sets `ON_ERROR_STOP` (directly, or via `\i test/pgxntool/psql.sql`) — without it, psql prints the error, keeps going, and the file "passes" regardless. pgxntool enforces this by default (`check-test-install-error-stop`, see `PGXNTOOL_ENABLE_TEST_INSTALL_ERROR_STOP_CHECK` to disable), but that only guarantees errors are caught — it does not give you real output validation. If you need actual output comparison, put that logic in `test/sql` instead (or use pgTap assertions from within the install file itself). +WARNING: **`+test/install/*.out+` is never actually compared against anything.** Unlike every other test type pgxntool supports, the `test/install` directory's actual output is written to the exact same file as its expected output, so there is no diff — a wrong or changed result will never fail the build, no matter how much it changes. The *only* thing that still fails the build is a hard SQL error, and only if the file sets `ON_ERROR_STOP` (directly, or via `\i test/pgxntool/psql.sql`) — without it, psql prints the error, keeps going, and the file "passes" regardless. pgxntool enforces this by default (`_check-test-install-error-stop`, see `PGXNTOOL_ENABLE_TEST_INSTALL_ERROR_STOP_CHECK` to disable), but that only guarantees errors are caught — it does not give you real output validation. If you need actual output comparison, put that logic in `test/sql` instead (or use pgTap assertions from within the install file itself). ==== Update & Upgrade (U&U) Testing @@ -810,13 +810,13 @@ Default: `yes`. Enables or disables the <<_verify_results_safeguard,verify-resul === PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED * -Default: `yes`. Enables or disables the check-stale-expected safeguard, which fails `make test` if `test/expected/` (or `test/build/expected/`) contains a `.out` file with no corresponding `.sql` file -- catching a stale file left behind after a test was renamed or removed. Set to `no` to make the check a complete no-op (it's dropped from `TEST_DEPS` entirely). +Default: `yes`. Enables or disables the `_check-stale-expected` safeguard, which fails `make test` if `test/expected/` (or `test/build/expected/`) contains a `.out` file with no corresponding `.sql` file -- catching a stale file left behind after a test was renamed or removed. Set to `no` to make the check a complete no-op (it's dropped from `TEST_DEPS` entirely). This is also the supported pattern for disabling one specific optional pgxntool feature: a documented `PGXNTOOL_ENABLE_*` variable, gating both the target's registration into `TEST_DEPS`/etc. and (where applicable) the target's own definition. Cleanly replacing or overriding an arbitrary pgxntool-generated recipe with your own entirely is a separate, larger, and not-yet-decided design question -- see https://github.com/Postgres-Extensions/pgxntool/issues/30[issue #30] (two proposed approaches) -- and is *not* what this mechanism solves. === PGXNTOOL_CHECK_EXPECTED_FILE_TYPES * -Default: `yes`. Sub-check of check-stale-expected, independent of `PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED`: fails (with a distinct error message and exit code from the orphaned-`.out` check) if `test/expected/` (or `test/build/expected/`) contains any file that isn't `*.out`. Set to `no` to disable just this sub-check while leaving the orphaned-`.out` check active. +Default: `yes`. Sub-check of `_check-stale-expected`, independent of `PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED`: fails (with a distinct error message and exit code from the orphaned-`.out` check) if `test/expected/` (or `test/build/expected/`) contains any file that isn't `*.out`. Set to `no` to disable just this sub-check while leaving the orphaned-`.out` check active. === PGXNTOOL_NO_PGXS_INCLUDE diff --git a/base.mk b/base.mk index 4fb62fd..b62828a 100644 --- a/base.mk +++ b/base.mk @@ -202,7 +202,7 @@ endif # pg_regress does report as a failure) if ON_ERROR_STOP is set. So it is # entirely up to each test/install/*.sql file to `\set ON_ERROR_STOP on` (or # `\i test/pgxntool/psql.sql`, which already does) if it wants failures -# caught at all. check-test-install-error-stop below enforces this by +# caught at all. _check-test-install-error-stop below enforces this by # default; see PGXNTOOL_ENABLE_TEST_INSTALL_ERROR_STOP_CHECK to disable it. # # Why not just force `-v ON_ERROR_STOP=1` onto the psql invocation instead of @@ -258,7 +258,7 @@ else endif # Variable: PGXNTOOL_ENABLE_TEST_INSTALL_ERROR_STOP_CHECK -# - Gates check-test-install-error-stop (see TEST_DEPS wiring below): fails +# - Gates _check-test-install-error-stop (see TEST_DEPS wiring below): fails # the build if a test/install/*.sql file neither includes # test/pgxntool/psql.sql nor has its own `\set`/`\unset ON_ERROR_STOP` # (any value counts) -- see the IMPORTANT note @@ -308,7 +308,7 @@ endif PGXNTOOL_VERIFY_RESULTS_MODE ?= pgtap # ------------------------------------------------------------------------------ -# check-stale-expected: catch orphaned/unexpected test/expected/ files +# _check-stale-expected: catch orphaned/unexpected test/expected/ files # ------------------------------------------------------------------------------ # Variable: PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED # - Can be set manually in Makefile or command line @@ -323,16 +323,16 @@ PGXNTOOL_VERIFY_RESULTS_MODE ?= pgtap # - Allowed values: "yes" or "no" (case-insensitive) # - Default: "yes" # - Set to "no" to disable just this sub-check while leaving the rest of -# check-stale-expected (the orphaned-.out check) active +# _check-stale-expected (the orphaned-.out check) active # - Passed through to check-stale-expected.sh; see that script for the # distinct error message/exit code this sub-check uses # # Variable: _PGXNTOOL_CHECK_STALE_EXPECTED_SCRIPT (internal shim, not user-facing) -# - Path to the script the check-stale-expected target invokes +# - Path to the script the _check-stale-expected target invokes # - Default: $(PGXNTOOL_DIR)/test/bin/check-stale-expected.sh # -# Implementation: See check-stale-expected target definition (search for -# "check-stale-expected:" in this file) +# Implementation: See _check-stale-expected target definition (search for +# "_check-stale-expected:" in this file) # ifdef PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED override PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED := $(call pgxntool_validate_yesno,$(PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED),PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED) @@ -427,11 +427,11 @@ installcheck: $(TEST_RESULT_FILES) $(TEST_SQL_FILES) | $(TESTDIR)/sql/ $(TESTDIR # installed (CREATE EXTENSION requires the control/SQL files to be in place). # PGXS's own installcheck target doesn't declare that dependency -- it assumes # the caller runs `make install installcheck` manually. That assumption breaks -# when something else (e.g. check-stale-expected below) depends on installcheck +# when something else (e.g. _check-stale-expected below) depends on installcheck # directly: `test`'s TEST_DEPS lists install/installcheck as independent, # unordered prerequisites, so nothing stops installcheck's own prerequisite # chain from running before install. An explicit edge here, same as -# check-stale-expected's, is the only ordering guarantee Make actually gives. +# _check-stale-expected's, is the only ordering guarantee Make actually gives. # # Gated behind PGXNTOOL_ENABLE_FS_INSTALL (see its definition above): when # disabled, `installcheck` must run against whatever is already installed @@ -452,7 +452,7 @@ endif TEST_DEPS = testdeps # ------------------------------------------------------------------------------ -# check-stale-expected: catch orphaned/unexpected test/expected/ files +# _check-stale-expected: catch orphaned/unexpected test/expected/ files # ------------------------------------------------------------------------------ # Purpose: test/expected/*.out must mirror test/sql/*.sql 1:1 (likewise # test/build/expected/*.out vs test/build/*.sql, when test-build is in use). @@ -470,30 +470,30 @@ TEST_DEPS = testdeps # See PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED / PGXNTOOL_CHECK_EXPECTED_FILE_TYPES # above for how to disable this entirely or just its non-.out file sub-check. ifeq ($(PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED),yes) -.PHONY: check-stale-expected -check-stale-expected: installcheck +.PHONY: _check-stale-expected +_check-stale-expected: installcheck @$(_PGXNTOOL_CHECK_STALE_EXPECTED_SCRIPT) $(TESTDIR) $(PGXNTOOL_CHECK_EXPECTED_FILE_TYPES) -TEST_DEPS += check-stale-expected +TEST_DEPS += _check-stale-expected endif # ------------------------------------------------------------------------------ -# check-test-install-error-stop: catch missing ON_ERROR_STOP in test/install +# _check-test-install-error-stop: catch missing ON_ERROR_STOP in test/install # ------------------------------------------------------------------------------ # Purpose: test/install/*.sql files never get a real pg_regress diff (see the # IMPORTANT note in the test/install section above) -- ON_ERROR_STOP is the # only thing that still turns a hard SQL error into a build failure. A file # passes if it includes test/pgxntool/psql.sql or has any `\set`/`\unset # ON_ERROR_STOP` command of its own. This is a pure static scan of file -# contents, so unlike check-stale-expected it doesn't need to run after +# contents, so unlike _check-stale-expected it doesn't need to run after # installcheck -- it needs no ordering edge at all. # # See PGXNTOOL_ENABLE_TEST_INSTALL_ERROR_STOP_CHECK above to disable. ifeq ($(PGXNTOOL_ENABLE_TEST_INSTALL),yes) ifeq ($(PGXNTOOL_ENABLE_TEST_INSTALL_ERROR_STOP_CHECK),yes) -.PHONY: check-test-install-error-stop -check-test-install-error-stop: +.PHONY: _check-test-install-error-stop +_check-test-install-error-stop: @$(_PGXNTOOL_CHECK_TEST_INSTALL_ERROR_STOP_SCRIPT) $(TESTDIR) -TEST_DEPS += check-test-install-error-stop +TEST_DEPS += _check-test-install-error-stop endif endif @@ -970,7 +970,7 @@ endif # # # This declaration is deliberately OUTSIDE the ifeq below (unlike e.g. -# check-stale-expected's own .PHONY, which lives inside its ifeq): testdeps' +# _check-stale-expected's own .PHONY, which lives inside its ifeq): testdeps' # own `testdeps: pgtap` prerequisite (see testdeps' definition) is # unconditional, so pgtap must always resolve to *some* rule. Without this # unconditional .PHONY, disabling the block below would leave `pgtap` From 66c803b768372780fc602a7ee20affdf9d2c8c84 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Wed, 7 Oct 2026 16:12:55 -0500 Subject: [PATCH 3/5] Regenerate README.html Co-Authored-By: Claude Opus 5.5 --- README.html | 96 +++++++++++++++++++++++++++++------------------------ 1 file changed, 53 insertions(+), 43 deletions(-) diff --git a/README.html b/README.html index 013c61c..431bb46 100644 --- a/README.html +++ b/README.html @@ -449,24 +449,25 @@

PGXNtool

  • 4. make targets
  • 5. Version-Specific SQL Files @@ -618,7 +619,16 @@

    -

    4.2. test

    +

    4.2. check-duplicate-docs

    +
    +

    Warns if two $(DOCS) entries would install to the same filename, which would otherwise fail make install.

    +
    +
    +

    all depends on this, so it also runs as part of a plain make, make install and make test; you only need to invoke it directly to check without building anything.

    +
    +
    +
    +

    4.3. test

    Runs your extension’s test suite: installs the extension and runs it through PGXS’s installcheck, first pulling in anything you’ve hooked into testdeps and, if enabled, sanity-checking your test SQL via test-build.

    @@ -682,7 +692,7 @@

    -

    4.3. test-build

    +

    4.4. test-build

    Validates that extension SQL files are syntactically correct before running the full test suite. This feature runs SQL files from test/build/ through pg_regress, providing better error messages than CREATE EXTENSION failures when there are syntax errors in your extension code.

    @@ -802,7 +812,7 @@

    When CREATE EXTENSION fails, PostgreSQL shows only "syntax error" with limited context. Running the SQL directly via \i shows the exact line and position of errors, making debugging much faster.

    -

    4.3.1. results-build

    +

    4.4.1. results-build

    Refreshes test/build/expected/*.out from the actual output of the last test-build run, mirroring results for the main suite:

    @@ -825,7 +835,7 @@

    -

    4.4. test/install

    +

    4.5. test/install

    Runs setup files before the main test suite within the same pg_regress invocation. This allows expensive one-time operations (like extension installation) to set up state that persists into the regular test files.

    @@ -904,13 +914,13 @@

    Warning

    -test/install/*.out is never actually compared against anything. Unlike every other test type pgxntool supports, the test/install directory’s actual output is written to the exact same file as its expected output, so there is no diff — a wrong or changed result will never fail the build, no matter how much it changes. The only thing that still fails the build is a hard SQL error, and only if the file sets ON_ERROR_STOP (directly, or via \i test/pgxntool/psql.sql) — without it, psql prints the error, keeps going, and the file "passes" regardless. pgxntool enforces this by default (check-test-install-error-stop, see PGXNTOOL_ENABLE_TEST_INSTALL_ERROR_STOP_CHECK to disable), but that only guarantees errors are caught — it does not give you real output validation. If you need actual output comparison, put that logic in test/sql instead (or use pgTap assertions from within the install file itself). +test/install/*.out is never actually compared against anything. Unlike every other test type pgxntool supports, the test/install directory’s actual output is written to the exact same file as its expected output, so there is no diff — a wrong or changed result will never fail the build, no matter how much it changes. The only thing that still fails the build is a hard SQL error, and only if the file sets ON_ERROR_STOP (directly, or via \i test/pgxntool/psql.sql) — without it, psql prints the error, keeps going, and the file "passes" regardless. pgxntool enforces this by default (_check-test-install-error-stop, see PGXNTOOL_ENABLE_TEST_INSTALL_ERROR_STOP_CHECK to disable), but that only guarantees errors are caught — it does not give you real output validation. If you need actual output comparison, put that logic in test/sql instead (or use pgTap assertions from within the install file itself).
    -

    4.4.1. Update & Upgrade (U&U) Testing

    +

    4.5.1. Update & Upgrade (U&U) Testing

    Beyond validating a plain install, it’s worth testing that your extension behaves correctly across the two transitions every extension with more than one release eventually goes through:

    @@ -986,7 +996,7 @@

    -

    4.5. testdeps

    +

    4.6. testdeps

    This rule allows you to ensure certain actions have taken place before running tests. By default it has a single prerequisite, pgtap, which will attempt to install pgtap from PGXN. This depneds on having the pgxn client installed.

    @@ -1022,7 +1032,7 @@

    -

    4.6. results

    +

    4.7. results

    Because make test ultimately runs installcheck, it’s using the Postgres test suite. Unfortunately, that suite is based on running diff between a raw output file and expected results. I STRONGLY recommend you use pgTap instead! With pgTap, it’s MUCH easier to determine whether a test is passing or not - tests explicitly pass or fail rather than requiring you to examine diff output. The extra effort of learning pgTap will quickly pay for itself. This example might help get you started.

    @@ -1058,7 +1068,7 @@

    -

    4.6.1. verify-results safeguard

    +

    4.7.1. verify-results safeguard

    By default, make results will refuse to run if your tests are failing, so you can’t accidentally promote incorrect output into the new expected results. Which failures it looks for is controlled by PGXNTOOL_VERIFY_RESULTS_MODE:

    @@ -1104,7 +1114,7 @@

    -

    4.7. tag

    +

    4.8. tag

    make tag will create a git tag for the current version of your extension, as determined by the META.json file (generated from META.in.json — see PGXN Distributions vs. Extensions), and push it to origin. The reason to do this is so you can always refer to the exact code that went into a released version. For where tag, dist, and post-tag-version-bump fit in a full release, see releasing-with-pgxntool.md.

    @@ -1125,13 +1135,13 @@

    4.

    -

    4.8. tree-is-clean

    +

    4.9. tree-is-clean

    make tree-is-clean fails, printing git status, if the working tree has uncommitted or untracked changes. tag and post-tag-version-bump depend on it.

    -

    4.9. post-tag-version-bump

    +

    4.10. post-tag-version-bump

    Committing versioned SQL files (see Committing Version Files) means ongoing development after a release can silently regenerate and overwrite the file that was just released, since make always regenerates whatever file matches the current default_version. make post-tag-version-bump bumps each extension’s default_version to a placeholder alias — stable by default — so a subsequent make instead regenerates sql/{ext}--stable.sql, keeping the released file frozen.

    @@ -1140,7 +1150,7 @@

    -

    4.10. dist

    +

    4.11. dist

    make dist will create a .zip file for your current version that you can upload to PGXN. It first runs tag (creating/pushing the version’s git tag as described above if needed), then uses git archive at that tag to build the .zip file, so the archive always matches the exact tagged commit. The file is named after the PGXN name and version (the top-level "name" and "version" attributes in META.json, generated from META.in.json). The .zip file is placed in the parent directory so as not to clutter up your git repo.

    @@ -1173,7 +1183,7 @@

    -

    4.11. pgxntool-sync

    +

    4.12. pgxntool-sync

    This rule will pull down the latest released version of PGXNtool via git subtree pull and then reconcile the files setup.sh copied into your project (.gitignore, test/deps.sql) with a 3-way merge (it also verifies the test/pgxntool symlink, recreating it if missing).

    @@ -1239,7 +1249,7 @@

    -

    4.12. pgxntool-version

    +

    4.13. pgxntool-version

    make pgxntool-version prints the version of the embedded pgxntool copy, read from the first line of pgxntool/HISTORY.asc. That line is "STABLE" instead of a version number if this copy was synced from an unreleased commit rather than a tagged release.

    @@ -1257,19 +1267,19 @@

    -

    4.13. list

    +

    4.14. list

    make list prints every make target defined in your project — including ones provided by PGXS and pgxntool, not just ones you wrote — one per line. Useful for discovering what’s available without reading through the Makefile.

    -

    4.14. print-%

    +

    4.15. print-%

    make print-VARNAME prints the current value (and origin) of any make variable, e.g. make print-PGXNVERSION. Useful for debugging why a variable isn’t set to what you expect.

    -

    4.15. distclean

    +

    4.16. distclean

    make distclean removes generated configuration files (META.json — generated from META.in.json — plus meta.mk and control.mk) that survive a normal make clean.

    @@ -1295,7 +1305,7 @@

    -

    4.16. pgtle

    +

    4.17. pgtle

    Generates pg_tle (Trusted Language Extensions) registration SQL files for deploying extensions in managed environments like AWS RDS/Aurora. See [_pg_tle_Support] for complete documentation.

    @@ -1312,7 +1322,7 @@

    -

    4.17. check-pgtle

    +

    4.18. check-pgtle

    Checks if pg_tle is installed and reports the version. This target: - Reports the version from pg_extension if CREATE EXTENSION pg_tle has been run in the database @@ -1328,7 +1338,7 @@

    -

    4.18. run-pgtle

    +

    4.19. run-pgtle

    Registers all extensions with pg_tle by executing the generated pg_tle registration SQL files in a PostgreSQL database. This target: - Requires pg_tle to be installed in the target database. This isn’t a make-level dependency on check-pgtle — pgtle.sh checks it itself when it runs, and will tell you to run make check-pgtle if pg_tle isn’t there @@ -1365,7 +1375,7 @@

    -

    4.19. print-pgtle

    +

    4.20. print-pgtle

    Prints the generated pg_tle registration SQL to stdout instead of running it, for consumers building a combined multi-extension install file. This target: - Depends on pgtle, so the SQL files are (re)generated first @@ -2119,7 +2129,7 @@

    8.16. PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED *

    -

    Default: yes. Enables or disables the check-stale-expected safeguard, which fails make test if test/expected/ (or test/build/expected/) contains a .out file with no corresponding .sql file — catching a stale file left behind after a test was renamed or removed. Set to no to make the check a complete no-op (it’s dropped from TEST_DEPS entirely).

    +

    Default: yes. Enables or disables the _check-stale-expected safeguard, which fails make test if test/expected/ (or test/build/expected/) contains a .out file with no corresponding .sql file — catching a stale file left behind after a test was renamed or removed. Set to no to make the check a complete no-op (it’s dropped from TEST_DEPS entirely).

    This is also the supported pattern for disabling one specific optional pgxntool feature: a documented PGXNTOOL_ENABLE_* variable, gating both the target’s registration into TEST_DEPS/etc. and (where applicable) the target’s own definition. Cleanly replacing or overriding an arbitrary pgxntool-generated recipe with your own entirely is a separate, larger, and not-yet-decided design question — see issue #30 (two proposed approaches) — and is not what this mechanism solves.

    @@ -2128,7 +2138,7 @@

    8.17. PGXNTOOL_CHECK_EXPECTED_FILE_TYPES *

    -

    Default: yes. Sub-check of check-stale-expected, independent of PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED: fails (with a distinct error message and exit code from the orphaned-.out check) if test/expected/ (or test/build/expected/) contains any file that isn’t *.out. Set to no to disable just this sub-check while leaving the orphaned-.out check active.

    +

    Default: yes. Sub-check of _check-stale-expected, independent of PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED: fails (with a distinct error message and exit code from the orphaned-.out check) if test/expected/ (or test/build/expected/) contains any file that isn’t *.out. Set to no to disable just this sub-check while leaving the orphaned-.out check active.

    @@ -2164,7 +2174,7 @@

    From acfee297f5dd2aa225a400304019073dec48033d Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Wed, 7 Oct 2026 17:45:15 -0500 Subject: [PATCH 4/5] .claude/CLAUDE.md: PGXNTOOL_distclean is API, not internal Co-Authored-By: Claude Opus 5.5 --- .claude/CLAUDE.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index f05f312..4de1682 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -33,11 +33,11 @@ start a background task for each — do not monitor them sequentially. including seams that exist so pgxntool-test can stub a script. Internal make targets likewise start with `_` (e.g. `_check-stale-expected`), which also keeps them out of `make list`. -- Older unprefixed internal variables (`TEST_DEPS`, `TEST_SQL_FILES`, - `TEST_BUILD_*`, `REGRESS_DBNAME`, `MAJORVER`, `GE91`, `PGXNTOOL_DIR`, - `PGXNTOOL_distclean`, ...) stay as they are, since consumers may - reference them. Don't rename them; give every new internal variable the - `_PGXNTOOL_` prefix. +- Internal variables that predate the convention (`TEST_DEPS`, + `TEST_SQL_FILES`, `TEST_BUILD_*`, `REGRESS_DBNAME`, `MAJORVER`, `GE91`, + ..., plus `PGXNTOOL_DIR`, which keeps its bare prefix) stay as they are, + since consumers may reference them. Don't rename them; give every new + internal variable the `_PGXNTOOL_` prefix. pgxntool-test's `test/standard/make-variables.bats` checks every variable base.mk defines against the classified list in its From d44a8d0395ada87ae15712cf8cbef0ea0375ebcf Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Wed, 7 Oct 2026 17:58:26 -0500 Subject: [PATCH 5/5] Name the new validate_choice helper _pgxntool_validate_choice It's internal plumbing, so it follows the _pgxntool_ convention. Co-Authored-By: Claude Opus 5.5 --- base.mk | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/base.mk b/base.mk index 3dd1ce9..36c7e79 100644 --- a/base.mk +++ b/base.mk @@ -91,9 +91,9 @@ pgxntool_validate_yesno = $(strip \ # Helper function: normalize a single-word variable to lowercase and validate # it against a list of allowed values. -# Usage: $(call pgxntool_validate_choice,VALUE,VARIABLE_NAME,ALLOWED_VALUES) +# Usage: $(call _pgxntool_validate_choice,VALUE,VARIABLE_NAME,ALLOWED_VALUES) # Returns the lowercase value, or errors if it isn't exactly one of ALLOWED_VALUES. -pgxntool_validate_choice = $(strip \ +_pgxntool_validate_choice = $(strip \ $(if $(and $(filter 1,$(words $(1))),$(filter $(3),$(shell echo "$(1)" | tr '[:upper:]' '[:lower:]'))),\ $(shell echo "$(1)" | tr '[:upper:]' '[:lower:]'),\ $(error $(2) must be one of: $(3); got "$(1)"))) @@ -320,7 +320,7 @@ endif # Default mode: pgtap (scans results/*.out for TAP failures) PGXNTOOL_VERIFY_RESULTS_MODE ?= pgtap -override PGXNTOOL_VERIFY_RESULTS_MODE := $(call pgxntool_validate_choice,$(PGXNTOOL_VERIFY_RESULTS_MODE),PGXNTOOL_VERIFY_RESULTS_MODE,pgtap diffs) +override PGXNTOOL_VERIFY_RESULTS_MODE := $(call _pgxntool_validate_choice,$(PGXNTOOL_VERIFY_RESULTS_MODE),PGXNTOOL_VERIFY_RESULTS_MODE,pgtap diffs) # ------------------------------------------------------------------------------ # _check-stale-expected: catch orphaned/unexpected test/expected/ files