Installation

This document needs to be merged with TESTING.md. The TESTING.md document was written more recently, but there may still be useful information below. (We appreciate your patience while we are in the slow process of updating the documentation.) If you would like to edit parts of this document, the file is docs/infiles/install.sct.

This document will attempt to show the steps needed to build and install the hl://Dig system.
The main sections are:

For the impatient...

TESTING.md contains the steps necessary on how to do the following without root privileges.

The standard GNU installation process works for hl://Dig.
./configure --prefix=/usr/local
make
make install
vi /usr/local/conf/hldig.conf
/usr/local/bin/rundig
(The final three commands must be issued as root.)

Extracting the software

There hasn't yet been a release of hl://Dig. You can get the source code from the git repository.

Configure

Once the distribution has been extracted, change to the newly created directory.
In this directory you will need execute the configure program:

% ./configure

This program will attempt to determine what your particular system can and can't do.

If you are going to change any of the sources to hl://Dig, then you can optionally add dependency information to all the Makefiles before running configure with the command

% automake

The configure program has some hl://Dig specific options in addition to the standard ones that you get when running 

    ./configure --help

--prefix=DIR
This is where all of the hl://Dig parts will be installed. Various other variables will use this value as their base. [default=/opt/www]
--bindir=DIR
All the hl://Dig executable programs will go here [default=/opt/www/bin].
--with-config-dir=DIR
where your config directory is [default=/opt/www/conf]
--with-default-config-file=FILE
Point this to where all the tools will look for the configuration file [default=/opt/www/conf/hldig.conf].
--with-common-dir=DIR
This directory is for files which can be shared between different search databases [default=/opt/www/share/hldig].
--with-database-dir=DIR
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/hldig].
--with-cgi-bin-dir=DIR
The directory where your HTTP server looks for CGI programs. This is where htsearch will get installed [default=/opt/www/cgi-bin].
--with-image-dir=DIR
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/hldig/www].
--with-image-url-prefix=LOCATION
This is the URL which points to the directory specified by the --with-image-dir=DIR option above [default=/hldig].
--with-search-dir=FILE
where the sample search form should be installed [default=/opt/www/hldig/www].
--with-search-form=FILE
The name of the file in which the sample search form will be installed, relative to the directory specified with --with-search-dir=DIR [default=search.html].

Compile

The configure program will have created Makefiles in all the important directories.

If make is not able to deal with the generated Makefiles, you should probably obtain GNU make.

Now build the complete system with

% make

(Sit back and relax for a while...)

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 system requirements for details on this.

Test

The information below is outdated and the test feature needs to be fixed. There is an open ticket to address the issue.
Once built, you can run tests if you provided the --enable-tests at configure time. These tests require that you have a working Apache daemon available with version >= 1.3.1. To run the tests execute:

If your Apache daemon is installed in a non standard place, specify it with the --with-apache=PATH configure option.

% make check

Install

Everything should have built at this point. To install the software, you need to execute

% make install

This will perform several tasks. It will first attempt to create the directories that you specified to ./configure. It will then copy the following programs to the --bindir=DIR directory:

  • hldig
  • hlmerge
  • hlfuzzy
  • hlnotify
  • hldump
  • hlstat
  • hlload

It will also copy the htsearch program to your --with-cgi-bin-dir=DIR directory.

After this, several files will be customized and installed. Here is a list of the files that get installed:

*--with-config-dir=DIR/hldig.conf
A minimal config file which can be used to create a search database for https://solbu.github.io/hldig/
*--with-search-form=FILE
A sample HTML document that contains a search form.
* --with-common-dir=DIR/footer.html
A sample HTML document that can be used as the search results footer.
* --with-common-dir=DIR/header.html
A sample HTML document that can be used as the search results header.
* --with-common-dir=DIR/nomatch.html
A sample HTML document that can be used if nothing was found.
* --with-common-dir=DIR/syntax.html
A sample HTML document that will be displayed if the user entered an illegal boolean expression. found.
* --with-common-dir=DIR/english.0
Default list of words with affixes that is used by hlfuzzy.
* --with-common-dir=DIR/english.aff
Default affix rule database that is used by hlfuzzy.
* --with-image-dir=DIR/star.gif
The default star image that is used to rank matches.
* --with-image-dir=DIR/star_blank.gif
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.
* --with-image-dir=DIR/logo.jpg
The nifty hl://Dig logo.
* --with-image-dir=DIR/button*.gif
Sample images used to show the search result pages.
* --bindir=DIR/rundig
A sample shell script which will create a database.
* --prefix=DIR/lib/hldig/*.{a,so}
The shared and static libraries.
* --prefix=DIR/include/hldig/*.h
The header files that allow anyone to develop a program based on the internals of hldig.

Note that these files will never replace any existing files that may already be installed.

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.

After the installation, you will be ready to test out everything. You can use the rundig script to make a test database of the online documentation at https://solbu.github.io/hldig/

The only thing left to do is to modify the hldig.conf config file which was placed in --with-config-dir=DIR/hldig.conf. The Configuration manual has the details on how what attributes are needed. Then, you'll be ready to begin running hl://Dig.

Shared Libraries

By default hl://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 --disable-shared configure option.

If you installed with shared libraries, you must be sure the system will find them. Usually it's done by adding the prefix/lib/hldig directory to the LD_LIBRARY_PATH. This is really system dependent and you must check your documentation.

Powered by simplectemplate - RSS rss