acvmod: Varnish Cache module creator

Acvmod is a framework for creating loadable modules for Varnish Cache (vmods). It provides a set of macros and templates for configuring the module using GNU autotools and includes several auxiliary tools for creating GNU-style ChangeLog, testsuite, etc.

It is intended to be included as a git submodule to the vmod project repository.

The bootstrap tool is designed to facilitate the task of creating a new vmod from the scratch. It takes a number of options supplying it with the additional data about the module, but in general, creating a new module is as simple as running:

./bootstrap -C $DIR $NAME

where $NAME is the module name and $DIR is the name of the directory where to create the skeleton for the module.

Suppose you start to write a module named vmod-new (traditionally, vmod names are prefixed with vmod_ or vmod-. Acvmod accepts the latter convention). Then, do the following:

1. Clone the acvmod:

   git clone git://git.gnu.org.ua/acvmod.git
   

2. Run

   acvmod/bootstrap -C ~/src/vmod-new --git new
   

The --git option instructs the tool that the module will be under control of Git, so that acvmod will add itself as a submodule.

This command will do the following:

• Create the directory ~/src/vmod-new
• Copy entire acvmod package to this directory
• Initialize an empty Git repository in ~/src/vmod-new
• Register acvmod as a Git submodule in this repository.
• Populate the directory with the files necessary to build a valid Varnish-Cache module
• Add these files to the repository index
• Run autoreconf to create the configure script and Makefiles.

The ~/src/vmod-new will now contain the following files:

COPYING
Makefile.am
acvmod/
configure.ac
m4/
src/
src/Makefile.am
src/vmod_new.c
src/vmod_new.vcc
tests/
tests/Makefile.am 
tests/atlocal.in
tests/testsuite.at

plus the Git infrastructure files and files created by autotools (configure, Makefile.am's, etc.)

Note, that the new project created by bootstrap can already be compiled with the usual commands:

./configure
make

This will produce a module that you can import into your VCL script using the

import new;

statement. Of course, apart from it, the module won't do anything useful, so it's now time to change to ~src/vmod-new, commit the changes and start hacking on the module source files src/vmod_new.c and src/vmod_new.vcc.

bootstrap --gnu \
          --git \
          -C ~/src/vmod-dict \
          --email gray@gnu.org \
          --url http://ps.gnu.org.ua/software/vmod-dict \            
          --description='Dictionary look-up for Varnish Cache' \
          --copying=gnu \
          dict

The AM_VARNISHAPI macro is used in configure.ac to check whether the varnish API components (header files and libraries) are installed and are of sufficiently modern version. The macro is invoked with one optional argument - the oldest required version of the API:

AM_VARNISHAPI([VERSION])

If VERSION argument is supplied, the macro checks if varnish API version is the same or newer than that version number. Otherwise, if package version string ends in -N.N.N, where N stands for a decimal digit, it checks if varnish API version is at least N.N.N. If API is older, it emits error message and aborts. If the version is newer, a warning message is emitted at the end of configure.

The AM_VARNISHAPI macro sets the following configuration variables:

VMODDIR

The path of the varnish module directory.

VARNISH_MAJOR

Major number of the varnish API version.

VARNISH_MINOR

Minor number of the varnish API version.

VARNISH_PATCH

Patchlevel number of the varnish API version.

VARNISHD

Full pathname of the varnishd binary.

VARNISHTEST

Full pathname of the varnishtest binary.

VARNISHAPI_PKGDATADIR

Varnish API package data directory.

VARNISHAPI_VMODTOOL

Absolute pathname of the vmodtool.py script.

The produced configure script determines the location where Varnish looks for loadable modules, and arranges for installing your module there. Most of the time that's what you and the end user would expect. However, there are cases when such behavior is undesirable.

For example, when packaging the module for distribution in binary form, the module should normally go to a temporary installation directory outside of the usual system-wide locations. To make it possible, the generated configure provides the --with-vmoddir option. Argument to this option defines the directory where to install the loadable module.

Another option is --without-vmoddir. If supplied, it instructs configure to follow the the standard practice of installing all files to subdirectories below the installation prefix (by default it is /usr/local; it can be changed via the --prefix command line option). This option is useful for testing the module. In fact, it is used by default when you run make distcheck to test and package your module.

The top.am file is included in the generated top-level Makefile.am. This file defines a rule for creating ChangeLog file from the git log, adds to the distribution the gencl script, used by that rule, and the file testsuite.inc, which provides macros for use in testsuite. It also sets up the distcheck goal to use the --without-vmoddir option, described above.

The project initialized by bootstrap is set up to use the Autotest-based testsuite. The testsuite is located in the directory tests. The stub file testsuite.at includes the file acvmod/testsuite.inc, which defines the AT_VARNISHTEST macro, which we recommend for writing the tests.

The syntax is:

AT_VARNISHTEST($MODULE, $VCL, $CLT [, $SRV])

The arguments are:

$MODULE

Name of the module.

$VCL

The VLC script. It needs not import the module itself.

$CLT

The program to use in the client part of the generated vtc file.

$SRV

The program to use in the server part of the generated vtc file.