Prev  Up  Next
Chapter 21. The Veil2 Implementation: What You Need To Know  Home  Chapter 23. How Veil2 Relates to the Original Veil

If you want to get into the details of the Veil2 implementation, this section is for you.

For most users there will never be any need to build Veil2 locally using anything except the pgxn client as described in the Installation section.

If, however, you wish to hack on the Veil2 internals or documentation, or are just curious you can clone Veil2 from the Veil2 github page, or get a zipped copy from Marc's PGXN pages.

The Veil2 directory structure is pretty flat and very simple:

bin

Home to a small number of helper scripts for the documentation build.

demo

Contains files associated with the demo extensions.

diagrams

Contains diagrams created by dia.

docs

Contains, mostly, xml source files for the documentation system. Is also used for some intermediate files for the documentation build, including the anchors and extracts directories.

html

Created by the docs target from make. Contains generated html documentation. Point your browser to index.html in here to see your latest updated docs.

sql

Contains the SQL sources for Veil2.

src

Contains the C source files for the Veil2 shared library.

test

Scripts for running unit tests on the Veil2 extension.

You may notice makefiles in many sub-directories. These simply change directory to their parent directory before re-running make there. This enables make to be run from any directory in the tree, making builds from tools like emacs much easier.

Veil2 uses a pretty standard autotools-based build system, though the GNUmakefile is largely hand-crafted.

The makefile, GNUmakefile manages all aspects of the build and installation processes. It uses the postgres pgxs build mechanisms to build the shared library and manage the installation of our postgres extensions.

The default target (run make with no parameters) is the C shared library veil2.so. Other targets include:

help

Provides a list of the makefile's major targets.

db

Creates a new clean vpd database into which we can install Veil2.

docs

Creates an html documentation tree including Doxygen documentation.

install

Installs our extensions into the active Postgres environment. This target does not imply a docs build. If you want docs installed you should build them first and then this target will ensure they are installed.

clean

Remove target, intermediate and junk files.

The Veil2 documentation is built using docbook. It is a relatively complex beast though, as there is automated extraction of SQL code, automated creation of diagram images and maps, and linkage with Doxygen documentation. This is what you need to know:

Releasing a new version of Veil2 to the world involves a number of steps. The makefile provides various targets to help in this process, primarily the zipfile target which creates a zipfile for release to PGXN once make is satisfied that all necesary steps have been taken.

Specifically, before creating the zipfile, make insists on the following:

  • that the PGXN metadata file, META.json contains correct filename and version information;

    Specifically, that the version numbers match what is defined in the VERSION file.

  • that there are no uncommitted changes;

  • that the current git branch is master;

    This is particularly necessary as other branches have to be used when uploading documentation to github.

  • that the HEAD branch in git has been tagged;

  • that github and other upstream repositories are up to date with respect to the local git repository;

  • that the latest version of documentation has been published to github pages.

Prev  Up  Next
Chapter 21. The Veil2 Implementation: What You Need To Know  Home  Chapter 23. How Veil2 Relates to the Original Veil