![[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 [Research Unix] / researchv10dc / cmd / icon / docs|
Return to icon_pi.1 CVS log | Up to [Research Unix] / researchv10dc / cmd / icon / docs |
1.1 root 1: .ds M \fH
2: .de Ds
3: .nf
4: .in +.5i
5: .ft H
6: .sp .5
7: ..
8: .de De
9: .ft R
10: .in -.5i
11: .fi
12: .sp .5
13: ..
14: .TH ICON_PI 1 "The University of Arizona \- 5/6/86"
15: .SH NAME
16: icon_pi \- construct personalized interpreter for Icon
17: .SH SYNOPSIS
18: \*Micon_pi\fR
19: .SH DESCRIPTION
20: A personalized interpreter is
21: a version of Icon in which the run-time system can be easily
22: augmented and modified by the user.
23: .PP
24: To set up a personalized interpreter, a new directory should
25: be created solely for the use of the interpreter; otherwise
26: files may be accidentally destroyed by the set-up process.
27: For the purpose of example, suppose this directory is
28: named \*Mmyicon\fR. The set-up process consists of
29: .Ds
30: mkdir myicon
31: cd myicon
32: icon_pi
33: .De
34: Note that \*Micon_pi\fR must be run in the area in which the personalized
35: interpreter is to be built.
36: .PP
37: The shell script \*Micon_pi\fR constructs three subdirectories:
38: \*Mh\fR, \*Mstd\fR, and \*Mpi\fR. The subdirectory \*Mh\fR
39: contains header files that are needed in C routines. The subdirectory
40: \*Mstd\fR contains the portions of the Icon system that are needed
41: to build a personalized interpreter. The subdirectory \*Mpi\fR
42: contains a \*MMakefile\fR for building a personalized interpreter
43: and also is the place where source code for new C functions normally
44: resides.
45: .PP
46: The \*MMakefile\fR that is constructed by \*Micon_pi\fR
47: contains two definitions to facilitate building personalized
48: interpreters:
49: .IP \*MOBJS\fR .5i
50: a list of object modules that are to be added to or replaced
51: in the run-time system. \*MOBJS\fR initially is empty.
52: .IP \*MLIB\fR
53: a list of library options that are used when the run-time system
54: is built. \*MLIB\fR initially is empty.
55: .PP
56: Performing a \fImake\fR in \*Mmyicon/pi\fR creates four additional files
57: in \*Mmyicon\fR:
58: .Ds
59: .ta 1i
60: picont \fRcommand processor\*M
61: pilink \fRlinker\*M
62: piconx \fRrun-time system\*M
63: piconx.hdr \fRheader for linker output\*M
64: .De
65: A link to \*Mpicont\fR also is constructed in \*Mmyicon/pi\fR so that
66: the new personalized interpreter can be tested in the directory in
67: which it is made.
68: .PP
69: The file \*Mpicont\fR normally is built only on the first \fImake\fR. The
70: file \*Mpilink\fR is built on the first \fImake\fR and is
71: rebuilt whenever the repertoire of built-in functions is changed.
72: The file \*Mpiconx\fR is rebuilt whenever the source code in the
73: run-time system is changed.
74: .PP
75: The user of the personalized interpreter uses \*Mpicont\fR in
76: the same fashion that the standard \*Micont\fR; see \fIicont(1)\fR.
77: (Note that the accidental use of \*Micont\fR in place of
78: \*Mpicont\fR may produce mysterious results.)
79: In turn, \*Mpicont\fR translates a source program using the
80: standard Icon translator and links it using \*Mpilink\fR.
81: The resulting icode file uses \*Mpiconx\fR.
82: Note that the location of \*Mpiconx\fR is built into the icode file.
83: .PP
84: The relocation bits and symbol tables in
85: \*Mpiconx\fR can be removed by
86: .Ds
87: make Stripx
88: .De
89: in \*Mmyicon/pi\fR. This reduces the size of this file substantially
90: but makes the use of debuggers impractical.
91: .PP
92: If a \fImake\fR is performed in \*Mmyicon/pi\fR before any
93: run-time files are added or modified, the resulting personalized
94: interpreter is identical to the standard one. Such a \fImake\fR can
95: be performed to verify that the personalized interpreter system
96: is performing properly.
97: .PP
98: Note that a personalized interpreter inherits the parameters and
99: configuration of the locally installed version of Icon in \*Mv6\fR, including
100: optional language extensions.
101: The file \*Mmyicon/h/config.h\fR contains configuration information.
102: The definitions in this file should not be changed.
103: .PP
104: To add a new function to the personalized interpreter, it is first
105: necessary to provide the C code, adhering to the conventions and
106: data structures used throughout Icon.
107: Some useful functions are
108: contained in \*Mv6/pi/pil\fR, where \*Mv6\fR is the root
109: of the source hierarchy for the Icon system.
110: The directory
111: \*Mv6/src/iconx\fR contains the source code for the standard built-in
112: functions, which also can be used as models for new ones.
113: .PP
114: Suppose that \*Mgetenv\fR from \*Mv6/pi/pil\fR is to be
115: added to a personalized interpreter. The source code can be obtained by
116: .Ds
117: cp v6/pi/pil/getenv.c myicon/pi
118: .De
119: (Note that the actual paths depend on the
120: local hierarchy.)
121: .PP
122: Four things now need to be done to
123: incorporate this function in the personalized interpreter:
124: .IP 1. 5n
125: Add a line consisting of
126: .Ds
127: FncDef(getenv)
128: .De
129: to \*Mmyicon/h/fdef.h\fR in proper alphabetical order.
130: This causes the linker and the run-time system to know about the new function.
131: .IP 2.
132: Add \*Mgetenv.o\fR to the definition of \*MOBJS\fR in
133: \*Mmyicon/pi/Makefile\fR.
134: This causes \*Mgetenv.c\fR to be compiled and the resulting
135: object file to be loaded with the run-time system when a \fImake\fR is performed.
136: .IP 3.
137: Add a dependency line in \*Mmyicon/pi/Makefile\fR for \*Mgetenv.o\fR
138: to reflect the file that it includes, namely
139: .Ds
140: getenv.o: ../h/rt.h
141: .De
142: .IP 4.
143: Perform a \fImake\fR in \*Mmyicon/pi\fR.
144: This produces
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.
174: The file \*Mmyicon/h/rt.h\fR contains declarations and definitions that
175: are used throughout the run-time system. This is where the declaration
176: for the structure of a new type of data object would be placed.
177: .PP
178: Care
179: must be taken when modifying header files not to make changes that
180: would produce inconsistencies between previously compiled components
181: of the Icon run-time system and new ones.
182: .SH FILES
183: .ta 1i
184: .nf
185: \*Mv6/pi\fR code for building personalized interpreters
186: \*Mv6/src/iconx\fR run-time system
187: .fi
188: .SH SEE ALSO
189: icont(1)
190: .LP
191: \fIPersonalized Interpreters for Version 6.0 of Icon\fR, Ralph E.
192: Griswold, TR 86-12, Department of Computer Science, The University
193: of Arizona, May 1986.
194: .LP
195: \fIThe Icon Programming Language\fR,
196: Ralph E. Griswold and Madge T. Griswold,
197: Prentice-Hall Inc.,
198: Englewood Cliffs, New Jersey,
199: 1983.
200: .LP
201: \fIVersion 6.0 of Icon\fR, Ralph E. Griswold, William H. Mitchell, and
202: Janalee O'Bagy,
203: TR 86-10,
204: Department of Computer Science, The University of Arizona,
205: May 1986.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.