| <section id="installation"> |
| <title>Apache Rivet &version; Installation</title> |
| <procedure> |
| <para> |
| Rivet &version; runs with the Apache 2.4.x HTTP web server. |
| 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 |
| <ulink url="http://tcl.apache.org/rivet/html/download.html">binary packages</ulink> |
| are already available for download. |
| </para> |
| <para> |
| Rivet &version2-generic; was restricted to work with the |
| <ulink url="&apachedoc-prefork;">prefork</ulink> 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 |
| <ulink url="https://en.wikipedia.org/wiki/Fork_(system_call)">fork</ulink> |
| 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 &version; is now able to run with the |
| <ulink url="&apachedoc-worker;">worker</ulink> |
| and the |
| <ulink url="&apachedoc-event;">event</ulink> |
| MPMs. Rivet &version; 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 |
| <ulink url="&apachedoc-winnt;">winnt</ulink>. |
| </para> |
| |
| <para> |
| If you need to build Apache Rivet yourself this is the procedure to follow |
| </para> |
| |
| <step performance="required"> |
| <title>Building Tcl: requirements</title> |
| <para> |
| Installing Rivet is about endowing the Apache HTTP webserver with the ability |
| of running scripts written with the Tcl programming language. |
| Therefore the |
| <ulink url="http://www.tcl.tk/">Tcl</ulink> 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 |
| <option>--with-tcl</option> option of the <command>configure</command> script |
| (see below). |
| </para> |
| <para> |
| Several Tcl packages shipped with rivet need also the |
| <ulink url="http://core.tcl.tk/itcl/">Itcl</ulink> |
| OOP extension of Tcl. If you need to run any of the |
| <link href="session_package">Session</link> or <link href="dio">DIO</link> |
| packages you need to install this language extension but you don't need it |
| to build mod_rivet |
| </para> |
| <para> |
| The |
| <ulink url="&apache-url;">Apache HTTP Webserver</ulink> development |
| files and libraries are required along with the |
| <ulink url="&apache-apr;">Apache Portable Runtime</ulink> |
| and the |
| <ulink url="&apache-apreq;">libapreq</ulink> library. |
| </para> |
| </step> |
| |
| <step> |
| <title>Building Rivet</title> |
| </step> |
| <step performance="optional"> |
| <title>Getting and Installing the Apache Sources</title> |
| <para> |
| 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 <option>--with-apxs</option> option to <command>configure</command> (see below). |
| </para> |
| <para> |
| 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 |
| </para> |
| </step> |
| |
| <step> |
| <title>Uncompress Sources</title> |
| <para> |
| Download the sources at <ulink url="&rivet-download;"/>. |
| </para> |
| |
| <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-&fullversion;.tar.gz |
| tar -xvf rivet-&fullversion;.tar.gz</programlisting> |
| </para> |
| </step> |
| |
| <step> |
| <title>Building Rivet</title> |
| <substeps> |
| <step> |
| <para> |
| Rivet uses the standard <command>./configure ; make ; make install</command> |
| sequence which installs to their target directories the Apache module, the binary libraries and the |
| Tcl code |
| </para> |
| <para> |
| There are several rivet specific options to configure that might be useful (or needed): |
| <variablelist> |
| <varlistentry> |
| <term>--with-apache</term> |
| <listitem> |
| <para> |
| Defines the configure internal variable 'apache_base'. This variable |
| points to the root of the Apache web server directory hierarchy |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <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. |
| </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]</term> |
| <listitem> |
| <para> |
| This option enables Rivet to display its version in the |
| logfiles when Apache is started. The default is to keep the Rivet version hidden. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>--with-rivet-target-dir=DIR</term> |
| <listitem> |
| <para> |
| 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) |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>--with-upload-dir=DIR</term> |
| <listitem> |
| <para> |
| Configures Rivet's default upload directory. It can be overridden in the configuration |
| either globally or specifically for a virtual host |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>--with-post-max=BYTES</term> |
| <listitem> |
| <para> |
| The value to this option establishes a default for the maximum size of POST data. |
| Default: 0 (unlimited size) |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>--enable-head-requests</term> |
| <listitem> |
| <para> |
| 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. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>--enable-rivet-commands-export</term> |
| <listitem> |
| <para> |
| By default Rivet's commands are put on the export list of the <code>::rivet</code> |
| 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 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>--enable-import-rivet-commands</term> |
| <listitem> |
| <para> |
| 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 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>--enable-virtual-interps-separation</term> |
| <listitem> |
| <para> |
| This option changes the default for the SeparateVirtualInterps configuration |
| variable. Default: 0 (no separation among interpreters) |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </para> |
| <para> |
| 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 |
| </para> |
| <programlisting>./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/rivet&version;</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 |
| </para> |
| <programlisting>make install</programlisting> |
| <para> |
| to install the resulting files. The <code>install</code> target |
| actually fires the <code>install-binaries</code> and |
| <code>install-packages</code> 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. |
| </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> |
| |
