This is an excerpt from SICS Protocol Implementation Measurement
System:User Manual, covering Appendix A: Installation guide. There
is also an excerpt on the Introduction and How to run SPIMS.

Appendix A

Installation Guide

A.1 Requirements

In order to use SPIMS you need:
*	A supported UNIX configuration.
*	The standard UNIX utilities like yacc, make, and awk.
*	The utilities in $SPIMSDIR/bin also require sed, ps and rsh, 
	but SPIMS can be used without its utilities.

The configurations that are supported in this release are:
*	BSD4.[2,3]
*	SunOS 3.5 and SunOS 4.0 on Suns.
*	Ultrix 2.0/3.0
*	DNIX

If your configuration is not supported see Section A.8 below.

The configuration is chosen by linking config/CONFIG to one of 
config/config.bsd
config/config.sunos
config/config.ultrix
config/config.dnix


A.2 Step by step cookbook

Note: all the file names are relative to $SPIMSDIR.

1	Load the distribution from the tape. 

2	Select your configuration from the files config/config.* and
link config/CONFIG to it.

3	Select which of the protocols you can support in your system.
Change the PROTOCOLS variable in Makefile.

4	E.g. FTAM requires the isode and ftam libraries.If these are
not on the standard search path for libraries add a -L switch to the
PROTO_LIB_LOCATIONS variable in ftam/Makefile. E.g. if the libraries
reside in /usr/isode add -L/usr/isode.(Footnote 1)

5	If some header files (e.g. for FTAM or for the socket
interface) are not in /usr/include or the SPIMS h directory, add a
switch to CONFIG_CFLAGS in config/CONFIG. E.g. if the socket interface
header files are rooted at /usr/include/bsd add -I/usr/include/bsd to
the CONFIG_CFLAGS variable.

6	If you have a binary distribution only: link the directory
with the object modules to OBJ.

7	Run ./make. This runs ./make config, followed by ./make on all
the PROTOCOLS. See the Makefiles section below for details.

8	Update the default protocols in the spims-test shell-script.

9	Define the environment variable $SPIMSDIR in your shell to be
the directory where SPIMS is installed. This variable is used by the
programs in the bin directory.

10 Add $SPIMSDIR/bin to the command search path in your shell.

11 Run spims-test.


Possible problems

$SPIMSDIR/make and $SPIMSDIR/Makefile still (!!) assumes that the
current directory is at the beginning of you command search path.

A.3 Directory structure

The SPIMS distribution is divided into several subdirectories under $SPIMSDIR.

bin		Shell script programs for running measurements.
config		Configuration information.
autoconf	Programs used when configuring a protocol with certain 
		measurement procedures et.c.
src		Source code for SPIMS itself. (Not supplied in the 
		binary distribution)
OBJ		Object code for all the modules in the src directory.
h		Header files.
protocols	Header files and source code for the protocol interfaces 
		to SPIMS.
protoaddrs	Header files and source code handling the protocol 
		specific addresses. (E.g. TCP port addresses and ISODE 
		presentation addresses)
dist		Source code for the random number generators with different 
		statistical distributions.
initiators	Source code for the initiator measurement procedures.
responders	Source code for the responder measurement procedures.
composers	Source code for the measurement composers.
benchmarks	Measurement specifications which are used by the 
		measurement programs in the bin directory.
filters		Filters for the measurement results. They are used by 
		the measurement programs in the bin directory. (The 
		filters are awk shell scripts).
infile		A random collection of measurement specifications (for 
		which there are no output filters due to their complexity).
outfile		Where random measurement results are stored.


A.4 Makefiles and make

There exists several Makefiles and make shell-scripts in SPIMS: 

Makefile	Runs make on the OBJ and the protocol directories, 
		and also aids when new protocols are added.
make		If the first parameter is a subdirectory it runs make 
		in that subdirectory. E.g. ./make tcp recompiles 
		SPIMS for the tcp protocol.
OBJ/Makefile	Creates object modules from the source code in the
		src directory.
OBJ/make	"/bin/make -f ../config/CONFIG -f Makefile"
config/Makefile	Used when compiling for the specific protocols. 
config/make	Runs /bin/make on the files ../config/CONFIG 
		../config/Makefile Makefile and makefile.conf
config/Makefile.protogen	Skeleton for the protocol specific 
		makefiles. Used when a new protocol is added.
<protocol>/Makefile	Only contains variable assignments which 
		define the protocol specific routines and libraries 
		to include, which application types that the protocol 
		can handle.
<protocol>/make	A logical link to ../config/make

Note: <protocol> refers to any protocol subdirectory such as tcp, or ftp.

The result of running make will be a bench and a demon program for
each of the protocols. In addition to creating the (protocol generic)
object modules in the OBJ directory, files have to be compiled for
each protocol. This is done by first doing a "make config" and then a
"make" (both done for each protocol).

"make config" creates a number of files in the <protocol> directory
(using the autoconf scripts):

makefile.conf	A makefile defining a number of variables and which 
		contains the dependencies for the protocol specific 
		modules, measurement procedures, measurement composers 
		and statistical distribution functions.
dists.h		A header file defining the distribution functions.
benchmarks.h	A header file defining the measurement procedures.
bench-auto.c	A source code file containing a routine which enters 
		the names of all the application types, measurement 
		composers and distribution functions in SPIMS' symbol 
		table for the bench program.
demon-auto.c	A source code file containing a routine which enters 
		the names of all the application types and distribution 
		functions in SPIMS' symbol table for the demon program.

"make config" also creates the links:
protospec.h	A link to the protocol specific header file 
		(in the protocols directory).
addrspec.h	A link to the address specific header file 
		(in the protoaddrs directory).

Finally, "make" in the <protocol> directory compiles the protocol
specific modules, the measurement procedures, the measurement
composers and the distribution functions and links these together with
modules from the OBJ directory to form the bench and the demon
programs.
 
A.5 The binary distribution

The binary distribution contains source code in the subdirectories:
*	vax.4.3BSD		vax code for new /usr/include/netdb.h
*	vax.4.2BSD		vax code for old /usr/include/netdb.h
*	sun3.SunOS3.5		mc68020 code for old /usr/include/netdb.h
*	sun3.SunOS4.0		mc68020 code for new /usr/include/netdb.h
*	sun4.SunOS4.0		sparc code

SPIMS expects source code to be in the OBJ directory, so a logic link
should be created to the appropriate directory.

A.6 Autoconfiguration

SPIMS uses the awk-based shell scripts in the autoconf directory to
create files which depend on the make file variables GENERAL_BASIC,
GENERAL_COMP, GENERAL_DIST, LOCAL_BASIC, LOCAL_COMP, LOCAL_DIST,
EXCLUDED_BASIC, EXCLUDED_COMP, EXCLUDED_DIST, PROTO_OBJS, ADDR_OBJS.

The autoconf programs are:
ofiles.awk	Generate "makefile code" defining the CONFIG_OBJS variable.
sfiles.awk	Generate "makefile code" defining the CONFIG_SOURCES variable.
depend.awk	Generate "makefile code" containing the dependencies 
		for CONFIG_OBJS.
distheader.awk	Generate information which is stored in dists.h
benchheader.awk	Generate information which is stored in benchmarks.h
bench-auto.awk	Generate C code which is stored in bench-auto.c
demon-auto.awk	Generate C code which is stored in demon-auto.c
exclude.awk	Do a set subtraction on names. This is used to exclude 
		the EXCLUDED routines from the configuration.

The autoconf programs are run when ./make config is done on a protocol.

A.7 Possible problems with ISODE protocols

Measurements on ISODE protocols requires that ISODE is installed and
working. The ISODE header files, libraries and databases have to be
installed, but there is currently no need no have an ISODE tsapd
running.

A.8 Porting SPIMS

If you have a source code release it is possible to compile on other
systems than the supported ones by altering the flags in config/CONFIG
and/or modifying the code. For the latter please consult the SPIMS:
Portability Guide.

The makefile variables being defined in config/CONFIG are:

CONFIG		The configuration e.g. "-DBSD"
CONFIG_CFLAGS	Flags passed to the C compiler when SPIMS is 
		compiled (e.g. -I switches)
CONFIG_LIBES	Flags passed to the loader when the programs are loaded.
LN		What link program to use (either "ln" or  "ln -s")
MAKE		How make is done in subdirectories. (e.g. "make $(MFLAGS)")
SHELL		What shell to use in make (not needed in BSD derivatives)
LDCC		What loader program to use.


In addition the following flags modify the behavior of SPIMS (they
could be defined in the CONFIG variable above):

BSD	(In src/{ipc_system.c,bench-metr.c,demon-logger.c,error.c,priority.c,		random.c} and h/{general.h,metrics.h,ipc_sig.h} )
	Berkeley type of Unix i.e. supporting sockets, getrusage() et.c.

SYSV	(same as above plus src/bio.c)
	System V type of Unix with added socket interface. Note: BSD 
	and SYSV are mutually exclusive.

BSD_PGRP	(In src/ipc_system.c and src/ipc_sig.c)
	Use BSD process groups.

DNIX	(In h/ipc.h src/bench-delay.c)
	Dnix special case. (Only together with SYSV)

ULTRIX	(In h/ipc_sig.h)
	Ultrix special handling. (Only together with BSD)


USE_DELAY	(In src/bench-delay.c)
	Use a busy wait when delaying instead of relying on the OS
clock. This avoids the problems with the course clock granularity, but
the delay routines have to be calibrated for each machine type.

MULTIPLE_IPADDR	(In src/ipc.c)
	Can be needed on machines that have multiple IP addresses
(i.e. that have more than one network interface).

XMALLOC_FILE	(In h/general.h src/malloc.c)
	For debugging malloc() and free(). The flags makes malloc and
free report the file name and line number where they are called.
Unfortunately this does not work for all protocols!

The requirements on the operating system to run this implementation of
SPIMS are basically:

*	A System V or BSD interface towards UNIX.
*	A BSD-like socket interface (Internet domain stream sockets 
	are used for SPIMS interprocess communication) 
*	Standard include files et.c.
*	Some protocols to measure the performance of!

________________Footnotes
1 Note that many loader does not support the -L flag. If so, the libraries 
have to be placed in one of the standard library directories.
