4.3BSD/usr/contrib/icon/docs/icon-pi.1

Compare this file to the similar file:
Show the results in this format: 

.ds M \fB
.if t .if !\nd .ds M \fM
.de Ds
.nf
.sp
.in +.5i
\\*M\c
..
.de De
.sp
.in
.ft R
.fi
..
.if t .if !\nd .ds M \fM
.TH ICON\-PI 1 "The University of Arizona \- 8/21/84"
.SH NAME
icon\-pi \- construct personalized interpreter for Icon
.SH SYNOPSIS
\f3icon\-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 three files
in \*Mmyicon\fR:
.Ds
.ta 1i
picont	\fRcommand processor\*M
pilink	\fRlinker\*M
piconx	\fRrun-time system\*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 \*Mpicont\fR, \*Mpilink\fR,
and \*Mpiconx\fR can be removed by
.Ds
make Strip
.De
in \*Mmyicon/pi\fR. This reduces the sizes of these files 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 \*Mv5g\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 from the Icon program library are
contained in \*Mv5g/pifuncs\fR, where \*Mv5g\fR is the root
of the source hierarchy for the Icon system.
The directory
\*Mv5g/functions\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 the Icon program library is to be
added to a personalized interpreter. The source code can be obtained by
.Ds
cp v5g/pifuncs/getenv.c myicon/pi
.De
(Note that the actual paths will be different, depending 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
PDEF(getenv)
.De
to \*Mmyicon/h/pdef.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. The result is
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. For example, error message text for
a new run-time error can be provided by adding it to \*Mmyicon/h/err.h\fR.
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 \w'\*Mv5g/operators\fR   'u
.nf
\*Mv5g/pilib\fR	code for building personalized interpreters
\*Mv5g/pifuncs\fR	functions from the Icon program library
\*Mv5g/functions\fR	built-in functions
\*Mv5g/operators\fR	built-in operators
\*Mv5g/rt\fR	run-time support routines
\*Mv5g/lib\fR	routines called by the interpreter
\*Mv5g/iconx\fR	the interpreter and start-up routines
.fi
.SH SEE ALSO
.I
The Icon Programming Language\fR,
Ralph E. Griswold and Madge T. Griswold,
Prentice-Hall Inc.,
Englewood Cliffs, New Jersey,
1983.
.LP
\fIVersion 5.9 of Icon\fR, Ralph E. Griswold, Robert K. McConeghy, and William H. Mitchell,
Department of Computer Science, The University of Arizona,
August 1984.
.LP
\fIInstallation and Maintenance Guide for Version 5.9 of Icon\fR,
Ralph E. Griswold and William H. Mitchell,
Department of Computer Science, The University of Arizona,
August 1984.
.LP
\fIA Tour Through the C Implementation of Icon; Version 5.9\fR,
Ralph E. Griswold, Robert K. McConeghy, and William H. Mitchell,
Department of Computer Science,
The University of Arizona, August 1984.
.LP
\fIThe Icon Program Library\fR, Ralph E. Griswold,
Department of Computer Science, The University of
Arizona, August 1984.
.LP
icont(1)