authorSergey Poznyakoff <>2017-08-08 15:24:38 (GMT)
committer Sergey Poznyakoff <>2017-08-08 15:33:23 (GMT)
commit754af24200ceda805c66994151ad1eba2dfb2619 (patch) (side-by-side diff)
parentba32780019480b89cd9d796b93a76cae6afe99ab (diff)
Add documentation
* README: New file. * bootstrap: Rename --copying to --license. Look for the license file in the directory "copying" first. * .gitignore: New file. * license/gnu: New file. * tmpl/ Use %[LICENSE] instead of %[COPYING] * tmpl/ Likewise. * tmpl/src/ Likewise. * tmpl/src/vmod.c: Likewise. * tmpl/src/vmod.vcc: Likewise. * tmpl/tests/ Likewise. * tmpl/tests/ Likewise.
Diffstat (more/less context) (ignore whitespace changes)
11 files changed, 296 insertions, 21 deletions
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..b2ea4fc
--- a/dev/null
+++ b/.gitignore
@@ -0,0 +1,4 @@
diff --git a/README b/README
new file mode 100644
index 0000000..9762ba4
--- a/dev/null
+++ b/README
@@ -0,0 +1,247 @@
+#+TITLE: Varnish Cache module creator
+* 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
+* 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:
+#+BEGIN_SRC shell-script
+ ./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*:
+ #+BEGIN_SRC shell-script
+ git clone git://
+2. Run
+ #+BEGIN_SRC shell-script -r
+ 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:
+ #+BEGIN_SRC shell-script
+ ./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 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=.
+*** 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.
+*** 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
+ is =No description yet=.
++ ~--url=URL~ :: URL of the project's web page. It is mentioned, among
+ others, in the generated =README= file.
++ ~--license=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/license= subdirectory, and if not found there, in the
+ current working directory.
+*** 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.
+** Another example
+The following command was used to create initial set up of the
+[[][vmod-dict]] module:
+ #+BEGIN_SRC shell-script
+ bootstrap --gnu \
+ --git \
+ -C ~/src/vmod-dict \
+ --email \
+ --url \
+ --description='Dictionary look-up for Varnish Cache' \
+ --license=gnu \
+ dict
+* The ~AM_VARNISHAPI~ macro
+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:
+#+BEGIN_SRC autoconf
+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 script.
+* 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.
+* 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.
+* 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:
+#+BEGIN_SRC autotest
+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.
+# Local Variables:
+# mode: org
+# paragraph-separate: "[ ]*$"
+# version-control: never
+# End:
diff --git a/bootstrap b/bootstrap
index 960a73a..d9a130e 100755
--- a/bootstrap
+++ b/bootstrap
@@ -22,7 +22,7 @@ bootstrap - creates a framework for writing a Varnish module
[B<-C> I<DIR>]
@@ -87,11 +87,14 @@ Sets the vmod version. Default is B<0.1>.
Sets the ULR of the vmod web page.
-=item B<--copying=>I<FILE>
+=item B<--license=>I<FILE>
-Reads copying information from I<FILE>. This text will be expanded (see
-B<VARIABLE EXPANSION>) and reproduced in the initial header of each
-created file.
+Reads the text of the license from I<FILE>. Unless I<FILE> begins with B</> or
+B<./>, the file will first be looked in the B<license> subdirectory and then
+in the current working directory.
+The text read froom I<FILE> will be expanded (see B<VARIABLE EXPANSION>)
+and reproduced in the initial header of each created file.
=item B<-?>
@@ -270,7 +273,8 @@ my @files = (
-my $wd;
+my $wd;
+my $license_file;
'h|?' => sub {
pod2usage(-message => "$program: $progdescr",
@@ -296,13 +300,7 @@ GetOptions(
'description=s' => \$dict{DESCR},
'version=s' => \$dict{VERSION},
'url=s' => \$dict{URL},
- 'copying=s' => sub {
- local $/ = undef;
- open(my $fd, '<', $_[1])
- or die "cannot open $_[1]: $!";
- $dict{COPYING} = <$fd>;
- close($fd);
- }
+ 'license=s' => \$license_file
) or exit(1);
$dict{MODULE} = shift @ARGV or usage;
@@ -317,7 +315,19 @@ unless (defined($dict{REALNAME})) {
$dict{REALNAME} = "User $ENV{USER}" if $dict{REALNAME} eq '';
-$dict{COPYING} =~ s/\%\{([\w_]+)\}/expvar($1)/gex;
+if ($license_file) {
+ unless ($license_file =~ m{^(\.{1,2})?/}) {
+ my $n = "$basedir/license/$license_file";
+ $license_file = $n if -f $n;
+ }
+ local $/ = undef;
+ open(my $fd, '<', $license_file)
+ or die "cannot open $license_file: $!";
+ $dict{LICENSE} = <$fd>;
+ close($fd);
+ $dict{LICENSE} =~ s/\%\{([\w_]+)\}/expvar($1)/gex;
if ($wd) {
create_dir($wd) unless -d $wd;
diff --git a/license/gnu b/license/gnu
new file mode 100644
index 0000000..33d1e35
--- a/dev/null
+++ b/license/gnu
@@ -0,0 +1,14 @@
+Vmod_%{MODULE} is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3, or (at your option)
+any later version.
+Vmod_%{MODULE} is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+GNU General Public License for more details.
+You should have received a copy of the GNU General Public License
+along with vmod_%{MODULE}. If not, see <>.
diff --git a/tmpl/ b/tmpl/
index 9ba757a..5fd2d0b 100644
--- a/tmpl/
+++ b/tmpl/
@@ -1,6 +1,6 @@
# This file is part of vmod_%{MODULE}.
# Copyright (C) %{YEAR} %{REALNAME}
ACLOCAL_AMFLAGS = -I m4 -I acvmod
diff --git a/tmpl/ b/tmpl/
index 088385e..72cb6b8 100644
--- a/tmpl/
+++ b/tmpl/
@@ -1,6 +1,6 @@
# This file is part of vmod_%{MODULE}.
# Copyright (C) %{YEAR} %{REALNAME}
AC_INIT([vmod-%{MODULE}], [%{VERSION}], [%{EMAIL}])
diff --git a/tmpl/src/ b/tmpl/src/
index c7066b1..f41363c 100644
--- a/tmpl/src/
+++ b/tmpl/src/
@@ -1,6 +1,6 @@
# This file is part of vmod_%{MODULE}.
# Copyright (C) %{YEAR} %{REALNAME}
diff --git a/tmpl/src/vmod.c b/tmpl/src/vmod.c
index 060882b..badfedb 100644
--- a/tmpl/src/vmod.c
+++ b/tmpl/src/vmod.c
@@ -1,6 +1,6 @@
/* This file is part of vmod_%{MODULE}.
Copyright (C) %{YEAR} %{REALNAME}
#include <config.h>
#include "vcl.h"
diff --git a/tmpl/src/vmod.vcc b/tmpl/src/vmod.vcc
index 48d6e0e..a4b115d 100644
--- a/tmpl/src/vmod.vcc
+++ b/tmpl/src/vmod.vcc
@@ -9,5 +9,5 @@ COPYRIGHT
| Copyright (C) %{YEAR} %{REALNAME}
diff --git a/tmpl/tests/ b/tmpl/tests/
index 448aaaf..e565e54 100644
--- a/tmpl/tests/
+++ b/tmpl/tests/
@@ -1,6 +1,6 @@
# This file is part of vmod_%{MODULE}.
# Copyright (C) %{YEAR} %{REALNAME}
EXTRA_DIST = $(TESTSUITE_AT) testsuite package.m4
DISTCLEANFILES = atconfig $(check_SCRIPTS)
diff --git a/tmpl/tests/ b/tmpl/tests/
index 11849de..14f3610 100644
--- a/tmpl/tests/
+++ b/tmpl/tests/
@@ -1,6 +1,6 @@
# This file is part of vmod_%{MODULE}.
# Copyright (C) %{YEAR} %{REALNAME}

Return to:

Send suggestions and report system problems to the System administrator.