aboutsummaryrefslogtreecommitdiff
path: root/README
blob: 68c2379696de31d5c9f96c16a1f427286c1fb015 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
#+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:

Return to:

Send suggestions and report system problems to the System administrator.