PGXNtool

Table of Contents

• 1. Install
• 2. Usage
• 3. make targets
  • 3.1. html
  • 3.2. test
  • 3.3. testdeps
  • 3.4. results
  • 3.5. tag
  • 3.6. dist
  • 3.7. pgxntool-sync
• 4. Document Handling
  • 4.1. Document Variables
  • 4.2. Document Rules
  • 4.3. The DOCS variable
• 5. Copyright

PGXNtool is meant to make developing new Postgres extensions for PGXN easier.

Currently, it consists a base Makefile that you can include instead of writing your own, a template META.json, and some test framework. More features will be added over time.

If you find any bugs or have ideas for improvements, please open an issue.

1. Install

This assumes that you’ve already initialized your extension in git.

Note	The --squash is important! Otherwise you’ll clutter your repo with a bunch of commits you probably don’t want.

git subtree add -P pgxntool --squash [email protected]:decibel/pgxntool.git release
pgxntool/setup.sh

TODO: Create a nice script that will init a new project for you.

2. Usage

Typically, you can just create a simple Makefile that does nothing but include base.mk:

include pgxntool/base.mk

3. make targets

These are the make targets that are provided by base.mk

Note	all the targets normally provided by Postgres PGXS still work.

3.1. html

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

3.2. test

Runs unit tests via the PGXS installcheck target. Unlike a simple make installcheck though, the test rule has the following prerequisites: clean testdeps install installcheck. All of those are PGXS rules, except for testdeps.

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

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

testdeps example from test_factory

testdeps: check_control

.PHONY: check_control
check_control:
	grep -q "requires = 'pgtap, test_factory'" test_factory_pgtap.control

If you want to over-ride the default dependency on pgtap you should be able to do that with a makefile override. If you need help with that, please open an issue.

Warning

It will probably cause problems if you try to create a testdeps rule that has a recipe. Instead of doing that, put the recipe in a separate rule and make that rule a prerequisite of testdeps as show in the example.

3.4. 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! The extra effort of learning pgTap will quickly pay for itself. This example might help get you started.

No matter what method you use, once you know that all your tests are passing correctly, you need to create or update the test output expected files. make results does that for you.

3.5. tag

make tag will create a git branch for the current version of your extension, as determined by the META.json file. The reason to do this is so you can always refer to the exact code that went into a released version.

If there’s already a tag for the current version that probably means you forgot to update META.json, so 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.

Warning

You will be very unhappy if you forget to update the .control file for your extension! There is an open issue to improve this.

3.6. dist

make dist will create a .zip file for your current version that you can upload to PGXN. The file is named after the PGXN name and version (the top-level "name" and "version" attributes in META.json). The .zip file is placed in the parent directory so as not to clutter up your git repo.

Note	Part of the clean recipe is cleaning up these .zip files. If you accidentally clean before uploading, just run make dist-only.

3.7. pgxntool-sync

This rule will pull down the latest released version of PGXNtool via git subtree pull.

Note	Your repository must be clean (no modified files) in order to run this. Running this command will produce a git commit of the merge.

Tip	There is also a pgxntool-sync-% rule if you need to do more advanced things.

4. Document Handling

PGXNtool supports generation and installation of document files. There are several variables and rules that control this behavior.

It is recommended that you commit any generated documentation files (such as HTML generated from Asciidoc) into git. That way users will have these files installed when they install your extension. If any generated files are missing (or out-of-date) during installation, PGXNtool will build them if Asciidoc is present on the system.

4.1. Document Variables

DOC_DIRS

Directories to look for documents in. Defined as += doc.

DOCS

PGXS variable. See [_the_docs_variable] below.

DOCS_HTML

Document HTML files. PGXNtool appends `$(ASCIIDOC_HTML) to this variable.

ASCIIDOC

Location of asciidoc or equivalent executable. If not set PGXNtool will search for first asciidoctor, then asciidoc.

ASCIIDOC_EXTS

File extensions to consider as Asciidoc. Defined as += adoc asciidoc.

ASCIIDOC_FILES

Asciidoc input files. PGXNtool searches each $(DOC_DIRS) directory, looking for files with any $(ASCIIDOC_EXTS) extension. Any files found are added to ASCIIDOC_FILES using +=.

ASCIIDOC_FLAGS

Additional flags to pass to Asciidoc.

ASCIIDOC_HTML

PGXNtool replaces each $(ASCIIDOC_EXTS) in $(ASCIIDOC_FILES) with html. The result is appended to ASCIIDOC_HTML using +=.

4.2. Document Rules

If Asciidoc is found (or $(ASCIIDOC) is set), the html rule will be added as a prerequisite to the install and installchec rules. That will ensure that docs are generated for install and test, but only if Asciidoc is available. The dist rule will always depend on html though, to ensure html files are up-to-date before creating a distribution.

The html rule simply depends on `$(ASCIIDOC_HTML). This rule is always present.

For each Asciidoc extension in $(ASCIIDOC_EXTS) a rule is generated to build a .html file from that extension using $(ASCIIDOC). These rules are generated from ASCIIDOC_template:

ASCIIDOC_template

define ASCIIDOC_template
%.html: %.$(1) # (1)
ifndef ASCIIDOC
	$$(warning Could not find "asciidoc" or "asciidoctor". Add one of them to your PATH,)
	$$(warning or set ASCIIDOC to the correct location.)
	$$(error Could not build %$$@)
endif # ifndef ASCIIDOC
	$$(ASCIIDOC) $$(ASCIIDOC_FLAGS) $$<
endef # define ASCIIDOC_template

1. $(1) is replaced by the extension.

These rules will always exist, even if $(ASCIIDOC) isn’t set (ie: if Asciidoc wasn’t found on the system). These rules will throw an error if they are run if $(ASCIIDOC) isn’t defined. On a normal user system that should never happen, because the html rule won’t be included in install or installcheck.

4.3. The DOCS variable

This variable has special meaning to PGXS. See the Postgres documentation for full details.

If DOCS is defined when PGXS is included then rules will be added to install everything defined by $(DOCS) in PREFIX/share/doc/extension.

Note	If DOCS is defined but empty some of the PGXS targets will error out. Because of this, base.mk will forcibly define it to be NULL if it’s empty.

PGXNtool appends all files found in all $(DOC_DIRS) to DOCS.

5. Copyright

Copyright (c) 2015 Jim Nasby <[email protected]>

PGXNtool is released under a BSD license. Note that it includes JSON.sh, which is released under a MIT license.