- Chapter 22. For Developers
- 22.1. Performing Local Builds
- 22.2. Running Unit Tests
- 22.3. The Documentation Build
- 22.4. Releases
|Chapter 21. The Veil2 Implementation: What You Need To Know||Home|| Chapter 23. How
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.
Veil2 directory structure is pretty
flat and very simple:
Home to a small number of helper scripts for the documentation build.
Contains files associated with the demo extensions.
Contains diagrams created by dia.
Contains, mostly, xml source files for the documentation system. Is also used for some intermediate files for the documentation build, including the
Created by the
docstarget from make. Contains generated html documentation. Point your browser to
index.htmlin here to see your latest updated docs.
Contains the SQL sources for
Contains the C source files for the
Scripts for running unit tests on the
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
You should be able to install Veil2 on any operating system,
though something Unix-like is recommended, as we use
gnu make for a lot of tasks.
Your requirements will depend on what you are trying to do.
- a C build environment (gcc, llvm, or some such);
- a currently supported version of Postgres.
Veil2 uses a pretty standard
autotools-based build system, though the
GNUmakefile is largely hand-crafted.
There should be no need to re-run
autoconf unless new dependencies for
documentation builds, etc need to be discovered. In this
case you would
Manually update the
- Run autoconf.
This would update the
which you would then re-run as shown below.
./configure script should be run any
time that you need to bump the
version. You will update the
file, and then run
Makefile.global, which is
You would also run the
after any updates to
which you might make if you need to change compilation flags
or some such.
GNUmakefile manages all
aspects of the build and installation processes. It uses
pgxs build mechanisms to
build the shared library and manage the installation of our
The default target (run
make with no
parameters) is the C shared library veil2.so. Other targets
Provides a list of the makefile's major targets.
Creates a new clean vpd database into which we can install
Creates an html documentation tree including Doxygen documentation.
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.
Remove target, intermediate and junk files.
Veil2 unit tests can be run from
make using the
target. They require the postgres unit testing extension
The tests leave no residue in the test database, so can be run
on any clean database. By default the
database will be used, but this can be changed by providing
make with a value for
marc:veil2$ make unit TESTDB=veil_unit_test_db Creating database veil_unit_test_db... CREATE DATABASE Performing unit tests... Running Veil2 unit tests... . . .
This test database can be dropped using:
marc:veil2$ make drop TESTDB=veil_unit_test_db Dropping database veil_unit_test_db... Pager usage is off. DROP DATABASE marc:veil2$
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:
There is a lot of nasty shell scripting involved. Trying to do this in a non-Unix environment is probably not an option.
Images are converted into
.png files from
.dia sources using
pstoimg, which on Debian comes from the
latex2html package. This is done by a
%.png: %.dia rule in the makefile.
The ERD and Views diagrams in the html documentation provide
clickable links. The maps for these are generated via
.coords targets, again created by rules in
The process for generating the map files is best discovered, if you need it, by exploring the code, starting from the makefile.
The Appendices A, B and C contain documentation that is largely automatically generated from the main veil SQL script. The extracts are created from the makefile by some fairly ugly shell scripts. Look for targets containing the word extract in the makefile.
The individual extract files are processed into the docbook
sql-definition xsl processing
instruction directives in the xml sources. These are handled
by an xsl template defined in the
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
is satisfied that all necesary steps have been taken.
Specifically, before creating the zipfile,
make insists on the following:
META.jsoncontains correct filename and version information;
Specifically, that the version numbers match what is defined in the
that there are no uncommitted changes;
that the current
This is particularly necessary as other branches have to be used when uploading documentation to
githas been tagged;
that github and other upstream repositories are up to date with respect to the local
that the latest version of documentation has been published to github pages.