diff --git a/HISTORY.asc b/HISTORY.asc index bdd5121..5cdb9e4 100644 --- a/HISTORY.asc +++ b/HISTORY.asc @@ -1,3 +1,19 @@ +STABLE +------ +== Add `print-pgtle` target for combined multi-extension pg_tle files +`make print-pgtle` prints the generated pg_tle registration SQL for each +extension to stdout, selecting the version directory from the new +`PGXNTOOL_PGTLE_TARGET_VERSION` variable (an actual pg_tle version, e.g. +`1.5.2`) or, if unset, the installed pg_tle version. This lets a consumer +build a combined multi-extension install file (e.g. +`$(MAKE) -C ../deps/cat_tools print-pgtle >> pgtle-all.sql`) without needing +to know the extension name or which `pg_tle/` version-range directory +applies. When invoking it recursively for stdout capture, pass +`--no-print-directory` -- otherwise GNU Make's own `Entering +directory`/`Leaving directory` announcements pollute the captured output. + +Issues fixed in this release: #21 + 2.3.0 ----- == Rename `PGTLE_VERSION` to `PGXNTOOL_PGTLE_VERSION` diff --git a/README.asc b/README.asc index 45c4b59..d2d71a9 100644 --- a/README.asc +++ b/README.asc @@ -346,6 +346,25 @@ After running `make run-pgtle`, you can create your extension in the database: CREATE EXTENSION "your-extension-name"; ---- +=== 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 +- Selects the version directory from `PGXNTOOL_PGTLE_TARGET_VERSION` if set (an actual pg_tle version like `1.5.2`, not a range like `PGXNTOOL_PGTLE_VERSION` uses), otherwise from the installed pg_tle version (queried the same way `run-pgtle` does) +- Errors if neither is available (no `PGXNTOOL_PGTLE_TARGET_VERSION` and pg_tle isn't installed) +- When invoked recursively (`$(MAKE) -C ... print-pgtle`) for stdout capture, pass `--no-print-directory` -- see warning below + +---- +make print-pgtle +make print-pgtle PGXNTOOL_PGTLE_TARGET_VERSION=1.5.2 +---- + +A dependency's registration SQL can be pulled into a combined file without the caller needing to know its extension name or which `pg_tle/` version-range directory applies: +---- +$(MAKE) --no-print-directory -C ../deps/cat_tools print-pgtle >> pgtle-all.sql +---- + +WARNING: Always pass `--no-print-directory` when invoking `print-pgtle` recursively from another Makefile's recipe (as above). GNU Make auto-prints `Entering directory`/`Leaving directory` announcements to stdout for recursive invocations, which silently corrupts a redirected combined SQL file with garbage lines. `--no-print-directory` suppresses them. + == Version-Specific SQL Files PGXNtool automatically generates version-specific SQL files from your base SQL file. These files follow the pattern `sql/{extension}--{version}.sql` and are used by PostgreSQL's extension system to install specific versions of your extension. @@ -554,7 +573,7 @@ PGXNtool appends *all* files found in all `$(DOC_DIRS)` to `DOCS`. [[_pg_tle_Support]] pgxntool can generate link:https://github.com/aws/pg_tle[pg_tle (Trusted Language Extensions)] registration SQL for deploying PostgreSQL extensions in managed environments like AWS RDS and Aurora where filesystem access is not available. -For make targets, see: <<_pgtle>>, <<_check_pgtle>>, <<_run_pgtle>>. +For make targets, see: <<_pgtle>>, <<_check_pgtle>>, <<_run_pgtle>>, <<_print_pgtle>>. === What is pg_tle? @@ -686,6 +705,10 @@ Default: auto-detected, the first of `asciidoctor` or `asciidoc` found on `PATH` Default: unset (generates every known pg_tle version range). Set on the command line to limit `make pgtle` to the single version range this value falls into. Not named `PGTLE_VERSION`: make auto-imports same-named environment variables, and that name collided silently with CI jobs that set a `PGTLE_VERSION` env var for an unrelated purpose (which pg_tle to test against). See <<_pgtle>>. +=== PGXNTOOL_PGTLE_TARGET_VERSION + +Default: unset (falls back to the installed pg_tle version). Set on the command line to an actual pg_tle version (e.g. `1.5.2`, not a range) to select which `pg_tle/` directory `make print-pgtle` reads from, without needing a database connection. Distinct from `PGXNTOOL_PGTLE_VERSION`, which holds a range and controls generation rather than selection. See <<_print_pgtle>>. + === PG_CONFIG Default: `pg_config`. Path to the `pg_config` binary used to detect the PostgreSQL version and locate PGXS. Override when the right `pg_config` isn't the one on `PATH`, such as when testing against a specific PostgreSQL install. diff --git a/README.html b/README.html index ba71c2a..7329e01 100644 --- a/README.html +++ b/README.html @@ -464,6 +464,7 @@

PGXNtool

  • 4.14. pgtle
  • 4.15. check-pgtle
  • 4.16. run-pgtle
    • +
  • 4.17. print-pgtle
  • 5. Version-Specific SQL Files @@ -501,16 +502,17 @@

    PGXNtool

  • 8.1. PGXN_REMOTE
  • 8.2. ASCIIDOC
  • 8.3. PGXNTOOL_PGTLE_VERSION
    • -
  • 8.4. PG_CONFIG
    • -
  • 8.5. TESTDIR
    • -
  • 8.6. TESTOUT
    • -
  • 8.7. PGXNTOOL_VERIFY_RESULTS_MODE
    • -
  • 8.8. PGXNTOOL_ENABLE_TEST_BUILD *
    • -
  • 8.9. PGXNTOOL_ENABLE_TEST_INSTALL *
    • -
  • 8.10. PGXNTOOL_ENABLE_VERIFY_RESULTS *
    • -
  • 8.11. PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED *
    • -
  • 8.12. PGXNTOOL_CHECK_EXPECTED_FILE_TYPES *
    • -
  • 8.13. PGXNTOOL_NO_PGXS_INCLUDE
    • +
  • 8.4. PGXNTOOL_PGTLE_TARGET_VERSION
    • +
  • 8.5. PG_CONFIG
    • +
  • 8.6. TESTDIR
    • +
  • 8.7. TESTOUT
    • +
  • 8.8. PGXNTOOL_VERIFY_RESULTS_MODE
    • +
  • 8.9. PGXNTOOL_ENABLE_TEST_BUILD *
    • +
  • 8.10. PGXNTOOL_ENABLE_TEST_INSTALL *
    • +
  • 8.11. PGXNTOOL_ENABLE_VERIFY_RESULTS *
    • +
  • 8.12. PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED *
    • +
  • 8.13. PGXNTOOL_CHECK_EXPECTED_FILE_TYPES *
    • +
  • 8.14. PGXNTOOL_NO_PGXS_INCLUDE
  • 9. Copyright
    • @@ -635,6 +637,18 @@

    Note +test exits non-zero (after printing regression.diffs) if any test fails. Previously it always exited 0 regardless of test results, silently masking failures from CI and other automation that relies on the exit code. + + + + +
    + + + + @@ -1071,7 +1085,7 @@

    4.9. 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.

    +

    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).

    +
    Note
    +    		 While you can still run make installcheck or any other valid PGXS make target directly, it’s recommended to use make test when using pgxntool. The test target ensures proper test isolation and correct dependency installation.
    @@ -1260,6 +1274,42 @@

    +
    +

    4.17. 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 +- Selects the version directory from PGXNTOOL_PGTLE_TARGET_VERSION if set (an actual pg_tle version like 1.5.2, not a range like PGXNTOOL_PGTLE_VERSION uses), otherwise from the installed pg_tle version (queried the same way run-pgtle does) +- Errors if neither is available (no PGXNTOOL_PGTLE_TARGET_VERSION and pg_tle isn’t installed) +- When invoked recursively ($(MAKE) -C …​ print-pgtle) for stdout capture, pass --no-print-directory — see warning below

    +
    +
    +
    +
    make print-pgtle
+make print-pgtle PGXNTOOL_PGTLE_TARGET_VERSION=1.5.2
    +
    +
    +
    +

    A dependency’s registration SQL can be pulled into a combined file without the caller needing to know its extension name or which pg_tle/ version-range directory applies:

    +
    +
    +
    +
    $(MAKE) --no-print-directory -C ../deps/cat_tools print-pgtle >> pgtle-all.sql
    +
    +
    +
    +

    + + + + +
    +
    Warning
    +    		 +Always pass --no-print-directory when invoking print-pgtle recursively from another Makefile’s recipe (as above). GNU Make auto-prints Entering directory/Leaving directory announcements to stdout for recursive invocations, which silently corrupts a redirected combined SQL file with garbage lines. --no-print-directory suppresses them. +
    +
     +
    @@ -1649,7 +1699,7 @@

    pgxntool can generate pg_tle (Trusted Language Extensions) registration SQL for deploying PostgreSQL extensions in managed environments like AWS RDS and Aurora where filesystem access is not available.

    -

    For make targets, see: pgtle, check-pgtle, run-pgtle.

    +

    For make targets, see: pgtle, check-pgtle, run-pgtle, print-pgtle.

    7.1. What is pg_tle?

    @@ -1893,61 +1943,67 @@

    -

    8.4. PG_CONFIG

    +

    8.4. PGXNTOOL_PGTLE_TARGET_VERSION

    +
    +

    Default: unset (falls back to the installed pg_tle version). Set on the command line to an actual pg_tle version (e.g. 1.5.2, not a range) to select which pg_tle/ directory make print-pgtle reads from, without needing a database connection. Distinct from PGXNTOOL_PGTLE_VERSION, which holds a range and controls generation rather than selection. See print-pgtle.

    +
    +
    +
    +

    8.5. PG_CONFIG

    Default: pg_config. Path to the pg_config binary used to detect the PostgreSQL version and locate PGXS. Override when the right pg_config isn’t the one on PATH, such as when testing against a specific PostgreSQL install.

    -

    8.5. TESTDIR

    +

    8.6. TESTDIR

    Default: test. Root directory for test input files: $(TESTDIR)/sql/, $(TESTDIR)/expected/, $(TESTDIR)/build/, $(TESTDIR)/install/. Overriding this on its own is unusual; it mainly exists so TESTOUT has a sensible default.

    -

    8.6. TESTOUT

    +

    8.7. TESTOUT

    Default: $(TESTDIR). Directory pg_regress writes actual test output to — $(TESTOUT)/results/, $(TESTOUT)/regression.diffs, etc. — via --outputdir in REGRESS_OPTS. Kept separate from TESTDIR so generated output can be pointed somewhere other than the directory holding your checked-in sql/expected files, if you want that separation.

    -

    8.7. PGXNTOOL_VERIFY_RESULTS_MODE

    +

    8.8. PGXNTOOL_VERIFY_RESULTS_MODE

    Default: pgtap. Controls how the verify-results safeguard decides whether tests are failing.

    -

    8.7.1. pgtap

    +

    8.8.1. pgtap

    Scans test/results/*.out for pgTap not ok lines and plan mismatches, falling back to checking for regression.diffs too. Use this mode when your test suite uses pgTap.

    -

    8.7.2. diffs

    +

    8.8.2. diffs

    Checks only for regression.diffs, matching classic pg_regress behavior. Use this mode when your tests use plain SQL expected-output comparison only.

    -

    8.8. PGXNTOOL_ENABLE_TEST_BUILD *

    +

    8.9. PGXNTOOL_ENABLE_TEST_BUILD *

    Default: auto-detected — yes if test/build/*.sql files exist, no otherwise. Enables or disables the test-build pre-flight SQL check. Set explicitly to yes if you want an error when test/build/ unexpectedly has no SQL files (catches accidental deletion of its contents), or to no to disable the check even when files are present.

    -

    8.9. PGXNTOOL_ENABLE_TEST_INSTALL *

    +

    8.10. PGXNTOOL_ENABLE_TEST_INSTALL *

    Default: auto-detected — yes if test/install/*.sql files exist, no otherwise. Enables or disables the test/install schedule-based setup feature. Same explicit-override semantics as PGXNTOOL_ENABLE_TEST_BUILD.

    -

    8.10. PGXNTOOL_ENABLE_VERIFY_RESULTS *

    +

    8.11. PGXNTOOL_ENABLE_VERIFY_RESULTS *

    Default: yes. Enables or disables the verify-results safeguard that blocks make results when tests are failing. Setting it to empty on the command line (make PGXNTOOL_ENABLE_VERIFY_RESULTS= results) also disables it.

    -

    8.11. PGXNTOOL_ENABLE_CHECK_STALE_EXPECTED *

    +

    8.12. 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).

    @@ -1956,13 +2012,13 @@

    -

    8.12. PGXNTOOL_CHECK_EXPECTED_FILE_TYPES *

    +

    8.13. 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.

    -

    8.13. PGXNTOOL_NO_PGXS_INCLUDE

    +

    8.14. PGXNTOOL_NO_PGXS_INCLUDE

    Default: unset (PGXS is included normally). Skips including PGXS ($(PGXS)) entirely. This is only for advanced scenarios where you need to manage the PGXS include yourself; most projects should never set this.

    @@ -1983,7 +2039,7 @@

    diff --git a/base.mk b/base.mk index 00dab50..d4faa3c 100644 --- a/base.mk +++ b/base.mk @@ -479,6 +479,42 @@ check-pgtle: run-pgtle: pgtle @$(PGXNTOOL_DIR)/pgtle.sh --run +# Print generated pg_tle registration SQL to stdout, for consumers building +# a combined multi-extension install file, e.g.: +# $(MAKE) --no-print-directory -C ../deps/cat_tools print-pgtle >> pgtle-all.sql +# --no-print-directory is required: GNU Make auto-prints "Entering +# directory"/"Leaving directory" to stdout for recursive invocations like +# this one, which would otherwise corrupt the redirected file. +# Depends on 'pgtle' so the SQL files are (re)generated first. +# Selects the directory via PGXNTOOL_PGTLE_TARGET_VERSION if set (an actual +# pg_tle version like 1.5.2, not a range), otherwise via the installed +# version (pgtle.sh --get-version). Deliberately not named PGTLE_VERSION or +# reusing PGXNTOOL_PGTLE_VERSION: a CI job's PGTLE_VERSION env var means +# "which pg_tle to test against," a concept that can legitimately diverge +# from "which version this printed artifact should target" -- collapsing +# them would silently produce a plausible-but-wrong artifact on divergence. +# PGXNTOOL_PGTLE_VERSION itself holds a range (e.g. 1.5.0+), not an exact +# version, so it can't be reused here either. +.PHONY: print-pgtle +print-pgtle: pgtle + @version="$(PGXNTOOL_PGTLE_TARGET_VERSION)"; \ + if [ -z "$$version" ]; then \ + version=$$($(PGXNTOOL_DIR)/pgtle.sh --get-version 2>/dev/null); \ + if [ -z "$$version" ]; then \ + echo "ERROR: pg_tle version not specified and pg_tle is not installed" >&2; \ + echo " Set PGXNTOOL_PGTLE_TARGET_VERSION=X.Y.Z, or run 'CREATE EXTENSION pg_tle;' first" >&2; \ + exit 1; \ + fi; \ + fi; \ + pgtle_dir=$$($(PGXNTOOL_DIR)/pgtle.sh --get-dir "$$version") || exit 1; \ + $(foreach ext,$(PGXNTOOL_EXTENSIONS),\ + f="$$pgtle_dir/$(ext).sql"; \ + if [ ! -f "$$f" ]; then \ + echo "ERROR: $$f does not exist (run 'make pgtle' first)" >&2; \ + exit 1; \ + fi; \ + cat "$$f";) + # These targets ensure all the relevant directories exist $(TESTDIR)/sql $(TESTDIR)/expected/ $(TESTOUT)/results/: @mkdir -p $@