![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to porting CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSD / contrib / icon / docs|
Return to porting CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / icon / docs |
1.1 root 1: .so tmac.tr
2: .sv |1.25i
3: .LP
4: .ce 10
5: \f3An Overview of the Porting Process for Version 5.9 of Icon\fR
6: .sp 2
7: Ralph E. Griswold
8: .sp 1
9: October 12, 1984
10: .ce 0
11: .sp 2
12: .NH
13: Introduction
14: .PP
15: The process of porting Version 5.9 of Icon to a new computer
16: is described in detail in [1].
17: This document is a companion to [1] an provides details of
18: testing to be carried out during the porting process.
19: .PP
20: Porting Icon starts out in the same way as installing an existing
21: implementation of Icon [2].
22: At a point in the installation process, the installer becomes a
23: porter and provides the code needed for the new computer. The porter
24: then becomes an installer again and completes the port by completing
25: the installation.
26: .PP
27: To carry out the port, following the instructions in [2] through
28: Section 2.2 (\fIConfiguring the Icon System\fR). In the root directory,
29: referred to as \*Mv5g\fR, configure Icon using
30: .Ds
31: Icon-setup \-port \-host \fIname
32: .De
33: where \fIname\fR is the value to be produced by the Icon keyword
34: \*M&host\fR.
35: .PP
36: Now carry out the porting process as described in [1].
37: When this is complete,
38: .Ds
39: make Clean
40: .De
41: to remove any object files left over from the porting process. Then
42: follow the instructions in [2], starting with Section 2.3
43: (\fICompiling Icon\fR).
44: .NH
45: Test Programs
46: .PP
47: There are three sub-directories in \*Mv5g\fR
48: that contain test programs
49: for use by the porter:
50: .IP \*Mv5g/port\fR 1i
51: This sub-directory contains programs and reference data for step-by-step
52: testing and checking
53: of each component of the port.
54: .IP \*Mv5g/samples\fR
55: This sub-directory contains standard programs that are used to test existing implementations of
56: Icon and which should be run at the completion of a port to be sure
57: that Icon works properly over a range of applications.
58: .IP \*Mv5g/test\fR
59: This sub-directory contains
60: programs and reference data for testing a wide range of Icon features,
61: including boundary conditions and unusual computations.
62: These programs may be useful in final checking of a new implementation
63: and in locating obscure errors.
64: .LP
65: In each of \*Mport\fR, \*Msamples\fR, and \*Mtest\fR, there is a \*MMakefile\fR
66: with a number of entries for performing different tests. In all cases,
67: standard test output is supplied in a sub-directory named \*Mdistr\fR and newly
68: created test output is placed in a sub-directory named \*Mlocal\fR.
69: The standard test output was produced on a VAX-11 running under 4.2bsd
70: \*U.
71: .Un
72: The scripts used by the \*MMakefile\fRs assume that the components
73: of the ported Icon system reside in their standard places in the
74: distribution hierarchy [2]. If this is not the case, the shell scripts
75: will have to be modified.
76: .PP
77: Each test compares the standard output in \*Mdistr\fR to the
78: newly created output in \*Mlocal\fR and reports any differences.
79: Some differences are to be expected, even in a correct port, since
80: output may depend on machine-dependent parameters, the local
81: environment, and so forth. In general, the causes of such irrelevant
82: differences should be obvious.
83: .NH
84: Testing During the Porting Process
85: .PP
86: The porting process consists of building the components of the Icon
87: system one by one. There is a test for each step.
88: Go to the directory \*Mv5g/port\fR for testing during the porting process.
89: .PP
90: Before testing, assign the value \*M1\fR to the environment variable \*MICONCORE\fR.
91: This will cause the Icon interpreter to produce a core dump in case of
92: an error, which may be helpful in debugging.
93: .NH 2
94: The Translator
95: .PP
96: Once the translator is constructed, test it by
97: .Ds
98: make Tran
99: .De
100: which runs the translator on a number of Icon programs,
101: produces ucode output in \*M.u1\fR and \*M.u2\fR files,
102: and compares it with corresponding standard output
103: files.
104: Since the translator is machine-independent and written
105: entirely in C, there should not be any differences.
106: .NH 2
107: The Linker
108: .PP
109: When the new linker is successfully compiled, test it by
110: .Ds
111: make Link
112: .De
113: which runs the Icon linker on the files produced by the translator during
114: the preceding test and produces linker debugging output in
115: \&\*M.ux\fR files.
116: This process is comparatively slow because of the generation of
117: debugging output.
118: The format of \*M.ux\fR files is somewhat dependent on
119: computer and operating system details. In addition, the indexes of
120: built-in functions, which appear in the \*M.ux\fR files, are determined
121: by the extensions that are included in the Icon system when it is configured
122: [2]. Consequently,
123: there are likely to be differences \(em even extensive ones \(em
124: between the locally generated \*M.ux\fR files and the distributed ones.
125: Differences are not checked by \*Mmake\0Link\fR, but they can be
126: determined separately by
127: .Ds
128: make Linkcheck
129: .De
130: If extensive differences are encountered,
131: it may be necessary to examine the output in
132: \*Mlocal\fR manually.
133: .NH 2
134: The Run-Time System
135: .PP
136: There are a number of steps in building the run-time system, and
137: each step should be checked separately.
138: The first test is
139: .Ds
140: make Basis
141: .De
142: which checks the elementary components of the run-time system that
143: are needed to run simple Icon programs.
144: The components involved are \*Miconx/start.s\fR, \*Mrt/setbound.s\fR,
145: \*Mlib/invoke.s\fR, \*Miconx/interp.s\fR, \*Mlib/efail.s\fR,
146: and \*Mlib/pfail.s\fR. See [1] for details. The remaining tests, and
147: the components of the run-time system that they check, in order, are:
148: .Ds
149: .ta 1.6i
150: make Arith # rt/arith.s
151: make Fail # rt/fail.s
152: make Pret # lib/pret.s
153: make Esusp # lib/esusp.s
154: make Lsusp # lib/lsusp.s
155: make Psusp # lib/psusp.s
156: make Suspend # rt/suspend.s
157: make Display # functions/display.c
158: make Gc # rt/gcollect.s\fR and \*Mrt/sweep.c
159: .De
160: .sp -1
161: .NH
162: Complete Testing
163: .PP
164: Once the port is complete and all the tests above have been passed
165: successfully, the tests in the \*Msamples\fR and \*Mtest\fR
166: directories should be performed.
167: .NH 2
168: Testing the Sample Programs
169: .PP
170: In the directory \*Mv5g/samples\fR, do
171: .Ds
172: make Std
173: .De
174: This test runs a number of sample programs and compares their output
175: with standard output. Differences should occur only in the
176: test program \*Mhello.icn\fR, which contains environment- and time-dependent
177: code.
178: .PP
179: Two groups of extensions to Version 5.9 can be included, optionally, when the Icon
180: system initially configured. See [2].
181: If the sets extension is included in the port,
182: then
183: .Ds
184: make Set
185: .De
186: to test these features. If the experimental extensions to Version 5.9
187: are included also, then
188: .Ds
189: make Xpx
190: .De
191: Alternatively, if both group of extensions are included, the three tests above
192: can be performed by
193: .Ds
194: make All
195: .De
196: .sp -1
197: .NH 2
198: Detailed Testing
199: .PP
200: Final detailed testing
201: should be done in the directory \*Mv5g/test\fR, using
202: .Ds
203: make Std
204: make Set
205: make Xpx
206: .De
207: or
208: .Ds
209: make All
210: .De
211: as appropriate.
212: .PP
213: The following programs may show differences for the indicated reasons:
214: .IP \*Mstd02.icn\fR .9i
215: The output may differ because of the number of hash chains in tables
216: is an installation-dependent parameter that affects the internal
217: organization of tables, to which this test is sensitive.
218: .IP \*Mstd06.icn\fR
219: This program contains environmental- and time-dependent code and its
220: output will certainly vary from the standard output.
221: .IP \*Mstd21.icn\fR
222: This program may terminate prematurely on systems with limited memory space.
223: .IP \*Mstd22.icn\fR
224: The output may differ for the same reasons as for \*Mstd02.icn\fR.
225: .IP \*Mstd26.icn\fR
226: The output may differ slightly because of differences in \*Mqsort\fR.
227: .IP \*Mstd29.icn\fR
228: This program calls operating system utilities; the output
229: may differ if these calls have different formats for their output.
230: .IP \*Mstd33.icn\fR
231: This program may terminate prematurely on systems with limited memory space.
232: .IP \*Mstd37.icn\fR
233: The output may differ for the same reasons as for \*Mstd02.icn\fR.
234: .IP \*Mset01.icn\fR
235: The output may differ because of the number of hash chains in sets
236: is an installation-dependent parameter that affects the internal
237: organization of sets, to which this test is sensitive.
238: .IP \*Mset02.icn\fR
239: The output may differ for the same reasons as for \*Mset01.icn\fR.
240: .PP
241: If the random numbers produced by the ported system differ from those
242: produced by the standard one, several tests may show differences in the
243: order of results or in the results themselves.
244: Any other differences that show up in these tests should be examined carefully.
245: .PP
246: Note that almost all of the tests end with an Icon run-time error.
247: This is intentional, and is used to check run-time error
248: detection in as many situations as possible.
249: .SH
250: References
251: .LP
252: 1. Mitchell, William H. \fIPorting the UNIX Implementation of Icon\fR.
253: Technical Report TR 83-10d, Department of Computer Science,
254: The University of Arizona. August 1984.
255: .LP
256: 2. Griswold, Ralph E. and William H. Mitchell. \fIInstallation and
257: Maintenance Guide for Version 5.9 of Icon\fR. Technical Report
258: TR 84-13a, Department of Computer Science, The University of Arizona.
259: October 1984.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.