TODO -- see TODO

Installing lq-text
==================

Before you begin, you will need the following:

[1] the lq-text distribution, e.g. lq-text-1.17.tgz

[2] the Berkeley DB distribution (optional)
    Version 1.85 is included with lq-text.

    If you already have DB installed, you can use the installed version;
    I have only tested with 1.85.  This is included with Linux and BSD,
    so use "dbnative" as the db type for Red Hat.


Unpack the distribution
    gunzip < lq-text-1.17.tgz | tar xvf -
This will create a directory called lq-text-1.17

You will need to choose where to install the package.
The default is /usr/local/lq-text/bin for binaries, and
man, lib and doc for man ages, library files and HTML documentation
respectively.

You'll need between 3 and 10 MBytes to do an install, depending on
the platform (i486 binaries are smaller than SPARC binaries) and
whether you use dynamic (smallest) or static (largest) linking for
the binaries.  The default is to use dynamic linking, and you shouldn't
normally need to change that.

You'll also need to configure the compiler for your platform.

You can do these two things (choose install directory and configre
compiler options) in two ways: you can either [1] use the GNU configure
package, or [2] edit a few files yourself:

[1] using configure

    Not availble, sorry.
    If you have time to help write autoconf scripts, pelase do!
    The old configure script I used is no longer included.


[2] editing files by hand

    You will need to edit the following files and follow the
    instructions in them:
	Makefile
	h/globals.h
    Review Makefile after editing h/globals.h

    The most important things are
	TOP (this directory)
	CC (e.g. gcc)
	CFLAGS (e.g. -O3)

    You should use the maximum optimisation provided by your C compiler.


[3] compiling

    First, run "make depend":
	make -i depend

    You can ignore errors; if this doesn't work, no matter.

    Now build the software with
	make
    
    This should end with a message like
	lq-text 1.17 built successfully in /build/lq-text-1.17
    although some versions of make will print other messages after that.
    

[4] testing

    You should test the software before installing it.  To do
    this, you will need to have approximately 10 MBytes of disk
    space available.  The test may take anything from a few minutes
    to an hour or so, depending on the speed of your machine.

    Run the tests like this:
	make test

    NOTE: some of these probably won't build.  Don't panic.
    Use make -i test.

    This should end with a message like
	All tests passed.
    
    If it didn't, see the following documentation topics:
	compiling
	porting
    (the files are in the docs directory)


[5] installing

    You can run
	make install
    to install lq-text.

    Man pages are not yet installed, TODO install them.

    Welcome to the best text retrieval package for Unix! :-)


TODO
====
    install man pages automatically (!)

    make a configure script, RPM, Solaris pkg, etc
    Someone offered to do a .deb but has not got round to it.

    pointers to Getting Started tutorial


Known Problems
=============

(See also PORTING and GuidedTour)

lqaddfile may run slowly if the database directory is mounted over a
network with NFS.  Run lqaddfile on the NFS server -- there's no problem
with having the data files on a remote system, as long as all of the
systems accessing (and indexing) the data have the same CPU architecture.
The speed difference is approximately a factor of two or three,
depending on the speed of the NFS server and the amount of memory
on the client.

With this distribution I am including both Ozan Yigit's sdbm package
and the BSD hash package (db) written by Ozan Yigit, Keith Bostic and
Margo Seltzer.  I'm including db 1.85.

Try using db first, and if that doesn't work use sdbm.  Sdbm has been
ported extensively, but has size limitations that may affect you in
some very obscure situations.  You'll get error messages at runtime
in these cases, when making a document index.

If you end up with one or more empty .dir or .pag files in the
LQTEXTDIR directory, you probably have a broken sdbm/ndbm/dbm.  Try
recompiling with a different dbm package if possible.

There are some tests, but it is not always clear how to run them.
I intend to make a little test suite...
If you get strange error messages, try
    testbin/dbmtry 5000
(this will make and leave behind either one or two files in /tmp).
Then try testbin/dbmtry 10000.  If that gives errors, the most likely
problem is that you have a faulty bcopy.  I have included a version
of bcopy() that is not linked in by default -- you could try using that.
Edit src/liblqtext/Makefile to include it.  Do not try to use memcpy(),
as it doesn't handle overlapping regions correctly.
Some systems have a memcopy() function which works and is faster, so you
could also do #define bcopy(src, dest, n)  memcopy(dest, src, n) in port.h

If -lmalloc fails, simply remove it in src/Makefile.
I will add a configure test for this one day...

You can use the highest available level of optimisation on all
the systems I've tried, including gcc -O6.  Under SunOS 1.4, you can even
compile with -O4 -Qoption iropt -l4 to do loop unrolling, if you want.
This makes the binaries bigger and may give a speed improvement.

For serious debugging, see the notes in src/Makefile.  If you are
debugging C programs without Centerline's testcentre/codecenter,
the first thing to do is to buy it.  It's worth it...

Otherwise, for debugging, compile with -DASCIITRACE.  You could also use
-DMALLOCTRACE, which makes the malloc() routines print messages to
stderr, which can be processed with awk -- see test/malloctrace.  If you
use -DWIDINBLOCK everything will be much slower, but more errors are
reported.  WIDINBLOCK makes lqaddfile store in each data block the Word
Number (WID) of the owner of that data block.   This uses 4 bytes out of
every 64 bytes of index, so you don't want to leave this on by mistake!

There is also a -DDEBUGPLACES, which more than doubles the size of the
index, slows things down, and when used with
    lqword -A > /dev/null
will test the database read/write code by puting markers around every
object that's written out.  It's really only for my own use, but if you
modify lq-text you may want to know what it's for.

If you obtained this package under the barefoot licence, rememeber to
go barefoot for 24 hours some time in the next week.  Send me a picture,
or write about what it was like.

Liam