



           I N S T A L L A T I O N       G U I D E


           FOR THE


           M O D U L A       C O M P I L E R          ( PDP-11 / UNIX SYSTEMS )












                                 RELEASE   1

                                  July 1978






























                                I. D.  Cottam

       UNIVERSITY OF YORK      -      DEPARTMENT OF COMPUTER SCIENCE

       Heslington, York, Y01 5DD, England       Telephone 0904-59861






Installation Guide, York MODULA Compiler                                 Page 2
July 1978, Rev.A.



       1_.  INTRODUCTION____________


       This document is the Installation Guide for the initial release
       of  the University of York MODULA compiling system.  The system
       is distributed on either 9-track magnetic  tape  or  RK05  disk
       cartridge.  Magnetic tapes are written on a TU10 at 800 bpi odd
       parity.  Documentation is distributed in machine readable form.



       2_.  FORMAT______ OF__ DISTRIBUTION____________ MEDIA_____


       Magnetic tapes are in UNIX "tp" format.  RK05 disks have a file
       structure  created  by  "mkfs".  Both media contain a two-level
       directory structure:



                   /usr/mod
                      |
                      | -------- general files
                      |
                      |
                      | ------------ mod
                      |               |
                      |               | -------- compiler source files
                      |
                      |
                      | ------------ tc
                                      | -------- compiler test cases
                                                 & associated software


       Attachment 1 lists all the file names  together  with  a  brief
       description of their contents/usage.
























Installation Guide, York MODULA Compiler                                 Page 3
July 1978, Rev.A.






       3_.  INSTALLING__________ THE___ SYSTEM______




          From magnetic tape:


           (a) Login under root (superuser)

           (b) Create, using mkdir, the following directories:

                 /usr/mod
                 /usr/mod/tc
                 /usr/mod/mod

           (c) Mount the magnetic tape and enter:

                 tp  mxv

               tp will list all the files as they are written to
               disk.  This list should be checked against that
               given in attachment 1.

           (d) The following files should be copied to /bin:

                 /usr/mod/modula
                 /usr/mod/modovly
                 /usr/mod/utg
                 /usr/mod/utl

               utg and utl are only useful to sites with GT40's or
               LSI-11's respectively.

           (e) Print the Functional Specification (/usr/mod/funcspec).
               After studying the specification you will probably need
               to modify the shell file "modshellfile" to reflect the
               available target PDP-11's and/or LSI-11's.

           (f) Copy the (possibly modified) modshellfile to /usr/bin:
               e.g.

                 cp  /usr/mod/modshellfile  /usr/bin/mod

               "mod" is the name used at York; you may, of course,
               change it to whatever you prefer.

           (g) Create the Test Plan:

                 chdir  /usr/mod/tc
                 createtestplan
                 cat testplan.doc > /dev/hopefully_a_line_printer






Installation Guide, York MODULA Compiler                                 Page 4
July 1978, Rev.A.



                 rm  testplan.doc

               The test plan is fairly large - ~ 200 pages.

           (h) Study the test plan and run all the test programs (as
               directed therein) to check that the installation was
               successful.

           (i) If you have any trouble contact Ian Cottam at the Dept.
               of Computer Science, University of York.






         From RK05 disk:


           Simply "mount" the cartridge and copy the files to other disks
           as your UNIX system manager dictates.  Continue from step (d)
           of the magnetic tape procedure.







































Installation Guide, York MODULA Compiler                                 Page 5
July 1978, Rev.A.






                               ATTACHMENT    1

                        SOFTWARE  BILL  OF  MATERIALS






       (a)  Directory  /usr/mod:

        (1) a.gt40.s  (2) a.lsi.s  (3) a.p2.s
        (4) a.p3.s  -  assembly-time parameter files for the four target
                       processors used at York.

        (5) bcpl2bcpl.bin
        (6) bcpl2tran.bin  -  BCPL compiler. Used in build* shell files to
                              compile the MODULA compiler.
                              (N.B. BCPL is not supported by the University
                               of York)

        (7) bcplcont.as  (8) bcplcont.lib  (9) bcplg28.as  (10) bcpllib.lib
        (11) bcplstop.as  (12) binaryio.as
        (13) binaryio.rlb  -  BCPL assembler, binary, and library files.

        (14) buildallp  -  uses all the build* shell files to re-compile
                           the MODULA compiler.  The compiler's base segment
                           is left in the file:  modula.  Overlay segments
                           are "archived" into the file:  modovly.

        (15) buildbase  (16) buildpass0  (17) buildpass1  (18) buildpass2
        (19) buildpass2d  (20) buildpass3  (21) buildpass3d
        (22) buildpass4  -  re-compile the named compiler segment.  If a change
                            is made to pass0-pass4 then only that segment need
                            be re-compiled.

        (23) end.s  -  contains "rts     pc" instruction. Fudged return
                       to primitive overlay handler; used in build*
                       shell files.

        (24) errors  -  list of all known errors which remain to be
                        corrected in MODULA compiler.

        (25) front.s  -  assembly parameter file; created by buildbase shell
                         file; used by buildpass0-buildpass4.

        (26) funcspec  -  functional specification of release 1 MODULA compiler.

        (27) grab.bin  -  binary of grab.s.

        (28) grab.s  -  external references to force loading of BCPL library
                        items that are only used within the overlay segments;






Installation Guide, York MODULA Compiler                                 Page 6
July 1978, Rev.A.



                        used in shell file buildbase.

        (29) installguide  -  this document.

        (30) modnucl.s  -  MODULA Nucleus ("as" format); used by mod shell file.

        (31) modovly  -  compiler overlays.

        (32) modula  -  compiler base or root segment.

        (33) ovly.bin  -  binary of ovly.s.

        (34) ovly.s  -  overlay handler ("as" format).

        (35) seqmod  -  shell file to compile very simple Sequential MODULA
                        programs that can be run under UNIX control.

        (36) seqmod.s  -  very simple nucleus ("as" format) to support
                          Sequential MODULA programs under UNIX; used by
                          seqmod and tstseqmod.

        (37) seqmodio.mod  -  MODULA module which defines simple I/O procedures;
                              used by shell file seqmod.

        (38) utg  -  binary of utg.c; used by shell file mod.

        (39) utg.c  -  utility to convert "ld" format to GT40
                       loader fromat.

        (40) utl  -  binary of utl.c; used by shell file mod.

        (41) utl.c  -  utility to convert "ld" format to LSI-11 loader
                       format.

        (42) modshellfile  -  compiles/assembles MODULA programs.



       (b) Directory  /usr/mod/mod:


        (1) base.bcl  (2) base.get  (3) pass0.bcl  (4) pass0.get
        (5) pass1.bcl  (6) pass1.get  (7) pass2.bcl  (8) pass2.get
        (9) pass2b.get  (10) pass2d.get  (11) pass2d.bcl  (12) pass3.bcl
        (13) pass3.get  (14) pass3b.bcl  (15) pass3b.get  (16) pass3d.bcl
        (17) pass3d.get  (18) pass4.bcl  (19) pass4.get  (20) pass4b.bcl
        (21) pass4b.get  -  MODULA compiler source code files.



       (c) Directory  /usr/mod/tc:


        (1) createtestplan  -  shell file to concatenate the various sections
                               of the Test Plan and nroff the result;






Installation Guide, York MODULA Compiler                                 Page 7
July 1978, Rev.A.



                               output left in testplan.doc.

        (2) macros  -  nroff macros used by createtestplan.

        (3) run1  (4) run2  (5) runseqmodtests
        (6) run1g  (7) run2g  (8) runwithnoeis
        (9) run1n  (10) run2n  (11) runwithnoopt
        (12) run1gn  (13) run2gn  (14) runnoeisnoopt
          -  shell files to run sequential test cases under UNIX; further
             details are given in the Test Plan.

        (15) testplan  -  first part of testplan.doc; this nroff format file is
                          used by the shell file createtestplan.

        (16) testset.inf  -  gives a "one-line" introduction to the files in
                             this directory.

        (17) testsetio.mod  -  an "output routines only" version of seqmodio.mod.

        (18) testsum.mod  -  a Sequential MODULA program to produce a summary
                             test report of the sequential test cases;
                             further details in Test Plan.

        (19) testsum.s  -  binary of testsum.mod.

        (20) tstseqmod  -  same as seqmod except testsetio.mod used in place of
                           seqmodio.mod.

        (21) trivial.mod  (22) syntaxerrs.mod  (23) semanerrs1.mod
        (24) semanerrs2.mod  (25) extend.mod  (26) t1a1.mod
        (27) t1a2.mod  (28) t1b1.mod  (29) t1b2.mod  (30) t1c1.mod
        (31) t1d1.mod  (32) t1d2.mod  (33) t1e1.mod  (34) t1e2.mod
        (35) t1f1.mod  (36) t1f2.mod  (37) t2a1.mod  (38) t2a2.mod
        (39) t2a3.mod  (40) t2a4.mod  (41) t2a5.mod  (42) t2a6.mod
        (43) t2a7.mod  (44) t2b1.mod  (45) t2b2.mod  (46) t2b3.mod
        (47) t2b4.mod  (48) t2b5.mod  (49) t2b6.mod  (50) t2c1.mod
        (51) t2c2.mod  (52) t2c3.mod  (53) t2c4.mod  (54) t2c5.mod
        (55) t2c7.mod  (56) t2c8.mod  (57) t2c9.mod  (58) t2c10.mod
        (59) t2c11.mod (60) t2c12.mod (61) t3a1.mod  (62) t3a2.mod
        (63) t3a4.mod  (64) t3a5.mod  (65) t3c1.mod  (66) t3c2.mod
        (67) t3c3.mod  (68) t3d1.mod  (69) t3d2.mod  (70) t3d3.mod
        (71) t3e1.mod  (72) t3e2.mod  (73) t3e3.mod  (74) t3f1.mod
        (75) t4a1.mod  (76) t4a2.mod  (77) t4a3.mod  (78) t4a4.mod
        (79) t4b1.mod  (80) t4b2.mod  (81) t4b3.mod  (82) t4b4.mod
        (83) t4b5.mod  (84) t4c1.mod  (85) t4c2.mod  (86) t4c3.mod
        (87) t4c4.mod  (88) t4c5.mod  (89) t4d1.mod  (90) t4d3.mod
        (91) t4d4.mod  (92) t4e1.mod  (93) t4e3.mod  (94) t4e4.mod
        (95) t4f1.mod  (96) t4f2.mod  (97) t4f3.mod  (98) t4f4.mod
        (99) t5a2.mod  (100) t5a3.mod  (101) t5a4.mod  (102) t8a1.mod
        (103) t8a3.mod  (104) t8a4.mod  (105) t8a5.mod  (106) test1.mod
        (107) test2.mod  (108) test3.mod  (109) test4.mod
        (110) test5.mod  -  Sequential MODULA test programs;
                            further details in testset.inf and
                            the Test Plan.







Installation Guide, York MODULA Compiler                                 Page 8
July 1978, Rev.A.



        (111) tick2.mod
        (112) test8.mod  - concurrent test programs (see Test Plan).

        (113) tick.mod  (114) killer.mod  (115) m2.mod  (116) morse.mod
        (117) race.mod  (118) t8b1.mod  (119) t8b2.mod  (120) test6.mod
        (121) test7.mod  (122) test9.mod  (123) test10.mod
        (124) test11.mod  -  concurrent programs of general interest
                             (see Test Plan).

        (125) primes  -  expected output from test3.mod.

        (126) queens8  -  expected output from t8a3.mod.

        (127) queens8.2  -  expected output from test2.mod.

        (128) semanerrs1.lst  -  expected list file resulting from comp-
                                 ilation of semanerrs1.mod.

        (129) semanerrs2.lst  -  expected list file resulting from comp-
                                 ilation of semanerrs2.mod.

        (130) synerrsmod.lst  -  expected list file resulting from comp-
                                 ilation of syntaxerrs.mod.

        (131) trivial.lst  -  expected list file resulting from compilation
                              of trivial.mod.

        (132) warshall  -  expected output from test4.mod.

































Installation Guide, York MODULA Compiler                                 Page 9
July 1978, Rev.A.






                               ATTACHMENT   2
             COMPILER  ERRORS  AND  ERROR  REPORTING  PROCEDURES





       Errors discovered in software supplied  by  the  University  of
       York,  Department  of  Computer  science, should be reported in
       writing, together with verifiable objective evidence, to:

               Mr I.D. Cottam
               University of York
               Dept. of Computer Science
               Heslington, York, Y01 5DD
               England

       For York to undertake corrective action,  reported errors  must
       be  demonstrable  in the officially released compiler. Versions
       of the compiler produced by modifying the distributed York com-
       piler  are  the  responsibility  of the organisation performing
       such modifications.  All users will receive corrections to  re-
       ported  errors.   Corrections  may be supplied in several ways;
       varying from source edits to a complete re-release of the  com-
       piling system.


       Error codes are assigned by York and have the form:

                    ("A"|"B"|"C") digit digit digit

       where:

                    A    -     critical errors; compiler crashing,
                               and/or major programmer inconvenience

                    B    -     deviation from language definition
                               and/or functional specification;
                               minor programmer inconvenience

                    C    -     nuisance problem.

       The three digits are a serial number starting at 001  for  each
       catagory of error.














Installation Guide, York MODULA Compiler                                Page 10
July 1978, Rev.A.






                     Known Errors in Release 1 Compiler



          A001 - Assignments to read only objects (such as constants or export-
                 ed variables) are not flagged. An erroneous a.out file (i.e.
                 "as" will complain) and/or a compiler crash may result.

          B001 - Function procedures with no assignment to the function name
                 are not flagged.

          B002 - Two modules at the same level exporting the same identifier
                 not flagged.

          B003 - Procedures with VAR formals accept non-VAR actuals. This
                 problem is related to A001.

          B004 - Function procedures used as procedure calls not flagged.

          B005 - The range of types to standard function procedures is not
                 checked for correctly.

          B006 - Incorrect code is produced for array constants whose elements
                 are of type bits.

          B007 - The compiler allows functions to return structured objects
                 but in complex cases produces incorrect code.

          C001 - If a syntactically incorrect program contains TAB characters
                 then the listing will not necessarily flag the relevant
                 portion of text containing the error.



























Installation Guide, York MODULA Compiler                                Page 11
July 1978, Rev.A.






                               ATTACHMENT   3
       MOVING THE MODULA COMPILER TO OTHER COMPUTERS / BCPL COMPILERS



       The University of York  will,  at  some  currently  unscheduled
       date,  release  a  version  of the compiler designed to be more
       portable across both machines and other BCPL compilers.  A  de-
       finition  of  the  intermediate  code (MCODE) will be published
       shortly. Some experiments have already been performed on moving
       the  (cross-)compiler  to  the  DECsystem 10 and the IBM System
       370.  Should you wish to move the Release 1 compiler to a  dif-
       ferent environment here are a few hints:

       * Make sure your BCPL compiler is reasonably standard, particu-
       larly regarding global vector conventions.

       * The compiler uses the full ASCII set, many users  will  prob-
       ably need to edit , for example, {  to  $(.

       * BCPL library routines will probably differ.

       * A recently discovered non-standard BCPL York compiler  depen-
       dency is that string lengths are held in the first word instead
       of the first byte. York BCPL will be corrected.

       * If you have a large host computer (e.g. IBM 370  or  DEC  10)
       discard the overlay mechanism.




       Good luck!


       Ian Cottam      78/07/14.





















