acvmod: Varnish Cache module creator
Table of Contents
1 Overview
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.
2 Creating new vmod
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:
- Clone the acvmod:
git clone git://git.gnu.org.ua/acvmod.git
- 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
.
2.1 Bootstrap options
The sample bootstrap invocation discussed above creates the module
sources using the default settings. To customize them, a number of
options are provided. You can always get a comprehensive summary of
these by running bootstrap --help
.
2.1.1 Strictness level
Automake strictness level defines how stringently Automake checks
standards conformance when creating Makefile.in
files. Three
mutually exclusive options are provided to control strictness:
--foreign
, --gnu
, and --gnits
. The default is --foreign
.
If --gnu
is used, the following additional files will be created:
AUTHORS
, NEWS
, README
, and ChangeLog
. The top-level
Makefile.am
file will include a rule for updating the latter from
the git commit history.
If --gnits
is specified, the above files and the file THANKS
will
be created.
2.1.2 Module description and URL
--version=N
- Sets module version number. Default value is 0.1.
--description=TEXT
- One-line textual description of the module.
It will be included in the
$Module
line of the created vcc file, and subsequently in the generated manpage. Default text isNo description yet
. --url=URL
- URL of the project's web page. It is mentioned, among
others, in the generated
README
file. --copying=FILE
- Name of the file containing short license text,
which will be reproduced in heading comments of each created
source file. Unless FILE begins with a directory separator
(
/
, or./
. or../
) it will be looked first in theacvmod/copying
subdirectory, and if not found there, in the current working directory.
2.1.3 Personal information
Some of the created files contain the author's personal information, such as email and real name. The bootstrap tool will do its best to deduce this information from the system user database. Use the following two options if it guesses wrong:
--email=EMAIL
- Sets your email address. The default is your user
name, followed by the
@
-sign, followed by the hostname of the machine on which bootstrap is run. --real-name=TEXT
- Your real-world name. By default it is looked up
in the Gecos field of your
/etc/passwd
record.
2.2 Another example
The following command was used to create initial set up of the vmod-dict module:
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
3 The AM_VARNISHAPI
macro
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.
4 Module installation directory
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.
5 The top.am
file
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.
6 Testsuite
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.