.so tmac.tr
.sv |1.25i
.LP
.ce 10
\f3An Overview of the Porting Process for Version 5.9 of Icon\fR
.sp 2
Ralph E. Griswold
.sp 1
October 12, 1984
.ce 0
.sp 2
.NH
Introduction
.PP
The process of porting Version 5.9 of Icon to a new computer
is described in detail in [1].
This document is a companion to [1] an provides details of
testing to be carried out during the porting process.
.PP
Porting Icon starts out in the same way as installing an existing
implementation of Icon [2].
At a point in the installation process, the installer becomes a
porter and provides the code needed for the new computer. The porter
then becomes an installer again and completes the port by completing
the installation.
.PP
To carry out the port, following the instructions in [2] through
Section 2.2 (\fIConfiguring the Icon System\fR). In the root directory,
referred to as \*Mv5g\fR, configure Icon using
.Ds
Icon-setup \-port \-host \fIname
.De
where \fIname\fR is the value to be produced by the Icon keyword
\*M&host\fR.
.PP
Now carry out the porting process as described in [1].
When this is complete,
.Ds
make Clean
.De
to remove any object files left over from the porting process. Then
follow the instructions in [2], starting with Section 2.3
(\fICompiling Icon\fR).
.NH
Test Programs
.PP
There are three sub-directories in \*Mv5g\fR
that contain test programs
for use by the porter:
.IP \*Mv5g/port\fR 1i
This sub-directory contains programs and reference data for step-by-step
testing and checking
of each component of the port.
.IP \*Mv5g/samples\fR
This sub-directory contains standard programs that are used to test existing implementations of
Icon and which should be run at the completion of a port to be sure
that Icon works properly over a range of applications.
.IP \*Mv5g/test\fR
This sub-directory contains
programs and reference data for testing a wide range of Icon features,
including boundary conditions and unusual computations.
These programs may be useful in final checking of a new implementation
and in locating obscure errors.
.LP
In each of \*Mport\fR, \*Msamples\fR, and \*Mtest\fR, there is a \*MMakefile\fR
with a number of entries for performing different tests. In all cases,
standard test output is supplied in a sub-directory named \*Mdistr\fR and newly
created test output is placed in a sub-directory named \*Mlocal\fR.
The standard test output was produced on a VAX-11 running under 4.2bsd
\*U.
.Un
The scripts used by the \*MMakefile\fRs assume that the components
of the ported Icon system reside in their standard places in the
distribution hierarchy [2]. If this is not the case, the shell scripts
will have to be modified.
.PP
Each test compares the standard output in \*Mdistr\fR to the
newly created output in \*Mlocal\fR and reports any differences.
Some differences are to be expected, even in a correct port, since
output may depend on machine-dependent parameters, the local
environment, and so forth. In general, the causes of such irrelevant
differences should be obvious.
.NH
Testing During the Porting Process
.PP
The porting process consists of building the components of the Icon
system one by one. There is a test for each step.
Go to the directory \*Mv5g/port\fR for testing during the porting process.
.PP
Before testing, assign the value \*M1\fR to the environment variable \*MICONCORE\fR.
This will cause the Icon interpreter to produce a core dump in case of
an error, which may be helpful in debugging.
.NH 2
The Translator
.PP
Once the translator is constructed, test it by
.Ds
make Tran
.De
which runs the translator on a number of Icon programs,
produces ucode output in \*M.u1\fR and \*M.u2\fR files,
and compares it with corresponding standard output
files.
Since the translator is machine-independent and written
entirely in C, there should not be any differences.
.NH 2
The Linker
.PP
When the new linker is successfully compiled, test it by
.Ds
make Link
.De
which runs the Icon linker on the files produced by the translator during
the preceding test and produces linker debugging output in
\&\*M.ux\fR files.
This process is comparatively slow because of the generation of
debugging output.
The format of \*M.ux\fR files is somewhat dependent on
computer and operating system details. In addition, the indexes of
built-in functions, which appear in the \*M.ux\fR files, are determined
by the extensions that are included in the Icon system when it is configured
[2]. Consequently,
there are likely to be differences \(em even extensive ones \(em
between the locally generated \*M.ux\fR files and the distributed ones.
Differences are not checked by \*Mmake\0Link\fR, but they can be
determined separately by
.Ds
make Linkcheck
.De
If extensive differences are encountered,
it may be necessary to examine the output in
\*Mlocal\fR manually.
.NH 2
The Run-Time System
.PP
There are a number of steps in building the run-time system, and
each step should be checked separately.
The first test is
.Ds
make Basis
.De
which checks the elementary components of the run-time system that
are needed to run simple Icon programs.
The components involved are \*Miconx/start.s\fR, \*Mrt/setbound.s\fR,
\*Mlib/invoke.s\fR, \*Miconx/interp.s\fR, \*Mlib/efail.s\fR,
and \*Mlib/pfail.s\fR. See [1] for details. The remaining tests, and
the components of the run-time system that they check, in order, are:
.Ds
.ta 1.6i
make Arith	#   rt/arith.s
make Fail	#   rt/fail.s
make Pret	#   lib/pret.s
make Esusp	#   lib/esusp.s
make Lsusp	#   lib/lsusp.s
make Psusp	#   lib/psusp.s
make Suspend	#   rt/suspend.s
make Display	#   functions/display.c
make Gc	#   rt/gcollect.s\fR and \*Mrt/sweep.c
.De
.sp -1
.NH
Complete Testing
.PP
Once the port is complete and all the tests above have been passed
successfully, the tests in the \*Msamples\fR and \*Mtest\fR
directories should be performed.
.NH 2
Testing the Sample Programs
.PP
In the directory \*Mv5g/samples\fR, do
.Ds
make Std
.De
This test runs a number of sample programs and compares their output
with standard output. Differences should occur only in the
test program \*Mhello.icn\fR, which contains environment- and time-dependent
code.
.PP
Two groups of extensions to Version 5.9 can be included, optionally, when the Icon
system initially configured. See [2].
If the sets extension is included in the port,
then
.Ds
make Set
.De
to test these features. If the experimental extensions to Version 5.9
are included also, then
.Ds
make Xpx
.De
Alternatively, if both group of extensions are included, the three tests above
can be performed by
.Ds
make All
.De
.sp -1
.NH 2
Detailed Testing
.PP
Final detailed testing
should be done in the directory \*Mv5g/test\fR, using
.Ds
make Std
make Set
make Xpx
.De
or
.Ds
make All
.De
as appropriate.
.PP
The following programs may show differences for the indicated reasons:
.IP \*Mstd02.icn\fR .9i
The output may differ because of the number of hash chains in tables
is an installation-dependent parameter that affects the internal
organization of tables, to which this test is sensitive.
.IP \*Mstd06.icn\fR
This program contains environmental- and time-dependent code and its
output will certainly vary from the standard output.
.IP \*Mstd21.icn\fR
This program may terminate prematurely on systems with limited memory space.
.IP \*Mstd22.icn\fR
The output may differ for the same reasons as for \*Mstd02.icn\fR.
.IP \*Mstd26.icn\fR
The output may differ slightly because of differences in \*Mqsort\fR.
.IP \*Mstd29.icn\fR
This program calls operating system utilities; the output
may differ if these calls have different formats for their output.
.IP \*Mstd33.icn\fR
This program may terminate prematurely on systems with limited memory space.
.IP \*Mstd37.icn\fR
The output may differ for the same reasons as for \*Mstd02.icn\fR.
.IP \*Mset01.icn\fR
The output may differ because of the number of hash chains in sets
is an installation-dependent parameter that affects the internal
organization of sets, to which this test is sensitive.
.IP \*Mset02.icn\fR
The output may differ for the same reasons as for \*Mset01.icn\fR.
.PP
If the random numbers produced by the ported system differ from those
produced by the standard one, several tests may show differences in the
order of results or in the results themselves.
Any other differences that show up in these tests should be examined carefully.
.PP
Note that almost all of the tests end with an Icon run-time error.
This is intentional, and is used to check run-time error
detection in as many situations as possible.
.SH
References
.LP
1. Mitchell, William H. \fIPorting the UNIX Implementation of Icon\fR.
Technical Report TR 83-10d, Department of Computer Science,
The University of Arizona. August 1984.
.LP
2. Griswold, Ralph E. and William H. Mitchell. \fIInstallation and
Maintenance Guide for Version 5.9 of Icon\fR. Technical Report
TR 84-13a, Department of Computer Science, The University of Arizona.
October 1984.