#+TITLE: Varnish Cache module creator * Overview *Acvmod* is a framework for creating loadable modules for [[https://varnish-cache.org][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. * 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 #+END_SRC 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://git.gnu.org.ua/acvmod.git #+END_SRC 2. Run #+BEGIN_SRC shell-script -r acvmod/bootstrap -C ~/src/vmod-new --git new #+END_SRC 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: #+BEGIN_EXAMPLE 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 #+END_EXAMPLE 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: #+BEGIN_SRC shell-script ./configure make #+END_SRC This will produce a module that you can import into your VCL script using the #+BEGIN_SRC C import new; #+END_SRC 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 [[https://www.gnu.org/software/automake/manual/html_node/Strictness.html][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. *** 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 [[https://puszcza.gnu.org.ua/projects/vmod-dict][vmod-dict]] module: #+BEGIN_SRC shell-script 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' \ --license=gnu \ dict #+END_SRC * 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 at most two arguments, both of which are optional: #+BEGIN_SRC autoconf AM_VARNISHAPI([MIN-VERSION],[MAX-VERSION]) #+END_SRC The =MIN-VERSION= argument specifies the oldest supported version of Varnish API. If the API is older than that, an error message will be emitted and configuration will be aborted. The =MAX-VERSION= argument specifies the newest version of Varnish API for which the package was tested. If the API is newer than that, a warning message will be emitted at the end of the run to inform the user about the fact. If MAX-VERSION is omitted, no such test is made. If the macro is called without arguments, its behavior depends on the package version (as specified in the AC_INIT macro call). If the version ends in -N.N.N (where _N_ stands for a decimal digit), the macro behaves as if it were invoked as ~AM_VARNISHAPI(N.N.N)~. Otherwise, no version checking is performed. 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. - ~VARNISH_BINDIR~ :: Varnish installation bin directory - ~VARNISH_SBINDIR~ :: Varnish installation sbin directory - ~VARNISHAPI_PKGDATADIR~ :: Varnish API package data directory. - ~VARNISHAPI_VMODTOOL~ :: Absolute pathname of the vmodtool.py 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 =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. * 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: #+BEGIN_SRC autotest AT_VARNISHTEST($VCL, $CLT [, $SRV]) #+END_SRC The arguments are: - ~$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: