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:

  1. Clone the acvmod:
    git clone 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:


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

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


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

Sets module version number. Default value is 0.1.
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 is No description yet.
URL of the project's web page. It is mentioned, among others, in the generated README 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 the acvmod/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:

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.
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 \
          --url \            
          --description='Dictionary look-up for Varnish Cache' \
          --copying=gnu \


The AM_VARNISHAPI macro is used in 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:


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:

The path of the varnish module directory.
Major number of the varnish API version.
Minor number of the varnish API version.
Patchlevel number of the varnish API version.
Full pathname of the varnishd binary.
Full pathname of the varnishtest binary.
Varnish API package data directory.
Absolute pathname of the 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 file

The file is included in the generated top-level 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, 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 includes the file acvmod/, which defines the AT_VARNISHTEST macro, which we recommend for writing the tests.

The syntax is:


The arguments are:

Name of the module.
The VLC script. It needs not import the module itself.
The program to use in the client part of the generated vtc file.
The program to use in the server part of the generated vtc file.

Date: 2017-08-08T17:15+0300

Author: Sergey Poznyakoff

Org version 7.9.3f with Emacs version 24

Validate XHTML 1.0