This is the file README in the Ithreads source distribution.

Ithreads is an instrumented user-level threads package that runs on several
uniprocessors and multiprocessors.  It offers support for shared-memory
parallel programming with an interface similar to Mach Cthreads.  Additionally
it offers the ability to perform system-level and application-level monitoring
of running programs.  This distribution contains the instrumented Ithreads 
library, facilities for processing and handling the event stream, a compiler
to assist in specifying application-level sensors and actuators, and a threads
level display tool.  Ithreads should work on the following 
architectures/operating systems:  

	  Sun Sparc SunOS 4.1.3
	  Sun Sparc Solaris 2.{3,4}
	  Sun Sparc Solaris 2.5 with LWPs
	  SGI MIPS IRIX 4.0.5
	  SGI MIPS IRIX 5.x
	  SGI MIPS IRIX 6.x
	  IBM RS6000 AIX 3.2	(gcc only, not native compilers)
	  x86 Linux

The uniprocessor support is intended for code development and debugging and 
classroom support.  The following machines are no longer supported, though
some files are still present. 

	  KSR KSR1 and KSR2 KSROS 1.1.4
	  KSR KSR1 and KSR2 KSROS 1.2
	  Sun Sun3 SunOS 4
	  Sequent Symmetry Dynix 3.1.2
	  BBN Butterfly ???

The Ithreads distribution at:
ftp.cc.gatech.edu:pub/software/cthreads/ithreads_distribution.tar.gz is
updated as our source tree changes.  At any time you fetch the code it is
possible that something might be broken on some host where it is supposed to
work.  This is unlikely for the Sparc target because we run tests on the
distribution there before building the tar file.  However we cannot test all
machine/OS/compiler combinations.  Your mileage may vary.  This is research
software and not a supported product.  We try to keep it working on the
machines we say we will, on at least some compiler available on those
machines.  We normally use gcc if we have it available on the host.

The Ithreads source distribution in its current form includes seven
separate packages: 'ithreads', 'pbio', 'dataexchange', 'reorder', 'lifetime', 
'sensor_spec', and 'threads_man'.  'ithreads' is the actual source code 
for the threads package itself.  'pbio' is a package of routines which
provide a semi-portable binary I/O facility.  These routines are used
by Ithreads monitoring and must be linked in with the Ithreads library.  
DataExchange is a slightly higher-level library providing general support for
processing event streams.  The package 'dataexchange' is DataExchange in its
simplist form, providing connection management.  It must also be included 
in the Ithreads library.  'reorder' is a more sophisticated version of
DataExchange that, in addition to connection management, instills a partial order
on the unordered event stream.  'lifetime' provides a threads lifetime
view graphical display.  It is useful for diagnosing performance problems in
threads-based programs.  'sensor_spec' compiles sensor and actuator 
specifications into C functions.  'threads_man' is the assembled man
pages for Ithreads.  They can be installed in a man3 directory
somewhere...  'pbio' and 'dataexchange' are also provided as separate
libraries for the benefit of non-threaded programs wishing to use
them.  The threads package contains a subdirectory 'tests' which
performs simple functional and consistency checks of Ithreads.  There
are currently no tests of the monitoring functionality.


THREADS FROM THE TAR DISTRIBUTION.....

   Untarring the distribution will result in creating seven directories
   corresponding to the seven repositories.  If you plan to install threads
   and/or the IO library, you will have to give arguments to the ./configure
   scripts before you build.  (See `configure -help`.)  Otherwise, things will
   build in such a way that you can experiment without such installation.


BUILDING THREADS
   To build all the packages you must do:

   cd pbio
   ./configure		# the configure script sets system characteristics and
			#   builds config.h and the Makefiles  SEE NOTE!
   make		        # actually build pbio

   cd ../dataexchange
   ./configure
   make			# build DataExchange

   cd ../ithreads
   ./configure		
   make			# build ithreads.

	# if you just want a threads library, you can stop here!

   cd ../gen_thread
   ./configure	
   make			# build gen_thread, a generic wrapper for 
			# threads libraries

   cd ../reorder
   ./configure	
   make			# build the reordering filter.

   cd ../sensor_spec
   ./configure	
   make			# build the sensor compiler.

   cd ../lifetime	# This requires Motif libraries!
   ./configure
   make			# build the lifetime thread view.


   Configure Note!
	If you wish to automatically run ithreads tests and install the
   libraries and include files in some standard location for all these
   packages, you'll need to use some arguments to ./configure.  In particular,
   most of the configure scripts recognize the following arguments:

  --prefix=PREFIX         install architecture-independent files in PREFIX
                          [/usr/local]
  --exec-prefix=EPREFIX   install architecture-dependent files in EPREFIX
                          [same as prefix]
  --bindir=DIR            user executables in DIR [EPREFIX/bin]
  --libdir=DIR            object code libraries in DIR [EPREFIX/lib]
  --includedir=DIR        C header files in DIR [PREFIX/include]

   These arguments control where files get placed when "make install" is done.
   Different options control the directories that configure searches when
   trying to find required packages.  For example, the configure script for
   the dataexchange package takes a "-with-pbio=<dir>" argument that specifies the
   location of the pbio package.  Given such an argument, configure searches
   the supplied directory and several likely subdirectory names ( <dir>/lib,
   <dir>/include, etc.) in order to locate the files it needs.  If no argument
   is specified, or if the required files are not found, configure searches
   other likely locations including /usr, /usr/local, /opt/misc,
   $HOME/<package_name>, ../<package_name>, etc.  When files are located, a
   -I<dir> or -L<dir> argument is added to compile or link line if necessary.
   Because both of these compiler arguments are order-sensitive, be aware of
   the possibility of unexpected results when several versions of the same
   library or include file exist in different locations.

   Also note that most of these packages have a "make depend" target that
   tries to put header file dependency information in the generated Makefile.
   Doing "make depend" is critical if you want to modify any of these
   packages.  However, if "makedepend" is not present on your system, you're
   on your own for generating the dependency info.

SAMPLE APPLICATION
   Included in the 'lifetime' package is a simple application that can
   be used to gain an understanding of how the pieces fit together.  See the
   README file in the 'lifetime' subdirectory for instructions on
   executing the application.

TESTING THREADS
   The 'tests' subdirectory of the package 'ithreads' contains a number of simple
   test programs, as well as files of their expected results.  There is a perl
   script, run_test, which runs the tests and compares the actual results to
   what is expected.  If you don't have perl, you can't test threads easily.
   If you have perl, you may have the edit the "#!" line at the top of
   'run_test' to reflect its location.  With that done, build and run the tests 
   using the following:

   cd ithreads/tests
   make

   Every time you execute 'make' it will run all the tests.  It will complain
   if any of them fail.  There's no easy way to run just a single test.  
   We need to fix this up sometime...

INSTALLING THREADS 
   On the CoC machines, threads is installed fresh every night into
   directories in ~chaos (~parallel on OIT machines).  If you're installing
   threads yourself, you only need to copy the files "libcthreads.a" and
   "cthread.h" into an appropriate place.  Alternatively you can specify the
   appropriate arguments to configure and let "make CTHREAD_INSTALL" take care
   of the whole thing for you...

THREADS IF YOU ARE ON GaTech CoC MACHINES....

   The packages comprising Ithreads are maintained each under separate
   CVS control.  If you are on a machine which mounts the GaTech
   College of Computing filesystems, you can checkout the most recent
   copy of the ithreads source by doing: 

	cvs -l -d ~chaos/CVSmaster checkout ithreads  
	# substitute 'pbio', 'dataexchange', 'reorder', 'sensor_spec', 
	# 'lifetime', or 'threads_man' for 'ithreads' to check out
	# the other packages. 

   This will create a directory named 'ithreads' in your current directory.
   Note that if you're intent on modifying threads and updating your changes
   into the library you've got to be a member of the 'chaos' group...  If
   you're not, you can do checkouts and updates (as long as you specify the -l
   (no logging) option to cvs, but you can never commit your changes.  See the
   man pages in ~chaos/man for a description of CVS.  (It's probably a good
   idea to add /users/c/chaos/man to your MANPATH environment variable if
   you're working with this stuff.)


NOTES ON MAKING CHANGES TO BE INCORPORATED IN THE DISTRIBUTION
   The basic rule is to try to be smart about changes.  Do everything you
     can to write code that will be easy to understand for others.

   Don't convolute things to save a subroutine call or otherwise be efficient
     in tiny ways.
   Change the code to make it look like whatever you're doing was designed in.
    (i.e., don't introduce a dozen small hacks instead of doing it the "right"
    way.  If in doubt about what the "right" way is, talk to someone with more
    of a clue.)
   Try to avoid #ifdef's.  (Try to eliminate the ones already there.)  
   If what you have to make machine specific changes to files that are not
     machine specific, migrate those functions to machine specific files.
   Write procedure prototypes so that they're used by compilers that support
     them. 
   Don't use gcc (or other compiler) specific extensions to C.
   Use the "-Wall" option to gcc and fix everything it warns you about.
   Try to follow the variable naming and code indentation conventions that are
     already in use.  Remember, tabs are 8 spaces, not some other number.
     Ithreads source uses "_" to separate words in names, not capitalization.
     We're indenting by 4 at every level.  (If your editor won't do this
     automatically, switch to an editor that's younger than you are.)
   Put in curly brackets {} even though you could leave them off.  (Like for
     an "if" with a single statement in the then part.)
   DON'T USE MAGIC NUMBERS!!  (Noone will understand what "if (flag == -2)"
     means in 6 months.  Use enumerations or at least symbolic #defines.)
   Don't be cute.
   Don't nest header file inclusions.  (Try to eliminate the ones that are
     still nested.)

   Much of this is old code.  If you spent time figuring out how something
     works because it wasn't commented, comment it!  Clean it up!  Make it
     less confusing!



Basic Installation on Windows NT
==================

This is a source-code release and may require tweaking in order to build in
your environment.  We typically build using 'make' from the MKS Toolkit and
their command-line interface to the Microsoft Visual C++ compiler.  Because
the configure script may not run under NT, we provide Makefile.nt and
config.nt.  You should copy or rename Makefile.nt to "makefile", and copy or
rename config.nt to "config.h".  Also, if you do not have 'sed' (available
from Cygnus or as part of the MKS toolkit), you should copy cthread.nt to
cthread.h.  Otherwise cthread.h will be built automatically.  

After this preparation, do "make all".  We do not provide a project workspace
or makefile configuration for VC++.  You *might* be able to create a Makefile
Project under VC++ and use nmake to build DataExchange.  However, I've found
that nmake doesn't like curly brackets in Makefiles.  So you probably would
have to edit Makefile.nt to change the curly brackets to smooth parens.  Also,
at this time, we build an object library, not a DLL.

The files Makefile.nt and config.nt were generated by the configure.nt
configuration script.  Configure.nt is itself derived from the Unix
"configure" script through the action of the sed script unix_to_nt.sed.  We
are able to run configure.nt using KSH with the MKS tools.  Your mileage may
vary.  Other versions of ksh or sh may work more or less like Unix and
configure or configure.nt may work more or less well.

Before you build DataExchange, you must build PBIO.  Because the path
searching mechanisms don't work well in configure.nt, PBIO *must* be
accessible in ../pbio from the dataexchange build directory.
