diff options
Diffstat (limited to 'static/v10/man1/icon_pi.1')
| -rw-r--r-- | static/v10/man1/icon_pi.1 | 205 |
1 files changed, 205 insertions, 0 deletions
diff --git a/static/v10/man1/icon_pi.1 b/static/v10/man1/icon_pi.1 new file mode 100644 index 00000000..2fc07e27 --- /dev/null +++ b/static/v10/man1/icon_pi.1 @@ -0,0 +1,205 @@ +.ds M \fH +.de Ds +.nf +.in +.5i +.ft H +.sp .5 +.. +.de De +.ft R +.in -.5i +.fi +.sp .5 +.. +.TH ICON_PI 1 "The University of Arizona \- 5/6/86" +.SH NAME +icon_pi \- construct personalized interpreter for Icon +.SH SYNOPSIS +\*Micon_pi\fR +.SH DESCRIPTION +A personalized interpreter is +a version of Icon in which the run-time system can be easily +augmented and modified by the user. +.PP +To set up a personalized interpreter, a new directory should +be created solely for the use of the interpreter; otherwise +files may be accidentally destroyed by the set-up process. +For the purpose of example, suppose this directory is +named \*Mmyicon\fR. The set-up process consists of +.Ds +mkdir myicon +cd myicon +icon_pi +.De +Note that \*Micon_pi\fR must be run in the area in which the personalized +interpreter is to be built. +.PP +The shell script \*Micon_pi\fR constructs three subdirectories: +\*Mh\fR, \*Mstd\fR, and \*Mpi\fR. The subdirectory \*Mh\fR +contains header files that are needed in C routines. The subdirectory +\*Mstd\fR contains the portions of the Icon system that are needed +to build a personalized interpreter. The subdirectory \*Mpi\fR +contains a \*MMakefile\fR for building a personalized interpreter +and also is the place where source code for new C functions normally +resides. +.PP +The \*MMakefile\fR that is constructed by \*Micon_pi\fR +contains two definitions to facilitate building personalized +interpreters: +.IP \*MOBJS\fR .5i +a list of object modules that are to be added to or replaced +in the run-time system. \*MOBJS\fR initially is empty. +.IP \*MLIB\fR +a list of library options that are used when the run-time system +is built. \*MLIB\fR initially is empty. +.PP +Performing a \fImake\fR in \*Mmyicon/pi\fR creates four additional files +in \*Mmyicon\fR: +.Ds +.ta 1i +picont \fRcommand processor\*M +pilink \fRlinker\*M +piconx \fRrun-time system\*M +piconx.hdr \fRheader for linker output\*M +.De +A link to \*Mpicont\fR also is constructed in \*Mmyicon/pi\fR so that +the new personalized interpreter can be tested in the directory in +which it is made. +.PP +The file \*Mpicont\fR normally is built only on the first \fImake\fR. The +file \*Mpilink\fR is built on the first \fImake\fR and is +rebuilt whenever the repertoire of built-in functions is changed. +The file \*Mpiconx\fR is rebuilt whenever the source code in the +run-time system is changed. +.PP +The user of the personalized interpreter uses \*Mpicont\fR in +the same fashion that the standard \*Micont\fR; see \fIicont(1)\fR. +(Note that the accidental use of \*Micont\fR in place of +\*Mpicont\fR may produce mysterious results.) +In turn, \*Mpicont\fR translates a source program using the +standard Icon translator and links it using \*Mpilink\fR. +The resulting icode file uses \*Mpiconx\fR. +Note that the location of \*Mpiconx\fR is built into the icode file. +.PP +The relocation bits and symbol tables in +\*Mpiconx\fR can be removed by +.Ds +make Stripx +.De +in \*Mmyicon/pi\fR. This reduces the size of this file substantially +but makes the use of debuggers impractical. +.PP +If a \fImake\fR is performed in \*Mmyicon/pi\fR before any +run-time files are added or modified, the resulting personalized +interpreter is identical to the standard one. Such a \fImake\fR can +be performed to verify that the personalized interpreter system +is performing properly. +.PP +Note that a personalized interpreter inherits the parameters and +configuration of the locally installed version of Icon in \*Mv6\fR, including +optional language extensions. +The file \*Mmyicon/h/config.h\fR contains configuration information. +The definitions in this file should not be changed. +.PP +To add a new function to the personalized interpreter, it is first +necessary to provide the C code, adhering to the conventions and +data structures used throughout Icon. +Some useful functions are +contained in \*Mv6/pi/pil\fR, where \*Mv6\fR is the root +of the source hierarchy for the Icon system. +The directory +\*Mv6/src/iconx\fR contains the source code for the standard built-in +functions, which also can be used as models for new ones. +.PP +Suppose that \*Mgetenv\fR from \*Mv6/pi/pil\fR is to be +added to a personalized interpreter. The source code can be obtained by +.Ds +cp v6/pi/pil/getenv.c myicon/pi +.De +(Note that the actual paths depend on the +local hierarchy.) +.PP +Four things now need to be done to +incorporate this function in the personalized interpreter: +.IP 1. 5n +Add a line consisting of +.Ds +FncDef(getenv) +.De +to \*Mmyicon/h/fdef.h\fR in proper alphabetical order. +This causes the linker and the run-time system to know about the new function. +.IP 2. +Add \*Mgetenv.o\fR to the definition of \*MOBJS\fR in +\*Mmyicon/pi/Makefile\fR. +This causes \*Mgetenv.c\fR to be compiled and the resulting +object file to be loaded with the run-time system when a \fImake\fR is performed. +.IP 3. +Add a dependency line in \*Mmyicon/pi/Makefile\fR for \*Mgetenv.o\fR +to reflect the file that it includes, namely +.Ds +getenv.o: ../h/rt.h +.De +.IP 4. +Perform a \fImake\fR in \*Mmyicon/pi\fR. +This produces +new versions of \*Mpilink\fR and \*Mpiconx\fR in \*Mmyicon\fR. +.LP +The function \*Mgetenv\fR now can be used like any other built-in +function. +.PP +More than one function can be included in a single source file. +If a function requires a library to be loaded, that library should +be added to the definition of \*MLIB\fR in the \*MMakefile\fR. +.PP +The use of personalized interpreters is not limited to the addition +of new functions. Any module in the standard run-time system can +be modified as well. +To modify an existing portion of the Icon run-time system, +copy the source code file from the standard system to \*Mmyicon/pi\fR. +(Source code for a few run-time routines is placed in \*Mmyicon/std\fR +when a personalized interpreter is set up. Check this directory +first and use that file, if appropriate, rather than making +another copy in \*Mmyicon/pi\fR.) When a source-code file in +\*Mmyicon/pi\fR has been modified, place it in the \*MOBJS\fR +list just like a new file and perform a \fImake\fR. Note that +an entire module must be replaced, even if a change is made to +only one routine. +Any module that is replaced must contain all the global variables in +the original module to prevent \fIld(1)\fR from also loading the +original module. There is no way to delete routines from the run-time +system. +.PP +The directory \*Mmyicon/h\fR contains header files that are included +in various source-code files. +The file \*Mmyicon/h/rt.h\fR contains declarations and definitions that +are used throughout the run-time system. This is where the declaration +for the structure of a new type of data object would be placed. +.PP +Care +must be taken when modifying header files not to make changes that +would produce inconsistencies between previously compiled components +of the Icon run-time system and new ones. +.SH FILES +.ta 1i +.nf +\*Mv6/pi\fR code for building personalized interpreters +\*Mv6/src/iconx\fR run-time system +.fi +.SH SEE ALSO +icont(1) +.LP +\fIPersonalized Interpreters for Version 6.0 of Icon\fR, Ralph E. +Griswold, TR 86-12, Department of Computer Science, The University +of Arizona, May 1986. +.LP +\fIThe Icon Programming Language\fR, +Ralph E. Griswold and Madge T. Griswold, +Prentice-Hall Inc., +Englewood Cliffs, New Jersey, +1983. +.LP +\fIVersion 6.0 of Icon\fR, Ralph E. Griswold, William H. Mitchell, and +Janalee O'Bagy, +TR 86-10, +Department of Computer Science, The University of Arizona, +May 1986. |