![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to tr86-12.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-12.roff CVS log | Up to [Research Unix] / researchv10dc / cmd / icon / docs |
1.1 root 1: .so tmac.tr
2: .DA "May 6, 1986"
3: .TR 86-12
4: .Gi
5: .TL
6: Personalized Interpreters for Version 6.0 of Icon
7: .AU
8: Ralph E. Griswold
9: .AE
10: .tr *\(**
11: .NH
12: Introduction
13: .PP
14: Despite the fact that the Icon programming language has a large repertoire
15: of functions and operations for string and list manipulation, as
16: well as for more conventional computations [1], users frequently
17: need to extend that repertoire. While many extensions can be
18: written as procedures that build on the existing repertoire, there
19: are some kinds of extensions for which this approach is unacceptably
20: inefficient, inconvenient, or simply impractical.
21: .PP
22: Icon itself is written C and its built-in functions
23: are written as corresponding C functions. Thus, the natural way to
24: extend Icon's computational repertoire is to add new C functions to it.
25: .PP
26: The Icon system is organized so that this is comparatively easy to do.
27: Adding a new function
28: does not require changes to the Icon translator,
29: since all functions have a common syntactic form. An entry must be made in
30: a table that is used by the linker and the run-time system in order to
31: identify built-in functions and connect references to them to the
32: code itself.
33: .PP
34: One method of adding new functions to Icon
35: is to
36: add the corresponding C functions to the Icon system itself
37: and to rebuild the entire system. This approach is impractical
38: for many applications. If the extensions are not of general
39: interest, it is inappropriate to include them in the public
40: version of Icon. On the other hand, Icon is a large and complicated system,
41: and having many private versions may create serious problems of
42: maintenance and disk usage. Furthermore, rebuilding the Icon system
43: is expensive. This approach therefore
44: may be impractical in a situation
45: such as a class in which students implement their own versions
46: of an extension.
47: .PP
48: To remedy these problems, a mechanism for building ``personalized
49: interpreters'' is included in \*U implementations of Icon.
50: This mechanism
51: .Un
52: allows a user to add C functions and to build a corresponding
53: interpreter quickly, easily, and without the necessity to have
54: a copy of the source code for the entire Icon system.
55: .PP
56: To construct a personalized interpreter, the user must perform
57: a one-time set up that copies relevant source files to a
58: directory specified by the user and builds the nucleus of a run-time system. Once this is
59: done, the user can add and modify C functions and include them
60: in the personalized run-time system with little effort.
61: .PP
62: Since the linker must know the names of built-in functions,
63: a personalized linker also is constructed. In order to run
64: Icon programs in a self-contained personalized run-time system,
65: personalized versions of the translator, \*Mpitran\fR, and the
66: command processor, \*Mpicont\fR,
67: are provided also.
68: .PP
69: The modifications that can be made to Icon via a personalized
70: interpreter essentially are limited to the run-time system: the
71: addition of new functions, modifications to existing functions
72: and operations, and modifications and additions to support routines. There
73: is no provision for changing the syntax of Icon, incorporating
74: new operators, keyword, or control structures.
75: .NH
76: Building and Using a Personalized Interpreter
77: .NH 2
78: Setting Up a Personalized Interpreter System
79: .PP
80: To set up a personalized interpreter, a new directory should
81: be created solely for the use of the interpreter; otherwise
82: files may be accidentally destroyed by the setup process.
83: For the purpose of example, suppose this directory is
84: named \*Mmyicon\fR. The setup consists of
85: .Ds
86: mkdir myicon
87: cd myicon
88: icon_pi
89: .De
90: Note that \*Micon_pi\fR must be run from the area in which the personalized
91: interpreter is to be built.
92: The
93: location of \*Micon_pi\fR may vary from site to site.
94: .PP
95: The shell script \*Micon_pi\fR constructs three subdirectories:
96: \*Mh\fR, \*Mstd\fR, and \*Mpi\fR. The subdirectory \*Mh\fR
97: contains header files that are needed in C routines. The subdirectory
98: \*Mstd\fR contains the machine-independent portions of the Icon system that are needed
99: to build a personalized interpreter.
100: The subdirectory \*Mpi\fR
101: contains a \*MMakefile\fR for building a personalized interpreter
102: and also is the place where source code for new C functions normally
103: resides. Thus, work on the personalized interpreter is done in
104: \*Mmyicon/pi\fR.
105: .PP
106: The \*MMakefile\fR that is constructed by \*Micon_pi\fR
107: contains two definitions to facilitate building personalized
108: interpreters:
109: .RS
110: .IP \*MOBJS\fR .5i
111: a list of object modules that are to be added to or replaced
112: in the run-time system. \*MOBJS\fR initially is empty.
113: .IP \*MLIB\fR
114: a list of library options that are used when the run-time system
115: is built. \*MLIB\fR initially is empty, but the math library is
116: loaded as a normal part of building the run-time system.
117: .RE
118: .LP
119: See the listing of the generic version of this \*MMakefile\fR in
120: Appendix A.
121: .NH 2
122: Building a Personalized Interpreter
123: .PP
124: Performing a \fImake\fR in \*Mmyicon/pi\fR creates four files
125: in \*Mmyicon\fR:
126: .Ds
127: .ta 1i
128: picont \fRcommand processor\*M
129: pilink \fRlinker\*M
130: piconx \fRrun-time system\*M
131: piconx.hdr \fRheader file for linker output\*M
132: .De
133: A link to \*Mpicont\fR also is constructed in \*Mmyicon/pi\fR so that
134: the new personalized interpreter can be tested in the directory in
135: which it is made.
136: .PP
137: The file \*Mpicont\fR normally is built only on the first \fImake\fR. The
138: file \*Mpilink\fR is built on the first \fImake\fR and is
139: rebuilt whenever the repertoire of built-in functions is changed
140: as a result of modifications to \*Mh/fdef.h\fR.
141: The file \*Mpiconx\fR is rebuilt whenever the source code in the
142: run-time system is changed.
143: .PP
144: The user of the personalized interpreter uses \*Mpicont\fR in
145: the same fashion that the standard \*Micont\fR is used.
146: (Note that the accidental use of \*Micont\fR in place of
147: \*Mpicont\fR may produce mysterious results.)
148: In turn, \*Mpicont\fR translates a source program using
149: \*Mpitran\fR and links it using \*Mpilink\fR.
150: The resulting icode file uses \*Mpiconx\fR.
151: .PP
152: The relocation bits and symbol tables in
153: \*Mpiconx\fR can be removed by
154: .Ds
155: make Stripx
156: .De
157: in \*Mmyicon/pi\fR. This reduces the size of this file substantially
158: but may interfere with debugging.
159: .PP
160: If a \fImake\fR is performed in \*Mmyicon/pi\fR before any
161: run-time files are added or modified, the resulting personalized
162: interpreter is identical to the standard one. Such a \fImake\fR can
163: be performed to verify that the personalized interpreter system
164: is performing properly.
165: .NH 2
166: Adding a New Function
167: .PP
168: To add a new function to the personalized interpreter, it is first
169: necessary to provide the C code, adhering to the conventions and
170: data structures used throughout Icon. Some examples of
171: C functions are included in Appendix B
172: of this report. The source code for several such functions is contained in
173: \*Mv6/pi/pil\fR, where \*Mv6\fR is the root of the Icon system.
174: The directory
175: \*Mv6/src/iconx\fR contains the source code for the standard
176: functions, which also can be used as models for new ones.
177: .PP
178: Suppose that \*Mgetenv\fR from \*Mv6/pi/pil\fR is to be
179: added to a personalized interpreter.
180: The source code can be obtained by
181: .Ds
182: cp v6/pi/pil/getenv.c myicon/pi
183: .De
184: (Note that the actual paths depend on the
185: local hierarchy.)
186: .PP
187: Three things now need to be done to
188: incorporate this function in the personalized interpreter:
189: .IP 1.
190: Add a line consisting of
191: .Ds
192: FncDef(getenv)
193: .De
194: to \*Mmyicon/h/fdef.h\fR in proper alphabetical order.
195: This causes the linker and the run-time system to know about the new function.
196: .IP 2.
197: Add \*Mgetenv.o\fR to the definition of \*MOBJS\fR in
198: \*Mmyicon/pi/Makefile\fR.
199: This causes \*Mgetenv.c\fR to be compiled and the resulting
200: object file to be loaded with the run-time system when a \fImake\fR is performed.
201: .IP 3.
202: Perform a \fImake\fR in \*Mmyicon/pi\fR. The result is
203: new versions of \*Mpilink\fR and \*Mpiconx\fR in \*Mmyicon\fR.
204: .LP
205: The function \*Mgetenv\fR now can be used like any other built-in
206: function.
207: .PP
208: More than one function can be included in a single source file.
209: See \*Mmath.c\fR in Appendix B.
210: To incorporate these functions in
211: a personalized interpreter, \*MFncDef\fR entries should be
212: made for each function in \*Mmath.c\fR and \*Mmath.o\fR should be added to
213: \*MOBJS\fR.
214: .NH 2
215: Modifying the Existing Run-Time System
216: .PP
217: The use of personalized interpreters is not limited to the addition
218: of new functions. Any module in the standard run-time system can
219: be modified as well.
220: .PP
221: To modify an existing portion of the Icon run-time system,
222: copy the source code file from \*Mv6/src/iconx\fR to \*Mmyicon/pi\fR.
223: (Source code for a few run-time routines is placed in \*Mmyicon/std\fR
224: when a personalized interpreter is set up. Check this directory
225: first and use that file, if appropriate, rather than making
226: another copy in \*Mmyicon/pi\fR.) When a source-code file in
227: \*Mmyicon/pi\fR has been modified, place it in the \*MOBJS\fR
228: list just like a new file and perform a \fImake\fR. Note that
229: an entire module must be replaced, even if a change is made to
230: only one routine.
231: Any module that is replaced must contain all the global variables in
232: the original module to prevent \fIld(1)\fR from also loading the
233: original module. There is no way to delete routines from the run-time
234: system.
235: .PP
236: The directory \*Mmyicon/h\fR contains header files that are included
237: in various source-code files.
238: The file \*Mmyicon/h/rt.h\fR contains declarations and definitions that
239: are used throughout the run-time system. This is where the declaration
240: for the structure of a new type of data object would be placed.
241: .PP
242: Care
243: must be taken when modifying header files not to make changes that
244: would produce inconsistencies between previously compiled components
245: of the Icon run-time system and new ones.
246: .SH
247: Reference
248: .IP 1.
249: Griswold, Ralph E. and Griswold, Madge T. \fIThe Icon Programming
250: Language\fR. Prentice-Hall, Inc., Englewood Cliffs, New Jersey. 1983.
251: .am Ds
252: .ps 8
253: .vs 9
254: ..
255: .am De
256: .ps 10
257: .vs 12
258: ..
259: .de Ta
260: .ta .8i +.8i +.8i +.8i +.8i +.8i +.8i +.8i
261: ..
262: .Ap "Appendix A \(em Makefile for Personalized Interpreters"
263: .sp
264: .PP
265: The ``generic'' \*MMakefile\fR for personalized interpreters follows.
266: A copy, with the
267: value of \*MDir\fR filled in and appropriate definitions for the flags,
268: is placed in \*Mmyicon/pi\fR when \*Micon_pi\fR is run.
269: .Ds
270: Dir=
271: .Dd
272: RHDRS= ../h/rt.h ../h/config.h ../h/cpuconf.h ../h/memsize.h
273: #
274: # To add or replace object files, add their names to the OBJS list below.
275: # For example, to add nfncs.o and iolib.o, use:
276: #
277: # OBJS=nfncs.o iolib.o (this is a sample line)
278: #
279: # For each object file added to OBJS, add a dependency line to reflect files
280: # that are depended on. In general, new functions depend on $(RHDRS).
281: # For example, if nfncs.c contains new functions, use
282: #
283: # nfncs.o: $(RHDRS)
284: #
285: .Dd
286: OBJS=
287: LIB=
288: .Dd
289: RTOBJS=../std/rconv.o ../std/idata.o $(OBJS)
290: .Dd
291: Pi: ../picont ../piconx ../pilink ../piconx.hdr
292: .Dd
293: \&../picont: ../std/icont.c ../h/config.h
294: rm -f ../picont picont
295: $(CC) $(CFLAGS) -o ../picont -DItran="\e"$(Dir)/pitran\e""\e
296: -DIconx="\e"$(Dir)/piconx\e"" \e
297: -DIlink="\e"$(Dir)/pilink\e"" ../std/icont.c
298: strip ../picont
299: ln ../picont picont
300: .Dd
301: \&../pilink: ../std/linklib ../std/builtin.o ../std/ilink.o
302: $(CC) $(LDFLAGS) -o ../pilink ../std/builtin.o ../std/ilink.o\e
303: ../std/linklib
304: strip ../pilink
305: .Dd
306: \&../std/ixhdr.o: ../h/config.h
307: cd ../std; $(CC) -c $(XCFLAGS) -DIconx="\e"$(Dir)/piconx\e"" ixhdr.c
308: .Dd
309: \&../piconx.hdr: ../std/ixhdr.o
310: $(CC) $(XLDFLAGS) ../std/ixhdr.o -o ../piconx.hdr
311: strip ../piconx.hdr
312: .Dd
313: \&../piconx: ../std/rtlib $(RTOBJS)
314: $(CC) $(LDFLAGS) -o ../piconx $(RTOBJS) ../std/rtlib $(LIB) -lm
315:
316: \&../std/idata.o: $(RHDRS) ../h/fdef.h
317: cd ../std; $(CC) -c $(CFLAGS) idata.c
318: .Dd
319: \&../std/rconv.o: $(RHDRS) ../h/fdef.h
320: cd ../std; $(CC) -c $(CFLAGS) rconv.c
321: .Dd
322: \&../std/builtin.o: ../std/ilink.h ../h/config.h ../h/fdef.h
323: cd ../std; $(CC) -c $(CFLAGS) builtin.c
324: .Dd
325: \&../std/ilink.o: ../std/ilink.h ../h/config.h ../h/header.h ../h/paths.h
326: cd ../std; $(CC) -c $(CFLAGS) -DHeader="\e"$(Dir)/piconx.hdr\e"" ilink.c
327: .Dd
328: Stripx: ../piconx
329: strip ../piconx
330: .De
331: .Ap "Appendix B \(em Sample C Functions"
332: .sp
333: .SH
334: getenv.c:
335: .LP
336: .de Ta
337: .ta 3i
338: ..
339: .Ds
340: .ta .8i
341: /*
342: * GETENV
343: *
344: * Get values of environment variables.
345: *
346: * Stephen B. Wampler
347: *
348: * Last modified 5/2/86 by Ralph E. Griswold
349: *
350: */
351: .Dd
352: #include "../h/rt.h"
353: .Dd
354: /*
355: * getenv(s) - return contents of environment variable s
356: */
357: .Dd
358: FncDcl(getenv,\*b1)
359: {
360: register char *p;
361: register int len;
362: char sbuf\^[256];
363: extern char *getenv();
364: extern char *alcstr();
365: .Dd
366: if (!Qual(arg1)) /* check legality of argument */
367: runerr(103, &arg1);
368: if (StrLen(arg1) \*(<= 0 || StrLen(arg1) \*(>= MaxCvtLen)
369: runerr(401, &arg1);
370: qtos(&arg1, sbuf); /* convert argument to C-style string */
371: .Dd
372: if ((p = getenv(sbuf)) != NULL) { /* get environment variable */
373: len = strlen(p);
374: strreq(len);
375: StrLen(arg0) = len;
376: StrLoc(arg0) = alcstr(p, len);
377: Return;
378: }
379: else /* fail if variable not in environment */
380: Fail;
381: }
382: .De
383: .bp
384: .SH
385: math.c:
386: .LP
387: .Ds
388: .ta .8i
389: /*
390: * MATH
391: *
392: * Miscellaneous math functions.
393: *
394: * Ralph E. Griswold
395: *
396: * Last modified 5/2/86
397: *
398: */
399: .Dd
400: #include "../h/rt.h"
401: #include <errno.h>
402: .Dd
403: int errno;
404: /*
405: * exp(x)
406: */
407: FncDcl(exp,\*b1)
408: {
409: int t;
410: double y;
411: union numeric r;
412: double exp();
413:
414: if ((t = cvreal(&arg1, &r)) == NULL) runerr(102, &arg1);
415: y = exp(r.real);
416: if (errno == ERANGE) runerr(252, NULL);
417: mkreal(y,\*b&arg0);
418: Return;
419: }
420: .Dd
421: /*
422: * log(x)
423: */
424: FncDcl(log,\*b1)
425: {
426: int t;
427: double y;
428: union numeric r;
429: double log();
430:
431: if ((t = cvreal(&arg1, &r)) == NULL) runerr(102, &arg1);
432: y = log(r.real);
433: if (errno == EDOM) runerr(251, NULL);
434: mkreal(y,\*b&arg0);
435: Return;
436: }
437: .Dd
438: /*
439: * log10(x)
440: */
441: FncDcl(log10,\*b1)
442: {
443: int t;
444: double y;
445: union numeric r;
446: double log10();
447:
448: if ((t = cvreal(&arg1, &r)) == NULL) runerr(102, &arg1);
449: y = log10(r.real);
450: if (errno == EDOM) runerr(251, NULL);
451: mkreal(y,\*b&arg0);
452: Return;
453: }
454: .Dd
455: /*
456: * sqrt(x)
457: */
458: FncDcl(sqrt,\*b1)
459: {
460: int t;
461: double y;
462: union numeric r;
463: double sqrt();
464:
465: if ((t = cvreal(&arg1, &r)) == NULL) runerr(102, &arg1);
466: y = sqrt(r.real);
467: if (errno == EDOM) runerr(251, NULL);
468: mkreal(y,\*b&arg0);
469: Return;
470: }
471: .De
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.