![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to icon-pi.1 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 icon-pi.1 CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / icon / docs |
1.1 root 1: .ds M \fB
2: .if t .if !\nd .ds M \fM
3: .de Ds
4: .nf
5: .sp
6: .in +.5i
7: \\*M\c
8: ..
9: .de De
10: .sp
11: .in
12: .ft R
13: .fi
14: ..
15: .if t .if !\nd .ds M \fM
16: .TH ICON\-PI 1 "The University of Arizona \- 8/21/84"
17: .SH NAME
18: icon\-pi \- construct personalized interpreter for Icon
19: .SH SYNOPSIS
20: \f3icon\-pi\fR
21: .SH DESCRIPTION
22: A personalized interpreter is
23: a version of Icon in which the run-time system can be easily
24: augmented and modified by the user.
25: .PP
26: To set up a personalized interpreter, a new directory should
27: be created solely for the use of the interpreter; otherwise
28: files may be accidentally destroyed by the set-up process.
29: For the purpose of example, suppose this directory is
30: named \*Mmyicon\fR. The set-up process consists of
31: .Ds
32: mkdir myicon
33: cd myicon
34: icon\-pi
35: .De
36: Note that \*Micon\-pi\fR must be run in the area in which the personalized
37: interpreter is to be built.
38: .PP
39: The shell script \*Micon\-pi\fR constructs three subdirectories:
40: \*Mh\fR, \*Mstd\fR, and \*Mpi\fR. The subdirectory \*Mh\fR
41: contains header files that are needed in C routines. The subdirectory
42: \*Mstd\fR contains the portions of the Icon system that are needed
43: to build a personalized interpreter. The subdirectory \*Mpi\fR
44: contains a \*MMakefile\fR for building a personalized interpreter
45: and also is the place where source code for new C functions normally
46: resides.
47: .PP
48: The \*MMakefile\fR that is constructed by \*Micon\-pi\fR
49: contains two definitions to facilitate building personalized
50: interpreters:
51: .IP \*MOBJS\fR .5i
52: a list of object modules that are to be added to or replaced
53: in the run-time system. \*MOBJS\fR initially is empty.
54: .IP \*MLIB\fR
55: a list of library options that are used when the run-time system
56: is built. \*MLIB\fR initially is empty.
57: .PP
58: Performing a \fImake\fR in \*Mmyicon/pi\fR creates three files
59: in \*Mmyicon\fR:
60: .Ds
61: .ta 1i
62: picont \fRcommand processor\*M
63: pilink \fRlinker\*M
64: piconx \fRrun-time system\*M
65: .De
66: A link to \*Mpicont\fR also is constructed in \*Mmyicon/pi\fR so that
67: the new personalized interpreter can be tested in the directory in
68: which it is made.
69: .PP
70: The file \*Mpicont\fR normally is built only on the first \fImake\fR. The
71: file \*Mpilink\fR is built on the first \fImake\fR and is
72: rebuilt whenever the repertoire of built-in functions is changed.
73: The file \*Mpiconx\fR is rebuilt whenever the source code in the
74: run-time system is changed.
75: .PP
76: The user of the personalized interpreter uses \*Mpicont\fR in
77: the same fashion that the standard \*Micont\fR (see \fIicont(1)\fR).
78: (Note that the accidental use of \*Micont\fR in place of
79: \*Mpicont\fR may produce mysterious results.)
80: In turn, \*Mpicont\fR translates a source program using the
81: standard Icon translator and links it using \*Mpilink\fR.
82: The resulting icode file uses \*Mpiconx\fR.
83: Note that the location of \*Mpiconx\fR is built into the icode file.
84: .PP
85: The relocation bits and symbol tables in \*Mpicont\fR, \*Mpilink\fR,
86: and \*Mpiconx\fR can be removed by
87: .Ds
88: make Strip
89: .De
90: in \*Mmyicon/pi\fR. This reduces the sizes of these files substantially
91: but makes the use of debuggers impractical.
92: .PP
93: If a \fImake\fR is performed in \*Mmyicon/pi\fR before any
94: run-time files are added or modified, the resulting personalized
95: interpreter is identical to the standard one. Such a \fImake\fR can
96: be performed to verify that the personalized interpreter system
97: is performing properly.
98: .PP
99: Note that a personalized interpreter inherits the parameters and
100: configuration of the locally installed version of Icon in \*Mv5g\fR, including
101: optional language extensions.
102: The file \*Mmyicon/h/config.h\fR contains configuration information.
103: The definitions in this file should not be changed.
104: .PP
105: To add a new function to the personalized interpreter, it is first
106: necessary to provide the C code, adhering to the conventions and
107: data structures used throughout Icon.
108: Some useful functions from the Icon program library are
109: contained in \*Mv5g/pifuncs\fR, where \*Mv5g\fR is the root
110: of the source hierarchy for the Icon system.
111: The directory
112: \*Mv5g/functions\fR contains the source code for the standard built-in
113: functions, which also can be used as models for new ones.
114: .PP
115: Suppose that \*Mgetenv\fR from the Icon program library is to be
116: added to a personalized interpreter. The source code can be obtained by
117: .Ds
118: cp v5g/pifuncs/getenv.c myicon/pi
119: .De
120: (Note that the actual paths will be different, depending on the
121: local hierarchy.)
122: .PP
123: Four things now need to be done to
124: incorporate this function in the personalized interpreter:
125: .IP 1. 5n
126: Add a line consisting of
127: .Ds
128: PDEF(getenv)
129: .De
130: to \*Mmyicon/h/pdef.h\fR in proper alphabetical order.
131: This causes the linker and the run-time system to know about the new function.
132: .IP 2.
133: Add \*Mgetenv.o\fR to the definition of \*MOBJS\fR in
134: \*Mmyicon/pi/Makefile\fR.
135: This causes \*Mgetenv.c\fR to be compiled and the resulting
136: object file to be loaded with the run-time system when a \fImake\fR is performed.
137: .IP 3.
138: Add a dependency line in \*Mmyicon/pi/Makefile\fR for \*Mgetenv.o\fR
139: to reflect the file that it includes, namely
140: .Ds
141: getenv.o: ../h/rt/h
142: .De
143: .IP 4.
144: Perform a \fImake\fR in \*Mmyicon/pi\fR. The result is
145: new versions of \*Mpilink\fR and \*Mpiconx\fR in \*Mmyicon\fR.
146: .LP
147: The function \*Mgetenv\fR now can be used like any other built-in
148: function.
149: .PP
150: More than one function can be included in a single source file.
151: If a function requires a library to be loaded, that library should
152: be added to the definition of \*MLIB\fR in the \*MMakefile\fR.
153: .PP
154: The use of personalized interpreters is not limited to the addition
155: of new functions. Any module in the standard run-time system can
156: be modified as well.
157: To modify an existing portion of the Icon run-time system,
158: copy the source code file from the standard system to \*Mmyicon/pi\fR.
159: (Source code for a few run-time routines is placed in \*Mmyicon/std\fR
160: when a personalized interpreter is set up. Check this directory
161: first and use that file, if appropriate, rather than making
162: another copy in \*Mmyicon/pi\fR.) When a source-code file in
163: \*Mmyicon/pi\fR has been modified, place it in the \*MOBJS\fR
164: list just like a new file and perform a \fImake\fR. Note that
165: an entire module must be replaced, even if a change is made to
166: only one routine.
167: Any module that is replaced must contain all the global variables in
168: the original module to prevent \fIld(1)\fR from also loading the
169: original module. There is no way to delete routines from the run-time
170: system.
171: .PP
172: The directory \*Mmyicon/h\fR contains header files that are included
173: in various source-code files. For example, error message text for
174: a new run-time error can be provided by adding it to \*Mmyicon/h/err.h\fR.
175: The file \*Mmyicon/h/rt.h\fR contains declarations and definitions that
176: are used throughout the run-time system. This is where the declaration
177: for the structure of a new type of data object would be placed.
178: .PP
179: Care
180: must be taken when modifying header files not to make changes that
181: would produce inconsistencies between previously compiled components
182: of the Icon run-time system and new ones.
183: .SH FILES
184: .ta \w'\*Mv5g/operators\fR 'u
185: .nf
186: \*Mv5g/pilib\fR code for building personalized interpreters
187: \*Mv5g/pifuncs\fR functions from the Icon program library
188: \*Mv5g/functions\fR built-in functions
189: \*Mv5g/operators\fR built-in operators
190: \*Mv5g/rt\fR run-time support routines
191: \*Mv5g/lib\fR routines called by the interpreter
192: \*Mv5g/iconx\fR the interpreter and start-up routines
193: .fi
194: .SH SEE ALSO
195: .I
196: The Icon Programming Language\fR,
197: Ralph E. Griswold and Madge T. Griswold,
198: Prentice-Hall Inc.,
199: Englewood Cliffs, New Jersey,
200: 1983.
201: .LP
202: \fIVersion 5.9 of Icon\fR, Ralph E. Griswold, Robert K. McConeghy, and William H. Mitchell,
203: Department of Computer Science, The University of Arizona,
204: August 1984.
205: .LP
206: \fIInstallation and Maintenance Guide for Version 5.9 of Icon\fR,
207: Ralph E. Griswold and William H. Mitchell,
208: Department of Computer Science, The University of Arizona,
209: August 1984.
210: .LP
211: \fIA Tour Through the C Implementation of Icon; Version 5.9\fR,
212: Ralph E. Griswold, Robert K. McConeghy, and William H. Mitchell,
213: Department of Computer Science,
214: The University of Arizona, August 1984.
215: .LP
216: \fIThe Icon Program Library\fR, Ralph E. Griswold,
217: Department of Computer Science, The University of
218: Arizona, August 1984.
219: .LP
220: icont(1)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.