InfoMagic Source Code 1993 July/THE_SOURCE_CODE_CD_ROM.iso/gnu/nihcl-3.0/doc/install.nihcl

Text File | 1990-05-25 | 14.2 KB | 572 lines

\begindata{text,1080728}
\textdsversion{12}
\define{italic
menu:[Font,Italic]
attr:[FontFace Italic Int Set]}
\define{bold
menu:[Font,Bold]
attr:[FontFace Bold Int Set]}
\define{chapter
menu:[Title,Chapter]
attr:[Justification LeftJustified Point 0]
attr:[FontFace Bold Int Set]
attr:[FontSize PreviousFontSize Point 4]}
\define{section
menu:[Title,Section]
attr:[Justification LeftJustified Point 0]
attr:[FontFace Bold Int Set]
attr:[FontSize PreviousFontSize Point 2]}
\define{subsection
menu:[Title,Subsection]
attr:[Justification LeftJustified Point 0]
attr:[FontFace Bold Int Set]}
\define{paragraph
menu:[Title,Paragraph]
attr:[Justification LeftJustified Point 0]
attr:[FontFace Italic Int Set]}
\define{bigger
menu:[Font,Bigger]
attr:[FontSize PreviousFontSize Point 2]}
\define{indent
menu:[Region,Indent]
attr:[LeftMargin LeftMargin Inch 32768]
attr:[RightMargin RightMargin Inch 32768]}
\define{typewriter
menu:[Font,Typewriter]
attr:[FontFace FixedFace Int Set]
attr:[FontFamily AndyType Int 0]}
\define{display
menu:[Region,Display]
attr:[LeftMargin LeftMargin Inch 32768]
attr:[RightMargin RightMargin Inch 32768]
attr:[Justification LeftJustified Point 0]}
\define{example
menu:[Region,Example]
attr:[LeftMargin LeftMargin Inch 32768]
attr:[Justification LeftJustified Point 0]
attr:[FontFace FixedFace Int Set]
attr:[FontFamily AndyType Int 0]}
\define{description
menu:[Region,Description]
attr:[LeftMargin LeftMargin Cm 171084]
attr:[Indent LeftMargin Cm -106350]}
\define{quotation
menu:[Region,Quotation]
attr:[LeftMargin LeftMargin Inch 32768]
attr:[RightMargin RightMargin Inch 32768]
attr:[FontFace Italic Int Set]}
\define{subscript
menu:[Font,Subscript]
attr:[Script PreviousScriptMovement Point 2]
attr:[FontSize PreviousFontSize Point -2]}
\define{superscript
menu:[Font,Superscript]
attr:[Script PreviousScriptMovement Point -6]
attr:[FontSize PreviousFontSize Point -2]}
\define{smaller
menu:[Font,Smaller]
attr:[FontSize PreviousFontSize Point -2]}
\define{heading
menu:[Title,Heading]
attr:[LeftMargin LeftMargin Inch -13107]
attr:[Justification LeftJustified Point 0]
attr:[FontFace Bold Int Set]}
\define{majorheading
menu:[Title,MajorHeading]
attr:[Justification Centered Point 0]
attr:[FontSize PreviousFontSize Point 4]}
\define{formatnote
menu:[Region,FormatNote]
attr:[Flags PassThru Int Set]}
\define{subheading
menu:[Title,Subheading]
attr:[Justification LeftJustified Point 0]
attr:[FontFace Bold Int Set]}
\define{center
menu:[Justify,Center]
attr:[Justification Centered Point 0]}
\define{flushleft
menu:[Justify,FlushLeft]
attr:[Justification LeftJustified Point 0]}
\define{flushright
menu:[Justify,FlushRight]
attr:[Justification RightJustified Point 0]}
\define{leftindent
menu:[Region,LeftIndent]
attr:[LeftMargin LeftMargin Inch 32768]}
\define{code
menu:[Region,Code]
attr:[FontFace FixedFace Int Set]
attr:[FontFamily AndyType Int 0]}
\formatnote{.ds Cl Installation

.so nihclmac.tr}

\section{INTRODUCTION}

\begindata{lookz, 1097376}
hidden
\enddata{lookz, 1097376}
\view{lookzview,1097376,0,0,0}

This is the Installation Guide for the NIH Class Library (previously known as
the "OOPS" Class Library) Revision 3.0.


The NIH Class Library is intended to be portable to a UNIX system compatible
with either System V or 4.2/4.3BSD and which supports the AT&T C++ translator
Release 2.00, Release 2.1, or other compatible C++ compiler.  We have ported
and tested this library on the following systems:

\indent{
Sun-3 with SunOS 3.5

Sun-3 with SunOS 4.0

Sun-4 with SunOS 4.0

}
Send comments to:


\indent{Keith Gorlen

Building 12A, Room 2033

Computer Systems Laboratory

Division of Computer Research and Technology

National Institutes of Health

Bethesda, MD 20892


phone: [phone]

Internet\indent{: [e-mail]}

uucp: uunet!nih-csl!kgorlen

}

\section{GUIDE TO THIS DISTRIBUTION KIT}


The NIH Class Library distribution kit consists of a main directory and the
following subdirectories:


\indent{\code{errfac     }Error Message Facility source files

\code{lib        }Source files for the basic library classes

\code{test       }Test suite for the basic library classes

\code{vector     }Source files for the Vector classes

\code{vectest    }Test suite for the Vector classes

\code{ex         }Example programs for the book

}
The main directory is refered to as \code{NIHCL} in the following discussion,
but may be placed anywhere.


Most subdirectories have files named \code{MAKEFILE} and \code{Makefile}.  The
\code{MAKEFILE} is used by the installation procedure, and should work with
both the System V and BSD version of the \code{make} utility.  The fancier
\code{Makefile} is used for development, and may not work under BSD.



\section{SUMMARY OF STEPS IN INSTALLING THE NIH CLASS LIBRARY}


\description{1.    Update C++ system library and include files

2.    Edit \code{NIHCL/Makefile}

3.    Edit \code{NIHCL/lib/nihclconfig.h}

4.    Build and install error message facility*

5.    Build NIHCL basic classes, Vector classes, and test suite

6.    Test basic classes and Vector classes

7.    Build NIHCL basic classes, Vector classes, and test suite with multiple
inheritance support

8.    Test basic classes and Vector classes with multiple inheritance support

9.    Install class libraries*

10.    Build example programs

11.    Test example programs

}
* root permission may be required




\section{INSTALLING THE NIH CLASS LIBRARY

}\subheading{
}\subsection{1. Update C++ system library and include files}


No updates to R2.00 of the AT&T C++ Translator are required.  However, if you
are using R2.1, be sure to make the changes documented in the section
\italic{COMPILING UNDER AT&T C++ TRANSLATOR RELEASE 2.1} in the \italic{NIH
Class Library Release Notes}.


\subsection{2. Edit NIHCL/Makefile}


Edit \code{NIHCL/Makefile} to change make variables as needed for your
environment.  Here are the settings shipped with the distribution kit:


\example{\smaller{# C++ compiler

CC = CC


# C++ debug switch

CCDEBUG =

#CCDEBUG = -g


# C++ flags

# NOTE: Disable +p option when compiling with AT&T R2.1

#CCFLAGS = +p

#CCFLAGS =


# C++ include files

I = /usr/include/CC


# If using BSD

SYS = BSD

# If using System V

#SYS = SYSV


# Compile with nested types

# (works with AT&T R2.1 and GNU C++)

NESTED_TYPES =

#NESTED_TYPES = -DNESTED_TYPES


# Disable AT&T R2.0/R2.1 bug work-around code

BUGDEFS =

#BUGDEFS = -DBUG_bC2728 -DBUG_38 -DBUG_39 -DBUG_OPTYPECONST

# Defining BUG_TOOBIG disables code that

# prevents C compiler "yacc stack overflows" error

#BUGDEFS = -DBUG_bC2728 -DBUG_38 -DBUG_39 -DBUG_OPTYPECONST -DBUG_TOOBIG


# Enable debug code

DEBUGDEFS =

#DEBUGDEFS = -DDEBUG_OBJIO -DDEBUG_PROCESS


# Flags for ln

#LNFLAGS =

LNFLAGS = -s


# If using "patch"

MAIN = _main.c_p

# If using "munch"

#MAIN = _main.c_m


# Target library for installation of Error Facility

LIB_ID = libC


# Target Directories for Installation


# directory for libnihcl.a

NIHCLLIBDIR = /usr/local/lib

# directory for NIHCL include files

NIHCLINCDIR = /usr/include/nihcl

# directory where $\{LIB_ID\}.a resides

CLIBDIR = /usr/local/lib/C++R2.0

# directory for errgen utility

ERRGENDIR = /usr/local/bin

# directory for errgen table file

ERRTABDIR = /usr/local/lib

# directory for errlib.h and errors.h

ERRINCDIR = $I}

}

\subsection{3. Edit NIHCL/lib files}


\paragraph{3.1 Edit \code{nihclconfig.h}}


The NIH Class Library source is configured for your system by setting flags in
\code{NIHCL/lib/nihclconfig.h} which specify the machine model and operating
system (UNIX variant).


To configure the NIH Class Library for one of the not yet implemented options,
at least all of the parameters appearing in \code{nihclconfig.h} will have to
be defined for that option.


The NIH Class Library should configure itself automatically for the following
machines:


\indent{sun/mc68000

sun/sparc

}
Classes \code{Process}, \code{HeapProc}, \code{StackProc}, \code{Scheduler},
\code{Semaphore}, and \code{SharedQueue} have some machine-specific
dependencies and will not work unless the \code{SETJMP()/LONGJMP()} functions
are properly defined.  See the \italic{NIH Class Library Release Notes} for
directions on porting the \code{Process} classes.


\paragraph{3.2 Edit \code{Object.h}}


The file \code{Object.h} defines three versions of a preprocessor macro named
\code{STRINGIZE}, which forms some symbol names by concatenating the class
name argument with other strings.  Each version does this a different way.
 The version for use with ANSI C preprocessors, conditionalized on the symbol
\code{__STDC__}, uses \code{##} for concatenation.  If you are not using an
ANSI C preprocessor, defining the symbol \code{BS_NL} in \code{Object.h}
selects the version that uses the sequence \code{\\}<newline> as the
concatenation separator, which seems to work with most System V UNIX systems.
 If you do not define \code{BS_NL}, you get the version of DEFINE_CLASS that
uses an empty comment sequence (\code{/**/}), which works with most Berkeley
UNIX systems.


\code{Object.h} should require no editing on most systems.


\subsection{4. Install error message facility


}(Skip this step for MASSCOMP/RTU)


\example{su     (if installing in protected directory)

make errorfacility}


This builds an error message registery facility and error processing library
similar to \code{errcom} and the 3E library routines on the MASSCOMP.


The \code{errgen} program reads a \code{.err} file to determine a facility
name, and then reads the file \code{$\{ERRTABDIR\}/errgen_tab} to lookup the
number assigned to that facility.  The facility number determines the
high-order bits of the error numbers which \code{errgen} assigns, assuring
that error numbers used by different libraries do not coincide.  Errgen
produces a \code{.h} file containing error symbols and their assigned numbers,
and a \code{.c} file containing a table of error messages and formatting
information.


This step creates a module containing the error handling library routines
named \code{errors.o} and adds it to \code{$\{CLIBDIR\}/$\{LIB_ID\}.a}, and it
copies the files \code{errlib.h} and \code{errors.h} into the directory
\code{$\{ERRINCDIR\}.}


The test program testerr on \code{NIHCL/errfac} verifies that the error
facilities have been built correctly.  It returns the first and last error
defined in the file \code{testerrs.err}.



\subsection{5. Build the NIH Class Library, Vector classes, and test suite

}
\example{make}



\subsection{6. Test the NIH Class Library

}
\example{make verify}


This runs the test suite and compares the output of each test program with the
contents of a \code{.v} file containing the correct output.  If the program
runs correctly, you'll see the message "No differences encountered".  Some
tests such as \code{date}, \code{identdict}, \code{process}, \code{random},
\code{stack}, and \code{tim} produce output to the terminal.  \code{date}
outputs yesterday's, today's, and tomorrow's date.  \code{identdict} dumps an
identity dictionary.  \code{random} prints out a list of random numbers.
 \code{stack} prints out a \code{CLTNEMPTY} error message to test error
reporting, and \code{tim} prints out the current date and time.


The \code{error} test program frequently fails to compare because its output
depends upon memory addresses that change from implementation to
implementation.  \code{error} should differ only in the object address printed
in the \code{CLTNEMPTY} error message.


The output of \code{fdset} depends upon the maximum number of allowable file
descriptors on your system.  The test output was generated under SunOS 4.0,
which has a limit of 64 file descriptors.


Several tests that print floating point numbers may fail to compare due to
formatting differences.


The byte size of the object printed by ex8-1 may vary for different systems.
 The test output was produced by a Sun-3.



\subsection{7. Build the NIH Class Library, Vector classes, and test suite
with multiple inheritance support

}
\example{make cleantest

make mi

}

\subsection{8. Test the NIH Class Library, Vector classes, and test suite with
multiple inheritance support

}
\example{make verify

}
This runs the same tests as in Step 6, with similar results.



\subsection{9. Install the NIH Class Libraries

}
\example{su     (if installing in protected directory)

make install}


The NIH Class Library archives \code{libnihcl.a}, \code{libnihclmi.a},
\code{libnihclvec.a}, and \code{libnihclvecmi.a} are copied to
\code{$\{NIHCLLIBDIR\}} and \code{ranlib} is executed on the libraries.  All
header files for basic classes are copied to directory
\code{$\{NIHCLINCDIR\}}.



\subsection{10. Build example programs

}
\example{make examples}



\subsection{11. Test example programs}


\example{make exverify}



\section{TROUBLE SHOOTING}


\subsection{YACC stack overflows}


Some test programs may fail to compile because they are too complicated for
your C compiler and get a "yacc stack overflow".  Either increase the table
space in your C compiler or simplify the program by breaking it up into
separate functions.  The inline copy constructors that Release 2.0
automatically generates are frequently the source of this error.  Explicitly
defining non-inline copy constructors solves the problem.  See the
\italic{Release Notes} for further details.


\subsection{Problems with class Exception}


Test programs error and except test class \code{Exception}, the the NIH Class
Library exception handler. If these programs fail to perform correctly
suspicion can be directed to the performance of system functions
\code{setjmp()} and \code{longjmp()}.


\subsection{Problems with Process classes}


Progams \code{process} and \code{stackproc} test the NIH Class Library
co-routine mechanism (classes \code{Process}, \code{HeapProc},
\code{StackProc}, and \code{Scheduler}), the object queue (class
\code{SharedQueue}) and semaphore (class \code{Semaphore}).  These are
machine-dependent and rely on the presence of \code{alloca()}, which all
systems do not provide, and on \code{setjmp()}/\code{longjmp()} being
implemented by saving/restoring all machine registers, which is not always the
case for all systems either.  If the \code{process} or \code{stackproc} tests
fail to compile, link, or run, check your system's implementations of
\code{alloca()} \code{setjmp()}, and \code{longjmp()} -- you may need to
implement your own versions.

\enddata{text,1080728}