diff options
author | Sergey Poznyakoff <gray@gnu.org> | 2017-08-08 18:24:38 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org> | 2017-08-08 18:33:23 +0300 |
commit | 754af24200ceda805c66994151ad1eba2dfb2619 (patch) | |
tree | d327735304517ee02049f4d3901af643a68f29ff | |
parent | ba32780019480b89cd9d796b93a76cae6afe99ab (diff) | |
download | acvmod-754af24200ceda805c66994151ad1eba2dfb2619.tar.gz acvmod-754af24200ceda805c66994151ad1eba2dfb2619.tar.bz2 |
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/Makefile.am: Use %[LICENSE] instead of %[COPYING]
* tmpl/configure.ac: Likewise.
* tmpl/src/Makefile.am: Likewise.
* tmpl/src/vmod.c: Likewise.
* tmpl/src/vmod.vcc: Likewise.
* tmpl/tests/Makefile.am: Likewise.
* tmpl/tests/testsuite.at: Likewise.
-rw-r--r-- | .gitignore | 4 | ||||
-rw-r--r-- | README | 247 | ||||
-rwxr-xr-x | bootstrap | 38 | ||||
-rw-r--r-- | license/gnu | 14 | ||||
-rw-r--r-- | tmpl/Makefile.am | 2 | ||||
-rw-r--r-- | tmpl/configure.ac | 2 | ||||
-rw-r--r-- | tmpl/src/Makefile.am | 2 | ||||
-rw-r--r-- | tmpl/src/vmod.c | 2 | ||||
-rw-r--r-- | tmpl/src/vmod.vcc | 2 | ||||
-rw-r--r-- | tmpl/tests/Makefile.am | 2 | ||||
-rw-r--r-- | tmpl/tests/testsuite.at | 2 |
11 files changed, 296 insertions, 21 deletions
diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b2ea4fc --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +.emacs +.emacs.* +README.html +*~ @@ -0,0 +1,247 @@ +#+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 one +optional argument - the oldest required version of the API: + +#+BEGIN_SRC autoconf + AM_VARNISHAPI([VERSION]) +#+END_SRC + +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. + +* 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($MODULE, $VCL, $CLT [, $SRV]) +#+END_SRC + +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: @@ -19,13 +19,13 @@ bootstrap - creates a framework for writing a Varnish module =head1 SYNOPSIS B<bootstrap> [B<-f>] [B<-C> I<DIR>] -[B<--copying=>I<FILE>] +[B<--license=>I<FILE>] [B<--description=>I<TEXT>] [B<--directory=>I<DIR>] [B<--email=>I<EMAIL>] [B<--force>] [B<--foreign>] [B<--git>] @@ -84,17 +84,20 @@ Sets a one-line vmod description for use in the vcc file header. Sets the vmod version. Default is B<0.1>. =item B<--url=>I<URL> 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<-?> Display short help. =item B<--help> @@ -267,13 +270,14 @@ my @files = ( { name => 'ChangeLog', func => \&mkcl, cond => \&strictness_gnu, gitignore => 1 }, { name => 'm4', func => \&create_dir } ); -my $wd; +my $wd; +my $license_file; GetOptions( 'h|?' => sub { pod2usage(-message => "$program: $progdescr", -exitstatus => 0) }, 'help' => sub { @@ -293,19 +297,13 @@ GetOptions( 'foreign' => sub { $dict{STRICTNESS} = 'foreign' }, 'real-name=s' => \$dict{REALNAME}, 'email=s' => \$dict{EMAIL}, '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; usage if @ARGV; @@ -314,13 +312,25 @@ $dict{EMAIL} = $ENV{USER} . '@' . hostname() unless (defined($dict{REALNAME})) { $dict{REALNAME} = (getpwnam($ENV{USER}))[6]; $dict{REALNAME} =~ s/,.*//; $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; system("cp -r $basedir $wd"); chdir $wd or die "Can't change to $wd: $!"; } diff --git a/license/gnu b/license/gnu new file mode 100644 index 0000000..33d1e35 --- /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 +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +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 <http://www.gnu.org/licenses/>. + diff --git a/tmpl/Makefile.am b/tmpl/Makefile.am index 9ba757a..5fd2d0b 100644 --- a/tmpl/Makefile.am +++ b/tmpl/Makefile.am @@ -1,9 +1,9 @@ # This file is part of vmod_%{MODULE}. # Copyright (C) %{YEAR} %{REALNAME} -# %[COPYING] +# %[LICENSE] ACLOCAL_AMFLAGS = -I m4 -I acvmod SUBDIRS = src tests include acvmod/top.am diff --git a/tmpl/configure.ac b/tmpl/configure.ac index 088385e..72cb6b8 100644 --- a/tmpl/configure.ac +++ b/tmpl/configure.ac @@ -1,9 +1,9 @@ # This file is part of vmod_%{MODULE}. # Copyright (C) %{YEAR} %{REALNAME} -# %[COPYING] +# %[LICENSE] AC_PREREQ(2.69) AC_INIT([vmod-%{MODULE}], [%{VERSION}], [%{EMAIL}]) AC_CONFIG_AUX_DIR([build-aux]) AC_CONFIG_MACRO_DIR([m4]) AC_CONFIG_SRCDIR(src/vmod_%{MODULE}.vcc) diff --git a/tmpl/src/Makefile.am b/tmpl/src/Makefile.am index c7066b1..f41363c 100644 --- a/tmpl/src/Makefile.am +++ b/tmpl/src/Makefile.am @@ -1,9 +1,9 @@ # This file is part of vmod_%{MODULE}. # Copyright (C) %{YEAR} %{REALNAME} -# %[COPYING] +# %[LICENSE] AM_CPPFLAGS=\ $(VARNISHAPI_CFLAGS)\ -DLOCALSTATEDIR=\"$(localstatedir)\" vmoddir = $(VMODDIR) 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,9 +1,9 @@ /* This file is part of vmod_%{MODULE}. Copyright (C) %{YEAR} %{REALNAME} - %[COPYING] + %[LICENSE] */ #include <config.h> #include "vcl.h" #include "vrt.h" #include "vas.h" #include "cache/cache.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 @@ -6,8 +6,8 @@ DESCRIPTION This module does blah blah blah. COPYRIGHT ========= | Copyright (C) %{YEAR} %{REALNAME} -| %[COPYING] +| %[LICENSE] diff --git a/tmpl/tests/Makefile.am b/tmpl/tests/Makefile.am index 448aaaf..e565e54 100644 --- a/tmpl/tests/Makefile.am +++ b/tmpl/tests/Makefile.am @@ -1,9 +1,9 @@ # This file is part of vmod_%{MODULE}. # Copyright (C) %{YEAR} %{REALNAME} -# %[COPYING] +# %[LICENSE] EXTRA_DIST = $(TESTSUITE_AT) testsuite package.m4 DISTCLEANFILES = atconfig $(check_SCRIPTS) MAINTAINERCLEANFILES = Makefile.in $(TESTSUITE) CLEANFILES = .TESTINIT FAILURE diff --git a/tmpl/tests/testsuite.at b/tmpl/tests/testsuite.at index 11849de..14f3610 100644 --- a/tmpl/tests/testsuite.at +++ b/tmpl/tests/testsuite.at @@ -1,7 +1,7 @@ # This file is part of vmod_%{MODULE}. # Copyright (C) %{YEAR} %{REALNAME} -# %[COPYING] +# %[LICENSE] m4_include([../acvmod/testsuite.inc]) AT_INIT # Include your tests here |