Return to icon-pi.1 CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / icon / docs

Annotation of 43BSD/contrib/icon/docs/icon-pi.1, revision 1.1

1.1     ! root        1: .ds M \fB
        !             2: .if t .if !\nd .ds M \fM
        !             3: .de Ds
        !             4: .nf
        !             5: .sp
        !             6: .in +.5i
        !             7: \\*M\c
        !             8: ..
        !             9: .de De
        !            10: .sp
        !            11: .in
        !            12: .ft R
        !            13: .fi
        !            14: ..
        !            15: .if t .if !\nd .ds M \fM
        !            16: .TH ICON\-PI 1 "The University of Arizona \- 8/21/84"
        !            17: .SH NAME
        !            18: icon\-pi \- construct personalized interpreter for Icon
        !            19: .SH SYNOPSIS
        !            20: \f3icon\-pi\fR
        !            21: .SH DESCRIPTION
        !            22: A personalized interpreter is
        !            23: a version of Icon in which the run-time system can be easily
        !            24: augmented and modified by the user.
        !            25: .PP
        !            26: To set up a personalized interpreter, a new directory should
        !            27: be created solely for the use of the interpreter; otherwise
        !            28: files may be accidentally destroyed by the set-up process.
        !            29: For the purpose of example, suppose this directory is
        !            30: named \*Mmyicon\fR. The set-up process consists of
        !            31: .Ds
        !            32: mkdir myicon
        !            33: cd myicon
        !            34: icon\-pi
        !            35: .De
        !            36: Note that \*Micon\-pi\fR must be run in the area in which the personalized
        !            37: interpreter is to be built.
        !            38: .PP
        !            39: The shell script \*Micon\-pi\fR constructs three subdirectories:
        !            40: \*Mh\fR, \*Mstd\fR, and \*Mpi\fR. The subdirectory \*Mh\fR
        !            41: contains header files that are needed in C routines. The subdirectory
        !            42: \*Mstd\fR contains the portions of the Icon system that are needed
        !            43: to build a personalized interpreter. The subdirectory \*Mpi\fR
        !            44: contains a \*MMakefile\fR for building a personalized interpreter
        !            45: and also is the place where source code for new C functions normally
        !            46: resides.
        !            47: .PP
        !            48: The \*MMakefile\fR that is constructed by \*Micon\-pi\fR
        !            49: contains two definitions to facilitate building personalized
        !            50: interpreters:
        !            51: .IP \*MOBJS\fR .5i
        !            52: a list of object modules that are to be added to or replaced
        !            53: in the run-time system. \*MOBJS\fR initially is empty.
        !            54: .IP \*MLIB\fR
        !            55: a list of library options that are used when the run-time system
        !            56: is built. \*MLIB\fR initially is empty.
        !            57: .PP
        !            58: Performing a \fImake\fR in \*Mmyicon/pi\fR creates three files
        !            59: in \*Mmyicon\fR:
        !            60: .Ds
        !            61: .ta 1i
        !            62: picont \fRcommand processor\*M
        !            63: pilink \fRlinker\*M
        !            64: piconx \fRrun-time system\*M
        !            65: .De
        !            66: A link to \*Mpicont\fR also is constructed in \*Mmyicon/pi\fR so that
        !            67: the new personalized interpreter can be tested in the directory in
        !            68: which it is made.
        !            69: .PP
        !            70: The file \*Mpicont\fR normally is built only on the first \fImake\fR. The
        !            71: file \*Mpilink\fR is built on the first \fImake\fR and is
        !            72: rebuilt whenever the repertoire of built-in functions is changed.
        !            73: The file \*Mpiconx\fR is rebuilt whenever the source code in the
        !            74: run-time system is changed.
        !            75: .PP
        !            76: The user of the personalized interpreter uses \*Mpicont\fR in
        !            77: the same fashion that the standard \*Micont\fR (see \fIicont(1)\fR).
        !            78: (Note that the accidental use of \*Micont\fR in place of
        !            79: \*Mpicont\fR may produce mysterious results.)
        !            80: In turn, \*Mpicont\fR translates a source program using the
        !            81: standard Icon translator and links it using \*Mpilink\fR.
        !            82: The resulting icode file uses \*Mpiconx\fR.
        !            83: Note that the location of \*Mpiconx\fR is built into the icode file.
        !            84: .PP
        !            85: The relocation bits and symbol tables in \*Mpicont\fR, \*Mpilink\fR,
        !            86: and \*Mpiconx\fR can be removed by
        !            87: .Ds
        !            88: make Strip
        !            89: .De
        !            90: in \*Mmyicon/pi\fR. This reduces the sizes of these files substantially
        !            91: but makes the use of debuggers impractical.
        !            92: .PP
        !            93: If a \fImake\fR is performed in \*Mmyicon/pi\fR before any
        !            94: run-time files are added or modified, the resulting personalized
        !            95: interpreter is identical to the standard one. Such a \fImake\fR can
        !            96: be performed to verify that the personalized interpreter system
        !            97: is performing properly.
        !            98: .PP
        !            99: Note that a personalized interpreter inherits the parameters and
        !           100: configuration of the locally installed version of Icon in \*Mv5g\fR, including
        !           101: optional language extensions.
        !           102: The file \*Mmyicon/h/config.h\fR contains configuration information.
        !           103: The definitions in this file should not be changed.
        !           104: .PP
        !           105: To add a new function to the personalized interpreter, it is first
        !           106: necessary to provide the C code, adhering to the conventions and
        !           107: data structures used throughout Icon.
        !           108: Some useful functions from the Icon program library are
        !           109: contained in \*Mv5g/pifuncs\fR, where \*Mv5g\fR is the root
        !           110: of the source hierarchy for the Icon system.
        !           111: The directory
        !           112: \*Mv5g/functions\fR contains the source code for the standard built-in
        !           113: functions, which also can be used as models for new ones.
        !           114: .PP
        !           115: Suppose that \*Mgetenv\fR from the Icon program library is to be
        !           116: added to a personalized interpreter. The source code can be obtained by
        !           117: .Ds
        !           118: cp v5g/pifuncs/getenv.c myicon/pi
        !           119: .De
        !           120: (Note that the actual paths will be different, depending on the
        !           121: local hierarchy.)
        !           122: .PP
        !           123: Four things now need to be done to
        !           124: incorporate this function in the personalized interpreter:
        !           125: .IP 1. 5n
        !           126: Add a line consisting of
        !           127: .Ds
        !           128: PDEF(getenv)
        !           129: .De
        !           130: to \*Mmyicon/h/pdef.h\fR in proper alphabetical order.
        !           131: This causes the linker and the run-time system to know about the new function.
        !           132: .IP 2.
        !           133: Add \*Mgetenv.o\fR to the definition of \*MOBJS\fR in
        !           134: \*Mmyicon/pi/Makefile\fR.
        !           135: This causes \*Mgetenv.c\fR to be compiled and the resulting
        !           136: object file to be loaded with the run-time system when a \fImake\fR is performed.
        !           137: .IP 3.
        !           138: Add a dependency line in \*Mmyicon/pi/Makefile\fR for \*Mgetenv.o\fR
        !           139: to reflect the file that it includes, namely
        !           140: .Ds
        !           141: getenv.o:   ../h/rt/h
        !           142: .De
        !           143: .IP 4.
        !           144: Perform a \fImake\fR in \*Mmyicon/pi\fR. The result is
        !           145: new versions of \*Mpilink\fR and \*Mpiconx\fR in \*Mmyicon\fR.
        !           146: .LP
        !           147: The function \*Mgetenv\fR now can be used like any other built-in
        !           148: function.
        !           149: .PP
        !           150: More than one function can be included in a single source file.
        !           151: If a function requires a library to be loaded, that library should
        !           152: be added to the definition of \*MLIB\fR in the \*MMakefile\fR.
        !           153: .PP
        !           154: The use of personalized interpreters is not limited to the addition
        !           155: of new functions. Any module in the standard run-time system can
        !           156: be modified as well.
        !           157: To modify an existing portion of the Icon run-time system,
        !           158: copy the source code file from the standard system to \*Mmyicon/pi\fR.
        !           159: (Source code for a few run-time routines is placed in \*Mmyicon/std\fR
        !           160: when a personalized interpreter is set up. Check this directory
        !           161: first and use that file, if appropriate, rather than making
        !           162: another copy in \*Mmyicon/pi\fR.) When a source-code file in
        !           163: \*Mmyicon/pi\fR has been modified, place it in the \*MOBJS\fR
        !           164: list just like a new file and perform a \fImake\fR. Note that
        !           165: an entire module must be replaced, even if a change is made to
        !           166: only one routine.
        !           167: Any module that is replaced must contain all the global variables in
        !           168: the original module to prevent \fIld(1)\fR from also loading the
        !           169: original module. There is no way to delete routines from the run-time
        !           170: system.
        !           171: .PP
        !           172: The directory \*Mmyicon/h\fR contains header files that are included
        !           173: in various source-code files. For example, error message text for
        !           174: a new run-time error can be provided by adding it to \*Mmyicon/h/err.h\fR.
        !           175: The file \*Mmyicon/h/rt.h\fR contains declarations and definitions that
        !           176: are used throughout the run-time system. This is where the declaration
        !           177: for the structure of a new type of data object would be placed.
        !           178: .PP
        !           179: Care
        !           180: must be taken when modifying header files not to make changes that
        !           181: would produce inconsistencies between previously compiled components
        !           182: of the Icon run-time system and new ones.
        !           183: .SH FILES
        !           184: .ta \w'\*Mv5g/operators\fR   'u
        !           185: .nf
        !           186: \*Mv5g/pilib\fR        code for building personalized interpreters
        !           187: \*Mv5g/pifuncs\fR      functions from the Icon program library
        !           188: \*Mv5g/functions\fR    built-in functions
        !           189: \*Mv5g/operators\fR    built-in operators
        !           190: \*Mv5g/rt\fR   run-time support routines
        !           191: \*Mv5g/lib\fR  routines called by the interpreter
        !           192: \*Mv5g/iconx\fR        the interpreter and start-up routines
        !           193: .fi
        !           194: .SH SEE ALSO
        !           195: .I
        !           196: The Icon Programming Language\fR,
        !           197: Ralph E. Griswold and Madge T. Griswold,
        !           198: Prentice-Hall Inc.,
        !           199: Englewood Cliffs, New Jersey,
        !           200: 1983.
        !           201: .LP
        !           202: \fIVersion 5.9 of Icon\fR, Ralph E. Griswold, Robert K. McConeghy, and William H. Mitchell,
        !           203: Department of Computer Science, The University of Arizona,
        !           204: August 1984.
        !           205: .LP
        !           206: \fIInstallation and Maintenance Guide for Version 5.9 of Icon\fR,
        !           207: Ralph E. Griswold and William H. Mitchell,
        !           208: Department of Computer Science, The University of Arizona,
        !           209: August 1984.
        !           210: .LP
        !           211: \fIA Tour Through the C Implementation of Icon; Version 5.9\fR,
        !           212: Ralph E. Griswold, Robert K. McConeghy, and William H. Mitchell,
        !           213: Department of Computer Science,
        !           214: The University of Arizona, August 1984.
        !           215: .LP
        !           216: \fIThe Icon Program Library\fR, Ralph E. Griswold,
        !           217: Department of Computer Science, The University of
        !           218: Arizona, August 1984.
        !           219: .LP
        !           220: icont(1)

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.