![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to tr86-11.roff CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / cmd / icon / docs|
Return to tr86-11.roff CVS log | Up to [Research Unix] / researchv10dc / cmd / icon / docs |
1.1 root 1: .so tmac.tr
2: .ds M \fC
3: .de Ta
4: .ta .8i +.8i +.8i +.8i +.8i +.8i +.8i
5: ..
6: .de Px
7: .ta 3.5i
8: ..
9: .ds CF \s10- \\n(PN - \s0
10: .de Ap
11: .bp
12: .ce 10
13: \f3\\$1\f1
14: .ce 0
15: .sp 2
16: .if !''\\$2' 'so \\$2
17: ..
18: .TR 86-11b
19: .DA "June 30, 1986"
20: .Gi
21: .TL
22: Installation Guide for Version 6.0 of Icon on UNIX Systems
23: .AU
24: Ralph E. Griswold
25: .AE
26: .tr *\(**
27: .NH
28: Introduction
29: .PP
30: If you are installing Version 6.0 of Icon on a computer with a version
31: of \*U
32: for which configuration information already
33: .Un
34: has been developed \(em a ``supported system'' \(em the installation may be as simple as
35: issuing a few \*Mmake\fR commands.
36: The presently supported systems are Amdahl 580 (UTS), the AT&T 3B series,
37: the HP 9000 (HP-UX), personal computers running PC/IX and XENIX,
38: the PDP-11 (Version 7 UNIX), the Pyramid 90x,
39: the Ridge 32, the Sun Workstation, and the VAX-11 (Berkeley and System V UNIX).
40: .PP
41: If you are installing Version 6.0 on a supported system, start with the next section.
42: Otherwise, skip to Section 7.
43: .PP
44: If you are installing Version 6.0 on a system that is running an earlier
45: version of Icon, be sure to read Section 6 concerning possible impacts
46: of Version 6.0 on present users.
47: .NH
48: Standard Installation
49: .PP
50: The standard installation uses configuration information that is
51: included with the distribution. This configuration information
52: should be correct for most sites. If you want to check it out
53: before proceeding, read Section 7.
54: .PP
55: For the standard installation, all files, including executable binaries,
56: are placed
57: in the directory \*M/usr/icon/v6\fR\s-2\u\(dg\d\s0. If you want executable binary files
58: .FS
59: .sp .5
60: \s-2\u\(dg\d\s0\^For HP-UX, the standard location is \*M/users/icon/v6\fR.
61: .FE
62: in some other location,
63: you must edit a file before proceeding. Think twice about this.
64: Icon executable binary files are referenced by full path names; they
65: cannot be moved, so it is important to select the correct paths at the start.
66: See Appendix A if you want to change the location of binary files.
67: .PP
68: The Icon distribution is rooted in \*Mv6\fR.
69: Unload the distribution files
70: into the installation directory (the standard installation directory
71: is \*M/usr/icon\fR).
72: See Appendix B, if necessary, for information on unloading
73: the distribution files.
74: See Appendix C for a listing of the distribution hierarchy.
75: .PP
76: In the description that follows, paths are relative to \*Mv6\fR.
77: For example, \*MMakefile\fR refers to the \*MMakefile\fR in the
78: top level of the distribution hierarchy.
79: .PP
80: There are four phases of the installation: setup, compilation,
81: installation,
82: and testing.
83: All are done using \*MMakefile\fR in \*Mv6\fR.
84: .PP
85: Setup is based on the name of the system being installed,
86: as shown in the right column of the following
87: table:
88: .DS
89: .ft R
90: .ta 2i 3.7i
91: .sp .5
92: \fIcomputer UNIX system name\fR
93: .sp .5
94: Amdahl 580 UTS \*Mamdahl_uts\fR
95: AT&T 3B2/5/15 System V \*Matt3b5\fR
96: AT&T 3B20 System V \*Matt3b20\fR
97: HP 9000 HP-UX \*Mhp9000\fR
98: IBM PC/XT/AT PC/IX \*Mpc_pcix\fR
99: IBM AT XENIX \*Mpc_xenix_smm\fR
100: PDP-11 (separate I & D spaces) Version 7 \*Mpdp11_v7\fR
101: Pyramid 90x Berkeley 4.2bsd \*Mpyramid_bsd\fR
102: Ridge 32 ROS \*Mridge\fR
103: Sun Workstation UNIX 4.2 \*Msun\fR
104: VAX-11 Berkeley 4.1bsd \*Mvax_4.1bsd\fR
105: VAX-11 Berkeley 4.2bsd & 4.3bsd \*Mvax_bsd\fR
106: VAX-11 System V \*Mvax_sysv\fR
107: .DE
108: Before proceeding, check the status of the system you plan to install.
109: In \*Mv6\fR
110: .Ds
111: make Status name=\fIname\fR
112: .De
113: where \fIname\fR is one of those given above. For example,
114: .Ds
115: make Status name=sun
116: .De
117: lists the status of Version 6.0 on the Sun Workstation.
118: .PP
119: There are some supported systems for which not all features of Version
120: 6.0 are implemented. If this is the case for your system,
121: proceed with the installation, but you may wish to implement the
122: missing features later. For this, see Section 7.
123: .PP
124: Start the installation with
125: .Ds
126: make Setup name=\fIname\fR
127: .De
128: where \fIname\fR is the name of your system as described above.
129: For example,
130: .Ds
131: make Setup name=vax_bsd
132: .De
133: configures Version 6.0 of Icon for a VAX running Berkeley 4.\fIn\fRbsd.
134: .PP
135: Compilation and installation are done by
136: .Ds
137: make Icon Install
138: .De
139: This takes a while. There may be warning messages on some systems,
140: but there should be no fatal errors.
141: .PP
142: For a standard installation, a few simple tests are sufficient to
143: check that Icon is running properly. The following does the job:
144: .Ds
145: make Test-icon
146: .De
147: This test compares local program output with the expected output.
148: There should be no differences.
149: .PP
150: If all is well, you may wish to copy the manual page \*Micont.1\fR in
151: \*Mv6/docs\fR to your local public manual area.
152: That's all there is to a standard installation.
153: .NH
154: Personalized Interpreters
155: .PP
156: Version 6.0 contains a ``personalized interpreter'' facility
157: [1] that allows an individual to modify and
158: extend a private copy of Icon's run-time system. To install this optional
159: component of Icon,
160: .Ds
161: make PI
162: .De
163: For testing, do
164: .Ds
165: make Test-pi
166: .De
167: Expect some differences in this test, since one function checks local
168: environment variables.
169: .PP
170: You may want to copy
171: the shell script \*Micon_pi\fR, which makes personalized interpreters,
172: from \*Mv6\fR to a public area for general use. You also may want to copy
173: the manual page
174: \*Micon_pi.1\fR in \*Mv6/docs\fR to the public manual area.
175: .NH
176: Icon Program Library
177: .PP
178: The Icon program library [2] contains a variety of programs
179: and procedures. To install this optional component of the Version 6.0
180: distribution,
181: .Ds
182: make Ipl
183: .De
184: This puts compiled programs in \*Mv6/ipl/progs\fR and translated
185: procedures in \*Mv6/ipl/procs\fR. To test the library,
186: .Ds
187: make Test-ipl
188: .De
189: You can copy
190: the programs in \*Mv6/ipl/progs\fR and the translated procedures
191: in \*Mv6/ipl/procs\fR to other locations if you want.
192: .NH
193: Cleaning Up
194: .PP
195: After Icon and any optional components have be installed, you
196: can remove non-source files and test results by
197: .Ds
198: make Clean
199: .De
200: You also can remove source files, but think twice about this,
201: since source files may be useful to persons using personalized
202: interpreters.
203: .NH
204: User Impacts
205: .PP
206: The language features of Version 6.0 are very similar to those of
207: preceding Versions 5.9 and 5.10. Therefore, most user programs
208: that run properly under versions 5.9 and 5.10 should run properly
209: under Version 6.0.
210: However, users should be encouraged to read the Version 6.0 description
211: [3].
212: There are two possible sources of operational problems: version checking
213: and link path specifications.
214: .PP
215: Prior to Version 6.0, there was no check that ucode files produced by the
216: Icon translator and executable icode files produced by the Icon linker
217: were compatible with the Icon run-time system.
218: Incompatible files simply caused mysterious program malfunction.
219: Version 6.0 produces
220: version-numbered files and checks compatibility. An attempt
221: to use a file produced by an earlier version results in a error
222: message from Version 6.0 (\*Mucode file has no version identification\fR).
223: .PP
224: Since executable files contain the full path name of the run-time
225: system (\*Miconx\fR), proper installation should avoid problems with
226: version numbers in icode files.
227: Ucode files, which are typically used in libraries included by
228: the \*Mlink\fR declaration, are more troublesome.
229: Incompatible versions may be confusing,
230: since the source of the
231: problem may be hidden.
232: Users should be advised to re-translate all ucode files when Version 6.0
233: is installed.
234: Similarly, if an earlier version of the Icon program library is in
235: use, it should be replaced by the Version 6.0 library, built under
236: Version 6.0 as described in Section 4. (Some earlier Icon program
237: library material has been deleted in Version 6.0; if such material is
238: in use, it can be added to the Version 6.0 library.)
239: .PP
240: The syntax of the \*MIPATH\fR environment variable, which is used
241: by the linker to search for files given in \*Mlink\fR declarations,
242: has changed in Version 6.0. Previously the separator was a colon;
243: in Version 6.0 it is a blank. Problems with \*MIPATH\fR usually
244: are indicated by the linker error message \*MCan't resolve referernce to file
245: \&\*(El \fR.
246: .NH
247: Configuring Version 6.0 for a New System
248: .PP
249: Version 6.0 of Icon makes two assumptions about sizes:
250: .RS
251: .IP 1. 4n
252: C \fIint\fRs are either 16 or 32 bits long.
253: .IP 2.
254: The sizes of C \fIint\fRs and C pointers are the same.
255: .RE
256: .LP
257: If your system violates either of these assumptions, don't try to
258: go on \(em but check back with us, since we are working on
259: removing these restrictions.
260: .PP
261: To install Icon on a system that is not supported in the
262: distribution, you must create a directory to hold files
263: containing configuration information. In the description
264: that follows, this directory is referred to as your
265: configuration directory.
266: .PP
267: First you need to select a name for your system.
268: The name should consist of a mnemonic for the computer, which may be followed
269: by an underscore and a mnemonic for the operating system,
270: in case there may be more than one operating system for the
271: computer.
272: Examples are \*Mvax_bsd\fR and \*Mvax_sysv\fR.
273: You may want to append an additional
274: underscore and a qualification if there is more than more likely
275: implementation for a given computer and operating system. An
276: example is \*Mpc_xenix_smm\fR for the small memory model
277: implementation of Icon on XENIX.
278: .PP
279: To build and initialize a new configuration directory,
280: .Ds
281: make System name=\fIname\fR
282: .De
283: where \fIname\fR is the name of your system.
284: .PP
285: Now
286: .Ds
287: cd v6/setup/\fIname\fR
288: .De
289: where you need to edit some files. The files that may need editing are
290: .Ds
291: .ta 1.2i
292: paths.h \fRpaths for executable binary files\*M
293: header.hdr \fRsizing for a bootstrap header file\*M
294: icont.hdr \fRflags for command processor \*MMakefile
295: iconx.hdr \fRflags and other definitions for the run-time system \*MMakefile
296: link.hdr \fRflags for the linker \*MMakefile
297: tran.hdr \fRflags for the translator \*MMakefile
298: pi.hdr \fRflags for the personalized interpreter \*MMakefile
299: config.trl \fRother configuration definitions\*M
300: rswitch.c \fRco-expression context switch\*M
301: rover.c \fRarithmetic overflow checks\*M
302: Ranlib \fRlibrary randomizer for personalized interpreters\*M
303: .De
304: .NH 2
305: \*Mpaths.h\fR
306: .PP
307: If \*M/usr/icon/v6\fR is acceptable as a location for all Icon
308: files, you don't have to change \*Mpaths.h\fR.
309: Otherwise, handle the file \*Mpaths.h\fR as described in Appendix A.
310: .NH 2
311: \*Mheader.hdr\fR
312: .PP
313: The file \*Mheader.hdr\fR contains a definition for \*MMaxHdr\fR,
314: which determines the amount of space that is reserved for \*Miconx.hdr\fR,
315: the bootstrapping program that gets Icon programs into execution.
316: You cannot determine the most appropriate value of \*MMaxHdr\fR until
317: after Icon has been compiled.
318: An overly large value just wastes file space in compiled Icon programs,
319: but a value that is not large enough prevents compiled Icon
320: programs from executing.
321: .PP
322: The value provided, 4096, is more than enough for most systems
323: and you can wait to change it until later. Remember, however,
324: that if Icon programs fail to execute, this value may be
325: too small.
326: .PP
327: After all else has been done and Icon has been compiled and
328: tested, come back to this file and change the value of \*MMaxHdr\fR
329: to the size of \*Mv6/src/icont/iconx.hdr\fR. You may need to
330: round the size up on some systems.
331: In any event, make \*MMaxHdr\fR a hundred or so larger than the
332: size of \*Miconx.hdr\fR to allow for a somewhat larger size
333: that may be needed for personalized interpreters.
334: .PP
335: On some systems, particularly UNIX emulators, many routines may be
336: included by the loader regardless of need. In this case, the size
337: of \*Miconx.hdr\fR may be impractically large. If this is the case
338: on your system, the header file can be eliminated altogether by
339: adding
340: .Ds
341: #define NoHeader
342: .De
343: to \*Mconfig.trl\fR (see Section 7.4). The effect of this definition
344: is to render Icon programs non-executable. Instead, they must be
345: run by using the \*M\-x\fR option after the program name when
346: \*Micont\fR is used, as in
347: .Ds
348: icont prog.icn -x
349: .De
350: Such a program also can be run as an argument of \*Miconx\fR, as in
351: .Ds
352: iconx prog
353: .De
354: where \*Mprog\fR is the result of translating and linking \*Mprog.icn\fR
355: as in the previous example.
356: .PP
357: If \*MNoHeader\fR is defined, the value of \*MMaxHdr\fR is irrelevant.
358: .NH 2
359: \*MMakefile\fR headers
360: .PP
361: The files \*Micont.hdr\fR, \*Miconx.hdr\fR, \*Mlink.hdr\fR, and \*Mtran.hdr\fR
362: provide headers for \*MMakefile\fRs in \*Mv6/src/icont\fR, \*Mv6/src/iconx\fR,
363: and so on. These headers are prepended to the standard bodies for the
364: \*MMakefile\fRs during setup.
365: .PP
366: Except for \*Miconx.hdr\fR, these headers serve only to specify flags for
367: \fIcc(1)\fR and \fIld(1)\fR via \*MCFLAGS\fR and \*MLDFLAGS\fR.
368: If your C optimizer is robust, you may wish to start with
369: .Ds
370: CFLAGS= -O
371: .De
372: in all these headers. In fact, if you are installing Icon on a computer
373: with a small address space, this flag (as well as others) may be necessary
374: to obtain modules small enough to load. However, if you encounter
375: problems during testing, suspect your optimizer first and try compiling
376: Version 6.0 without the \*M\-O\fR flag.
377: .PP
378: Other \fIcc\fR and \fIld\fR flags vary considerably from system to system.
379: You may want to review your local manual pages for these processors and
380: look at the header files in the other configuration areas.
381: .PP
382: There are two other definitions in \*Miconx.hdr\fR: \*MRSWITCH\fR and
383: \*MROVER\fR, which depend on whether the local co-expression
384: context switch and arithmetic overflow checks are written in
385: C or assembly language. The initial values of these definitions
386: are \*Mrswitch.c\fR and \*Mrover.c\fR, and dummy C routines
387: are provided. To start out, leave these definitions as they are;
388: the default routines can be replaced later. See Sections 7.7 and 7.8.
389: .PP
390: The file \*Mpi.hdr\fR provides a header for the personalized interpreter
391: \*MMakefile\fR, which is in \*Mv6/Pimakefile\fR. In addition to the usual
392: \fIcc\fR and \fIld\fR flags, you should provide definitions for
393: \*MXCFLAGS\fR and \*MXLDFLAGS\fR that are the same as those for
394: \*MCFLAGS\fR and \*MLDFLAGS\fR in \*Micont.hdr\fR. This assures that
395: the header file in the personalized interpreter is the same size as
396: the one in the regular version of Icon.
397: .NH 2
398: \*Mconfig.trl\fR
399: .PP
400: The remaining configuration information is contained in \*Mconfig.trl\fR.
401: The definitions in this file as provided by \*MSetup\fR are for
402: a ``vanilla'' 32-bit computer. Changes may be needed as follows:
403: .SH
404: \*MFork\fR
405: .PP
406: If your system supports \fIvfork(2)\fR, change the definition of
407: \*MFork\fR from \*Mfork\fR to \*Mvfork\fR.
408: .SH
409: \*MHostStr\fR
410: .PP
411: Change the definition of \*MHostStr\fR, which provides the value
412: of the Icon keyword \*M&host\fR, to some string that adequately
413: identifies your installation. If you want to use a local system
414: routine to provide the host name automatically, read Appendix D.
415: .SH
416: \*MHz\fR
417: .PP
418: If you are running in a 50-hz environment, change the
419: definition of \*MHz\fR from \*M60\fR to \*M50\fR.
420: .SH
421: \*MIntSize\fR, \*MLongSize\fR, and \*MPtrSize\fR
422: .PP
423: Define these constants to the the sizes, in bits, of you C \*Mint\fRs,
424: \*Mlong\fRs and pointers, respectively.
425: These values normally are 16 or 32.
426: \*MNoOver\fR
427: .PP
428: Initially, \*Mconfig.trl\fR contains
429: .Ds
430: #define NoOver
431: .De
432: This definition disables arithmetic overflow checks, which must be
433: written in assembly language. Leave this definition in for the
434: first round, although you may want to remove it later (see Section 7.8).
435: .SH
436: \*MSysTime\fR
437: .PP
438: The system \*Minclude\fR file \*Mtime.h\fR is in different locations on
439: different systems \(em either \*M<time.h>\fR or \*M<sys/time.h>\fR.
440: Define \*MSysTime\fR accordingly.
441: .PP
442: If you give the incorrect location,
443: a fatal error will occur during the compilation of \*Mv6/src/iconx/lmisc.c\fR.
444: The use of this definition also depends on your C preprocessor
445: making macro substitutions in \*M#include\fR directives. Most preprocessors
446: do, but if yours does not, edit \*M/v6/src/iconx/lmisc.c\fR and
447: replace \*MSysTime\fR there by the appropriate value. If you have to
448: do this, make a note to come back later and place the definition under
449: the control of conditional compilation as described in Section 7.5.
450: .SH
451: Names of Indexing Routines
452: .PP
453: Different versions of UNIX use different names for the routines for
454: locating substrings within strings. Version 6.0 of Icon uses
455: \*Mindex\fR and \*Mrindex\fR. The other possibilities are \*Mstrchr\fR
456: and \*Mstrrchr\fR. If your system uses the latter names, add
457: .Ds
458: #define index strchr
459: #define rindex strrchr
460: .De
461: to \*Mconfig.trl\fR.
462: .SH
463: Other Definitions
464: .PP
465: There are several other configuration details that are needed for
466: a few systems. Most of these can be handled by optionally defined
467: symbols.
468: .PP
469: If your system needs a specific check for division by floating-point
470: zero, as opposed to relying on a signal, add
471: .Ds
472: #define ZeroDivide
473: .De
474: to your \*Mconfig.trl\fR file.
475: .PP
476: If your system requires C \fIdouble\fRs to be aligned at double-word
477: boundaries, add
478: .Ds
479: #define Double
480: .De
481: to your \*Mconfig.trl\fR file.
482: .PP
483: Most computers have down-growing C stacks, for which stack addresses
484: decrease as values are pushed. If you have an up-growing stack, for
485: which stack addresses increase as values are pushed, add
486: .Ds
487: #define UpStack
488: .De
489: to your \*Mconfig.trl\fR file.
490: .PP
491: Icon includes its own versions of \*Mmalloc\fR and \*Mfree\fR, so that
492: it can manage its storage region without interference from allocation
493: by the operating system. Normally, Icon's \*Mmalloc\fR and \*Mfree\fR
494: are loaded instead of the system library routines. If your system
495: insists on loading its own library routines, multiple definitions will
496: occur as a result of the \fIld\fR in \*M/v6/src/iconx\fR.
497: .PP
498: If multiple definitions occur in \*Miconx\fR, go back and add
499: .Ds
500: #define IconAlloc
501: .De
502: to \*Mconfig.trl\fR. This definition
503: causes Icon's routines to be named differently to avoid collision
504: with the system routine names.
505: .PP
506: One possible effect of this definition is to interfere with Icon's
507: expansion of its memory region in case the initial values for allocated
508: storage are not large enough to accommodate a program that produces a
509: lot of data.
510: This problem appears in the form of run-time error 304 or 305 and can
511: be circumvented on a case-by-case basis by increasing the
512: initial values for allocated storage by setting environment variables [4].
513: .NH 2
514: Modifications to the Distributed Source Code
515: .PP
516: The configuration system is designed to avoid modifications to
517: the distributed source code for Version 6.0. However, on some
518: systems, it may be necessary to modify the source code.
519: .PP
520: If you need to modify the source code, do it under the control of
521: conditional compilation keyed to the name of your system. Add
522: .Ds
523: #define \fINAME\fR
524: .De
525: where \fINAME\fR is an all-uppercase name that identifies your system.
526: For example, the \*Mconfig.trl\fR for Sun Workstations contains
527: .Ds
528: #define SUN
529: .De
530: .LP
531: Then use
532: .Ds
533: #ifdef \fINAME\*M
534: .do
535: #endif \fINAME\*M
536: .De
537: or similar constructions where you need local source-code modifications.
538: For example, this technique can be used to handle the problem that
539: may arise with \*MSysTime\fR, described in Section 7.4. Note
540: that nested \*M#ifdef\fRs may be needed in places where there are several
541: different local modifications.
542: .PP
543: It is important to be consistent and careful about the use of such
544: conditional compilations; if done properly, your modifications can be
545: backed into the central version of the source code at the University
546: of Arizona and will be in place for you when subsequent
547: versions are released.
548: See Section 8.
549: .NH 2
550: Initial Installation of a New System
551: .PP
552: Once you have edited the configuration files as described in the
553: previous sections, proceed with setup, compilation, and installation
554: as described in Section 2. You may need to iterate.
555: If you make a change in a configuration file after a compilation, be
556: sure to perform the setup again; some aspects of the setup are
557: far-reaching and not obvious.
558: .PP
559: More testing is recommended for a new installation than for one
560: that has been successfully installed elsewhere.
561: As a start, do
562: .Ds
563: make Test-icon
564: .De
565: If that works,
566: .Ds
567: make Test-large
568: .De
569: or
570: .Ds
571: make Test-small
572: .De
573: depending on whether you defined \*MPtrSize\fR to be 32 or 16 earlier.
574: These tests are quite extensive and contain some real grinders;
575: be prepared to wait a while. See \*Mv6/tests/Makefile\fR for more
576: information.
577: .PP
578: There will be some differences between local and standard results
579: in \*Mcheck\fR, since
580: it contains site and time-dependent tests. Other minor discrepancies
581: may occur because of differences in the handling of floating-point
582: arithmetic on different systems.
583: .PP
584: Do \fInot\fR run any other tests until you have implemented the
585: co-expression context switch (see Section 7.7) and decided what to
586: do about arithmetic overflow checking (see Section 7.8).
587: .NH 2
588: Co-Expressions
589: .PP
590: All aspects of co-expression creation and activation are written
591: in C in Version 6.0 except for a routine, \*Mcoswitch\fR, that is needed for
592: context switching. This routine requires assembly
593: language, since it must manipulate hardware registers.
594: It can either be written as a C routine with \*Masm\fR directives
595: or as an assembly language routine.
596: .PP
597: When a new configuration directory is set up, a file \*Mrswitch.c\fR is
598: provided with
599: a version of \*Mcoswitch\fR that results in error termination if an Icon
600: program attempts to activate a co-expression.
601: .PP
602: Calls to the context switch have the form \*Mcoswitch(old_cs,new_cs,first)\fR,
603: where \*Mold_cs\fR is a pointer to an array of words that contain C state
604: information for the current co-expression, \*Mnew_cs\fR is a pointer to
605: an array of words that hold C state information for a co-expression to
606: be activated, and \*Mfirst\fR is 1 or 0, depending on whether or not
607: the new co-expression has or has not been activated before.
608: The zeroth element of a C state array always contains the stack pointer
609: (\fIsp\fR) for that co-expression. The other elements (15 are provided)
610: can be used to save any C frame pointers and any
611: other registers your C compiler expects to be preserved across calls.
612: .PP
613: The first thing \*Mcoswitch\fR does is to save the current pointers
614: and registers in the \*Mold_cs\fR array. Then it tests \*Mfirst\fR.
615: If \*Mfirst\fR is zero, \*Mcoswitch\fR sets \fIsp\fR from
616: \*Mnew_cs[0]\fR, clears the C frame pointers, and \fIcalls\fR
617: \*Minterp\fR. If \*Mfirst\fR is not zero, it loads the (previously saved)
618: \fIsp\fR, C frame pointers, and registers from \*Mnew_cs\fR and
619: returns.
620: .PP
621: Written in C, \*Mcoswitch\fR has the form:
622: .DS
623: .ta 1i
624: .ft C
625: /*
626: * coswitch
627: */
628: coswitch(old_cs, new_cs, first)
629: int *old_cs, *new_cs;
630: int first;
631: {
632: .do 2i
633: /* save sp, frame pointers, and other registers in old_cs */
634: .do 2i
635: if (first == 0) { /* this is first activation */
636: .do 2i
637: /* load sp from new_cs[0] and clear frame pointers */
638: .do 2i
639: interp(0, 0);
640: syserr("interp() returned in coswitch");
641: }
642: else {
643: .do 2i
644: /* load sp, frame pointers, and other registers from new_cs */
645: .do 2i
646: }
647: }
648: .DE
649: Appendix E contains \*Mcoswitch\fR for the VAX.
650: Other examples are contained in the configuration directories in
651: \*Mv6/setup\fR.
652: .PP
653: If you do not want to implement the context switch, the only effect will
654: be that Icon programs that attempt to activate a co-expression will
655: terminate with an error message. If you chose to implement the context
656: switch, replace \*Mrswitch.c\fR in your configuration directory
657: by either a new \*Mrswitch.c\fR or an assembly language file named
658: \*Mrswitch.s\fR. The setup process will copy your file to the
659: appropriate place prior to compilation. If you use \*Mrswitch.s\fR,
660: change the definition of \*MRSWITCH\fR in \*Miconx.hdr\fR in your
661: configuration area to
662: .Ds
663: RSWITCH=rswitch.s
664: .De
665: If your assembler requires special flags, add an appropriate
666: definition for \*MOFLAGS\fR to \*Miconx.hdr\fR.
667: .PP
668: To test your context switch,
669: .Ds
670: make Test-lcoexpr
671: .De
672: or
673: .Ds
674: make Test-scoexpr
675: .De
676: depending on whether you defined \*MPtrSize\fR to be 32 or 16 earlier.
677: There should be no differences in the comparison of outputs.
678: .PP
679: If you have trouble with your context switch, the first thing to do
680: is double-check the registers that your C compiler expects to
681: be preserved across calls \(em different C compilers on the same
682: computer may have different requirements.
683: .PP
684: Another possible source of problems is built-in stack checking.
685: Co-expressions rely on being able to specify an arbitrary region
686: of memory for the C stack. If your C compiler generates code for
687: stack probes that expects the C stack to be at a specific location,
688: you may need to disable this code or replace it with something
689: more appropriate.
690: .PP
691: If your system does not allow the C stack to be at an arbitrary
692: place in memory, there is probably little hope of implementing
693: co-expressions.
694: .NH 2
695: Arithmetic Overflow Checks
696: .PP
697: C does not provide overflow checking for integer addition, subtraction,
698: or multiplication. Icon, on the other hand, is supposed to check for
699: overflow. This requires assembly-language code.
700: .PP
701: The \*Mconfig.trl\fR file provided when a new configuration area is
702: set up provides the definition
703: .Ds
704: #define NoOver
705: .De
706: which causes overflow checking to be bypassed.
707: .PP
708: If you do not want to implement overflow checking, you need do nothing.
709: If you want to implement overflow checking, remove the definition
710: of \*MNoOver\fR from your \*Mconfig.trl\fR and write routines
711: \*Mckadd\fR, \*Mcksub\fR, and \*Mckmul\fR that call \*Mrunerr(203,0)\fR
712: in the case of overflow. Appendix F contains the overflow checking
713: routine for the VAX.
714: Other examples are contained in the configuration directories in
715: \*Mv6/setup\fR.
716: .PP
717: If you supply overflow checking routines, put them in the file
718: \*Mrover.s\fR in your configuration directory. The setup will copy
719: this file to the appropriate place prior to compilation.
720: .PP
721: To test overflow checking,
722: .Ds
723: make Test-over
724: .De
725: There should be no differences in the comparison of outputs if overflow
726: checking is working properly.
727: .PP
728: You should also rerun previous tests at this point to make sure
729: that arithmetic still works properly.
730: .NH 2
731: Personalized Interpreters
732: .PP
733: The personalized interpreter system uses \fIar(1)\fR. On most
734: UNIX systems, it is necessary to use \fIranlib(1)\fR so that the
735: loader can access the archive. The script \*MRanlib\fR that is
736: provided when a new configuration directory is initialized contains
737: calls of \fIranlib\fR for this purpose.
738: .PP
739: Some UNIX systems, notably System V, handle this problem directly
740: in \fIar(1)\fR and do not have \fIranlib(1)\fR. If your system does
741: not use \fIranlib(1)\fR, change \*MRanlib\fR to an empty script by
742: .Ds
743: echo "" >Ranlib
744: .De
745: in your configuration directory.
746: .
747: .a
748: .PP
749: Test your personalized interpreter system as described in Section
750: 3. If the test programs fail to execute, suspect the size of
751: \*Mv6/tests/pi/piconx.hdr\fR, the personalized interpreter
752: version of \*Miconx.hdr\fR. If it is larger than \*MMaxHdr\fR,
753: something is wrong. Check the file \*Mpi.hdr\fR in your
754: configuration directory as described in Section 7.3.
755: .NH
756: Trouble Reports and Feedback
757: .PP
758: If you run into problems, contact the Icon Project:
759: .DS
760: .ft R
761: Icon Project
762: Department of Computer Science
763: The University of Arizona
764: Tucson, AZ 85721
765: .sp .5
766: (602) 621-6613
767: .sp .5
768: \*Micon\[email protected]
769: {ihnp4,noao,mcnc,utah-cs}!arizona!icon-project
770: .DE
771: .PP
772: Please also let us know of any suggestions for improvements to the
773: installation process and corrections or refinements to configuration
774: files for supported systems.
775: .PP
776: If you installed a previously unsupported system,
777: send a copy of the files
778: in your configuration directory and any files in \*Mv6/src\fR that
779: you modified to
780: so that we can back them in to the central version of the source.
781: .SH
782: Acknowledgement
783: .PP
784: Gregg Townsend made a number of helpful suggestions related to the
785: process for installing Version 6.0.
786: .SH
787: References
788: .LP
789: 1. Griswold, Ralph E. \fIPersonalized Interpreters for Version 6.0 of Icon\fR,
790: Technical Report TR 86-12, Department of Computer Science, The University
791: of Arizona. May 1986.
792: .LP
793: 2. Griswold, Ralph E. \fIThe Icon Program Library; Version 6.0\fR,
794: Technical Report TR 86-13, Department of Computer Science, The University
795: of Arizona. May 1986.
796: .LP
797: 3. Griswold, Ralph E., William H. Mitchell, and Janalee O'Bagy.
798: \fIVersion 6.0 of Icon\fR, Technical Report TR 86-10, Department of
799: Computer Science, The University of Arizona. May 1986.
800: .LP
801: 4. Griswold, Ralph E. \fIICONT(1)\fR, manual page for \fIUNIX
802: Programmer's Manual\fR, Department of Computer Science, The
803: University of Arizona. May 1986.
804: .Ap "Appendix A \(em Changing the Locations of Version 6.0 Files"
805: .sp
806: .PP
807: As mentioned in Section 2, the distributed files are rooted in \*Mv6\fR.
808: The standard location for this hierarchy is \*M/usr/icon/v6\fR\s-2\u1\d\s0.
809: .FS
810: \s-2\u1\d\s0\^For HP-UX, the standard location is \*M/users/icon/v6\fR.
811: The location \*M/usr/icon/v6\fR is used here for convenience.
812: .FE
813: The hierarchy can be placed somewhere else if you desire, but
814: before performing the setup, you must edit a file that
815: specifies where the binary files are to be installed.
816: .PP
817: The directory \*Mv6/setup\fR contains a subdirectory for each
818: supported system. For example, \*Mv6/setup/sun\fR contains the
819: configuration information for the Sun Workstation. To get to the
820: configuration information for your system,
821: .Ds
822: cd v6/setup/\fIname\fR
823: .De
824: where \fIname\fR is the name of your system.
825: .PP
826: The file \*Mpaths.h\fR,
827: as distributed, is the same for all systems and contains
828: .Ds
829: .ta 1.8i
830: #define RootPath "/usr/icon/v6"
831: #define IcontPath "/usr/icon/v6/bin/icont"
832: #define TranPath "/usr/icon/v6/bin/itran"
833: #define LinkPath "/usr/icon/v6/bin/ilink"
834: #define IconxPath "/usr/icon/v6/bin/iconx"
835: #define HeaderPath "/usr/icon/v6/bin/iconx.hdr"
836: .De
837: \*MRootPath\fR gives the location of the \*Mv6\fR hierarchy.
838: .PP
839: The five binary files referenced are:
840: .Ds
841: .ta 1i
842: icont \fRIcon command processor \(em all the typical user knows about\*M
843: itran \fRIcon translator\*M
844: ilink \fRIcon linker\*M
845: iconx \fRIcon run-time system\*M
846: iconx.hdr \fRbootstrap program that gets Icon programs into execution
847: .De
848: The command processor \*Micont\fR calls the other programs.
849: .PP
850: There are two reasons for changing these paths:
851: .RS
852: .IP 1. 4n
853: If \*Mv6\fR is
854: unloaded in an area other than \*M/usr/icon/v6\fR,
855: you probably want the binary files installed in that area instead of
856: \*M/usr/icon/v6\fR.
857: .IP 2.
858: You may want to install some or all of the binary files in a public
859: area.
860: .RE
861: .LP
862: For example, if you want to unload Icon in \*M/usr/irving/v6\fR,
863: edit \*Mpaths.h\fR to be
864: .Ds
865: .ta 1.8i
866: #define RootPath "/usr/irving/v6"
867: #define IcontPath "/usr/irving/v6/bin/icont"
868: #define TranPath "/usr/irving/v6/bin/itran"
869: #define LinkPath "/usr/irving/v6/bin/ilink"
870: #define IconxPath "/usr/irving/v6/bin/iconx"
871: #define HeaderPath "/usr/irving/v6/bin/iconx.hdr"
872: .De
873: Similarly, if you want \*Micont\fR to reside in \*M/usr/local/icont\fR,
874: edit the line for \*Micont\fR to be
875: .Ds
876: .ta 1i 2i
877: #define IcontPath "/usr/local/icont"
878: .De
879: \fICaution:\fR If you have a previously installed version of Icon, do not
880: put \*Miconx\fR at that place \(em
881: \*Miconx\fR for Version 6.0 is incompatible with \*Miconx\fR for
882: previous versions and replacing a previous \*Miconx\fR by Version 6.0
883: \*Miconx\fR will invalidate all previously compiled Icon programs.
884: .Ap "Appendix B \(em Unloading the Distribution Files"
885: .sp 2
886: .PP
887: The Icon distribution files are distributed in a variety of ways.
888: The usual distribution is magnetic tape, although
889: it is available on 5-\(14\(fm\(fm diskettes in DOS and
890: PC/IX formats. The directions that follow refer to magnetic tape
891: distribution only.
892: .PP
893: The Icon system is provided on tape in \fItar\fR or \fIcpio\fR format, recorded
894: at 1600 or 6250 bpi as specified when Version 6.0 is ordered.
895: Tapes are written in \fItar\fR format at 1600 bpi if no specification
896: is given.
897: The format and recording density are marked on the label on the tape.
898: .PP
899: To unload the tape,
900: do a \fIcd\fR to the directory that is to hold
901: the Icon hierarchy (that is, the directory in which \*Mv6\fR is to be
902: created) and mount the tape.
903: The precise
904: \fItar\fR or \fIcpio\fR command to unload the distribution
905: tape depends on the local environment.
906: On a VAX running 4.\fIn\fRbsd, use
907: the following command for a 1600 bpi \fItar\fR distribution tape:
908: .Ds
909: tar x
910: .De
911: Similarly, on a VAX running System V with a 6250 bpi \fIcpio\fR tape,
912: use:
913: .Ds
914: cpio -icdB </dev/rmt/0h
915: .De
916: .Ap "Appendix C \(em The Distribution Hierarchy"
917: .sp 2
918: .Ds
919: .ta 1i +1i +1i +1i +1i +1i +1i +1i
920: /v6 \fRroot of the Version 6.0 hierarchy\*M
921: /bin \fRstandard location for binary files\*M
922: /book \fRprograms from the Icon book\*M
923: /docs \fRsource text for documents\*M
924: /ipl \fRIcon program library\*M
925: /pi \fRpersonalized interpreter system\*M
926: /setup \fRsetup and configuration files\*M
927: /src \fRsource code for the Icon system\*M
928: /tests \fRtest programs\*M
929: .De
930: .Ap "Appendix D \(em Host Name"
931: .sp 2
932: .PP
933: The default method for specifying the host name that determines the
934: value of \*M&host\fR is the definition of \*MHostStr\fR in
935: \*Mconfig.trl\fR in the configuration directory. There are three other
936: ways of specifying the host; only one may be used.
937: .SH
938: \*MWhoHost\fR
939: .PP
940: On some versions of UNIX, notably Version 7 and 4.1bsd, the file
941: \*M/usr/include/whoami.h\fR contains the host name. If your system has
942: this file and you want to
943: use this name,
944: .Ds
945: #define WhoHost
946: .De
947: .SH
948: \*MGetHost\fR
949: .PP
950: Some versions of UNIX, notably 4.2bsd and 4.3bsd, provide the
951: host name via the \fIgethostname(2)\fR system call. If your system supports
952: this system call and you want
953: to use this name,
954: .Ds
955: #define GetHost
956: .De
957: .SH
958: \*MUtsName\fR
959: .PP
960: Some versions of UNIX, such as System V, provide the host name via
961: the \fIuname(2)\fR system call. If your system supports this call
962: and you want to use this name,
963: .Ds
964: #define UtsName
965: .De
966: .Ap "Appendix E \(em Sample Co-Expression Context Switch"
967: .sp 2
968: .SH
969: \*Mrswitch.c\fR for the VAX under Berkeley UNIX:
970: .LP
971: .Ds
972: .ta 2.5i
973: coswitch(old_cs, new_cs, first)
974: int *old_cs, *new_cs;
975: int first;
976: .Dd
977: {
978: asm(" movl 4(ap),r0");
979: asm(" movl 8(ap),r1");
980: asm(" movl sp,0(r0)");
981: asm(" movl fp,4(r0)");
982: asm(" movl ap,8(r0)");
983: asm(" movl r11,16(r0)");
984: asm(" movl r10,20(r0)");
985: asm(" movl r9,24(r0)");
986: asm(" movl r8,28(r0)");
987: asm(" movl r7,32(r0)");
988: asm(" movl r6,36(r0)");
989: .Dd
990: if (first == 0) { /* this is first activation */
991: asm(" movl 0(r1),sp");
992: asm(" clrl fp");
993: asm(" clrl ap");
994: interp(0, 0);
995: syserr("interp() returned in coswitch");
996: }
997: .Dd
998: else {
999: asm(" movl 0(r1),sp");
1000: asm(" movl 4(r1),fp");
1001: asm(" movl 8(r1),ap");
1002: asm(" movl 16(r1),r11");
1003: asm(" movl 20(r1),r10");
1004: asm(" movl 24(r1),r9");
1005: asm(" movl 28(r1),r8");
1006: asm(" movl 32(r1),r7");
1007: asm(" movl 36(r1),r6");
1008: }
1009: }
1010: .De
1011: .Ap "Appendix F \(em Sample Arithmetic Overflow Checking Routine"
1012: .sp 2
1013: .SH
1014: \*Mrover.s\fR for the VAX under Berkeley UNIX:
1015: .Ds
1016: .globl _ckadd
1017: .globl _cksub
1018: .globl _ckmul
1019:
1020: .text
1021: .align 1
1022: _ckadd: .word 0
1023: addl3 4(ap),8(ap),r0 # Perform addition
1024: jvs oflow # Branch if overflow
1025: ret # Return result in r0
1026:
1027: .align 1
1028: _cksub: .word 0
1029: subl3 8(ap),4(ap),r0 # Perform subtraction
1030: jvs oflow # Branch if overflow
1031: ret # Return result in r0
1032:
1033: .align 1
1034: _ckmul: .word 0
1035: mull3 4(ap),8(ap),r0 # Perform multiplication
1036: jvs oflow # Branch if overflow
1037: ret # Return result in r0
1038:
1039: oflow: # Got overflow on an operation
1040: pushl $0
1041: pushl $203
1042: calls $1,_runerr # runerr(203,0)
1043: .De
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.