             QDDB VERSION 1.43 INSTALLATION NOTES


                       CONTENTS

1. Qddb quick installation notes
2. Qddb miscellaneous install notes
3. System specific installation notes
4. Monochrome displays
5. Miscellaneous X comments

-------------------------------------------------------------

1. Qddb quick installation notes
--------------------------------

See the scripts in qddb-<version>/Notes/ called:

	tk3-setup.sh   -- Tk version 3.6a
	tk4-setup.sh   -- Tk version 4.X
	itcl2-setup.sh -- [incr Tcl] version 2.0 
           (see ITCL2.X NOTES below)
	itcl2.1-setup.sh -- [incr Tcl] version 2.1 
           (see ITCL2.X NOTES below)
	itcl2.2-setup.sh -- [incr Tcl] version 2.2
           (see ITCL2.X NOTES below)

We are frequently asked the question 

        "Which setup is best supported?"

We use itcl2.2 for our own purposes, but we support all
the configurations listed above EXCEPT tk3.   Tk3.6 is
obsolete now, and we have no desire to maintain it.  We
include it only for the convenience of those who cannot
switch to Tk4.X.    The version that uses Tk4/itcl1.5 does not 
support the new report generator.   Use itcl2.2 if you
can.

--------------------------

The following assumes you have all the packages described 
in section (2) of this file.

Edit the scripts and replace all the variable definitions
with the appropriate values for your system and configuration.
Don't forget to change CC and CFLAGS; invalid CFLAGS can 
cause configure to fail.

Next, if you use sh, ksh, bash, or other Bourne shell 
compatible shell, you can then do something like:

	$ . Notes/itcl2.2-setup.sh

Now, you can configure and make with something like:

	$ rm -rf /usr/local/qddb/* # or whatever the prefix is
	$ ./configure --with-tk --with-itcl2 --with-tktable \
	      --with-blt --with-tix --enable-maxmem=10240
	$ make install

The best minimum configuration is:

	$ rm -rf /usr/local/qddb/* # or whatever the prefix is
	$ ./configure --with-tk --with-itcl2 --with-tktable \
		--with-blt
	$ make install

BLT can be excluded, but it provides a busy cursor that
is needed to keep the user from clicking on things when
Qddb is doing something important.   It also provides the
graphs and barcharts for the report generator.  BLT 2.1
barcharts require a patch available from:

    ftp://ftp.hsdi.com/pub/qddb/sources/blt2.1-barchart.patch

The manual in Doc/Manual/qddb-guide.ps.gz (you'll need
to gunzip it first) contains more information about the
various configuration options.


2. Qddb miscellaneous install notes
-----------------------------------

You need:
    1) Flex 2.5.4 and Bison 1.25 (previous versions may work)
    2) Tcl 7.X and Tk 4.X
    3) [incr Tcl] 2.2 or [incr Tcl] 1.5 + Tcl 7.4 patches (see below)
    4) BLT 2.1

---Tk4 NOTES (also see ITCL2.0 NOTES below!)

You should *definitely* run the Tcl/Tk test suites before
installing Qddb with Tcl 7.4 and Tk 4.0.   Some optimizers seem
to break Tk and the tests will core dump.   If you see this behavior,
disable (or reduce the level of) optimization.  "make test" is
the command to use in either the tcl-7.4 or tk-4.0 source directory.
If you do not see a core dump during the tests, it is probably ok.
You may see a few of the tests fail (but not core dump); ignore the
failures.   On BSD/OS and Linux, the "-O9 -m486" optimization 
options appear to be fine under GCC 2.7.2.

If you plan to use [incr Tcl] 1.5, you should grab the copy from
    ftp.ms.uky.edu:/pub/unix/qddb/tcl/itcl-1.5-tk4.tar.gz

Also, when installing itcl-1.5, blt-2.1, or any other extension with 
Tk-4.0:

 * make sure that you are compiling the extensions with the Tcl-7.4
 * and Tk-4.0 headers/libraries!!!   The easiest way to be sure is to
 * install the sources under a different source tree than the tk-3.6
 * stuff:
 *     /usr/src/tk4 # tcl-7.4 and tk-4.0 extensions and sources
 *            tcl-7.4
 *            tk-4.0
 *            tcl -> tcl-7.4 (symlink)
 *            tk -> tk-4.0 (symlink)
 *            blt-2.0
 *            itcl-1.5
 *            tix-4.0.4
 *            ....

The new Tcl/Tk install their libraries as libtcl7.4.a and libtk4.0.a
so you can keep separate versions around.   Personally, I like to
keep them in separate directories.   For example, you might configure 
Tcl/Tk and extensions with --prefix=/usr/local/tk4.   Then you can
set up Qddb with:

#(or modify Notes/tk4-setup.sh and type ". Notes/tk4-setup.sh")
$ export TK_INCLUDE_DIR=/usr/local/tk4/include
$ export TK_LIBRARY_DIR=/usr/local/tk4/lib
$ export TK_LIBRARY_NAME=tk4.0
$ export TCL_INCLUDE_DIR=/usr/local/tk4/include
$ export TCL_LIBRARY_DIR=/usr/local/tk4/lib
$ export TCL_LIBRARY_NAME=tcl7.4
$ export ITCL_LIBRARY_DIR=/usr/local/tk4/lib
$ export BLT_LIBRARY_DIR=/usr/local/tk4/blt/lib
$ export TIX_LIBRARY_DIR=/usr/local/tk4/lib
$ export TIX_LIBRARY_NAME=tix4.0
$ export CC=xgcc
$ export CFLAGS="-g -O9 -m486 -Wall"
$ export MAKE=gmake
$ ./configure --prefix=/usr/local/qddb --with-tk \
    --with-blt --with-itcl --with-tktable --with-tix \
    --with-gnumalloc --enable-maxmem=10240
# If you are installing over an old version of 
# Qddb, you should 'rm -rf /usr/local/qddb/*' before making.
<stuff deleted>
checking for X... libraries /usr/X11R6/lib, headers /usr/X11R6/include
Using BLT_LIBRARY_DIR value: /usr/local/tk4/blt/lib
checking for -lsocket... no
checking for -lnsl... no
Using TCL_INCLUDE_DIR value: /usr/local/tk4/include
Using TK_INCLUDE_DIR value: /usr/local/tk4/include
Using TCL_LIBRARY_DIR value: /usr/local/tk4/lib
Using TK_LIBRARY_DIR value: /usr/local/tk4/lib
checking your version of Tk... Tk version 4
Using ITCL_LIBRARY_DIR value: /usr/local/tk4/lib
Using TIX_LIBRARY_DIR value: /usr/local/tk4/lib
<stuff deleted>
$ gmake install

This should install and make Qddb without warning.   Now
you can use the new version of nxqddb:

$ nxqddb MyDatabase

---ITCL 2.X NOTES (see Notes/NOTES-itcl2.X for detailed
instructions):

[incr Tcl] 2.0 has a couple bugs in it that must be fixed
before Qddb will work properly.

	ftp.ms.uky.edu:/pub/unix/qddb/tcl/itcl2.0-qddb.patch

itcl2.0.tar.gz is also in that same directory for your
convenience.  The patch also fixes a bug in the menu handling
Tk library.

[incr Tcl] 2.1 doesn't have these problems, but you should
apply the patch:

	ftp.ms.uky.edu:/pub/unix/qddb/tcl/itcl2.1-qddb.patch

if you plan to incorporate Tix into your qddb_wish.

[incr Tcl] 2.2 works properly out of the box.   We strongly
recommend it.

If you want to compile BLT and Tix, you need to do the 
following:

	1. unpack the itcl2.2 distribution
	2. apply the patch appropriate for your version of
           itcl.
	3. unpack BLT 2.1, Tix, etc. in the itcl2.X directory!
	4. configure and compile itcl2.X
	5. cd into each extension directory, set up any
           environment variables you need, configure and
           compile.   For Tix, make sure that you set up
           the following variables to point to the tcl/tk
           sources in the itcl 2.X distribution.   Something
           like the following:
              TCLINCLUDES=/usr/src/itcl2.X/tcl7.X
              TKINCLUDES=/usr/src/itcl2.X/tk4.X
              TCL_LIBRARY=/usr/src/itcl2.X/tcl7.X
              TK_LIBRARY=/usr/src/itcl2.X/tk4.X
        6. install itcl2.X and your extensions.   Remember
           that itcl2.X currently installs a new libtk4.[45].a 
           and libtcl7.[45].a.   I like to use 
              ./configure --prefix=/usr/local/itcl
           for itcl2.X so I can keep the original versions 
           around under a separate directory.

Next, edit the file qddb-<version>/Notes/itcl2.2-setup.sh and
correct the paths and compiler options.   If you run ksh,
bash, or sh, type the following:

	$ cd qddb-<version>
	$ vi Notes/itcl2-setup.sh # edit to your liking
	$ . Notes/itcl2-setup.sh
	$ ./configure --with-tk --with-itcl2 --with-tktable \
		--with-tix --with-blt
	# NOTE: tktable is included in Qddb for convenience.
	$ make
	$ make install

If you have other widgets you use with itcl2.X, you may
have to do some hacking to get them to work.    See the
file Notes/NOTES-itcl2 for some miscellaneous comments
and detailed installation instructions.  Old Fx scripts
usually need only a mild amount of hacking to get them
working.

3. System specific installation notes
-------------------------------------

* DEC Alpha OSF/1:

    When configuring, you should use the standard C compiler:
	CC="cc -std1" ./configure [options]

    Qddb apparently brings out a bug in GCC on the Alpha, so don't use GCC
    on DEC Alphas.   (this note may be old, we don't have access to an Alpha
    anymore)

    --with-mallocstats and --with-gnumalloc cannot be used with DEC Alpha OSF/1
    --enable-maxmem=22528 seems to be about right for an active 64MB DEC Alpha.

* HP/UX A.09.03:
    Tested with the standard C compiler.    If you plan to use Qddb over
    NFS without a lock daemon, you probably want to compile with
    --disable-record-locking (this is bad for multi-user databases).
    Otherwise, Qddb appears to wait for the locks forever.   If you use
    the lock daemon, you shouldn't have any problems.

* BSD/386 V1.1, BSD/OS V2.0, BSD/OS V2.1:
  (this is where we do the majority of our development)
  V1.1, V2.0.1: Configure with:
        $ export CC=gcc2 CFLAGS="-O9 -m486" MAKE=gmake
        $ ./configure <options>
    (-O9 is only available in gcc=2.7.1 and later)
  V2.1: Configure with (you need the LIBS=-lipc environment variable):
        $ export CC=gcc2 CFLAGS="-O9 -m486" LIBS=-lipc
        $ ./configure <options>

* Solaris 2.3:  Tcl 7.3 seems to include compat/dirent.h, compat/getcwd.c and 
    compat/opendir.c when it shouldn't.   It also seems to use 
    compat/dirent.h.   Force the configure script not to use the compat stuff.
    This is not true of Tcl-7.4/Tk-4.0 and later.

* SunOS 4.1.3, 4.1.4:
    Only tested with GCC and GNU make.   We had to use CC="gcc -static"
    to get it to link under 4.1.4.   (Because we didn't compile
    Tcl/Tk/etc. into shared libraries?)   Make sure your CFLAGS="-O"
    and not "-O9 -m486" (and don't set LIBS="-lipc"!) because it 
    will confuse configure.   You may have to link your libraries
    such as libitcl2.1.a to libitcl.a to get the link to work.

* FreeBSD 2.1, 2.2:
    Make sure you have gcc 2.7.2 or later installed.   Also, use gmake.

* Linux: Linux record locking once was very broken (as of 1.1.69 or so) so if 
    you have problems, try configuring with --disable-record-locking.   Qddb 
    attempts to work around Linux' old record locking problems.  We currently 
    know of no problems with this workaround.   Linux 1.2 and later claim
    to be POSIX compliant; there should be no problems with record locking
    if you run a Linux kernel later than 1.2 (we know 1.2.8, 1.2.13, and 2.X
    work fine.)    Note that we currently use Red Hat 4.0 for testing; we will
    gladly accept donations of other distributions if you want a particular
    one well-supported.

    Note that by default, some Linux distributions do not like <BackSpace>.
    You may need to do something like:
        xmodmap -e "keysym Delete = BackSpace"
    in your .xsession and/or .xinitrc file.   Something like this does
    pretty good too:
        # ~/.xsession or ~/.xinitrc
        xmodmap /usr/X11/lib/X11/etc/xmodmap.std

We have reports that Qddb runs under IRIX, UnixWare, Ultrix, OSF/1
and NetBSD. Please let us know if you successfully compile it on
something else.

Please refer to the manual pages, "A Guide to Qddb", and
the "Qddb User's Guide" for more information.

4. Monochrome displays
----------------------
nxqddb should work properly on monochrome displays if
you have your .Xdefaults set up for use with other
Tk-based programs.   If you tend to use a dark
background and light foreground, you may want to
add something like the following lines to your .Xdefaults file.

#ifndef COLOR
*Entry*foreground: black
*Entry*background: white
*Text*foreground: black
*Text*background: white
*Listbox*foreground: black
*Listbox*background: white
*Button*foreground: black
*Button*background: white
*Scrollbar*foreground: white
*Scrollbar*background: black
*Label*foreground: white
*Label*background: black
*activeForeground: black
*activeBackground: white
*Checkbutton*selector: white
*Radiobutton*selector: white
*Menu*selector: white
#endif

5. Miscellaneous X comments (this note is obsolete!)
-----------------------------------------------------
For those of you that do not typically use Tk-based
applications, the <Alt> key should be mapped as <Mod2>.
Anywhere you see <Alt> as an accelerator, use
whatever you have bound as <Mod2>.   On a PC keyboard,
you can:

    xmodmap -e "clear Mod1"
    xmodmap -e "clear Mod2"
    xmodmap -e "add Mod2 = Alt_L"

Again, on Linux, you probably want to put something like:

    xmodmap -e "keysym Delete = BackSpace"

in your .xsession and/or .xinitrc file.   Linux maps the
backspace key to output <Delete>; Tk apps won't work very
well otherwise.


