summaryrefslogtreecommitdiffabout
authorSergey Poznyakoff <gray@gnu.org>2017-08-08 15:24:38 (GMT)
committer Sergey Poznyakoff <gray@gnu.org>2017-08-08 15:33:23 (GMT)
commit754af24200ceda805c66994151ad1eba2dfb2619 (patch) (side-by-side diff)
treed327735304517ee02049f4d3901af643a68f29ff
parentba32780019480b89cd9d796b93a76cae6afe99ab (diff)
downloadacvmod-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.
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--.gitignore4
-rw-r--r--README247
-rwxr-xr-xbootstrap38
-rw-r--r--license/gnu14
-rw-r--r--tmpl/Makefile.am2
-rw-r--r--tmpl/configure.ac2
-rw-r--r--tmpl/src/Makefile.am2
-rw-r--r--tmpl/src/vmod.c2
-rw-r--r--tmpl/src/vmod.vcc2
-rw-r--r--tmpl/tests/Makefile.am2
-rw-r--r--tmpl/tests/testsuite.at2
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 @@
+.emacs
+.emacs.*
+README.html
+*~
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 [[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:
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<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>]
@@ -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;
GetOptions(
'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
+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,6 +1,6 @@
# This file is part of vmod_%{MODULE}.
# Copyright (C) %{YEAR} %{REALNAME}
-# %[COPYING]
+# %[LICENSE]
ACLOCAL_AMFLAGS = -I m4 -I acvmod
diff --git a/tmpl/configure.ac b/tmpl/configure.ac
index 088385e..72cb6b8 100644
--- a/tmpl/configure.ac
+++ b/tmpl/configure.ac
@@ -1,6 +1,6 @@
# This file is part of vmod_%{MODULE}.
# Copyright (C) %{YEAR} %{REALNAME}
-# %[COPYING]
+# %[LICENSE]
AC_PREREQ(2.69)
AC_INIT([vmod-%{MODULE}], [%{VERSION}], [%{EMAIL}])
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,6 +1,6 @@
# This file is part of vmod_%{MODULE}.
# Copyright (C) %{YEAR} %{REALNAME}
-# %[COPYING]
+# %[LICENSE]
AM_CPPFLAGS=\
$(VARNISHAPI_CFLAGS)\
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}
- %[COPYING]
+ %[LICENSE]
*/
#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}
-| %[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,6 +1,6 @@
# This file is part of vmod_%{MODULE}.
# Copyright (C) %{YEAR} %{REALNAME}
-# %[COPYING]
+# %[LICENSE]
EXTRA_DIST = $(TESTSUITE_AT) testsuite package.m4
DISTCLEANFILES = atconfig $(check_SCRIPTS)
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,6 +1,6 @@
# This file is part of vmod_%{MODULE}.
# Copyright (C) %{YEAR} %{REALNAME}
-# %[COPYING]
+# %[LICENSE]
m4_include([../acvmod/testsuite.inc])
AT_INIT

Return to:

Send suggestions and report system problems to the System administrator.