                      Sqsh - Installation Notes

Description
-=-=-=-=-=-

The follow document describes how to build and install the Sqsh SQL
shell, version 1.5. For an overall description of the package, please
refer to the file README.

Supported Platforms
-=-=-=-=-=-=-=-=-=-=-

This program has been built and tested (although by no means would I
say thoroughly) on a whole slew of platforms, including Solaris 2.x,
SunOS 4.x, HP-UX 10.x, HP-UX 11.x, IRIX 5.x, IRIX 6.x, NCR SVR4,
Dynix/ptx 2.x, NeXT, AIX 3.x, AIX 4.x, Digital UNIX 3.x, DG/UX 5.4.x,
Linux 2.x, and NetBSD (I am sure that there are more).

I am always interested in hearing of any trials and tribulations
that you encounter when trying to port sqsh to variable platforms.

Requirements
-=-=-=-=-=-=-

In order to build this package, you will need:

   o  Sybase CT-Library

      Unfortunately you need to buy this package for most platforms.
      For Linux (and those OS's capable of emulating it), Open Client
      10.0.4 is given out with the free distribution of ASE 11.0.3.3.
      This distribution is available from most major Linux distributions,
      such as Red Hat (www.redhat.com), Caldera (www.caldera.com),
      and S.u.S.E (www.suse.com).  Feature note: it should be relatively
      trivial to port Sqsh to support new databases, such as University
      Ingres or Postgres.  If there are any companies out there that
      would like me to port it to their database, I am willing to work for 
      hardware. A 20" LCD panel display and a 9G Cheeta should do
      nicely =8-)~

   o  X11R4 or Later (optional)

      To take advantage of the X Windowing System display style, you 
      must have at least X11R4 (R5 or later recommended).  This may 
      be found from ftp://ftp.x.org.

   o  GNU Readline library (optional)

      If you want emacs/vi style keyboard editing, this package is a must.
      I'll warn you though, it'll add some major bulk to the executable.
      You can get it from ftp://prep.ai.mit.edu/pub/gnu/readline-2.2.tar.gz.

Problems
-=-=-=-=-

If you have any trouble while trying to build sqsh, first make sure
that you read the FAQ supplied with the distribution.

Building
-=-=-=-=-

Sqsh takes advantage of the GNU auto-configuration package (a truly
nifty tool) so it should be relatively easy to make and build. 
Just follow the following directions:

1) Set $SYBASE

   In order for auto-configuration to work correctly, the environment
   variable SYBASE must be correctly set to point to your base SYBASE
   directory.  For bourne shell users (sh, bash, zsh, etc.), simply
   do:

      % SYBASE=/usr/local/sybase
      % export SYBASE
   
   or for csh and that ilk, do:

      % setenv SYBASE /usr/local/sybase

2) Run "configure"

   $ ./configure

   The configure shell script goes out and attempts to figure out
   exactly what your machine looks like.  The script supports the
   following options:

       --prefix=DIR

         Specifies an alternate base directory in which to install
         the sqsh binary and man page (in DIR/{man,bin}). By default
         this is /usr/local.

      --exec_prefix=DIR

         This option allows the binary to be installed in a directory
         other than the one specified with --prefix, instead the
         binary will be placed in DIR/bin.
      
      --with-readline

         If you have the GNU Readline library available (see Requirements,
         above), supply this flag to enable readline support in sqsh. 
         Supplying this option will cause 'configure' to attempt to
         automatically determine the location of your readline header
         files and libraries.  Hints may be supplied as to the location
         of these files using the INCDIRS and LIBDIRS environment
         variables described below, otherwise a search-path of common
         installation locations are used instead.

      --with-x

         Enables X windows support in sqsh.  This requires the existence
         of X11R4 or later on your system.  By default, if this flag
         is not supplied, X support is disabled.

      --without-x

         Disables X support.  This is the same as running configure
         without '-with-x'.
      
      --x-includes=<incdir>
      
         By default, if --with-x is supplied configure will auto-
         matically attempt to find the location of your X11 
         include directory.  If it fails or chooses the wrong
         directory, this option may be supplied to force it to
         use <incdir>.
   
      --x-libraries=<libdir>

         As with --x-includes, this will override configures attempts
         to automatically determine the location of your X11 libraries.
      
      --with-motif[=<path>]

         Causes the X support for sqsh to use Motif widgets rather than
         the default (and rather crude) Athena widget set.  Enabling
         this option also automatically enables --with-x. If <path>
         is supplied, then <path>/include/X11 will be used to find the
         Motif include headers, and <path>/lib will be chosen to find
         Motif libraries.

      --with-static

         Forces sqsh to be compiled by statically linking in the
         appropriate Open Client libraries rather than dynamically
         linking with them.  Note that all other libraries continue
         to be dynamically linked.

      --with-gcc

         Forces configure to chose gcc as the compiler of choice
         regardless of whether or not a different C compiler is
         found earlier in your path.
      
   Also, the following environment variables may be set prior to
   running 'configure' to alter its behavior:

      CC 
         Forces configure to use the value of $CC as the default
         C compiler.  This variable may also specify flags to pass
         to the compiler, such as "cc -O -Wall".

      INCDIRS
         When attempting to discover the location of the readline
         header files (only when --with-readline is specified), this
         variable may supply a colon separated set of directories
         in which to look for the header files, rather than the
         default search path.

      LIBDIRS
         As with INCDIRS, this variable is used to track down the
         location of the readline library.

   When configure has finished it should have generated Makefile,
   and config.h.

3) Edit the file 'Makefile' and follow the directions as the top.  This
   will step you through specifying where to find the Sybase and 
   GNU readline libraries and include files.

4) OPTIONAL: Browse through 'config.h'.  This file is generated by 
   configure as it makes guesses about the configuration of your systems,
   and will probably not have to be touched.  If you don't understand
   the meaning of a define, you should probably leave it alone.

5) OPTIONAL: Browse through 'sqsh_config.h', you probably won't have 
   to change many of these values, they are simply default values for 
   various items, such as temporary directories, etc.

6) Now, attempt to build it:

   $ make

   This will (hopefully) create the sqsh executable.

7) Now, try to install it:

   $ make install

   This will install the binary into ${prefix}/bin, or ${exec_prefix}/bin,
   if --exec_prefix was specified.

   Optionally, you may also execute:

   $ make install-wrapper

   which will install a shell script wrapper around sqsh to automatically
   set the LD_LIBRARY_PATH on your platform.

8) Install man pages.

   For most machines you simply type:

   $ make install.man

   Which will cause the man page to be copied into ${prefix}/man/man3.
   However, if your machine supports compressed man pages, you may use:

   $ make install.zman

   Which will cause the man page to be compressed and copied into
   ${prefix}/man/man3.Z.

Now if all went well, you have a working program with man pages and
everything.  However, if you ever decide to do the unimaginable, and
get rid of all traces of the program, try:

   $ make uninstall
   $ make uninstall.man

or, if need be:

   $ make uninstall.zman

Common Problems
-=-=-=-=-=-=-=-

If your compiler generates warnings about certain variables being
clobbered by a longjmp, then turn off any optimization flags that
may have been set in the Makefile.

Good Luck
-=-=-=-=-

Well, hopefully everything went OK for you.  If you have any problems
or you run across any bugs in the program, contact me at:

Scott C. Gray (gray@voicenet.com, sgray@sybase.com)
27-Jul-1998
