Rivet 3.0 runs with the Apache 2.2.x and 2.4.x HTTP web servers. It is known to build and run on various Linux distributions (Debian & Ubuntu, Redhat, SuSE and CentOS), FreeBSD and OpenBSD. For some of these Unix-like operative systems binary packages are already available for download.

Rivet 2.x was restricted to work with the prefork MPM of the Apache HTTP webserver. MPM modules are fundamental components of the webserver architecture. They provide multiple implementations of multiprocessing in order to better suit specific OS features and scalability requirements. The prefork MPM exploited the UNIX traditional approach to multiprocess server applications based on the fork system call. This model has several limitations but also some advantages. The solution we adopted tries to attain the best from any MPM as much as possible and Rivet 3.0 is now able to run with the worker and the event MPMs. Rivet 3.0 has not been ported to OS of the Windows family but we feel that the current design would fit just fine with the Windows specific MPMs such as winnt.

If you need to build Apache Rivet yourself this is the procedure to follow

1. Building Tcl: requirements

   Installing Rivet is about endowing the Apache HTTP webserver with the ability of running scripts written with the Tcl programming language. Therefore the Tcl language with its runtime, development libraries and shell (≥8.5.10 required, ≥8.6.0 recommended) have to be installed. Building Rivet you will have to tell the scripts where the Tcl libraries are located via the --with-tcl option of the configure script (see below).

   Several Tcl packages shipped with rivet need also the Itcl OOP extension of Tcl. If you need to run any of the Session or DIO packages you need to install this language extension but you don't need it to build mod_rivet

   The Apache HTTP Webserver development files and libraries are required along with the Apache Portable Runtime and the libapreq library.

2. Building Rivet

3. Getting and Installing the Apache Sources

   You can build Rivet either statically (compiled into the Apache web server) or dynamically (as a loadable shared library). We recommend that you build Rivet as a shared library, for maximum flexibility. We will tell Rivet where it the Apache development files and libraries are located via the --with-apxs option to configure (see below).

   Most modern Unix OS (Linux and FreeBSD systems included) come with their own packages of the Apache Web Server executables, runtime libraries and development files and libraries. Check the documentation of the package manager of your OS to find out how to install this software

4. Uncompress Sources

   Download the sources at http://tcl.apache.org/rivet/html/download.html.

   We will assume that you have Apache installed at this point. You must uncompress the Rivet sources in the directory where you wish to compile them.

   gunzip rivet-3.0.3.tar.gz
   tar -xvf rivet-3.0.3.tar.gz

5. Building Rivet

   1. Rivet uses the standard ./configure ; make ; make install sequence which installs to their target directories the Apache module, the binary libraries and the Tcl code

      There are several rivet specific options to configure that might be useful (or needed):

      --with-apache

      Defines the configure internal variable 'apache_base'. This variable points to the root of the Apache web server directory hierarchy

      --with-tcl

      This points to the directory where the tclConfig.sh file is located.

      --with-tclsh

      This points to the location of the tclsh executable.

      --with-apxs

      The location of the apxs program that provides information about the configuration and compilation options of Apache modules.

      --with-apache-include[=DIR]

      Locates the Apache include files on your computer, if they're not in standard directory.

      --enable-version-display=[yes|no]

      This option enables Rivet to display its version in the logfiles when Apache is started. The default is to keep the Rivet version hidden.

      --with-rivet-target-dir=DIR

      This option is for fine tuning of the installation final directories. Rivet Tcl packages, commands and loadable libraries go into the same directory hierarchy (by default is ${apache_base}/lib/rivet${PACKAGE_VERSION}, where $apache_base takes the value set by --with-apache)

      --with-upload-dir=DIR

      Configures Rivet's default upload directory. It can be overridden in the configuration either globally or specifically for a virtual host

      --with-post-max=BYTES

      The value to this option establishes a default for the maximum size of POST data. Default: 0 (unlimited size)

      --enable-head-requests

      By default HEAD requests don't go through the usual request processing which leads to script execution and therefore resource consumption and Rivet returns a standard hardcoded HTML header to save CPU time. --enable-head-requests can change the default.

      --enable-rivet-commands-export

      By default Rivet's commands are put on the export list of the ::rivet namespace. With this option you may prevent it thus forcing the programmers to fully qualify in their code. By default this option is enabled and it can be changed in the configuration with the directive ExportRivetNS. Disabling this option can be also reverted to 'On' with the --enable-import-rivet-commands switch

      --enable-import-rivet-commands

      Rivet's namespace is by default imported into the global namespace. Enabling the import of Rivet's commands overrides the switch and forces --enable-rivet-commands-export=yes thus demanding the commands to be exported (otherwise it would generate errors at run-time). This option is disabled by default and it can be changed in the configuration with the ImportRivetNS directive

      --enable-virtual-interps-separation

      This option changes the default for the SeparateVirtualInterps configuration variable. Default: 0 (no separation among interpreters)

      Example: configuring the build system to compile Rivet for an Apache HTTP server custom installation, using tcl8.6. In this specific case the determination of the apxs path is redundant and it could be omitted since it could be inferred from the --with-apache option value

      ./configure --with-tcl=/usr/lib/tcl8.6/ --with-tclsh=/usr/bin/tclsh8.6 \
      	    --with-apxs=/usr/local/apache2/bin/apxs --with-apache=/usr/local/apache2 \
      	    --with-rivetlib-target-dir=/usr/local/apache2/rivet3.0

   2. Run make

      At this point, you are ready to run make, which should run to completion without any errors (a warning or two is OK, generally).

   3. Install

      Now, you are ready to run the

      make install

      to install the resulting files. The install target actually fires the install-binaries and install-packages targets which in turn copy the binary modules and Tcl packages to their destination directories. This commands create a functional Rivet environment with its core language.

6. Apache Configuration Files

   Rivet is relatively easy to configure - we start off by adding the module itself:

   LoadModule rivet_module	/usr/lib/apache2/modules/mod_rivet.so

   This tells Apache to load the Rivet shared object, wherever it happens to reside on your file system. Now we have to tell Apache what kind of files are "Rivet" files and how to process them:

   AddType application/x-httpd-rivet rvt
   AddType application/x-rivet-tcl tcl

   These tell Apache to process files with the .rvt and .tcl extensions as Rivet files.

   The characters encoding can be changed using the header type command, but you can also change the default charset for the whole site:

   AddType 'application/x-httpd-rivet;charset=utf-8' rvt

   All the pages generated by Rivet on this site will be sent with a Content-Type:'text/html;charset=utf-8' header.

   You may also wish to use Rivet files as index files for directories. In that case, you would do the following:

   DirectoryIndex index.html index.htm index.shtml index.cgi index.tcl index.rvt

   For other directives that Rivet provides for Apache configuration, please see the section called “Apache Rivet 3.0 Configuration”.