Return to porting CVS log

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

Annotation of 43BSD/contrib/icon/docs/porting, revision 1.1

1.1     ! root        1: .so tmac.tr
        !             2: .sv |1.25i
        !             3: .LP
        !             4: .ce 10
        !             5: \f3An Overview of the Porting Process for Version 5.9 of Icon\fR
        !             6: .sp 2
        !             7: Ralph E. Griswold
        !             8: .sp 1
        !             9: October 12, 1984
        !            10: .ce 0
        !            11: .sp 2
        !            12: .NH
        !            13: Introduction
        !            14: .PP
        !            15: The process of porting Version 5.9 of Icon to a new computer
        !            16: is described in detail in [1].
        !            17: This document is a companion to [1] an provides details of
        !            18: testing to be carried out during the porting process.
        !            19: .PP
        !            20: Porting Icon starts out in the same way as installing an existing
        !            21: implementation of Icon [2].
        !            22: At a point in the installation process, the installer becomes a
        !            23: porter and provides the code needed for the new computer. The porter
        !            24: then becomes an installer again and completes the port by completing
        !            25: the installation.
        !            26: .PP
        !            27: To carry out the port, following the instructions in [2] through
        !            28: Section 2.2 (\fIConfiguring the Icon System\fR). In the root directory,
        !            29: referred to as \*Mv5g\fR, configure Icon using
        !            30: .Ds
        !            31: Icon-setup \-port \-host \fIname
        !            32: .De
        !            33: where \fIname\fR is the value to be produced by the Icon keyword
        !            34: \*M&host\fR.
        !            35: .PP
        !            36: Now carry out the porting process as described in [1].
        !            37: When this is complete,
        !            38: .Ds
        !            39: make Clean
        !            40: .De
        !            41: to remove any object files left over from the porting process. Then
        !            42: follow the instructions in [2], starting with Section 2.3
        !            43: (\fICompiling Icon\fR).
        !            44: .NH
        !            45: Test Programs
        !            46: .PP
        !            47: There are three sub-directories in \*Mv5g\fR
        !            48: that contain test programs
        !            49: for use by the porter:
        !            50: .IP \*Mv5g/port\fR 1i
        !            51: This sub-directory contains programs and reference data for step-by-step
        !            52: testing and checking
        !            53: of each component of the port.
        !            54: .IP \*Mv5g/samples\fR
        !            55: This sub-directory contains standard programs that are used to test existing implementations of
        !            56: Icon and which should be run at the completion of a port to be sure
        !            57: that Icon works properly over a range of applications.
        !            58: .IP \*Mv5g/test\fR
        !            59: This sub-directory contains
        !            60: programs and reference data for testing a wide range of Icon features,
        !            61: including boundary conditions and unusual computations.
        !            62: These programs may be useful in final checking of a new implementation
        !            63: and in locating obscure errors.
        !            64: .LP
        !            65: In each of \*Mport\fR, \*Msamples\fR, and \*Mtest\fR, there is a \*MMakefile\fR
        !            66: with a number of entries for performing different tests. In all cases,
        !            67: standard test output is supplied in a sub-directory named \*Mdistr\fR and newly
        !            68: created test output is placed in a sub-directory named \*Mlocal\fR.
        !            69: The standard test output was produced on a VAX-11 running under 4.2bsd
        !            70: \*U.
        !            71: .Un
        !            72: The scripts used by the \*MMakefile\fRs assume that the components
        !            73: of the ported Icon system reside in their standard places in the
        !            74: distribution hierarchy [2]. If this is not the case, the shell scripts
        !            75: will have to be modified.
        !            76: .PP
        !            77: Each test compares the standard output in \*Mdistr\fR to the
        !            78: newly created output in \*Mlocal\fR and reports any differences.
        !            79: Some differences are to be expected, even in a correct port, since
        !            80: output may depend on machine-dependent parameters, the local
        !            81: environment, and so forth. In general, the causes of such irrelevant
        !            82: differences should be obvious.
        !            83: .NH
        !            84: Testing During the Porting Process
        !            85: .PP
        !            86: The porting process consists of building the components of the Icon
        !            87: system one by one. There is a test for each step.
        !            88: Go to the directory \*Mv5g/port\fR for testing during the porting process.
        !            89: .PP
        !            90: Before testing, assign the value \*M1\fR to the environment variable \*MICONCORE\fR.
        !            91: This will cause the Icon interpreter to produce a core dump in case of
        !            92: an error, which may be helpful in debugging.
        !            93: .NH 2
        !            94: The Translator
        !            95: .PP
        !            96: Once the translator is constructed, test it by
        !            97: .Ds
        !            98: make Tran
        !            99: .De
        !           100: which runs the translator on a number of Icon programs,
        !           101: produces ucode output in \*M.u1\fR and \*M.u2\fR files,
        !           102: and compares it with corresponding standard output
        !           103: files.
        !           104: Since the translator is machine-independent and written
        !           105: entirely in C, there should not be any differences.
        !           106: .NH 2
        !           107: The Linker
        !           108: .PP
        !           109: When the new linker is successfully compiled, test it by
        !           110: .Ds
        !           111: make Link
        !           112: .De
        !           113: which runs the Icon linker on the files produced by the translator during
        !           114: the preceding test and produces linker debugging output in
        !           115: \&\*M.ux\fR files.
        !           116: This process is comparatively slow because of the generation of
        !           117: debugging output.
        !           118: The format of \*M.ux\fR files is somewhat dependent on
        !           119: computer and operating system details. In addition, the indexes of
        !           120: built-in functions, which appear in the \*M.ux\fR files, are determined
        !           121: by the extensions that are included in the Icon system when it is configured
        !           122: [2]. Consequently,
        !           123: there are likely to be differences \(em even extensive ones \(em
        !           124: between the locally generated \*M.ux\fR files and the distributed ones.
        !           125: Differences are not checked by \*Mmake\0Link\fR, but they can be
        !           126: determined separately by
        !           127: .Ds
        !           128: make Linkcheck
        !           129: .De
        !           130: If extensive differences are encountered,
        !           131: it may be necessary to examine the output in
        !           132: \*Mlocal\fR manually.
        !           133: .NH 2
        !           134: The Run-Time System
        !           135: .PP
        !           136: There are a number of steps in building the run-time system, and
        !           137: each step should be checked separately.
        !           138: The first test is
        !           139: .Ds
        !           140: make Basis
        !           141: .De
        !           142: which checks the elementary components of the run-time system that
        !           143: are needed to run simple Icon programs.
        !           144: The components involved are \*Miconx/start.s\fR, \*Mrt/setbound.s\fR,
        !           145: \*Mlib/invoke.s\fR, \*Miconx/interp.s\fR, \*Mlib/efail.s\fR,
        !           146: and \*Mlib/pfail.s\fR. See [1] for details. The remaining tests, and
        !           147: the components of the run-time system that they check, in order, are:
        !           148: .Ds
        !           149: .ta 1.6i
        !           150: make Arith     #   rt/arith.s
        !           151: make Fail      #   rt/fail.s
        !           152: make Pret      #   lib/pret.s
        !           153: make Esusp     #   lib/esusp.s
        !           154: make Lsusp     #   lib/lsusp.s
        !           155: make Psusp     #   lib/psusp.s
        !           156: make Suspend   #   rt/suspend.s
        !           157: make Display   #   functions/display.c
        !           158: make Gc        #   rt/gcollect.s\fR and \*Mrt/sweep.c
        !           159: .De
        !           160: .sp -1
        !           161: .NH
        !           162: Complete Testing
        !           163: .PP
        !           164: Once the port is complete and all the tests above have been passed
        !           165: successfully, the tests in the \*Msamples\fR and \*Mtest\fR
        !           166: directories should be performed.
        !           167: .NH 2
        !           168: Testing the Sample Programs
        !           169: .PP
        !           170: In the directory \*Mv5g/samples\fR, do
        !           171: .Ds
        !           172: make Std
        !           173: .De
        !           174: This test runs a number of sample programs and compares their output
        !           175: with standard output. Differences should occur only in the
        !           176: test program \*Mhello.icn\fR, which contains environment- and time-dependent
        !           177: code.
        !           178: .PP
        !           179: Two groups of extensions to Version 5.9 can be included, optionally, when the Icon
        !           180: system initially configured. See [2].
        !           181: If the sets extension is included in the port,
        !           182: then
        !           183: .Ds
        !           184: make Set
        !           185: .De
        !           186: to test these features. If the experimental extensions to Version 5.9
        !           187: are included also, then
        !           188: .Ds
        !           189: make Xpx
        !           190: .De
        !           191: Alternatively, if both group of extensions are included, the three tests above
        !           192: can be performed by
        !           193: .Ds
        !           194: make All
        !           195: .De
        !           196: .sp -1
        !           197: .NH 2
        !           198: Detailed Testing
        !           199: .PP
        !           200: Final detailed testing
        !           201: should be done in the directory \*Mv5g/test\fR, using
        !           202: .Ds
        !           203: make Std
        !           204: make Set
        !           205: make Xpx
        !           206: .De
        !           207: or
        !           208: .Ds
        !           209: make All
        !           210: .De
        !           211: as appropriate.
        !           212: .PP
        !           213: The following programs may show differences for the indicated reasons:
        !           214: .IP \*Mstd02.icn\fR .9i
        !           215: The output may differ because of the number of hash chains in tables
        !           216: is an installation-dependent parameter that affects the internal
        !           217: organization of tables, to which this test is sensitive.
        !           218: .IP \*Mstd06.icn\fR
        !           219: This program contains environmental- and time-dependent code and its
        !           220: output will certainly vary from the standard output.
        !           221: .IP \*Mstd21.icn\fR
        !           222: This program may terminate prematurely on systems with limited memory space.
        !           223: .IP \*Mstd22.icn\fR
        !           224: The output may differ for the same reasons as for \*Mstd02.icn\fR.
        !           225: .IP \*Mstd26.icn\fR
        !           226: The output may differ slightly because of differences in \*Mqsort\fR.
        !           227: .IP \*Mstd29.icn\fR
        !           228: This program calls operating system utilities; the output
        !           229: may differ if these calls have different formats for their output.
        !           230: .IP \*Mstd33.icn\fR
        !           231: This program may terminate prematurely on systems with limited memory space.
        !           232: .IP \*Mstd37.icn\fR
        !           233: The output may differ for the same reasons as for \*Mstd02.icn\fR.
        !           234: .IP \*Mset01.icn\fR
        !           235: The output may differ because of the number of hash chains in sets
        !           236: is an installation-dependent parameter that affects the internal
        !           237: organization of sets, to which this test is sensitive.
        !           238: .IP \*Mset02.icn\fR
        !           239: The output may differ for the same reasons as for \*Mset01.icn\fR.
        !           240: .PP
        !           241: If the random numbers produced by the ported system differ from those
        !           242: produced by the standard one, several tests may show differences in the
        !           243: order of results or in the results themselves.
        !           244: Any other differences that show up in these tests should be examined carefully.
        !           245: .PP
        !           246: Note that almost all of the tests end with an Icon run-time error.
        !           247: This is intentional, and is used to check run-time error
        !           248: detection in as many situations as possible.
        !           249: .SH
        !           250: References
        !           251: .LP
        !           252: 1. Mitchell, William H. \fIPorting the UNIX Implementation of Icon\fR.
        !           253: Technical Report TR 83-10d, Department of Computer Science,
        !           254: The University of Arizona. August 1984.
        !           255: .LP
        !           256: 2. Griswold, Ralph E. and William H. Mitchell. \fIInstallation and
        !           257: Maintenance Guide for Version 5.9 of Icon\fR. Technical Report
        !           258: TR 84-13a, Department of Computer Science, The University of Arizona.
        !           259: October 1984.

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