ICON_PI(1)

NAME
icon_pi - construct personalized interpreter for Icon

SYNOPSIS
icon_pi

DESCRIPTION
A personalized interpreter is a version of Icon in which the run-time system can be easily augmented and modified by the user.

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 myicon. The set-up process consists of mkdir myicon cd myicon icon_pi Note that icon_pi must be run in the area in which the personalized interpreter is to be built.

The shell script icon_pi constructs three subdirectories: h, std, and pi. The subdirectory h contains header files that are needed in C routines. The subdirectory std contains the portions of the Icon system that are needed to build a personalized interpreter. The subdirectory pi contains a Makefile for building a personalized interpreter and also is the place where source code for new C functions normally resides.

The Makefile that is constructed by icon_pi contains two definitions to facilitate building personalized interpreters:

OBJS
    a list of object modules that are to be added to or replaced in the run-time system. OBJS initially is empty.

LIB a list of library options that are used when the run-time system is built. LIB initially is empty.

Performing a make in myicon/pi creates four additional files in myicon:
picont    command processor
pilink    linker
piconx    run-time system
piconx.hdr    header for linker output
A link to picont also is constructed in myicon/pi so that the new personalized interpreter can be tested in the directory in which it is made.

The file picont normally is built only on the first make. The file pilink is built on the first make and is rebuilt whenever the repertoire of built-in functions is changed. The file piconx is rebuilt whenever the source code in the run-time system is changed.

The user of the personalized interpreter uses picont in the same fashion that the standard icont; see icont(1). (Note that the accidental use of icont in place of picont may produce mysterious results.) In turn, picont translates a source program using the standard Icon translator and links it using pilink. The resulting icode file uses piconx. Note that the location of piconx is built into the icode file.

The relocation bits and symbol tables in piconx can be removed by make Stripx in myicon/pi. This reduces the size of this file substantially but makes the use of debuggers impractical.

If a make is performed in myicon/pi before any run-time files are added or modified, the resulting personalized interpreter is identical to the standard one. Such a make can be performed to verify that the personalized interpreter system is performing properly.

Note that a personalized interpreter inherits the parameters and configuration of the locally installed version of Icon in v6, including optional language extensions. The file myicon/h/config.h contains configuration information. The definitions in this file should not be changed.

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 v6/pi/pil, where v6 is the root of the source hierarchy for the Icon system. The directory v6/src/iconx contains the source code for the standard built-in functions, which also can be used as models for new ones.

Suppose that getenv from v6/pi/pil is to be added to a personalized interpreter. The source code can be obtained by cp v6/pi/pil/getenv.c myicon/pi (Note that the actual paths depend on the local hierarchy.)

Four things now need to be done to incorporate this function in the personalized interpreter:

1.  Add a line consisting of FncDef(getenv) to myicon/h/fdef.h in proper alphabetical order. This causes the linker and the run-time system to know about the new function.

2.  Add getenv.o to the definition of OBJS in myicon/pi/Makefile. This causes getenv.c to be compiled and the resulting object file to be loaded with the run-time system when a make is performed.

3.  Add a dependency line in myicon/pi/Makefile for getenv.o to reflect the file that it includes, namely getenv.o: ../h/rt.h

4.  Perform a make in myicon/pi. This produces new versions of pilink and piconx in myicon.

The function getenv now can be used like any other built-in function.

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 LIB in the Makefile.

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 myicon/pi. (Source code for a few run-time routines is placed in myicon/std when a personalized interpreter is set up. Check this directory first and use that file, if appropriate, rather than making another copy in myicon/pi.) When a source-code file in myicon/pi has been modified, place it in the OBJS list just like a new file and perform a make. 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 ld(1) from also loading the original module. There is no way to delete routines from the run-time system.

The directory myicon/h contains header files that are included in various source-code files. The file myicon/h/rt.h 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.

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.

FILES
v6/pi	code for building personalized interpreters
v6/src/iconx	run-time system

SEE ALSO
icont(1)

Personalized Interpreters for Version 6.0 of Icon, Ralph E. Griswold, TR 86-12, Department of Computer Science, The University of Arizona, May 1986.

The Icon Programming Language, Ralph E. Griswold and Madge T. Griswold, Prentice-Hall Inc., Englewood Cliffs, New Jersey, 1983.

Version 6.0 of Icon, Ralph E. Griswold, William H. Mitchell, and Janalee O'Bagy, TR 86-10, Department of Computer Science, The University of Arizona, May 1986.