update README.rst

README.rst

@@ -115,7 +115,7 @@ example::
   import re2;
 
   sub vcl_init {
-  	new myset = re2.set();
+        new myset = re2.set();
 	myset.add("foo");
 	myset.add("bar");
 	myset.add("baz");
@@ -794,6 +794,118 @@ Example::
 REQUIREMENTS
 ============
 
-The VMOD requires Varnish 4.1.2 and the RE2 library. It has been tested
-against RE2 versions 2015-05-01 through 2016-04-01.
+The VMOD requires Varnish 4.1.2 and the RE2 library. It has been
+tested against RE2 versions 2015-05-01 through 2016-04-01.
+
+INSTALLATION
+============
+
+The VMOD is built against a Varnish installation, and the autotools
+use ``pkg-config(1)`` to locate the necessary header files and other
+resources for both Varnish and RE2. This sequence will install the VMOD::
+
+  > ./autogen.sh	# for builds from the git repo
+  > ./configure
+  > make
+  > make check		# to run unit tests in src/tests/*.vtc
+  > make distcheck	# run check and prepare a distribution tarball
+  > sudo make install
+
+If you have installed Varnish and/or RE2 in non-standard directories,
+call ``autogen.sh`` and ``configure`` with the ``PKG_CONFIG_PATH``
+environment variable set to include the paths where the ``.pc`` files
+can be located for ``varnishapi`` and ``re2``. For example, when
+varnishd configure was called with ``--prefix=$PREFIX``, use::
+
+  > PKG_CONFIG_PATH=${PREFIX}/lib/pkgconfig
+  > export PKG_CONFIG_PATH
+
+By default, the vmod ``configure`` script installs the vmod in
+the same directory as Varnish, determined via ``pkg-config(1)``. The
+vmod installation directory can be overridden by passing the
+``VMOD_DIR`` variable to ``configure``.
+
+Other files such as this man-page are installed in the locations
+determined by ``configure``, which inherits its default ``--prefix``
+setting from Varnish.
+
+For developers
+--------------
+
+The VMOD source code is in C and C++, since the RE2 API is
+C++. Compilation has been tested with gcc/g++ and clang.
+
+The build specifies C99 conformance for C sources (``-std=c99``), and
+C++11 for C++ (``-std=c++11``). For both, all compiler warnings are
+turned on, and all warnings are considered errors (``-Werror -Wall``).
+The code should always build without warnings or errors under these
+constraints.
+
+By default, ``CFLAGS`` and ``CXXFLAGS`` are set to ``-g -O2``, so that
+symbols are included in the shared library, and optimization is at
+level ``O2``. To change or disable these options, set ``CFLAGS``
+and/or ``CXXFLAGS`` explicitly before calling ``configure`` (they may
+be set to the empty string).
+
+For development/debugging cycles, the ``configure`` option
+``--enable-debugging`` is recommended (off by default). This will turn
+off optimizations and function inlining, so that a debugger will step
+through the code as expected.
+
+By default, the VMOD is built with the stack protector enabled
+(compile option ``-fstack-protector``), but it can be disabled with
+the ``configure`` option ``--disable-stack-protector``.
+
+LIMITATIONS
+===========
+
+The VMOD allocates Varnish workspace for captured groups and rewritten
+strings. If operations fail with "insufficient workspace" error
+messages in the Varnish log (with the ``VCL_Error`` tag), increase the
+varnishd runtime parameters ``workspace_client`` and/or
+``workspace_backend``.
+
+The RE2 documentation states that successful matches are slowed quite
+a bit when they also capture substrings. There is also additional
+overhead from the VMOD, unless the ``never_capture`` flag is true, to
+manage data about captured groups in the workspace. This overhead is
+incurred even if there are no capturing expressions in a pattern,
+since it is always possible to call ``backref(0)`` to obtain the
+matched portion of a string.
+
+So if you are using a pattern only to match against strings, and never
+to capture subexpressions, consider setting the ``never_capture``
+option to true, to eliminate the extra work for both RE2 and the VMOD.
+
+AUTHOR
+======
+
+* Geoffrey Simmons <geoff@uplex.de>
+
+UPLEX Nils Goroll Systemoptimierung
+
+HISTORY
+=======
+
+* version 0.1: initial version
+
+SEE ALSO
+========
+
+* varnishd(1)
+* vcl(7)
+* RE2 git repo: https://github.com/google/re2
+* RE2 syntax: https://github.com/google/re2/wiki/Syntax
+* "Implementing Regular Expressions": https://swtch.com/~rsc/regexp/
+
+  * Series of articles motivating the design of RE2, with discussion
+    of how RE2 compares with PCRE
+
+COPYRIGHT
+=========
+
+This document is licensed under the same conditions as the libvmod-re2
+project. See LICENSE for details.
+
+* Copyright (c) 2016 UPLEX Nils Goroll Systemoptimierung