TODO -- see TODO

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

Before you begin, you will need the following:

[1] the lq-text 1.16 distribution, lq-text-1.6.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,
    although lq-text may go several times faster with the version
    included here, as "ndbm.c" has been edited to tune the parameters.


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

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

You'll need between 1 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 dynamic (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!


[2] editing files by hand

    Only do this if you did not use configure!

    First, run the following to put the files in place, e.g. in case
    you tried running configure and something went wrong:
	cd src
	sh setup.sh
    
    Now 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

[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.16 built successfully in /build/lq-text-1.16
    
[4] testing

    You should test the software before installing it.  To do
    this, you will need to have approximately TODO 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 won't build right now.  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
	mailing-list
    (the files are in the docs directory)

[5] installing

    You can run
	make install
    to install lq-text.

TODO
move the rest of the file to the right places!

Known Problems


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 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.

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.

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, 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 Saber-C, the first thing to do is to buy it.
It's worth it...  I don't have sabre.project files lying around; sorry.
If you modify the Makefiles to work with sabre or centreline, please
do let me know. [Sabre C is commercial, from Centreline or Centerline,
I forget which.  I think the product is now called Codecentre or
testcenter]

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.

See also PORTING and GuidedTour.


