Update docs for installation and how to contribute.

CONTRIBUTING.rst

@@ -12,6 +12,19 @@ the website. You can also write to <varnish-support@uplex.de>.
 For developers
 --------------
 
+The VDP depends heavily on function calls that are internal to
+Varnish, and are not part of the public APIs provided for VMODs and
+delivery or fetch processors. This is why the build requires a Varnish
+source tree, identified with the ``VARNISHSRC`` variable in the
+invocation of ``configure``, as described in `INSTALL.rst
+<INSTALL.rst>`_. Some of the function and struct definitions that are
+declared static in the Varnish source are copied in the
+``src/foreign`` directory of the VDP source.
+
+Elements of the Varnish code that are not public may be changed
+without notice in future versions. In that case, the VDP code will
+have to be updated as the need arises.
+
 The VDP source code is in C, and compilation has been tested with gcc
 and clang. The code MUST always compile successfully with both of
 them.
@@ -31,6 +44,19 @@ For development/debugging cycles, the ``configure`` option
 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
+Experience has shown that adding ``-ggdb3`` to ``CFLAGS`` is
+beneficial if you need to examine the VDP with the gdb debugger. The
+shared object for a VDP (as for VMODs) is loaded from a directory
+relative to the Varnish home directory (by default
+``/usr/local/var/$INSTANCE`` for development builds). A debugger needs
+to locate the shared object from that relative path to load its
+symbols, so the Varnish home directory should be the current working
+directory when the debugger is run. For example::
+
+  # To run gdb and examine a coredump
+  $ cd /usr/local/var/myinstance
+  $ gdb /usr/local/sbin/varnishd /path/to/coredump
+
+By default, the VDP is built with the stack protector enabled
 (compile option ``-fstack-protector``), but it can be disabled with
 the ``configure`` option ``--disable-stack-protector``.

INSTALL.rst

 INSTALLATION
 ============
 
+RPMs
+~~~~
+
+Binary, debuginfo and source RPMs for the VDP are available at:
+
+	https://pkg.uplex.de/
+
+The packages are built for Enterprise Linux 7 (el7), and hence will
+run on compatible distros (such as RHEL7, Fedora, CentOS 7 and Amazon
+Linux).
+
+To add the repo to your YUM configuration::
+
+  yum-config-manager --add-repo https://pkg.uplex.de/rpm/7/uplex-varnish/x86_64/
+
+The RPM for the VDP requires a Varnish installation from the official
+packages:
+
+	https://packagecloud.io/varnishcache
+
+You can then install the VDP with::
+
+  yum install --nogpgcheck vdp-pesi
+
+If you have problems or questions concerning the RPMs, post an issue
+to the source repository web site for the VDP, or contact
+<varnish-support@uplex.de>.
+
 Building from source
 ~~~~~~~~~~~~~~~~~~~~
 
-The VDP is built against a Varnish installation, and the autotools use
-``pkg-config(1)`` to locate the necessary header files and other
-resources for Varnish. This sequence will install the VDP::
+The VDP is built against both a Varnish development installation *and*
+a Varnish source tree. The Varnish source tree must be built, so that
+generated sources are present; that is, its build process must be
+carried out at least as far the execution of ``make``.  The build
+version of installed Varnish must match the version of the source
+tree; this means that the "commit ID" portion of the version string of
+installed Varnish must match the HEAD of the source tree.  A simple
+solution is to build and install Varnish from the source tree.  If
+Varnish is installed by other means (for example from package), then
+the commit IDs must match.
+
+For the installation, the autotools use ``pkg-config(1)`` to locate
+the necessary header files and other resources for Varnish. The root
+directory of the source tree is identified by the variable
+``VARNISHSRC`` in the invocation of ``configure``.
+
+This sequence will install the VDP::
 
   > ./autogen.sh	# for builds from the git repo
-  > ./configure
+  > ./configure VARNISHSRC=/path/to/source/tree
   > make
   > make check		# to run unit tests in src/tests/*.vtc
   > make distcheck	# run check and prepare a distribution tarball
@@ -27,8 +69,8 @@ configure was called with ``--prefix=$PREFIX``, use::
   > PKG_CONFIG_PATH=${PREFIX}/lib/pkgconfig
   > export PKG_CONFIG_PATH
 
-By default, the ``configure`` script installs the VDP in the same
-directory as Varnish, determined via ``pkg-config(1)``. The vmod
+By default, the ``configure`` script installs the VDP in the VMOD
+directory for Varnish, determined via ``pkg-config(1)``. The VMOD
 installation directory can be overridden by passing the ``VMOD_DIR``
 variable to ``configure``.