| <section id="installation"> |
| <title>Apache Rivet Installation</title> |
| <procedure> |
| <step> |
| <title>Check Dependencies</title> |
| <para> |
| To install Rivet 2.1.0, you will need Tcl 8.5 or greater and the Apache HTTP server version 2.2.x. |
| It is known to run on Linux, FreeBSD, OpenBSD, Solaris and HPUX. Windows NT is also possible |
| - please see the directions in the distribution. |
| </para> |
| <para> |
| <note> |
| Check your Apache installation for |
| Rivet requires Apache HTTP Webserver to run |
| prefork as mpm. |
| </note> |
| </para> |
| <para> |
| If you're building Apache yourself from sources be careful to specify |
| <command>--with-mpm=prefork</command> when running ./configure. |
| Rivet doesn't support the run time mpm specification available in the Apache 2.3 |
| development version. |
| </para> |
| </step> |
| <step> |
| <title>Get Rivet</title> |
| <para> |
| Download the sources at <ulink url="http://tcl.apache.org/rivet/download.html"/>. Currently |
| the only way to obtain Rivet. In the future, we hope to have a FreeBSD port, Debian package, RPM's, and windows |
| binaries. |
| </para> |
| </step> |
| <step performance="required"> |
| <title>Install Tcl</title> |
| <para> |
| If you don't have <ulink url="http://www.tcl.tk">Tcl</ulink> already, you need it! |
| If you already have it, you should just be able to use your system Tcl as |
| long as it is recent. You can tell Rivet build scripts where Tcl is via |
| the <option>--with-tcl</option> option to <command>configure</command> (see below). |
| </para> |
| </step> |
| <step performance="optional"> |
| <title>Get and Install Apache Sources</title> |
| <para> |
| Rivet needs some Apache include (.h) files in order to build. The easiest way |
| to get them is to download the source code of the Apache web server, although some systems |
| (Debian GNU/Linux for example) make it possible to install only the headers and other |
| development files. If you intend to build Rivet statically (compiled into the Apache web |
| server instead of loaded dynamically), you definitely need the sources. |
| We recommend that you build Rivet as a loadable shared library, for maximum flexibility, |
| meaning that you also build Apache to be able to load modules. Other than that, |
| the default Apache install is fine. We will tell Rivet where it is located via the |
| <option>--with-apxs</option> option to <command>configure</command> (see below). |
| </para> |
| <para> |
| The source code for the Apache web server may be found by |
| following the links here: <ulink |
| url="http://httpd.apache.org/"/>. |
| </para> |
| </step> |
| <step> |
| <title>Uncompress Sources</title> |
| <para> |
| 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. |
| |
| <programlisting>gunzip rivet-X.X.X.tar.gz |
| tar -xvf rivet-X.X.X.tar.gz</programlisting> |
| |
| </para> |
| </step> |
| <step> |
| <title>Building Rivet</title> |
| <substeps> |
| <step> |
| <para> |
| On Linux or Unix systems, Rivet uses the standard <command>./configure ; make ; make install</command> technique. |
| </para> |
| <para> |
| There are several rivet specific options to configure that might be useful (or needed): |
| <variablelist> |
| <varlistentry> |
| <term>--with-tcl</term> |
| <listitem> |
| <para> |
| This points to the directory where the |
| <filename>tclConfig.sh</filename> file is located. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>--with-tclsh</term> |
| <listitem> |
| <para>This points to the location of the |
| <filename>tclsh</filename> executable.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>--with-apxs</term> |
| <listitem> |
| <para>The location of the <filename>apxs</filename> |
| program that provides information about the |
| configuration and compilation options of Apache modules. |
| The name of this program varies depending on how Apache was |
| packaged. For examples Debian Apache 2.2 packagers chose |
| to rename apxs to allow cohexistence with Apache 1.3. |
| <programlisting>--with-apxs=/usr/bin/apxs2</programlisting> |
| SuSE apxs includes also the MPM name for which Apache was compiled |
| <programlisting>--with-apxs=/usr/sbin/apxs2-prefork</programlisting> |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>--with-apache-version=[1|2]</term> |
| <listitem> |
| <para> |
| This option tells the build scripts whether you want to build Rivet for the |
| Apache 1.x or Apache 2.x server. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>--with-apache-include[=DIR]</term> |
| <listitem> |
| <para> |
| Locates the Apache include files on your computer, if they're not in standard directory. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>--enable-version-display=[yes|no] (default: no)</term> |
| <listitem> |
| <para> |
| This option enables Rivet to display its version in the logfiles when Apache is started. |
| The default is to keep Rivet version hidden. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>--with-rivet-target-dir=DIR</term> |
| <listitem> |
| <para> |
| This option tells the install script where Rivet's Tcl packages have to be copied. |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>--with-upload-dir=DIR (default: '/tmp')</term> |
| <listitem> |
| <para> |
| Sets the default directory where Rivet stores files in an upload |
| operation. (Can be changed in the conf with the parameter 'UploadDirectory', |
| see ) |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>--enable-head-request (default: 'no') </term> |
| <listitem> |
| If enabled returns the real headers in response to a HEAD http request. (Can |
| be changed in the configuration with the 'HonorHeaderOnlyRequests' parameter) |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>--enable-virtual-interps-separation (default: 'no')</term> |
| <listitem> |
| When enabled each virtual host will have its own interpreter. (Can be changed in the |
| configuration with the 'SeparateVirtualInterps' parameter) |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>--with-post-max=BYTES Maximum size of data in a POST (default: 0=unlimited)</term> |
| <listitem> |
| Form data are sent to the server in either a GET or a POST operation. Data in POST |
| can be large and you can set the default maximumx size of data that can be accepted |
| in a POST. (Can be changed in configuration with the 'UploadMaxSize' parameter) |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>--disable-upload-var</term> |
| <listitem> |
| By default uploads are stored in Tcl variables. |
| This switch sets the default for the configuration |
| parameter 'UploadFilesToVar' to 0. |
| (Can be changed in the configuration) |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>--disable-rivet-commands-export</term> |
| <listitem> |
| Rivet commands are created in the ::rivet namespace. To improve code readability |
| it is recommended you write your scripts using the fully qualified name |
| definitions. For compatibility with existing code, commands are exported from |
| ::rivet and can be thus imported into any namespace (global namespace included) |
| with the command |
| <programlisting>namespace import -force ::rivet::*</programlisting> |
| The default value for this option may change in the future. |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>--disable-import-rivet-commands</term> |
| <listitem> |
| Rivet commands can be imported imported into the global namespace. This |
| is done by default and can be disabled using this option. In future |
| versions of Rivet the default will be changed to off and eventually |
| removed altogether. |
| <note>This option implicitly sets --enable-rivet-commands-export</note> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </para> |
| <para> |
| Example: configuring the build system to compile Rivet for an apache 2.x server, using tcl8.5 and |
| specifying a custom name for the apxs program. |
| </para> |
| <programlisting> |
| ./configure --with-tcl=/usr/lib/tcl8.5/ --with-tclsh=/usr/bin/tclsh8.5 \ |
| --with-apxs=/usr/bin/apxs2 --with-apache=/usr --with-apache-version=2 |
| </programlisting> |
| </step> |
| <step> |
| <title>Run make</title> |
| <para> |
| At this point, you are ready to run make, which should |
| run to completion without any errors (a warning or two |
| is ok, generally). |
| </para> |
| </step> |
| <step> |
| <title>Install</title> |
| <para> |
| Now, you are ready to run the <command>make |
| install</command> to install the resulting files. |
| This should copy the shared object (like |
| <filename>mod_rivet.so</filename>, if one was |
| successfully created, into Apache's |
| <filename>libexec</filename> directory, as well as |
| install some support scripts and various code. |
| </para> |
| </step> |
| </substeps> |
| </step> |
| <step> |
| <title>Apache Configuration Files</title> |
| <para> |
| Rivet is relatively easy to configure - we start off by |
| adding the module itself: |
| </para> |
| |
| <programlisting>LoadModule rivet_module <replaceable>/usr/lib/apache2/modules/mod_rivet.so</replaceable> |
| </programlisting> |
| |
| <para> |
| 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: |
| </para> |
| |
| <programlisting>AddType application/x-httpd-rivet .rvt |
| AddType application/x-rivet-tcl .tcl</programlisting> |
| |
| <para> |
| These tell Apache to process files with the |
| <filename>.rvt</filename> and <filename>.tcl</filename> |
| extensions as Rivet files. |
| </para> |
| <para> |
| The characters encoding can be changed using the <command>header type</command> command, |
| but you can also change the default charset for the whole site: |
| </para> |
| <programlisting>AddType 'application/x-httpd-rivet;charset=utf-8' rvt</programlisting> |
| <para> |
| All the pages generated by Rivet on this site will be sent with a |
| <command>Content-Type:'text/html;charset=utf-8'</command> header. |
| </para> |
| <para>You may also wish to use Rivet files as index files for |
| directories. In that case, you would do the following:</para> |
| <programlisting>DirectoryIndex index.html index.htm index.shtml index.cgi index.tcl index.rvt</programlisting> |
| <para> |
| For other directives that Rivet provides for Apache |
| configuration, please see <xref linkend="directives"/>. |
| </para> |
| </step> |
| </procedure> |
| </section> |
| |
