<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<title>
ht://Dig: Installation
</title>
</head>
<body bgcolor="#eef7ff">
<h1>
Installation
</h1>
<p>
ht://Dig Copyright © 1995-2001 <a href="THANKS.html">The ht://Dig Group</a><br>
Please see the file <a href="COPYING">COPYING</a> for
license information.
</p>
<hr size="4" noshade>
<p>
This document will attempt to show the steps needed to build
and install the ht://Dig system.<br>
The main sections are:
</p>
<ul>
<li>
<a href="where.html">Getting the software</a>
</li>
<li>
<a href="#extract">Extracting the software</a>
</li>
<li>
<a href="#configure">Configure</a>
</li>
<li>
<a href="#compile">Compile</a>
</li>
<li>
<a href="#test">Test</a>
</li>
<li>
<a href="#install">Install</a>
</li>
<li>
<a href="#sharelib">Shared Libraries</a>
</li>
</ul>
<hr noshade>
<h2>
<a name="extract">Extracting the software</a>
</h2>
<p>
The distribution of ht://Dig is in the form of a gzipped tar
file. The name of the file will be something like <code>
htdig-3.2.0.tar.gz</code>. To extract, you can use either the GNU
tar command as follows:
</p>
<blockquote>
% <strong>tar xzf <em>tarfile.tar.gz</em></strong>
</blockquote>
<p>
If you do not have GNU tar, you can do the following:
</p>
<blockquote>
% <strong>gunzip -c <em>tarfile.tar.gz</em> | tar xf -</strong>
</blockquote>
<p>
In either case, a new directory will be created under which the
distribution will be extracted. The directory it creates will
be <code>htdig-</code> followed by the version number.
</p>
<hr noshade>
<h2>
<a name="configure">Configure</a>
</h2>
<p>
Once the distribution has been extracted, change to the newly
created directory.<br>
In this directory you will need execute the <code>configure</code> program:
<blockquote>
% <strong>./configure</strong>
</blockquote>
<p>
This program will attempt to determine what your particular
system can and can't do.
</p>
<!--
<p>
The <strong>configure</strong> program may produce some warnings about
libguile and guile. Ignore those warnings since they do not
affect the ht://Dig program at all.
</p>
-->
<p>
Before running configure you can optionally add dependency information
to all the Makefiles with the command
</p>
<blockquote>
% <strong>automake</strong>
</blockquote>
<p>
This only needs to be done if you are going to change any of
the sources to ht://Dig and requires <strong>GCC</strong>.
</p>
<p>
The <strong>configure</strong> program has some ht://Dig specific options
in addition to the standard ones that you get when running
<pre>
./configure --help
</pre>
</p>
<dl>
<dt>
<code>--prefix=DIR</code>
</dt>
<dd>
This is where all of the ht://Dig parts will be installed.
Various other variables will use this value as their base.
[default=/opt/www]
</dd>
<dt>
<code>--bindir=DIR</code>
</dt>
<dd>
All the ht://Dig executable programs will go here
[default=/opt/www/bin].
</dd>
<dt>
<code>--with-config-dir=DIR</code>
</dt>
<dd>
where your config directory is [default=/opt/www/conf]
</dd>
<dt>
<code>--with-default-config-file=FILE</code>
</dt>
<dd>
Point this to where all the tools will look for the
configuration file [default=/opt/www/conf/htdig.conf].
</dd>
<dt>
<code>--with-common-dir=DIR</code>
</dt>
<dd>
This directory is for files which can be shared between
different search databases [default=/opt/www/share/htdig].
</dd>
<dt>
<code>--with-database-dir=DIR</code>
</dt>
<dd>
Set this to the directory where the search databases are
going to be. (Make sure there is plenty of space on the
partition you put this on!) [default=/opt/www/var/htdig].
</dd>
<dt>
<code>--with-cgi-bin-dir=DIR</code>
</dt>
<dd>
The directory where your HTTP server looks for CGI
programs. This is where htsearch will get installed
[default=/opt/www/cgi-bin].
</dd>
<dt>
<code>--with-image-dir=DIR</code>
</dt>
<dd>
Define this to be a place that can be accessed by your web
server. This is where a couple of images will be installed
[default=/opt/www/htdocs/htdig].
</dd>
<dt>
<code>--with-image-url-prefix=LOCATION</code>
</dt>
<dd>
This is the URL which points to the directory specified by
the <code>--with-image-dir=DIR</code> option above
[default=/htdig].
</dd>
<dt>
<code>--with-search-dir=FILE</code>
</dt>
<dd>
where the sample search form should be installed
[default=/opt/www/htdocs/htdig].
</dd>
<dt>
<code>--with-search-form=FILE</code>
</dt>
<dd>
The name of the file in which the sample search form will
be installed, relative to the directory specified with
<code>--with-search-dir=DIR</code> [default=search.html].
</dd>
</dl>
<hr noshade>
<h2>
<a name="compile">Compile</a>
</h2>
<p>
The configure program will have created Makefiles in all the
important directories.
<p>
If <strong>make</strong> is not able to deal with the generated Makefiles,
you should probably obtain
<a href="ftp://ftp.gnu.org/pub/gnu/">GNU make</a>.
</p>
<p>
Now build the complete system with
</p>
<blockquote>
% <strong>make</strong>
</blockquote>
<p>
(Sit back and relax for a while...)
</p>
<p>
If the compilation failed with the error that it cannot find
libht.a, the most likely problem is that your system does not
have libstdc++ installed. Please check the
<a href="require.html">system requirements</a> for details on this.
</p>
<hr noshade>
<h2>
<a name="test">Test</a>
</h2>
<p>
Once built, you can run tests if you provided the
<code>--enable-tests</code> at configure time. These tests
require that you have a working
<a href=http://www.apache.org/>Apache</a> daemon available with
version >= 1.3.1. To run the tests execute:
</p>
<p>
If your <a href=http://www.apache.org/>Apache</a> daemon is
installed in a non standard place, specify it with the
<code>--with-apache=PATH</code> configure option.
</p>
<blockquote>
% <strong>make check</strong>
</blockquote>
<hr noshade>
<h2>
<a name="install">Install</a>
</h2>
<p>
Everything should have built at this point. To install the
software, you need to execute
</p>
<blockquote>
% <strong>make install</strong>
</blockquote>
<p>
This will perform several tasks. It will first attempt to
create the directories that you specified to <strong>./configure</strong>.
It will then copy the following programs to the <code>
--bindir=DIR</code> directory:
</p>
<ul>
<li>
htdig
</li>
<li>
htmerge
</li>
<li>
htfuzzy
</li>
<li>
htnotify
</li>
<li>
htdump
</li>
<li>
htstat
</li>
<li>
htload
</li>
</ul>
<p>
It will also copy the htsearch program to your
<code>--with-cgi-bin-dir=DIR</code> directory.
</p>
<p>
After this, several files will be customized and installed.
Here is a list of the files that get installed:
</p>
<blockquote>
<dl>
<dt>
<em><img src="bdot.gif" width=9 height=9 alt="*"><code>--with-config-dir=DIR</code></em>/htdig.conf
</dt>
<dd>
A minimal config file which can be used to create a
search database for http://www.htdig.org/
</dd>
<dt>
<em><img src="bdot.gif" width=9 height=9 alt="*"><code>--with-search-form=FILE</code></em>
</dt>
<dd>
A sample HTML document that contains a search form.
</dd>
<dt>
<em><img src="bdot.gif" width=9 height=9 alt="*"> <code>--with-common-dir=DIR</code></em>/footer.html
</dt>
<dd>
A sample HTML document that can be used as the search
results footer.
</dd>
<dt>
<em><img src="bdot.gif" width=9 height=9 alt="*"> <code>--with-common-dir=DIR</code></em>/header.html
</dt>
<dd>
A sample HTML document that can be used as the search
results header.
</dd>
<dt>
<em><img src="bdot.gif" width=9 height=9 alt="*"> <code>--with-common-dir=DIR</code></em>/nomatch.html
</dt>
<dd>
A sample HTML document that can be used if nothing was
found.
</dd>
<dt>
<em><img src="bdot.gif" width=9 height=9 alt="*"> <code>--with-common-dir=DIR</code></em>/syntax.html
</dt>
<dd>
A sample HTML document that will be displayed if the
user entered an illegal boolean expression. found.
</dd>
<dt>
<em><img src="bdot.gif" width=9 height=9 alt="*"> <code>--with-common-dir=DIR</code></em>/english.0
</dt>
<dd>
Default list of words with affixes that is used by
htfuzzy.
</dd>
<dt>
<em><img src="bdot.gif" width=9 height=9 alt="*"> <code>--with-common-dir=DIR</code></em>/english.aff
</dt>
<dd>
Default affix rule database that is used by htfuzzy.
</dd>
<dt>
<em><img src="bdot.gif" width=9 height=9 alt="*"> <code>--with-image-dir=DIR</code></em>/star.gif
</dt>
<dd>
The default star image that is used to rank matches.
</dd>
<dt>
<em><img src="bdot.gif" width=9 height=9 alt="*"> <code>--with-image-dir=DIR</code></em>/star_blank.gif
</dt>
<dd>
The default placeholder image that is the same size as
the star, but is blank. This is used to align the
results in the short listing.
</dd>
<dt>
<em><img src="bdot.gif" width=9 height=9 alt="*"> <code>--with-image-dir=DIR</code></em>/htdig.gif
</dt>
<dd>
The nifty ht://Dig logo.
</dd>
<dt>
<em><img src="bdot.gif" width=9 height=9 alt="*"> <code>--with-image-dir=DIR</code></em>/button*.gif
</dt>
<dd>
Sample images used to show the search result pages.
</dd>
<dt>
<em><img src="bdot.gif" width=9 height=9 alt="*"> <code>--bindir=DIR</code></em>/rundig
</dt>
<dd>
A sample shell script which will create a database.
</dd>
<dt>
<em><img src="bdot.gif" width=9 height=9 alt="*"> <code>--prefix=DIR</code>/lib/htdig</em>/*.{a,so}
</dt>
<dd>
The shared and static libraries.
</dd>
<dt>
<em><img src="bdot.gif" width=9 height=9 alt="*"> <code>--prefix=DIR</code>/include/htdig</em>/*.h
</dt>
<dd>
The header files that allow anyone to develop a program
based on the internals of htdig.
</dd>
</dl>
</blockquote>
<p>
Note that these files will <em>never</em> replace any existing
files that may already be installed.
</p>
<p>
It is also important to note that these files are mostly
examples. As they stand, they will work, but you probably
want to modify them to reflect your needs.
</p>
<p>
After the installation, you will be ready to test out
everything. You can use the <code>rundig</code> script to make a
test database of the online documentation at
http://www.htdig.org/
</p>
<p>
The only thing left to do is to modify the <code>
htdig.conf</code> config file which was placed in <em>
<code>--with-config-dir=DIR</code></em>/htdig.conf. The <a href="attrs.html">
Configuration</a> manual has the details on how what
attributes are needed.
</p>
<hr noshade>
<h2>
<a name="sharelib">Shared Libraries</a>
</h2>
<p>
By default ht://Dig is compiled with shared libraries. If
running on a platform other than Linux or FreeBSD, this may
be a problem. We recommend that you compile with the
<code>--disable-shared</code> configure option.
</p>
<p>
If you installed with shared libraries, you must be sure the
system will find them. Usually it's done by adding the
prefix/lib/htdig directory to the LD_LIBRARY_PATH.
This is really system dependent and you must check your
documentation.
</p>
<hr size="4" noshade>
<a href="author.html">Andrew Scherpbier <andrew@contigo.com> & the ht://Dig Group</a>
Last modified: $Date: 2001/02/15 17:05:33 $
</body>
</html>
