---------------------------------------------------------------------------
NOTE: You may want to set your tabstop to 3; this will make everything
      look properly indented.
---------------------------------------------------------------------------


1. Distribution

This library package is distributed in shar archive kit form. After all
the archives are unpacked, you should end up with the following
directory structure:

	README				:	You should read this file first
	INSTALL				:	This is this file
	Makefile				:	Top-level makefile
	libconf				:	Shell script for configuration support
	fixman				:	Shell script for fixing man pages
	sysinc				:	Shell script to create protected header files (you
								may not need this)
	./libs				
	./libs/include
	./libs/man
	./libs/lib
	./libs/src/{sio,str,pset,misc,xlog,timer,pq,fsma,dict}



2. Requirements

The TIMER library requires a system that supports the setitimer(2)
system call, and either the sigvec(2) or sigaction(2) system calls. If
these are not available on your system, this library will be useless.
The rest of the libraries should work on any UNIX system.


3. Compiling

You can compile the libraries using the top level Makefile, or
you may go to each library directory and use the Makefile there.
In the following I will assume the former approach.


3.1. Library dependencies

Some of the libraries depend on others (i.e. they expect the header
files exported by those libraries), so there are restrictions on
the order of compilation. The dependency list is as follows:

STR 			depends on 		SIO
TIMER			depends on		PQ
DICT			depends on		FSMA
XLOG			depends on		SIO

The only dependency you can work around is that of STR on SIO (in case
you want to use STR but not SIO). Check the README in libs/src/str
for more information. In the following, I will assume that SIO will
also be used.

The top level Makefile handles the compilation order correctly.



3.2. Compiling using the top level Makefile

The majority of the libraries should compile without any problem.  The
only possible exceptions are SIO, XLOG and TIMER because they depend on
facilities provided by the operating system. You can customize these
libraries for your system using appropriate preprocessor flags.  These
flags are documented in the makefiles of the particular libraries, as
well as on the top level Makefile.

If your system is running SunOS 4.x, Solaris 2.x, Ultrix 4.x, or if it
is POSIX-compatible, you can find the appropriate flag settings in the
top level Makefile.  If your system is not among those, you have two
options: you can either check the top level Makefile for the particular
flags that may need to be set, or you can use the libconf script whose
purpose is to determine the appropriate flags for your system.

libconf relies on being able to interpret correctly the output of the
'nm' command. The distributed version of the script relies on BSD
4.3-style output. In this output, each symbol in an object file is
preceded by the letter 'T' if it is a function, or by the letter 'D' if
it is a variable. The libconf script variables "nm_defined_func" and
"nm_defined_var" are set to these letters.  If the output of 'nm' on
your system uses different conventions for determining what is a
function and what is a variable, you should change the values of those
two variables accordingly. Note that these values can be arbitrary
regular expressions (which are parsed by egrep), not just single
letters.

Finally, the library man pages make use of the ".SB" request, which
reduces the size of the following text by one point and makes it
boldface. This is available on SunOS 4.x, but may not be available on
your system. If that is the case, you can use the fixman script to
convert all occurrences of ".SB" to ".B". The script is invoked with
	fixman manpage manpage ...
If the script modifies a manpage, it will also save the original in a
file named after the manpage, with the string ".orig" appended to its
name.  For example, if sio.3 is modified, then sio.3.orig will be the
original man page.



3.3. Library creation and installation

Since some libraries depend on others, the top level Makefile does not
simply compile each library, but also installs it. The installation
process is controlled by the Makefile variables LIBDIR (the .a files
will go here), INCLUDEDIR (the include files will go here), and MANDIR
(the man pages will go here).

By default, the top level Makefile assumes that the 'ranlib' command
needs to be applied to each library archive. This is true for
BSD-derived systems, but is may be unnecessary for other systems (for
example, System V-derived systems). If this is the case for your
system, you should set the RANLIB variable in the top level Makefile to
'true'.

The other possible installation complication is the 'install' command.
The top level Makefile assumes a BSD 4.3-compatible install command
that accepts the "-c" option. If your system does not have such a
command, use the following settings:
	INSTALL	= cp
	FMODE		=
If your system has such a command but not at a standard place, set the
INSTALL variable to the pathname of the command (for example, for
SVR4-compatible systems, set INSTALL to "/usr/ucb/install -c".

You can undo an installation by typing "make uninstall". However, the
values of the variables LIBDIR, INCLUDEDIR, and MANDIR should not have
changed since the last "make install".



4. Compilation problems

4.1. Unprotected system include files

Typically, system include files start with the protective sequence

#ifndef __special_flag
#define __special_flag
....
#endif

This allows the file to be included multiple times without a
compilation error. Some of the libraries rely on this property, so on
systems that don't have such include files, those libraries will fail
to compile.

To circumvent this problem, I have provided the 'sysinc' script, which
can be used as follows:

   sysinc -d <clone_dir> header_files_and_C_files_of_all_libraries

The script will find all the system include files used by the specified
header and C-source files, and then it will create a "clone" directory
structure of include files with the same name as the system include
files, under "clone_dir". These clone files will have the protective
sequence, and will include the corresponding system include files.

You can then set the SYSINC variable of the top level Makefile as follows:
	SYSINC = -I<clone_dir>
Note that "clone_dir" should be an absolute pathname.

4.2. C compiler does not support 'void *' pointers

   libs/src/pset/pset.h:   change the typedef of __pset_pointer from 'void *'
                           to 'char *'
   libs/src/xlog/xlog.h:   change the typedef of xlog_h from 'void *'
                           to 'char *'
   libs/src/xlog/impl.h:   in 'struct xlog' change the type of the
                           xl_callback_arg and xl_data fields from 'void *'
                           to 'char *'
   libs/src/pq/pq.h:       change the typedefs of pq_h and pq_obj from
                           'void *' to 'char *'
   libs/src/timer/timer.h: in 'struct timer_action' change the type of the
                           ta_arg field from 'void *' to 'char *';
                           also change the typedef of timer_h from 'void *'
                           to 'char *'
   libs/src/timer/timer.c: in the line:
                              void  *arg        = tp->t_action.ta_arg ;
                           change the type of 'arg' from 'void *' to 'char *'

You may wonder why there is no '#ifdef' for this problem. The reason is
that decent C compilers have supported 'void *' pointers since a long time,
and there is now a free C compiler, gcc, that also supports such pointers.
Therefore, I don't want to overburden the code with more '#ifdefs' just
for the sake of outdated C compilers.


5. Epilogue

Please send all comments/suggestions/bug-reports to panos@cs.colorado.edu

	-- Panos Tsirigotis, Nov. 26, 1993 --

