From b1b9e8a2005984129c09fe4b56f943686ed72ad9 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Wed, 7 Oct 2026 16:11:12 -0500 Subject: [PATCH] Fix stale and inaccurate user docs found in 2.4.0 release review README.asc: - PGXNTOOL_PGTLE_VERSION takes an exact range name (e.g. 1.5.0+), not a plain version mapped to a range; a plain version creates a bogus pg_tle// directory. Fix the example and both descriptions. - make test: document the FS_INSTALL gating of install and the two safeguard checks (stale expected files, test/install ON_ERROR_STOP); test files run in byte-value order, not alphabetical; drop history narration from the exit-status note. - PGXNTOOL_ENABLE_FS_INSTALL=no also drops test-build's install prerequisite. - tag pushes to $(PGXN_REMOTE), not always origin. - test/install layout: there is no test/install/.gitignore. - testdeps/pgtap is a no-op with PGXNTOOL_ENABLE_PGXN_INSTALL=no; installcheck reaches all only through install. - Document the built-in pgxntool-sync-master/-local/-local-master sources, PGXNTOOL_POST_TAG_VERSION's allowed characters, and bin/version's optional history-file argument. - Fix the <<_Document_Handling>> cross-reference's case. CLAUDE.md: canonical repo URL, .asc doc extension, and the full make test chain with its gating and safeguard checks. pgtle.sh: comment/message-only changes (canonical repo URL, SEE ALSO pointing at README.asc's pg_tle Support section). README.html regenerated with asciidoctor. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 13 ++-- README.asc | 46 +++++++++------ README.html | 167 ++++++++++++++++++++++++++++++++++------------------ pgtle.sh | 6 +- 4 files changed, 149 insertions(+), 83 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c13877c..cca492c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -91,7 +91,7 @@ https://github.com/Postgres-Extensions/pgxntool-test Extension projects include pgxntool via git subtree: ```bash -git subtree add -P pgxntool --squash git@github.com:decibel/pgxntool.git release +git subtree add -P pgxntool --squash git@github.com:Postgres-Extensions/pgxntool.git release pgxntool/setup.sh ``` @@ -151,7 +151,7 @@ project/ │ ├── deps.sql # Load extension and test dependencies │ ├── sql/*.sql # Test SQL files │ └── expected/*.out # Expected test outputs -└── doc/ # Optional docs (*.adoc, *.asciidoc) +└── doc/ # Optional docs (*.adoc, *.asciidoc, *.asc) ``` ## Commands for Extension Developers (End Users) @@ -160,7 +160,7 @@ These are the commands extension developers use (documented for context): ```bash make # Build extension (generates versioned SQL, docs) -make test # Full test: testdeps → install → installcheck → show diffs +make test # Full test: testdeps → [test-build] → [install] → installcheck → safeguard checks → show diffs ([...] = when enabled; see Critical Testing Rules) make results # Run tests and update expected output files make html # Generate HTML from Asciidoc sources make tag # Create git tag for current META.json version @@ -176,9 +176,10 @@ make pgxntool-sync # Update to latest pgxntool via git subtree pull ### Critical Testing Rules **NEVER use `make installcheck` directly**. Always use `make test` instead. The `make test` target ensures: -- Correct test dependency installation (`testdeps`, and `test-build` when enabled) -- Extension is installed before tests run (`install`) +- Correct test dependency installation (`testdeps`, and `test-build` when enabled); `testdeps`' default `pgtap` prerequisite auto-installs pgtap via `pgxn install`, a no-op when `PGXNTOOL_ENABLE_PGXN_INSTALL=no` +- Extension is filesystem-installed before tests run (`install`), unless `PGXNTOOL_ENABLE_FS_INSTALL=no` - Test comparison via `installcheck`, with diffs shown on failure +- Safeguard checks that fail the run: the stale-expected-file check (orphaned or non-`.out` files in `test/expected/`, run after `pg_regress`), and, when `test/install` is in use, the check that every `test/install/*.sql` file sets `ON_ERROR_STOP` Note: `make test` intentionally does *not* depend on `clean` — depending on `clean` caused problems with incremental/watch-based builds (see `base.mk`). If your tests need a clean build to pass, that's a sign of a missing dependency elsewhere, not something to fix by adding `clean` back. @@ -223,7 +224,7 @@ When tests fail, examine the diff output carefully. The actual test output in `t ### Document Generation - Auto-detects `asciidoctor` or `asciidoc` -- Generates HTML from `*.adoc` and `*.asciidoc` in `$(DOC_DIRS)` +- Generates HTML from `*.adoc`, `*.asciidoc` and `*.asc` in `$(DOC_DIRS)` - HTML required for `make dist`, optional for `make install` - Template-based rules via `ASCIIDOC_template` diff --git a/README.asc b/README.asc index 012943c..11df229 100644 --- a/README.asc +++ b/README.asc @@ -42,7 +42,7 @@ These are the make targets that are provided by base.mk NOTE: all the targets normally provided by Postgres http://www.postgresql.org/docs/current/static/extend-pgxs.html[PGXS] still work. If you need to skip PGXS being included entirely (for advanced/non-standard setups), set `PGXNTOOL_NO_PGXS_INCLUDE` in your Makefile before `include pgxntool/base.mk`. === html -This will build any .html files that can be created. See <<_Document_Handling>>. +This will build any .html files that can be created. See <<_document_handling>>. === check-duplicate-docs Warns if two `$(DOCS)` entries would install to the same filename, which would otherwise fail `make install`. @@ -50,20 +50,25 @@ Warns if two `$(DOCS)` entries would install to the same filename, which would o `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. === 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>>. +Runs your extension's test suite: filesystem-installs the extension (unless `PGXNTOOL_ENABLE_FS_INSTALL=no`) 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>>. + +`make test` also fails on two safeguard checks: + +- The stale-expected-file check, run after `pg_regress` finishes: fails if `test/expected/` (or `test/build/expected/`) has a `.out` file with no matching `.sql`, or a file that isn't `.out`. See <<_pgxntool_enable_check_stale_expected>>. +- When <<_testinstall,test/install>> is in use, the `ON_ERROR_STOP` check: fails if any `test/install/*.sql` file neither includes `test/pgxntool/psql.sql` nor sets `ON_ERROR_STOP` itself. See <<_pgxntool_enable_test_install_error_stop_check>>. `make test` runs `pg_regress` in up to two separate passes: 1. If <<_test_build,test-build>> is enabled, it runs first, in its own isolated pass over `test/build/*.sql`. If it fails, the second pass never happens — there's no point checking install/query behavior against a build that doesn't even come up cleanly. 2. The main pass follows: any <<_testinstall,test/install>> files, then your regular `test/sql/*.sql` files, together in a single `pg_regress` invocation (so state the install files create persists into the regular tests). -Within each pass, files run in alphabetical order by filename. +Within each pass, files run in byte-value (ASCII) order of their filenames. Whether `test-build` runs is controlled by the `PGXNTOOL_ENABLE_TEST_BUILD` variable — see <<_test_build>> for what it does and how to turn it on/off. NOTE: `test` intentionally does *not* depend on `clean` — that caused problems with incremental/watch-based builds. If your tests need a clean build to pass, that's a sign of a missing dependency elsewhere rather than something to fix by adding `clean` back. -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. +NOTE: `test` exits non-zero (after printing `regression.diffs`) if any test fails, so CI and other automation can rely on its exit code. 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. @@ -175,11 +180,10 @@ Runs setup files before the main test suite within the same `pg_regress` invocat test/install/ ├── *.sql # SQL setup files (checked in) ├── *.out # GENERATED, gitignored -- see WARNING below -├── .gitignore # Ignores pg_regress artifacts (*.out.diff) -└── schedule # GENERATED - auto-created by make +└── schedule # GENERATED, gitignored - auto-created by make ---- -The `schedule` file is generated automatically and listed in `.gitignore`. Do not edit it. `*.out` is gitignored too, for the reason explained below — don't commit it. +The `schedule` file is generated automatically and listed in the top-level `.gitignore` that `setup.sh` installs. Do not edit it. `*.out` is gitignored too, for the reason explained below — don't commit it. **Ordering:** Install files run in plain byte-value (ASCII) order of their filenames, guaranteed regardless of filesystem or locale. If one install file depends on another having already run, encode that dependency in the filenames themselves (e.g. `01_roles.sql` before `02_extension.sql`). @@ -237,7 +241,7 @@ NOTE: This pattern isn't (yet) native to pgxntool — you wire up the mode selec - https://github.com/Postgres-Extensions/pg_count_nulls/blob/9f088ac36f6345023bb5b3d20ad0e4aa6ade0d69/test/sql/extension_tests.sql[pg_count_nulls `test/sql/extension_tests.sql`] additionally demonstrates testing an extension installed into a non-default schema. It's a useful reference for that specific problem, but it also defines its assertions as plpgsql functions rather than plain pgTAP calls — a pattern that adds complexity of its own and isn't recommended as a model for U&U testing itself. === 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 http://pgtap.org[pgtap] from PGXN. This depneds on having the pgxn client installed. +This rule allows you to ensure certain actions have taken place before running tests. By default it has a single prerequisite, `pgtap`, which installs http://pgtap.org[pgtap] from PGXN (via the pgxn client) if it isn't already filesystem-installed. `pgtap` is a no-op when `PGXNTOOL_ENABLE_PGXN_INSTALL=no`; see <<_pgxntool_enable_pgxn_install>>. You can add any other dependencies you want by simply adding another `testdeps` rule. For example: @@ -293,7 +297,7 @@ make PGXNTOOL_ENABLE_VERIFY_RESULTS=no results ---- === 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 link:releasing-with-pgxntool.md[releasing-with-pgxntool.md]. +`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 `$(PGXN_REMOTE)` (`origin` by default; see <<_pgxn_remote>>). 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 link:releasing-with-pgxntool.md[releasing-with-pgxntool.md]. If a tag for the current version already exists and points at your current commit, `make tag` does nothing — this makes it safe for other targets (like `dist`) to depend on `tag` without worrying about re-running it. If the existing tag points at a *different* commit — meaning you likely forgot to bump the version — you'll get an error. If you're certain you want to over-write the tag, you can do `make forcetag`, which removes the existing tag (via `make rmtag`) and creates a new one. @@ -329,12 +333,18 @@ TIP: The actual work is done by `pgxntool/pgxntool-sync.sh`, so you can run it d TIP: `pgxntool-sync.sh` itself delegates the 3-way merge of `setup.sh`-copied files to `pgxntool/update-setup-files.sh `, which you can also run directly -- for example, to redo or debug just the merge step without pulling again. `` is the pgxntool subtree commit that was current *before* the sync you want to re-merge. -TIP: There is also a `pgxntool-sync-%` rule if you need to do more advanced things. `make pgxntool-sync-` pulls from the ` ` defined by the `pgxntool-sync-` make variable. +TIP: There is also a `pgxntool-sync-%` rule if you need to do more advanced things. `make pgxntool-sync-` pulls from the ` ` defined by the `pgxntool-sync-` make variable. Three are built in: + +`pgxntool-sync-master`:: `https://github.com/Postgres-Extensions/pgxntool.git master` -- the unreleased development branch. +`pgxntool-sync-local`:: `../pgxntool release` -- the `release` branch of a sibling `../pgxntool` checkout. +`pgxntool-sync-local-master`:: `../pgxntool master` -- the `master` branch of that sibling checkout. + +CAUTION: Syncing from anything other than a release can add unwanted history to your repo and make later merges harder to resolve. === 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. -TIP: The actual work is done by `pgxntool/bin/version`, so you can run it directly (`pgxntool/bin/version`) if you'd rather not go through `make`. +TIP: The actual work is done by `pgxntool/bin/version`, so you can run it directly (`pgxntool/bin/version`) if you'd rather not go through `make`. It optionally takes a `` argument to read instead of `pgxntool/HISTORY.asc`. It exits non-zero if that file is missing, empty, or its first line is neither `STABLE` nor an `X.Y.Z` version. === 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. @@ -357,12 +367,14 @@ Generates pg_tle (Trusted Language Extensions) registration SQL files for deploy `make pgtle` generates SQL files in `pg_tle/` subdirectories organized by pg_tle version ranges. For version range details, see `pgtle_versions.md`. -Set `PGXNTOOL_PGTLE_VERSION` on the command line to limit generation to the single version range that value falls into, instead of every known range: +Set `PGXNTOOL_PGTLE_VERSION` on the command line to a range name (`1.0.0-1.4.0`, `1.4.0-1.5.0` or `1.5.0+`) to generate only that range instead of every known range: ---- -make pgtle PGXNTOOL_PGTLE_VERSION=1.5.0 +make pgtle PGXNTOOL_PGTLE_VERSION=1.5.0+ ---- +The value must be one of those range names exactly; it is not mapped from a plain pg_tle version. Any other value (e.g. `1.5.0`) is not validated and produces a bogus `pg_tle/1.5.0/` directory. + === 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 @@ -575,7 +587,7 @@ PGXNtool replaces each `$(ASCIIDOC_EXTS)` in `$(ASCIIDOC_FILES)` with `html`. The result is appended to `ASCIIDOC_HTML` using `+=`. === Document Rules -If Asciidoc is found (or `$(ASCIIDOC)` is set), `html` is added as a dependency of the `all` target, which both `install` and `installcheck` depend on — so docs get built for install and test, but only if Asciidoc is available. +If Asciidoc is found (or `$(ASCIIDOC)` is set), `html` is added as a dependency of the `all` target, which `install` depends on (and `installcheck` reaches through `install` when `PGXNTOOL_ENABLE_FS_INSTALL=yes`) — so docs get built for install and test, but only if Asciidoc is available. The `dist` rule always depends on `html` directly, regardless of whether Asciidoc was found, to ensure html files are up-to-date before creating a distribution. The `html` rule simply depends on `$(ASCIIDOC_HTML). @@ -746,7 +758,7 @@ make dist PGXN_REMOTE=upstream === PGXNTOOL_POST_TAG_VERSION -Default: `stable`. The placeholder value `make post-tag-version-bump` sets `default_version` to. Not valid semver, but PostgreSQL doesn't require semver for extension versions. If you override this, also update the `sql/*--stable.sql` line and its `!sql/*--*--stable.sql` negation (which keeps the `{old}--stable` update script tracked) in your `.gitignore` to match. +Default: `stable`. The placeholder value `make post-tag-version-bump` sets `default_version` to. It must be non-empty and contain only ASCII letters, digits, `.` and `-`; anything else makes `post-tag-version-bump` fail. Not valid semver, but PostgreSQL doesn't require semver for extension versions. If you override this, also update the `sql/*--stable.sql` line and its `!sql/*--*--stable.sql` negation (which keeps the `{old}--stable` update script tracked) in your `.gitignore` to match. === ASCIIDOC @@ -754,7 +766,7 @@ Default: auto-detected, the first of `asciidoctor` or `asciidoc` found on `PATH` === PGXNTOOL_PGTLE_VERSION -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>>. +Default: unset (generates every known pg_tle version range). Set on the command line to a range name (`1.0.0-1.4.0`, `1.4.0-1.5.0` or `1.5.0+`, exactly) to limit `make pgtle` to that one range; any other value is passed through unvalidated and generates a bogus `pg_tle//` directory. 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 @@ -798,7 +810,7 @@ Default: `yes`. Enables or disables a build-time check that every `test/install/ === PGXNTOOL_ENABLE_FS_INSTALL * -Default: `yes`. Controls whether `install` is a prerequisite of `test`/`verify-results`, and whether `installcheck` depends on `install`. Set to `no` for "existing mode" testing, where the extension under test was deployed some other way (e.g. registered via pg_tle instead of the filesystem, or installed by a binary pg_upgrade) -- with this set, `make test`/`make installcheck`/`make verify-results` run against whatever is already installed instead of filesystem-installing first. +Default: `yes`. Controls whether `install` is a prerequisite of `test`/`verify-results`, and whether `installcheck` and <<_test_build,test-build>> depend on `install`. Set to `no` for "existing mode" testing, where the extension under test was deployed some other way (e.g. registered via pg_tle instead of the filesystem, or installed by a binary pg_upgrade) -- with this set, `make test`/`make installcheck`/`make verify-results` run against whatever is already installed instead of filesystem-installing first. === PGXNTOOL_ENABLE_PGXN_INSTALL * diff --git a/README.html b/README.html index 013c61c..e12c0de 100644 --- a/README.html +++ b/README.html @@ -449,24 +449,25 @@

PGXNtool

  • 4. make targets
  • 5. Version-Specific SQL Files @@ -614,13 +615,35 @@

    4.1. html

    -

    This will build any .html files that can be created. See [_Document_Handling].

    +

    This will build any .html files that can be created. See Document Handling.

    -

    4.2. test

    +

    4.2. check-duplicate-docs

    -

    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.

    +

    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: filesystem-installs the extension (unless PGXNTOOL_ENABLE_FS_INSTALL=no) 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.

    +
    +
    +

    make test also fails on two safeguard checks:

    +
    +
    +

    make test runs pg_regress in up to two separate passes:

    @@ -636,7 +659,7 @@

    -

    Within each pass, files run in alphabetical order by filename.

    +

    Within each pass, files run in byte-value (ASCII) order of their filenames.

    Whether test-build runs is controlled by the PGXNTOOL_ENABLE_TEST_BUILD variable — see test-build for what it does and how to turn it on/off.

    @@ -660,7 +683,7 @@

    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. +test exits non-zero (after printing regression.diffs) if any test fails, so CI and other automation can rely on its exit code. @@ -682,7 +705,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 +825,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 +848,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.

    @@ -853,12 +876,11 @@

    test/install/ ├── *.sql # SQL setup files (checked in) ├── *.out # GENERATED, gitignored -- see WARNING below -├── .gitignore # Ignores pg_regress artifacts (*.out.diff) -└── schedule # GENERATED - auto-created by make +└── schedule # GENERATED, gitignored - auto-created by make

    -

    The schedule file is generated automatically and listed in .gitignore. Do not edit it. *.out is gitignored too, for the reason explained below — don’t commit it.

    +

    The schedule file is generated automatically and listed in the top-level .gitignore that setup.sh installs. Do not edit it. *.out is gitignored too, for the reason explained below — don’t commit it.

    Ordering: Install files run in plain byte-value (ASCII) order of their filenames, guaranteed regardless of filesystem or locale. If one install file depends on another having already run, encode that dependency in the filenames themselves (e.g. 01_roles.sql before 02_extension.sql).

    @@ -910,7 +932,7 @@

    -

    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,9 +1008,9 @@

    -

    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.

    +

    This rule allows you to ensure certain actions have taken place before running tests. By default it has a single prerequisite, pgtap, which installs pgtap from PGXN (via the pgxn client) if it isn’t already filesystem-installed. pgtap is a no-op when PGXNTOOL_ENABLE_PGXN_INSTALL=no; see PGXNTOOL_ENABLE_PGXN_INSTALL *.

    You can add any other dependencies you want by simply adding another testdeps rule. For example:

    @@ -1022,7 +1044,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 +1080,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,9 +1126,9 @@

    -

    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.

    +

    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 $(PGXN_REMOTE) (origin by default; see PGXN_REMOTE). 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.

    If a tag for the current version already exists and points at your current commit, make tag does nothing — this makes it safe for other targets (like dist) to depend on tag without worrying about re-running it. If the existing tag points at a different commit — meaning you likely forgot to bump the version — you’ll get an error. If you’re certain you want to over-write the tag, you can do make forcetag, which removes the existing tag (via make rmtag) and creates a new one.

    @@ -1125,13 +1147,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 +1162,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 +1195,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).

    @@ -1232,14 +1254,42 @@

    Tip

    -There is also a pgxntool-sync-% rule if you need to do more advanced things. make pgxntool-sync-<name> pulls from the <repo> <ref> defined by the pgxntool-sync-<name> make variable. +There is also a pgxntool-sync-% rule if you need to do more advanced things. make pgxntool-sync-<name> pulls from the <repo> <ref> defined by the pgxntool-sync-<name> make variable. Three are built in: + + + +
    +
    +
    +
    pgxntool-sync-master
    +
    +

    https://github.com/Postgres-Extensions/pgxntool.git master — the unreleased development branch.

    +
    +
    pgxntool-sync-local
    +
    +

    ../pgxntool release — the release branch of a sibling ../pgxntool checkout.

    +
    +
    pgxntool-sync-local-master
    +
    +

    ../pgxntool master — the master branch of that sibling checkout.

    +
    +
    +
    +
    + + + +
    +
    Caution
    +    		 +Syncing from anything other than a release can add unwanted history to your repo and make later merges harder to resolve.
    -

    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.

    @@ -1250,26 +1300,26 @@

    Tip

    -The actual work is done by pgxntool/bin/version, so you can run it directly (pgxntool/bin/version) if you’d rather not go through make. +The actual work is done by pgxntool/bin/version, so you can run it directly (pgxntool/bin/version) if you’d rather not go through make. It optionally takes a <history-file> argument to read instead of pgxntool/HISTORY.asc. It exits non-zero if that file is missing, empty, or its first line is neither STABLE nor an X.Y.Z version.
    -

    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 +1345,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.

    @@ -1303,16 +1353,19 @@

    -

    Set PGXNTOOL_PGTLE_VERSION on the command line to limit generation to the single version range that value falls into, instead of every known range:

    +

    Set PGXNTOOL_PGTLE_VERSION on the command line to a range name (1.0.0-1.4.0, 1.4.0-1.5.0 or 1.5.0+) to generate only that range instead of every known range:

    -
    make pgtle PGXNTOOL_PGTLE_VERSION=1.5.0
    +
    make pgtle PGXNTOOL_PGTLE_VERSION=1.5.0+
    +
    +

    The value must be one of those range names exactly; it is not mapped from a plain pg_tle version. Any other value (e.g. 1.5.0) is not validated and produces a bogus pg_tle/1.5.0/ directory.

    +
    -

    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 +1381,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 +1418,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 @@ -1713,7 +1766,7 @@

    <

    6.2. Document Rules

    -

    If Asciidoc is found (or $(ASCIIDOC) is set), html is added as a dependency of the all target, which both install and installcheck depend on — so docs get built for install and test, but only if Asciidoc is available. +

    If Asciidoc is found (or $(ASCIIDOC) is set), html is added as a dependency of the all target, which install depends on (and installcheck reaches through install when PGXNTOOL_ENABLE_FS_INSTALL=yes) — so docs get built for install and test, but only if Asciidoc is available. The dist rule always depends on html directly, regardless of whether Asciidoc was found, to ensure html files are up-to-date before creating a distribution.

    @@ -2023,7 +2076,7 @@

    8.2. PGXNTOOL_POST_TAG_VERSION

    -

    Default: stable. The placeholder value make post-tag-version-bump sets default_version to. Not valid semver, but PostgreSQL doesn’t require semver for extension versions. If you override this, also update the sql/--stable.sql line and its !sql/--*--stable.sql negation (which keeps the {old}--stable update script tracked) in your .gitignore to match.

    +

    Default: stable. The placeholder value make post-tag-version-bump sets default_version to. It must be non-empty and contain only ASCII letters, digits, . and -; anything else makes post-tag-version-bump fail. Not valid semver, but PostgreSQL doesn’t require semver for extension versions. If you override this, also update the sql/--stable.sql line and its !sql/--*--stable.sql negation (which keeps the {old}--stable update script tracked) in your .gitignore to match.

    @@ -2035,7 +2088,7 @@

    8.4. PGXNTOOL_PGTLE_VERSION

    -

    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.

    +

    Default: unset (generates every known pg_tle version range). Set on the command line to a range name (1.0.0-1.4.0, 1.4.0-1.5.0 or 1.5.0+, exactly) to limit make pgtle to that one range; any other value is passed through unvalidated and generates a bogus pg_tle/<value>/ directory. 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.

    @@ -2101,7 +2154,7 @@

    8.13. PGXNTOOL_ENABLE_FS_INSTALL *

    -

    Default: yes. Controls whether install is a prerequisite of test/verify-results, and whether installcheck depends on install. Set to no for "existing mode" testing, where the extension under test was deployed some other way (e.g. registered via pg_tle instead of the filesystem, or installed by a binary pg_upgrade) — with this set, make test/make installcheck/make verify-results run against whatever is already installed instead of filesystem-installing first.

    +

    Default: yes. Controls whether install is a prerequisite of test/verify-results, and whether installcheck and test-build depend on install. Set to no for "existing mode" testing, where the extension under test was deployed some other way (e.g. registered via pg_tle instead of the filesystem, or installed by a binary pg_upgrade) — with this set, make test/make installcheck/make verify-results run against whatever is already installed instead of filesystem-installing first.

    @@ -2164,7 +2217,7 @@

    diff --git a/pgtle.sh b/pgtle.sh index e6229fd..b891e7d 100755 --- a/pgtle.sh +++ b/pgtle.sh @@ -2,7 +2,7 @@ # # pgtle.sh - Generate pg_tle registration SQL for PostgreSQL extensions # -# Part of pgxntool: https://github.com/decibel/pgxntool +# Part of pgxntool: https://github.com/Postgres-Extensions/pgxntool # # SYNOPSIS # pgtle.sh --extension EXTNAME [--pgtle-version VERSION] @@ -112,7 +112,7 @@ # 1 Error (missing files, validation failure, C code detected, etc.) # # SEE ALSO -# pgxntool/README-pgtle.md - Complete user guide +# pgxntool/README.asc, "pg_tle Support" section - Complete user guide # https://github.com/aws/pg_tle - pg_tle documentation # @@ -620,7 +620,7 @@ validate_delimiter() { Found: $PGTLE_DELIMITER This delimiter is used internally by pgtle.sh to wrap SQL content. You must modify your SQL to not contain this string. If this poses a - serious problem, please open an issue at https://github.com/decibel/pgxntool/issues" + serious problem, please open an issue at https://github.com/Postgres-Extensions/pgxntool/issues" fi }