.de Ds
.DS
.ft B
.ss 9
..
.de De
.DE
.ss 4
.fr R
..
.if n .fp M I
.ss 9
.sv |1.25i
.ce 2
\f3Installation and Maintenance Guide for Release 5g of Icon\fR
.sp
.ss 4
.PP
This document describes how to install Release 5g of the Icon programming
language.  The installation procedure is simple; it requires  the
distribution tape to be unloaded onto the target machine, the setting of
site specific constants, and the recompilation of the Icon
system itself.  This document also contains information that may
be of use to maintainers of Icon systems.
.NH 1
System Requirements
.PP
This distribution of Version 5 Icon is targeted for VAX-11s
and PDP-11s (with separate instruction and data spaces)
running the UNIX* operating system. This distribution package has been tested
under V7 and 4.1bsd, and no problems should be encountered when installing
Icon under one of these versions of UNIX.
.PP
When the system is unloaded, it requires about 1200 kilobytes of disk space.
During recompilation, a total of 3000 kilobytes is required.  Once
the system has been built, it is possible to delete the source code.
Such a configuration requires 900 kilobytes of disk space.  These
figures vary slightly depending upon the logical organization of
a particular disk.
.NH 1
Installation Procedure
.NH 2
Unloading the Distribution Tape
.PP
The system is distributed as a \fItar\fR archive on magnetic tape.
The \fItar\fR
hierarchy is rooted at the directory \fBv5g\fR.  Mount the distribution tape
and do a \fIcd\fR to the directory that you wish to hold
the system hierarchy.
.PP
The precise
\fItar\fR command to unload the distribution
tape depends on the local environment.  If you are
on a VAX and the distribution tape density is 1600 bpi, the following
command should extract the contents of the tape:
.Ds
tar x
.De
On a PDP-11 with a 1600 bpi distribution tape, use:
.Ds
tar xf /dev/rmt0
.De
For example, if you want the system to reside at \fB/usr/icon/v5g\fR on a VAX,
you might type:
.Ds
cd /usr
mkdir icon
cd icon
tar x
.De
.NH 2
System Configuration
.PP
\fINote\fR: File names used in the following sections are usually relative to
the root directory for the Icon hierarchy.  For example, if
the Icon system is unloaded as described above, the root directory
is \fB/usr/icon/v5g\fR, and
the file name \fBint/bin/Makefile\fR refers to
\fB/usr/icon/v5g/int/bin/Makefile\fR.
.PP
The installer must perform a site-specific configuration of the Icon
system.  This configuration is accomplished the shell script
\fBint/bin/icon-setup\fR.
\f3icon-setup\fR accepts a number of parameters and modifies
several source files to produce a ready-to-compile Icon system tailored
as specified by the parameters.
.PP
.ne 1i
\f3icon-setup\fR has the following synopsis:
.IP \f3icon-setup
.nf
\-vax\ \-pdp11\ \-host\ \fIstring\fP
[\-hz\ \fIrate\fP]\ [\-nofp]\ [\-ext]\ [\-directex]
[\-ibin\ \fIlibrary directory for the Icon interpreter\fP]
[\-cbin\ \fIlibrary directory for the Icon compiler\fP]
[\-iconx\ \fIlocation of the Icon interpreter\fP]
.fi
.PP
The parameters have the following meanings:
.IP \f3\-vax\ \ \fRand\fP\ \ \-pdp11\fR
.br
These are mutually exclusive options that control the selection of
machine dependent portions of code.  Select one as appropriate
for your machine.
.IP \f3\-host\fR\ \ \fIstring\fR
.br
The Icon system has a keyword, \fB&host\fR, whose value should be the
name of the host machine where the system is running.  On some systems,
notably 4.2bsd, System III, and System V, it is possible to
determine the name of the system at runtime via a system call.
On other systems, 4.1bsd for example,
the file \fB/usr/include/whoami.h\fR contains
the name of the host in a \fB#define\fR statement.  If neither
of these methods is available, or one wishes to pick an arbitrary
string for \fB&host\fR, that can be done.
If you are on 4.2bsd, specify \f3gethost\fR for \fIstring\fR,
this will cause the \fIgethostname(2)\fR function to be used.
If you are on System III, System V, or some other system that
supports the \fIuname\fR(2) system call, specify \f3uname\fR for
\fIstring\fR.  If you are on a system with a \fB/usr/include/whoami.h\fR
file that has a \fB#define\fR for \fBsysname\fR, then specify
\f3whoami\fR for \fIstring\fR.  If none of these
are available on your machine, or if you want to give \fB&host\fR some
value besides that of the machine name, specify an arbitrary
string (you may need quotes around it) for \fIstring\fR, for
example: \f3\-host\fR\ \ \f3UNIX\fR.
.IP \f3\-hz\fR\ \ \fIrate\fR
.br
This parameter specifies the cycle rate of the electrical environment
you are in.  The rate defaults to 60 Hz and you only need to specify
\f3\-hz\fR if you are not in a 60 Hz electrical environment.  If the
rate is incorrect, the value of the \fB&time\fR keyword will be wrong.
.IP \f3\-nofp\fR
.br
Specify \f3\-nofp\fR if you are on a PDP-11 that does not have
floating point hardware.
.IP \f3\-directex\fR
.br
Specify this if you are on a 4.1bsd or later system.  This option
causes the use of a feature of the \fIexec\fR(2) system call to make
interpretable files directly executable.
.IP \f3\-ext\fR
.br
Enables a number of extensions to standard Version 5 as described in [4].
These features may be of
interest to persons wishing to experiment with extensions to Icon.
However, the extensions are not supported.
.IP \f3\-ibin\ \fIdirectory\fR\ and\ \ \f3\-cbin\ \fIdirectory\fR
.br
The directories \fBint/bin\fR and \fBcmp/bin\fR
contain executable versions of the Icon translator, the Icon linker,
and various libraries.  The path names of these directories are built
into \fIicont\fR and \fIiconc\fR, the programs that control the
translation of Icon programs.  By default, the fully qualified names
of \fBint/bin\fR and \fBcmp/bin\fR are used for \f3\-ibin\fR and
\f3\-cbin\fR respectively.  Specifying \f3\-ibin\fR and/or \f3\-cbin\fR
causes \fIicont\fR and/or \fIiconc\fR to use the specified
directory as its library directory.  If alternate directories are
specified, after the Icon system is built,
copy all of the files in \fBint/bin\fR
and/or \fBcmp/bin\fR into the specified directories.
.IP \f3\-iconx\ \fIinterpreter-location\fR
.br
By default, the \fIinterpreter-location\fR is the fully qualified
name of \fBint/bin/iconx\fR.  If \f3\-ibin\fR is specified, then
\fIinterpreter-location\fR defaults to \fIibin-directory/\fBiconx\fR.
If the fully qualified name of \fBiconx\fR is longer than 32 characters
and you are on a VAX running 4.1bsd, consult Section 3.1 to determine
what to specify for \f3\-ibin\fR.
.PP
Before \f3icon-setup\fR
modifies a file, it copies a generic version of the
file into place and works on it.  Thus, \f3icon-setup\fR can be run a number
of times and only the last run has any lasting effect.
\f3icon-setup\fR is like any other UNIX command and thus all of its
arguments must be specified on one command line.
.PP
For example, if you are on a VAX running 4.1bsd, all you need is
.Ds
icon-setup -vax -directex -host whoami
.De
If you have a PDP-11 running V7, you don't have a hardware floating
point unit, and you want \fB&host\fR to be ``Unix Version 7'', you should use
.Ds
icon-setup -pdp11 -nofp -host ``Unix Version 7''
.De
Suppose you are on a VAX running System V, you have a 50 hz electrical
environment, you wish the library directories for the interpreter and the
compiler to be \fB/usr/lib/icon/interp\fR and \fB/usr/lib/icon/comp\fR
respectively,
and the Icon interpreter to reside at \fB/usr/bin/iconx\fR.  You also wish
to include the language extensions.  You would need:
.Ds
icon-setup -vax -hz 50 -ext -host uname -ibin /usr/lib/icon/interp
\ \ \ -cbin /usr/lib/icon/comp -iconx /usr/bin/iconx
.De
Note that the last example must be entered as one logical command line.
.NH 2
System Compilation
.PP
This distribution of Icon contains no executable binary files and no
object files, so the system must be completely recompiled from the
source.  After you have run \f3icon-setup\fR,
you are ready to compile the system.  Issuing
a \fImake\fR command in \fBint/bin\fR or \fBcmp/bin\fR completely rebuilds
the interpreter or the compiler, respectively.  We recommend that
you build the interpreter first and then if there are no problems, proceed
to the compiler.
.PP
The complete system construction process is:
.Ds
cd \fBv5g\fP
\fBint/bin/icon-setup \fIappropriate arguments\fP
cd \fBint/bin\fP
make
cd \fB../../cmp/bin\fP
make
.De
.PP
At this point, you should have a working Icon system.
The samples directory contains programs and associated
test data.  If you desire to test the system, consult the
file \fBsamples/Readme\fR.
.PP
You may wish to place a copy
\fBint/bin/icont\fR and \fBcmp/bin/iconc\fR in a public
directory such as \fB/usr/bin\fR or \fB/usr/local\fR to provide general user
access to Icon.
\fBdocs/icont.1\fR and \fBdocs/iconc.1\fR are \fIman\fR pages for
\fIicont\fR and \fIiconc\fR, you may wish to copy the appropriate set
into \fB/usr/man/man1\fR.
Once you are sure that the system is working, you can issue the
command \fBmake clean-all\fR
in \fBint/bin\fR and \fBcmp/bin\fR to remove all
non-source files from the source directories.
.NH 1
Special Installation Considerations
.NH 2
Direct Execution of Interpretable Files
.PP
When an Icon program is processed by the interpreter translator
and linker using the \fIicont\fR command, the result is a file
containing opcodes and data in a format that the Icon interpreter
understands.  Rather than having the user ``execute'' this interpretable file
by running the Icon interpreter with the file as an argument, the
Icon system uses one of two methods to make the interpretable
files appear to be directly executable.
.PP
In 4.1bsd (and later 4.nbsd) systems, a feature of \fIexec\fR(2)
system call can be used to enable the interpretable file produced by
the linker to appear to be directly executable.  When \fIexec\fR
is called with a file to execute, it examines the first two
characters of the file.  If the first two characters are \fB#!\fR, \fIexec\fR
assumes that the next argument on the line is the name of a
program for which the file is to serve as input.  The program
then is executed with the named file (the file that is being ``executed'')
as its argument.  Thus, instead of having to run the Icon interpreter with the
interpretable file as input, the interpretable file can be executed directly.
.PP
An alternative method is used on systems whose \fIexec\fR(2) system
call doesn't have this feature.  An executable file is prepended
to the data used by the interpreter.  The executable portion of the
file will merely run the Icon interpreter with the file
itself and any supplied arguments as the arguments for the interpreter.
.PP
If \f3\-directex\fR is
specified for \f3icon-setup\fR, the former method will be used,
otherwise, the latter method will be used.  The first method is
preferable in that the interpretable files are smaller and they
start executing more quickly.
.PP
There is a potential complication in using the first method.
The 4.1bsd \fIexec\fR(2) system call
imposes a length limitation of 32 characters on the name of
the program to be run.  If the name exceeds 32 characters, execution
of the interpretable file fails.
For example, suppose the Icon
interpreter (\fBiconx\fR) on a system is located at
\fB/usr/csc/local/icon/v5g/int/bin/iconx\fR.  This path name is longer
than 32 characters, and is thus unsuitable for inclusion in interpretable
files.  One way to solve the problem is to link 
\fB/usr/csc/local/icon/v5g/int/bin/iconx\fR to \fB/usr/local/iconx\fR,
and have interpretable files reference \fB/usr/local/iconx\fR.  You may need to
employ a similar solution on your system.  Two things need to be done.
First, find a filesystem location where a copy of \fBint/bin/iconx\fR
can be referenced with a fully qualified path name that is no more than
32 characters long.
Second, when you configure the system using \f3icon-setup\fR, specify
the new location of \fBiconx\fR using the \f3\-iconx\fR option.
For example:
.Ds
icon-setup \fIother arguments\fP\ \-iconx /usr/local/iconx
.De
Be sure to place a copy of \fBiconx\fR in the specified location after
the system is completely built.  It is also possible to get around
this problem by not specifying \f3\-directex\fR and having Icon
prepend the executable header on interpretable files.
.NH 2
PDP-11 Systems without Separate I/D Spaces
.PP
This version is designed to run on PDP-11s with separate instruction
and data spaces.  Some persons have decreased the sizes of various
internal structures and have brought up Icon on machines without separate
I/D spaces, but only small programs can be run.  These adaptations to non-I/D
machines were done with an earlier version of Icon and we do not
have details of the changes required.
.NH 1
Assorted Information
.PP
The following sections contain information that is not needed during
the installation process, but may be helpful in understanding the
organization of the system.
.NH 2
System Layout
.PP
The Icon system has four top-level directories branching off from \fBv5g\fR:
.IP \fBdocs\fR \w'samples'u+2n
System documentation and man pages.
.IP \fBsamples\fR
Sample programs and associated data.
.IP \fBbook\fR
Source code for procedures appearing in [1].
.IP \fBint\fR
Source code hierarchy for the Icon interpreter.
.IP \fBcmp\fR
Source code hierarchy for the Icon compiler.
.NH 2
System Components
.PP
The following directories contain various components of the Icon
system and branch off from both \fBcmp\fR and \fBint.\fR  (The directory
\fBiconx\fR only appears in \fBint.\fR)
.IP \fBtran\fR \w'operators'u+2n
Soure code for the Icon translator.
.IP \fBlink\fR
Source code for the Icon linker.
.IP \fBh\fR
Header files that are included in other source files.
.IP \fBfunctions\fR
Source code for the Icon builtin functions.
.IP \fBlib\fR
Source code for runtime support routines that are directly callable from
an Icon program.
.IP \fBoperators\fR
Source code for the Icon operators.
.IP \fBrt\fR
Source code for the Icon runtime system.
.IP \fBiconx\fR
Source code for the Icon interpreter proper.
.IP \fBbin\fR
Libraries and executable versions of various system components.
The source for programs that control Icon translation also resides here.
.NH 2
Source File Linking
.PP
The bulk of the source code for the Icon compiler and interpreter
is very similar and in most cases, analogous files are linked between
the cmp and int hierarchies.  For example, \fBint/functions/write.c\fR is
linked to \fBcmp/functions/write.c\fR.  In some cases, preprocessor control
statements are used to select portions of code in a particular file
depending upon whether the compiler or interpreter is being compiled.
Occasionally, files that are linked may not be in analogous directories,
for example, \fBint/iconx/start.s\fR and \fBint/iconx/init.c\fR are linked to
\fBcmp/rt/start.s\fR and \fBcmp/rt/init.c\fR
respectively.  The only directories where
some analogous source files are not linked are \fBint/link\fR and \fBcmp/link.\fR
In addition, \fBMakefile\fRs are linked when possible.
.PP
Because the same source is used to produce versions of Icon on both VAXs
and PDP-11s, the portions of the code that are machine dependent are
bracketed with preprocessor control statements to select sections
appropriate for each machine.  This is primarily used for assembler
source files, but also is used in a few cases for C source files.
In some cases where differences are extreme (as for assembler files),
the section of code for the VAX appears in its entireity
and is followed by the code for the PDP-11 in its entireity.
.PP
If you decide to make
source modifications, check link counts to be sure that you are not
modifying more files than you think are, or less files than you think you are.
.NH 2
Recompilation of System Components
.PP
Execution of the \fImake\fR command while in any source code
directory causes the system component in that
directory to be rebuilt.  Doing a \fImake\fR in \fBcmp/bin\fR
or \fBint/bin\fR causes the appropriate system to be rebuilt.
.PP
The directories \fBiconx\fR, \fBtran\fR, and \fBlink\fR
each contain code for a single program.
Doing a \fImake\fR in any of these directories causes
the particular program to be remade.  The resulting program may then
be copied into the appropriate bin directory (\fBcmp/bin\fR or \fBint/bin\fR).
.PP
The directories \fBfunctions\fR, \fBlib\fR, \fBoperators\fR, and \fBrt\fR
each contain source code for a
part of the Icon runtime system.  The Icon interpreter,
\fBiconx\fR, is formed by linking all the runtime subroutines together with
the routines in \fBint/iconx\fR. Icon programs processed by the Icon
compiler are linked together with a library (\fBcmp/bin/libi.a\fR)
of the runtime system subroutines.
When changes are made to the interpreter runtime system, all affected
libraries must be rebuilt and then \fBiconx\fR must be rebuilt.  For example,
if the files \fBint/operators/bang.c\fR and \fBint/functions/read.c\fR
have been modified,
the following sequence of commands rebuilds the interpreter.
.Ds
.ta 1.75i
cd int/functions
make
cd ../operators
make
cd ../iconx
make
cp iconx ../bin	# copy new version of interpreter to int/bin
.De
Alternatively, performing a \fBmake\fR in \fBint/bin\fR has
the same effect.
Similarly, if the changes have been made in the compiler rather than
in the interpreter, these commands rebuild the compiler:
.Ds
.ta 1.75i
cd cmp/functions
make
cd ../operators
make
cd ../bin
make lib	# rebuild and randomize libi.a
.De
If disk space is critical on your system,
it is possible to delete all \fBv5g\fR directories
except for \fBint/bin\fR and \fBcmp/bin\fR, and retain a functional
Icon system.  That configuration requires about 500 kilobytes
of disk space.
.NH 2
PDP-11 \f(BIyacc\f3 modifications for the Icon Translator
.PP
You only need to be concerned with this section if you are going to
modify the Icon grammar, contained in the file \fBcmp/tran/ucon.g\fR.
The version of \fIyacc\fR distributed with VAX systems is large enough
to build the Icon parser [3], but it may be necessary to build a
version of \fIyacc\fR with larger parameters if you are on a PDP-11.
The following defined constants in the file \fBdextern\fR (in
the \fIyacc\fR source directory)
should be given the values listed below.
Larger values are acceptable for all these constants, but
are not necessary.
.Ds
# ifdef HUGE
# define ACTSIZE 3000
# define MEMSIZE 6000
# define NSTATES 300
# define NTERMS 127
# define NPROD 200
# define NNONTERM 100
# define TEMPSIZE 1200
# define CNAMSZ 4100
# define LSETSIZE 200
# define WSETSIZE 200
# endif
.De
The constant
\fBHUGE\fR should be defined instead of \fBMEDIUM\fR
at the end of the file \fByacc/files\fR.
.PP
Then \fIyacc\fR should be rebuilt.
.NH 2
Obtaining Source Code Listings
.PP
Execution of the command
.Ds
make Listall
.De
in any of the directories except \fBbin\fR produces
listings of all source files from that directory on standard output.
Use the command
.Ds
make List
.De
to obtain listings of all files that have been altered since the
last \fBmake List\fR or \fBmake Listall\fR.
.SH
Electronic Mail and Problem Reporting
.PP
A mailbox has been established to facilitate communication with
us, should you have problems or questions.  Use the following
addresses for electronic mail:
.DS
.ta 2.5i
\fBicon-project.arizona@rand-relay\fR	(CSNET and ARPANET)
\fBarizona!icon-project\fR	(Usenet and uucpnet)
.DE
We currently
have uucp connections established through \fBgi\fR, \fBmcnc\fR,
\fBucbvax\fR, and \fButah-cs\fR.
.PP
If you encounter any problems with the Icon system, or if
you have any suggestions about Icon in general or the installation
process in particular, please contact us.  If you do not have
access to electronic mail facilities,
please use the Trouble Report Forms supplied in the
distribution package or call Ralph Griswold at 602-626-1829
(602-621-6609 after April 8, 1983).
.SH
References
.LP
1. Ralph E. Griswold and Madge T. Griswold,
\fIThe Icon Programming Language\fR.  Prentice-Hall Inc., Englewood
Cliffs, New Jersey. 1983.
.LP
2. \fITape Directory for Release 5g of Icon\fR. Department of Computer Science, The University of
Arizona. March 1983.
.LP
3.  Coutant, Cary A. and Wampler, Stephen B. \fIA Tour Through the
C Implementation of Icon; Version 5\fR. Technical Report TR 81-11a,
Department of Computer Science, The University of Arizona. December 1981.
.LP
4. Ralph E. Griswold and William H. Mitchell, \fIExperimental Extensions
to Icon\fR. Department of Computer Science, The University of Arizona.
March 1983.
.nf
.sp 4
Ralph E. Griswold  (\fBralph.arizona@rand-relay\fR, \fBarizona!ralph\fR)
William H. Mitchell  (\fBwhm.arizona@rand-relay\fR, \fBarizona!whm\fR)
.sp 1
March 12, 1983

