path: root/static/unix-v10/man1/icon_pi.1

.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.