Please read the file README in this directory for additional important
information on The DICT Development Group, this software, mailing lists, etc.

INSTALLATION
============

0. Before building Dictionary server (dictd) or Dictionary client (dict),
   you should build (and optionally install) libmaa library.

        cd libmaa
        ./configure
        make
        make install

   Installing libmaa is actually not mandatory. See below.

1.  Configure the source code and Makefiles:

        ./configure

    NOTE: the configure script accepts the common --prefix flag for
    installing the software in an installer-defined location.  For example,
    you can do something like:

        ./configure --prefix=/opt/gnu

    NOTE: as of version 1.8.0, dictd supports plugins.
    If you do not want support for them, disable it:

        ./configure --disable-plugin

    NOTE: as of version 1.9.10, dictd can be built
    with any regex engine you want. By default system-wide one is used.
    It is assumed that it is libc library.

      Example: (to build dictd with TRE regex library):

        env LDFLAGS='-L/usr/local/lib/ -ltre' \
           CPPFLAGS='-I/usr/local/include/tre' ./configure
        make

    You can also link dictd/dict/... against libmaa statically.

        env LDFLAGS='-Llibmaa/.libs' CPPFLAGS='-Ilibmaa' ./configure
        make 

2.  Compile the client and server software:

        make 

    NOTE: If you want to build only the client software, use 'make
    dict' instead of just 'make'. In order to make dictd, dictfmt or
    dictzip only, run 'make dictd', 'make dictfmt' or 'make dictzip'.

    [The dict client has been tested under Cygwin+Win98. As of version
    1.9.9, dictd can also be run on cygwin from inetd. It has been
    tested on NT4/sp6 + cygwin-1.3.6 and W2K + cygwin-1.3.22]

    NOTE: If you use an old version of flex, you may get errors.  Try
    upgrading it.

3.  Install the client, server, and manual pages:

        make install

    NOTE: If you only built the client software in step 2, use
    'make install.dict' instead of 'make install'.
    You can also use 'make install.dictd', 'make install.dictfmt' and
    'make install.dictzip'.

4.  Uninstall the client, server, and manual pages:

        make uninstall

    NOTE: If you only built the client software in step 2, use 'make
    uninstall.dict' instead of 'make uninstall' You can also use 'make
    uninstall.dictd', 'make uninstall.dictfmt' and 'make
    uninstall.dictzip'.

5.  Several plugin examples are available.
    One of them is C++-based 'popen' plugin which runs an external program
    for both DEFINE and MATCH queries.

    If you want to build/install/uninstall these samples,
    run the following commands respectively:

        make samples

        make install.samples

        make uninstall.samples

    Also 'man_popen' dictionary based on 'popen' plugin is available.
    Its functionality is a subset of that of the 'man' command.
    Only 'exact' and 'substring' search strategies are implemented.
    In order to test 'man_dict' dictionary and 'popen' plugin,
    you can make the following:

        ./configure --prefix=/usr/local \
                    --libexecdir=/usr/local/libexec/dictd
        make dict
        make dictd
        make samples
        make install.samples
        ./dictd -dnodetach -dnofork -c examples/dictd_popen.conf

    and then in another terminal run

        ./dict -h localhost man
        ./dict -h localhost -s substring -m malloc

    NOTE: If you configure 'dictd' with '--disable-plugin' option,
          this test will fail.

    NOTE: After testing complete, do not forget to run

        rm -rf /tmp/dictd

6.  Install any databases you would like dict/dictd to utilize.  The
    database(s) should be installed in a location that the 'dictd'
    server process has access to.  The preformatted dictd-usable databases
    you need can be found at any of the following locations:

        ftp://ftp.dict.org/dict/pre/               [most up to date]
        ftp://ftp.cs.unc.edu/pub/users/faith/dict/pre/ [mirror]

    a)  Make a directory to contain the dictionary database(s).  We'll
        use '/opt/public/dict-dbs' for this EXAMPLE.

    b)  For the sake of this document and to get you up and running, let's
        say you're only interested in the Webster 1913 dictionary database.
        In that case, get the latest 'dict-web1913...' file from one of the
        locations above.

    c)  Unpackage the 'dict-web1913...' file and put the resulting files
        (see below) into /opt/public/dict-dbs (our EXAMPLE area...).

           web1913.dict.dz   The 'dictzip' format database
           web1913.index     The index of the database

7.  To setup a proper server, you will need to configure a dictd.conf
    file.  Please see the man page dictd.8 and the example .conf files
    included with the source code for an explanation of the syntax needed
    and other important details.  By default, dictd will try to find this
    file as '/etc/dictd.conf', however if you start 'dictd' with the
    '-c /your/path/to/your/conf/file/mydictd.conf', it will use that
    file as the configuration file instead.

    For our example, with our web1913 database in /opt/public/dict-dbs,
    a MINIMAL dictd.conf file would be:

        database web1913 { data "/opt/public/dict-dbs/web1913.dict.dz"
                          index "/opt/public/dict-dbs/web1913.index" }

8.  If you're installing this software for "intranet" use, you will want to
    setup a 'dict.conf' file which the client software (dict) uses to
    locate servers and such.  The syntax of the dict.conf file is not
    documented anywhere that I can find, however if you have your 'dictd'
    server running on the host named dict.company.com, then you should put
    the following line in your dict.conf file so that users of the 'dict'
    client do not have to specify '-h dict.company.com' each time they
    want to query dictd:

        server dict.company.com

9.  That's it really.  Now pieces everything together, run your dictd and
    point it at your config file, and try running dict!


GENERAL EXTRA INSTALL HELP
==========================

If the above information all isn't very clear, here's a view of good
distributed environment's setup:

    /usr/local/sbin/dictd         # Accessible from all hosts on our net
    /usr/local/bin/dict           # Accessible from all hosts on our net
    /usr/local/bin/dictfmt        # Accessible from all hosts on our net
    /usr/local/etc/dictd.conf     # Accessible from all hosts on our net
    /usr/local/etc/dict.conf      # Accessible from all hosts on our net
    /usr/local/lib/dict-dbs       # Accessible from all hosts on our net

    /usr/local/etc/dictd.conf contains 2 lines:

        database web1913 { data "/opt/public/dict-dbs/web1913.dict.dz"
                          index "/opt/public/dict-dbs/web1913.index" }

    /usr/local/etc/dict.conf contains 1 line:

        server dict

This setup allows ANY host on the network to quickly and easily become
the dictd server.  All you have to do is setup a 'host alias' for the
name 'dict' to point at whatever host you want to be the dictd server
and then start dictd on that host.
 
NOTE:  I had to install the dictd.conf and dict.conf in that location
       BY HAND.  This is not done automatically for you.

[INSTALL file courtesy Jeff Blain <jblaine@linus.mitre.org>]
