diff --git a/doc/install.doc b/doc/install.doc index f9edb7e18..7453a1b62 100644 --- a/doc/install.doc +++ b/doc/install.doc @@ -15,7 +15,7 @@ Introduction This document describes the process of installing Amsterdam Compiler Kit. It depends on your combination of hard- and software how -hard it will be to install the kit. +hard it will be to install the Kit. This description is intended for a PDP 11/44 running .UX Version 7. @@ -24,7 +24,8 @@ as they have separate instruction and data space. Installation on machine's without this feature, like PDP 11/34, PDP 11/60 requires extensive surgery on some programs and is thought of as impossible. -See chapter 6 for installation on other systems. +Installation on VAX'en running BSD4.1 should also be easy. +See section 7 for installation on other systems. .NH Restoring tree .PP @@ -34,7 +35,7 @@ distribution tree structure is restored. Proceed as follows .IP " -" 10 Create a directory, for example /usr/em, on a device -with at least 20000 blocks left. +with at least 15 Megabytes left. .IP " -" Change to that directory (cd ...); it will be the working directory. .IP " -" @@ -46,26 +47,39 @@ Keep a copy of the original distribution to be able to repeat the process of installation in case of disasters. This copy is also useful as a reference point for diff-listings. .LP +.bp The directories in the tree contain the following information: -.nr PD 1v -.IP "lib" 14 -.br -almost all binaries and shell files used by commands and -library em_data.a from misc/data -.IP "lib/ack" -.br -The command descriptor files used by the program ack. +.sp 1 .nr PD 0 -.IP "bin" +.IP "bin" 14 +.br +the few utilities that knot things together. +See the section about "Commands". +.IP "lib" +.br +root of a tree containing almost all binaries and libraries used by +commands. +All files specific to a certain machine are collected in one subtree +per machine. E.g. "lib/pdp", "lib/z8000". +The names used here are the same names as used for subdirectories +of "mach". +.IP "lib/descr" +.br +Command descriptor files used by the program ack. +.IP "lib/LLgen" +.br +Files used by the LL(1) Parser-generator. .br -the few utilities that knot things together .IP "etc" .br -The MAIN description of EM sits here. -contains files (e.g. em_table) describing +The main description of EM sits here. +Files (e.g. em_table) describing the opcodes and pseudos in use, the operands allowed, effect in stack etc. etc. -Make in this directory creates most of the files in h +Make in this directory creates most of the files in "h" +and "util/data". +This make should only be called when the EM definition is +changed. .IP "include" .br More or less system independent include files needed by modules @@ -74,59 +88,43 @@ Especially needed for "stdio". .IP "h" .br The #include files for: -.nf -as_spec.h Used by EM assembler and interpreters. -em_abs.h Contains trap numbers and address for lin and fil -em_flag.h Definition of bits in array em_flag in lib/em_data.a - Describes parameters effect on flow of instructions -em_mes.h Definition of names for mes pseudo numbers -em_mnem.h instruction => compact mapping. -em_pseu.h pseudo instruction => compact mapping -em_ptyp.h Useful for compact code reading/writing, - defines classes of parameters -em_spec.h Definition of constants used in compact code -local.h Various definitions for local versions -pc_err.h Definitions of error numbers in Pascal -pc_file.h Macro's used in file handling in Pascal -em_path.h Pathnames used by \fIack\fP, intended - for all utilities -pc_size.h Sizes of objects used by Pascal compiler and - run-time system. -em_reg.h Definition of names for register types. +.TS +l l. +arch.h Definition of the ACK archive format. +as_spec.h Used by EM assembler and interpreters. +bc_io.h Used by the Basic run-time system. +bc_string.h Used by the Basic run-time system. +cg_pattern.h Used by the backend program "cg" and its bootstrap. +cgg_cg.h Used by the backend program "ncg" and its bootstrap. +em_abs.h Contains trap numbers and address for lin and fil +em_flag.h Definition of bits in array em_flag in lib/em_data.a + Describes parameters effect on flow of instructions +em_mes.h Definition of names for mes pseudo numbers +em_mnem.h instruction => compact mapping. +em_path.h Pathnames used by \fIack\fP, intended + for all utilities +em_pseu.h pseudo instruction => compact mapping +em_ptyp.h Useful for compact code reading/writing, + defines classes of parameters +em_reg.h Definition of mnemonics indicating register type. +em_spec.h Definition of constants used in compact code +local.h Various definitions for local versions +pc_err.h Definitions of error numbers in Pascal +pc_file.h Macro's used in file handling in Pascal +pc_size.h Sizes of objects used by Pascal compiler and + run-time system. +em_reg.h Definition of names for register types. +.TE .IP "doc" .br -Documentation -.nf -cg.doc Use and internal specification of the backend. -.br -regadd.doc Update for cg.doc concerning register variables -.br -regadd.doc Description of steps to add register variables. -.br -ack.doc Layout of description files needed for each machine. -.br -cref.doc C reference manual, addendum -.br -install.doc Ack Installation Guide -.br -pcref.doc Pascal reference manual, addendum -.br -peep.doc Description of the peephole optimizer -.br -em.doc EM reference manual -.br -toolkit.doc A general overview of the toolkit -.br -v7bugs.doc Bugs in the standard V7 system -.br -val.doc Pascal validation suite version 3 report -.nf +This directory contains the unformatted documents for the kit. +A list of the available documents can be found in the last section. .IP "doc/em.doc" .br The EM-manual IR-81 .IP "doc/em.doc/int" .br -The EM interpreter written in pascal +The EM interpreter written in Pascal .IP "mkun" .br The PUBMAC macro package for nroff/troff from the Katholieke Universiteit at @@ -137,101 +135,38 @@ the Makefile installs the macro package in This package is in the public domain. .IP "mach" .br -just there to group the directories for all machines -these directories have sub-directories named: -.nf - as the assembler ( *.s + libraries => a.out ) - cg the new backend ( *.m => *.s ) - lib the libraries for all run-time systems - these libraries are used by the assembler. - libpc Used to create Pascal run-time system in 'lib' - libcc Used to create C run-time system in 'lib' - libem Sources for EM runtime system, result sits in 'lib' - test Various tests - dl Down-load programs - int Source for an interpreter -available are: - PMDS II 68000, wordsize 2, ptrsize 4 - mach/m68k2 - mach/m68k2/as - mach/m68k2/cg - mach/m68k2/libem - mach/m68k2/lib - mach/m68k2/dl - mach/m68k2/libpc - mach/m68k2/libcc - mach/m68k2/libsys - bare 6809 - mach/6809 - mach/6809/as - 8080, wordsize 2, ptrsize 2 - mach/8080 - mach/8080/as - mach/8080/test - mach/8080/libcc - mach/8080/lib - bare 8086, wordsize 2, ptrsize 2 - mach/i86 - mach/i86/as - mach/i86/lib - mach/i86/libcc - mach/i86/dl - mach/i86/libem - mach/i86/libpc - mach/i86/saio (library for stand-alone EM on 86/12A ) - pdp 11, UNIX/V7, wordsize 2, ptrsize 2 - mach/pdp - mach/pdp/test - mach/pdp/libem - mach/pdp/lib - mach/pdp/libcc - mach/pdp/libpc - mach/pdp/cg - mach/pdp/int -PDP 11/44 EM interpreter - vax 780, UNIX V7, wordsize 4, ptrsize 4 - mach/vax4 - mach/vax4/cg - mach/vax4/lib - mach/vax4/libcc - mach/vax4/libem - mach/vax4/libpc - z80, CP/M, wordsize 2, ptrsize 2 - mach/z80 - mach/z80/as - mach/z80/libem - mach/z80/lib - mach/z80/libcc - mach/z80/libpc - mach/z80/int -Z80 EM interpreter - z80, nascom - mach/z80a - mach/z80a/dl - vax 11/780, Berkeley UNIX, wordsize 2, ptrsize 4 - mach/vax2 - mach/vax2/cg - mach/vax2/lib - mach/vax2/libpc - mach/vax2/libem - bare 6500, wordsize 2, ptrsize 2 - mach/6500 - mach/6500/as - mach/6500/dl - mach/6500/libem - mach/6500/lib - bare 6800, wordsize 2, ptrsize 2 - mach/6800 - mach/6800/as - EM virtual machine code, wordsize 2, ptrsize 2 - mach/int - mach/int/libcc - mach/int/libpc - mach/int/lib - mach/int/test - The directory proto contains files used by most machines. - e.g. makefiles for libraries for C and Pascal - mach/proto - mach/proto/libg -.fi +just there to group the directories with all sources for each machine. +The section about "Machines" of this manual indicates which subdirectories +are used for which systems. +.br +These directories have subdirectories named: +.in +3n +.TS +l l. +as the assembler ( *.s + libraries => a.out ) +cg the backend ( *.m => *.s ) +ncg the new backend ( *.m => *.s ) +libbc Used to create Basic run-time system and libraries +libcc Used to create C run-time system and libraries +libpc Used to create Pascal run-time system and libraries +libem Sources for EM runtime system, intended to depend only on CPU type +libsys Sources for system-dependent EM library +test Various tests +dl Down-load programs +cv Conversion programs for a.out files. +int Source for an interpreter +.TE +.in -3n +The directory proto contains files used by most machines +like machine-independent sources and Makefiles. +.in +3n +.TS +l l. +mach/proto/libg Makefile for compiling libraries. +mach/proto/as Assembler sources. +mach/proto/cg Current backend sources. +mach/proto/ncg New backend sources. +.TE .IP "emtest" .br Contains prototype of em test set. @@ -240,7 +175,7 @@ Contains prototype of em test set. Man files for various utilities .IP "lang" .br -just there to group the directories for all front-ends +Just there to group the directories for all front-ends .IP "lang/pc" .br Pascal front-end @@ -252,7 +187,7 @@ Source of Pascal run-time system ( in EM or C ) Some test programs written in Pascal .IP "lang/pc/pem" .br -The compiler proper +The Pascal compiler proper .IP "lang/cem" .br C front-end @@ -262,10 +197,10 @@ Directories with sources of C runtime system, libraries (in EM or C) .IP "lang/cem/libcc/gen" .br Sources for routines in chapter III of UNIX programmers manual, -excluding STDIO +excluding Stdio .IP "lang/cem/libcc/stdio" .br -STDIO sources +Stdio sources .IP "lang/cem/libcc/mon" .br Sources for routines in chapter II, written in EM @@ -281,9 +216,21 @@ Programs developed for pinpointing previous errors .IP "lang/cem/ctest/ct*" .br The test programs. +.IP "lang/basic/src" +.br +The compiler proper. +.IP "lang/basic/lib" +.br +Basic run-time library source. +.IP "lang/basic/test" +.br +Various Basic programs. .IP "util" .br -Contains directories with various utilities +Contains directories with sources for various utilities +.IP "util/ack" +.br +The program used for translation with the Kit. .IP "util/opt" .br EM peephole optimizer (*.k => *.m) @@ -303,30 +250,586 @@ The archiver to be used for ALL EM utilities .IP "util/cgg" .br A program needed for compiling backends. +.IP "util/ncgg" +.br +A program needed for compiling the newest backends. .IP "util/cpp" .br The V7 C preprocessor. +.IP "util/shf" +.br +Various shell files. +.IP "util/LLgen" +.br +The extended LL(1) parser generator. +.ne 4 .LP All pathnames mentioned in the text of this document are relative to the -working directory, unless they start with '/'. -.PP -The person doing the installation needs permission to write in the -directories of the Amsterdam Compiler Kit distribution tree. -Preferably you should log in as sys (uid=3,gid=0). +ACK home directory, unless they start with '/'. +.sp 1 .NH +Adapting ACK to your system +.PP +Before compiling the sources in the Kit some installation dependent +actions have to be taken. +Most of these are performed by an interactive shell script in the file +first in a directory of the same name. +.LP +These actions are: +.sp 1 +.IP - +Automatically checking whether you included the ACK bin directory in your +shell PATH. +See also the section on "commands". +.IP - +Automatically setting the pathname of the parent directory in ../h/em_path.h. +See also the section on "pathnames". +.IP - +Asking you for the type of system you have +and creating the shell script "ack_sys" in the Kit's bin directory. +Several utilities make use of "ack_sys" to determine the type of +system you have. +The current choice is between: +.sp 1 +.TS +c c c +l l l. +answer system type default machine +pdp_v7 PDP11 with sep I/D and version 7 pdp +vax_bsd4_1a VAX11 with BSD4.1a vax2 +vax_bsd4_1c VAX11 with BSD4.1c vax2 +vax_bsd4_2 VAX11 with BSD4.2 vax2 +pc_ix IBM PC with PC/IX ix +m68_unisoft Motorola 68000 with Unisoft UNIX m68k2 +m68_pmds Philips PMDS pmds +ANY Neither of the above m68k2 +.TE +.sp 1 +As mentioned before the installation on VAX'en and PDP11's should +be easy. +The pc_ix and m68 systems are also known to behave reasonably, +but the installation procedure has not been extensively tested. +For ANY you can use any name you fancy, +but the Kit will not be able to compile programs for your system. +If you want to do that you have to read the section about "compilation +on a different machine". +.IP - +Automatically setting the default machine for which code is +produced to your own type of system according to the table above. +This in done in the file "h/local.h". +See also the section 8.2. +.IP - +Automatically editing a few description files that tell +ACK to use your system's assembler. +On both the PDP and the VAX the Kit uses the native assembler and linker. +The description files in lib/pdp/descr, lib/vax2/descr and +lib/vax4/descr have to be altered to prevent +attempts to assemble programs with unsuitable assemblers. +The original descr files are copied to descr.orig. +.IP - +Automatically installing the special include directory for vax2. +This will only be done on VAX systems. +The shell scripts needed by ACK for the vax2 backend differ slightly +from the one issued by Berkeley. +.br +Note: this has only been tested under BSD4.1a. +.IP - +Automatically editing the system.h file in mach/vax[24]/libem. +Again, only on VAXen. +These files reflect whether you have BSD4.1a, BSD4.1c or BSD4.2. +.LP +.sp 1 +Some actions still have to be done by hand. +.sp 1 +.IP - +The VAX backends cannot be booted on systems +with a 16-bit address space systems. +The program lib/cgg needs more memory than available to transform +the table into files suitable for the C-compiler. +Therefore files tables1.h and tables1.c have been provided in +the directories mach/vax[24]/cg. +These must be copied to tables.h and tables.c on their respective +directories to get working code-generators for the VAX on PDP11's. +You will hardly be able to use these, because the +code generated by these programs cannot be +assembled and loaded without a native VAX assembler, +but its nice to be able to look at the code produced. +.IP - +The installation of the PUBMAC macro package is not done +automatically because you needs super-user privileges to do +that on most systems. +This macro package is used with several of the documents +provided in the Kit. +.IP - +UNIX V7 as originally distributed contains a few bugs that +prevent correct execution of some of the larger programs. +See the section named "Fixes for the UNIX V7 system" +about what to do. +.IP - +The manual files for the Kit can be copied to their +appropriate place in the system by giving the command "make install" +in the man directory. +.NH +Compiling the Kit +.PP +The next step in the installation process is to compile +the sources in the Kit and install them in their places +in the lib and bin directories. +.PP +Most directories containing sources have Makefiles +used to compile and install the programs in that +directory. +All programs needed for compilation and/or cross compilation +with the Kit are installed in the directories "bin" and "lib" +by these Makefiles. +These Makefiles adhere to a standard which is described in the +section 9. +.LP +You do not have to start all these Makefiles separately. +We wrote a shell script calling the make's needed to install +the whole Kit. +This script consists of the file TakeAction in the Kit's root +directory and a few files called Action in some directories. +The Action files describe in a very simple form which actions +have to be performed in which directories. +The default action is to start "make install". +The output of each make is diverted to a file called "Out" +in the same directory as the make was started in. +If the make was successful (return code 0) the Out file is removed +and the script TakeAction produces a small message telling you +that it succeeded in fulfilling its goal. +If the make was not successful (any other return code) the Out file +is left alone for further examination and a small message telling you +to look at that file is produced by TakeAction. +.LP +For some programs the scripts already know they can't be +installed on your type of system. +In that case they produce a message "Sorry, ....." and +happily proceed with further installation commands. +.PP +Compilation of the whole Kit might take anything from a few +hours to more than a day. +If you do not want to install libraries etc. for a particular +machine you can edit the file Action and remove the relevant entries. +.PP +If this compilation went reasonably successful you should be able +to use the Kit. +Read the next section and the manuals provided +with the Kit (in the man directory) on how to use it. +.NH 2 +Possible problems you may meet +.NH 3 +on Unisoft m68000 systems. +.PP +The Unisoft C compiler has a bug which impedes the correct +translation of the peephole optimizer. +For a more detailed description of this phenomenen see +the file "mach/m68k2/Unisoft_bug". +.NH 3 +with backends +.PP +The backends for the PDP11, VAX with BSD4.1, Motorola 68000 and +Intel 8086 have been heavily used by ourselves and are well tested. +The backends for the other machines are known to run our own +test programs, +but might reveal errors when more heavily used. +.NH 2 +An example output of TakaAction. +.PP +.DS +System definition -- done +EM definition -- done +C preprocessor -- done +EM definition library -- done +Encode/Decode -- done +Shell files in bin -- done +EM assembler -- done +EM Peephole optimizer -- done +ACK archiver -- done +Program 'ack' -- done +Bootstrap for backend tables -- done +LL(1) Parser generator -- done +Bootstrap for newest form of backend tables -- done +C frontend -- done +Basic frontend -- done +Intel 8086 assembler -- done +Intel 8086 backend -- done +Intel 8086 download program(s) -- done +Intel 8086 C libraries -- done +Intel 8086 EM library -- done +Intel 8086 Pascal library -- done +Intel 8086 Stand-alone io library -- done +Intel 8086 Basic library -- done +Intel 8086 support -- done +MSC6500 assembler -- done +MSC6500 backend -- done +MSC6500 download program(s) -- done +MSC6500 C libraries -- done +MSC6500 EM library -- done +MSC6500 Pascal library -- done +MSC6500 Basic library -- done +MSC6500 support -- done +Motorola 6800 assembler -- done +Motorola 6800 support -- done +Motorola 6805 assembler -- done +Motorola 6805 support -- done +Motorola 6809 assembler -- done +Motorola 6809 support -- done +Intel 8080 assembler -- done +Intel 8080 support -- done +2-2 Interpreter C libraries -- done +2-2 Interpreter Pascal library -- done +2-2 Interpreter Basic library -- done +2-2 Interpreter support -- done +2-4 Interpreter C libraries -- done +2-4 Interpreter Pascal library -- done +2-4 Interpreter Basic library -- done +2-4 Interpreter support -- done +4-4 Interpreter C libraries -- done +4-4 Interpreter Pascal library -- done +4-4 Interpreter Basic library -- done +4-4 Interpreter support -- done +Sorry, IBM PC/IX conversion program(s) can only be made on pc_ix systems +IBM PC/IX support -- done +Motorola 68000 2-4 assembler -- done +Motorola 68000 2-4 backend -- done +Sorry, Motorola 68000 interpreters can only be made on m68* systems +Sorry, the m68k? conversion program has to be translated on the target machine +Motorola 68000 2-4 C libraries -- done +Motorola 68000 2-4 EM library -- done +Motorola 68000 2-4 Pascal library -- done +Motorola 68000 2-4 System library -- done +Motorola 68000 2-4 Basic library -- done +Motorola 68000 2-4 support, see mach/m68k2/Out +NS16032 assembler -- done +NS16032 support -- done +PDP 11 assembler -- done +PDP 11 backend -- done +PDP 11 interpreter -- done +PDP 11 C libraries -- done +PDP 11 EM library -- done +PDP 11 Pascal library -- done +PDP 11 Basic library -- done +PDP 11 support -- done +PMDS download program(s) -- done +PMDS EM library -- done +PMDS support -- done +Signetics 6502 assembler -- done +Signetics 2650 support -- done +Vax 2-4 backend -- done +Sorry, Vax 2-4 Basic library can only be made on vax* systems +Sorry, Vax 2-4 C libraries can only be made on vax* systems +Sorry, Vax 2-4 EM library can only be made on vax* systems +Sorry, Vax 2-4 Pascal library can only be made on vax* systems +Vax 2-4 support -- done +Vax 4-4 backend -- done +Sorry, Vax 4-4 C libraries can only be made on vax* systems +Sorry, Vax 4-4 EM library can only be made on vax* systems +Sorry, Vax 4-4 Pascal library can only be made on vax* systems +Sorry, Vax 4-4 Basic library can only be made on vax* systems +Vax 4-4 support, see mach/vax4/Out +Z80 assembler -- done +Z80 support -- done +Zilog Z8000 assembler -- done +Zilog Z8000 backend -- done +Zilog Z8000 C libraries -- done +Zilog Z8000 EM library -- done +Zilog Z8000 Pascal library -- done +Zilog Z8000 Basic library -- done +Zilog Z8000 support -- done +Nascon download program(s) -- done +Nascom support -- done +Failed for Pascal frontend, see lang/pc/pem/Out +.DE +.PP +The lines starting with "Sorry, " tell you that certain programs cannot +be translated on your machine. +The lines starting with "Failed for" tell +you that certain programs/libraries which were expected to, +but did not compile. +Only the Pascal frontend failed to compile in this example. +If you want to repeat a certain part of the installation, look in +the Action file for the directory in which that part is to be found. +If that directory contains an Action file issue the command +"sh EMHOME/TakeAction", otherwise type "make install". +.NH +Commands +.PP +The following commands are available in the bin directory after compilation +of the kit: +.sp 1 +.IP "\fIack\fP, \fIacc\fP, \fIabc\fP, \fIapc\fP and their links" +.br +The names mentioned here can be used to compile Pascal, C, etc... programs. +Most of the links can be used to generate code for a particular +machine. +See also the section about "Machines" +.IP \fIarch\fP +.br +The archiver used for the EM- and universal assembler. +.IP \fIem\fP +.br +This program selects a interpreter to execute an e.out file. +Interpreters exist for PDP-11 and Motorola 68000 systems. +.IP \fIeminform\fP +.br +The program to unravel the post-mortem information of +the EM interpretator for the PDP-11. +.IP \fILLgen\fP +.br +The LL(1) parser generator. +.IP \fIack_sys\fP +.br +A shell script producing an identification of your system. +Used by some utilities to determine what is, and what is +not feasible on your system. (Like translating PDP assembly). +.IP \fImarch\fP +.br +A shell script used while compiling libraries. +.sp 1 +.LP +We currently make the Kit available to our users by telling +them that they should include the bin directory of the Kit in +their PATH shell variable. +The programs will still work when moved to a different +directory or linked to. +Copying should preferably be done with tar, since links are +heavily used. +Renaming of the programs linked to \fIack\fP will not always +produce the desired result. +This program uses its call name as an argument. +Any call name not being \fIcc\fP, \fIacc\fP, \fIabc\fP, \fIpc\fP or \fIapc\fP will be +interpreted as the name of a 'machine description' and the +program will try to find a description file with that name. +The installation process will only touch the utilities in the Kit's bin +directory, not your own copies. +.NH +Machines +.PP +Underneath you will find a table with entries for all commands in +the bin directory used to (cross)compile for a particular machine. +The name in the first column give the name in the bin directory. +The column headed dir indicates which subdirectories of +lib are needed for compilation. +The column head i/p contains the integer and pointer size used in units of +bytes. +The subdirectories with the same name in mach contain the sources. +A * in the column headed 'fp' indicates whether floating point can be used +for that particular machine. +.TS +c c c c c c c +l l l l l l l. +command system i/p languages fp dir remarks + +pdp PDP/UNIX V7 2/2 C * pdp needs sep. I/D + Pascal No assembler + Basic + +vax2 VAX/BSD 4.? 2/4 C * vax2 No assembler + Pascal + Basic + +vax4 VAX/BSD 4.? 4/4 C * vax4 No assembler + Basic + +m68k2 M68000/Unisoft 2/4 C m68k2 + Pascal + Basic + +m68k4 M68000/PMDS 4/4 C m68k2 + Basic m68k4 + +pmds M68000/PMDS 2/2 C pmds Philips Micro + Pascal m68k2 Devel. System + Basic + +i86 Bare 8086 2/2 C i86 For ISBC 86/12A + Pascal + Basic + +ix IBM PC/IX 2/2 C ix IBM PC with PC/IX + Pascal i86 Causes kernel crashes + Basic + +z8000 Zilog 8000 2/2 C z8000 Central Data + Pascal CPU board + Basic + +int Same as int22 +int22 EM machine 2/2 C * int22 Needs interpreter + Pascal + Basic + +int24 EM machine 2/4 C * int24 Needs interpreter + Pascal + Basic + +int44 EM machine 4/4 C * int44 Needs interpreter + Basic + +6500 6502/BBC 2/2 C 6500 + Pascal + Basic + +6800 Bare 6800 6800 Assembler only + +6805 Bare 6805 6805 Assembler only + +6809 Bare 6809 6809 Assembler only + +ns Bare NS16032 ns Assembler only + +i80 Hermac/z80 2/2 C i80 + Pascal + Basic + +z80 Hermac/z80 2/2 C z80 \fIi80\fP is faster + Pascal + Basic + +s2650 Signetics 2650 s2650 Assembler only +.TE +.PP +The commands \fBint\fP, \fBint22\fP, \fBint24\fP and \fBint44\fP +produce e.out files with EM machine code which must be interpreted. +The Kit contains two interpreters one running under PDP 11/V7 UNIX +and the PMDS system. +The first one can only interpret 2/2 e.out files, +the other takes 2/4 and 4/4 files. +The PDP 11 interpreter executes floating point instructions. +The interpreter on the PMDS traps if you try to use floating point. +.LP +The program \fBem\fP in the bin directory calls the appropriate +interpreter. +The interpreters are sought in the int22, int24 and int44 +subdirectories of lib. +.NH +Compilation on a different machine. +.PP +The Kit be installed and used as a cross-compiler +for C and Basic programs on any UNIX machine. +The presence of most UNIX utilities is essential for compilation. +A few of the programs you certainly need are: C-compiler, Yacc, sed, +make and lex. +Except the Pascal compiler proper all programs +can be translated on a normal UNIX system, like V7, BSD4.1. +.PP +We know there are certain problems with System V. +Some of the character/string routines are named differently, +ctype(3) seems to have a different naming scheme. +The most annoying thing is that in printf format strings the +role of the format %03x is taken by something like %.3x. +Several programs suffer from this format change. +.NH 2 +Backend +.PP +The existence of a backend with a system call library +for your system is essential +if you wish to produce executable files for that system. +Rewriting the system call library if the one supplied does +not work on your system is fairly straightforward. +If no backend exists for your CPU type you have to write one yourself +which is a major undertaking. +.NH 2 +Pascal +.PP +When you can produce executable code it is also possible to boot the Pascal +Compiler, +which is written in Pascal itself. +The Kit contains the compact code files for the 2/2 and 2/4 +versions of the Pascal compiler. +The current version of this compiler can only be used on machines +with a 16-bit word size and 16- or 32-bit pointers. +The Makefile automatically tries to boot the Pascal compiler +from one of these compact code files, if the compiler proves +unable to compile itself. +.NH 2 +Universal assembler +.PP +The native assemblers and loaders are used on PDP-11 and VAX. +The description files in lib/*/descr for other systems use our +universal assembler. +The load file produced by this assembler is not directly +usable in any system known to us, +but has to be converted before it can be put to use. +The \fIcv\fP programs convert our a.out format into +executable files. +The \fIdl\fP programs present for some machines unravel +these our a.out files and transmit commands to load memory +to a microprocessor over a serial line. +The file man/a.out.5 contains a description of the format of +the universal assembler load file, +it might be useful to those who wish or need to write their +own conversion programs. +.LP +One warning has to be issued here. +The universal assembler a.out files contain integers and/or +longs with the bytes in the order your own system uses. +Copying these files to machines with a different byte order +will not always produce the desired results. +.NH 2 +Compiling libraries +.PP +The Kit contains sources for part II and III of the C-library, +they have been grabbed from our V7 system and sometimes +altered in a EM dependent way or replaced altogether when the original +was in assembly. +These files can be used to make libraries for the Ack C-compiler. +The recompilation process uses a few include files. +The include directory in the EM home directory contains a few more +or less system independent include files. +Some backends, like the vax2 backend also need a few include files +of their own, replacing ones in /usr/include. +The include files are sought in lib/*/include. +The system dependent include files are fetched from /usr/include +on the system you use to recompile. +This may lead to several problems. +Sometimes the system differs so much from V7 that certain manifest constants +do not exist any more. +At other times these include files were written for a compiler without +a restriction on name length. +In that case - I've seen it happen - people tend to use differing +identifiers that are identical in the first eight characters. +All these problems you have to solve yourself, +the libraries are only included as an extra and too much system +dependent to give any guarantees. +.NH +Options +.NH 2 +Default machine +.PP +There is one important option in h/local.h. +The utility \fIack\fP uses a default machine name when called +as \fIacc\fP, \fIcc\fP, \fIabc\fP, \fIapc\fP, \fIpc\fP or \fIack\fP. +The machine name used for default is determined by the +definition of ACKM in h/local.h. +The Kit is distributed with "pdp" as the default machine, +but the shell script "first" in the directory "first" alters this +to suit your own system. +There is nothing against using the Kit as a cross-compiler +and by default produce code that can't run on your own system. +But...., you have to alter the Makefile for the Pascal frontend +in that case. +That Makefile assumes that calling \fBapc\fP and \fBacc\fP will +produce a.out's that can run on your own system. +Change the definitions of ACC and APC in that Makefile according to your +needs. +.NH 2 Pathnames .PP Absolute pathnames are concentrated in "h/em_path.h". -Only the pascal runtime system and the utility \fIack\fP use -absolute pathnames to access files in the kit. +Only the Pascal runtime system and the utility \fIack\fP use +absolute pathnames to access files in the Kit. The tree is distributed with /usr/em as the working directory. The definition of EM_DIR in em_path.h should be altered to specify the root directory for the Compiler Kit distribution on your system. +This is done automatically the the shell script "first" in the +directory "first". Em_path.h also specifies which directory should be used for temporary files. -Most programs from the kit do indeed use that directory +Most programs from the Kit do indeed use that directory although some remain stubborn and use /tmp or /usr/tmp. .LP The shape of the tree should not be altered lightly because @@ -335,75 +838,17 @@ utility \fIack\fP know the shape of the ACK tree. All pathnames in all Makefiles are relative, that is do not have "/" as the first character. The knowledge of the utility \fIack\fP about the shape of the tree is -concentrated in the files in the directory lib/ack. +concentrated in the files in the directory lib/*/descr and lib/descr/*. .NH -Commands +Makefiles .PP -The kit is distributed with all available commands in the bin -directory. -The commands distributed are: -.IP "\fIack\fP, \fIacc\fP, \fIapc\fP and their links" -.br -They are used to compile the Pascal, C, etc... programs. -.IP \fIarch\fP -.br -The archiver used for the EM- and universal assembler. -.IP "\fIem\fP and \fIeminform\fP" -.br -The EM interpretator for the PDP-11 and the program to unravel -its post-mortem information. -.LP -We currently make the kit available to our users by telling -them that they should include the bin directory of the kit in -their PATH shell variable. -The programs will still work when moved to a different -directory. -The copying should preferably be done with tar, since links are -heavily used. -Renaming of the programs linked to \fIack\fP will not always -produce the desired result. -This program uses its call name as an argument. -Any call name not being \fIcc\fP, \fIacc\fP, \fIpc\fP or \fIapc\fP will be -interpreted as the name of a 'machine description' and the -program will try to find a description file with that name. -All recompilations will only touch the utilities in the bin -directory, not your own copies. -.NH -Options -.PP -There is one important option in h/local.h. -The utility \fIack\fP uses a default machine name when called -as \fIacc\fP, \fIcc\fP, \fIapc\fP, \fIpc\fP or \fIack\fP. -The machine name used for default is determined by the -definition of ACKM in h/local.h. -The current definition is \fIpdp\fP. -.PP -The distribution is tailored to one specific opreating system per CPU type. -For some of these CPU's it is possible to tailor the distribution to another -operating system. -The steps to be taken are described in READ_ME (or README) files in the -subdirectories of the directory in EM_DIR/mach for that particular machine. -For example: The vax2 distribution is tailoerd to BSD4.1, but has #define's -for BSD4.1c and BSD4.2. -For the names and places of these define's look in EM_DIR/mach/vax2/cg and -EM_DIR/mach/vax2/libem. -.NH -Recompilation -.PP -The kit comes with binaries in the directories \fBbin\fP and -\fBlib\fP. -Some directories among mach/*/lib contain archives with object files, -notably mach/pdp/lib. -The binaries and object files are for a PDP 11/44 with floating -point running UNIX V7. -.PP -Almost all directories contain a "Makefile" or a shell command file called -"make". +Most directories contain a "Makefile". Apart from commands applying to that specific directory these files all recognize a few special commands. When called with one of these they will apply the command to their own directory and all subdirectories. The special commands are: +.sp 1 .IP "install" 20 recompile and install all binaries and libraries. .br @@ -412,9 +857,6 @@ They ignore such errors and notify the user with the message "~....... error code n: ignored". Whenever such a message appears in the output you can ignore it too. -.br -The installation of the PUBMAC macro package is not done -automatically from the higher level directory. .IP "cmp" recompile all binaries and libraries and compare them to the ones already installed. @@ -440,92 +882,15 @@ Example: .sp 1 .fi given as command in the home directory will cause -recompilation of all programs in the kit. -.LP -Recompilation of the complete kit lasts about 9 hours an a PDP -11/44. -.NH 2 -Recompilation on a different machine. -.PP -Installation on other systems will often require recompilation -of all programs. -The presence of a C compiler is essential for recompilation. -Except the Pascal compiler proper all programs are written in C. -Some modules are derived from \fIyacc\fP sources. -Retranslating these programs from that yacc source is not -necessary, although it might improve performance. -Some versions of \fIyacc\fP 'know' that the resulting C programs will -run on a 32-bit int machine. -C modules produced by such a \fIyacc\fP are not portable and -should not be used to (cross)compile programs for 16-bit machines. -We assume a version UNIX which, apart from the C-compiler, -contains most normal utilities, like ed, sed, grep, make, the -Bourne shell etc. -All Makefiles use the system C-compiler. -The existence of a backend for your system is of course essential -if you wish to produce executable files for that system. -When the backend exists it is also possible to boot the Pascal -Compiler, -that is written in Pascal itself. -The kit contains the compact code files for the 2/2 and 2/4 -versions of the Pascal compiler. -The current version of this compiler can only be used on machines -with a 16-bit word size and 16- or 32-bit pointers. -The Makefile automatically tries to boot the Pascal compiler -from one of these compact code files, if the compiler proves -unable to compile itself. -.PP -The native assemblers and loaders are used on PDP-11 and VAX. -The description files in lib/ack for other systems use our -universal assembler. -The load file produced by this assembler is not directly -usable in any system known to us, -but has to be converted before it can be put to use. -The \fIdl\fP programs present for some machines unravel -these load files and transmit commands to load memory -to a microprocessor over a serial line. -The PDP-11 version of our universal assembler is supplied -with a conversion program. -The file man/a.out.5 contains a description of the format of -the universal assembler load file, -it might be useful to those who wish or need to write their -own conversion programs. -.br -Berkeley UNIX for the VAX'en has (at least) three different -versions, BSD4.1a, BSD4.1c and BSD4.2. The READ_ME files in the -directories mach/vax2/cg, mach/vax2/libem, mach/vax4/cg and -mach/vax4/libem tell you how to adapt the vax2 and vax4 backend -to these versions. -.NH 2 -Recompiling libraries -.PP -The kit contains sources for part II and III of the C-library, except -the math functions, they are grabbed from our V7 system and sometimes -altered in a EM dependent way or replaced altogether when the original -was in assembly. -These files can be used to make libraries for the Ack C-compiler. -The recompilation process uses a few include files. -The include directory in the EM home directory contains a few more -or less system independent include files. -The system dependent include files are fetched from /usr/include -on the system you use to recompile. -This may lead to several problems. -Sometimes the system differs so much from V7 that certain manifest constants -do not exist any more. -At other times these include files were written for a compiler without -a restriction on name length. -In that case - I've seen it happen - people tend to use differing -identifiers that are identical in the first eight characters. -All these problems you have to solve yourself, -the libraries are only included as an extra and too much system -dependent to give any guarantees. +compilation of all programs in the directory and copying of the results +to the bin and lib directories. .NH -Fixes to the UNIX V7 system +Fixes for the UNIX V7 system .PP -UNIX System V7 has a few bugs that prevent a part of or the whole kit +UNIX System V7 has a few bugs that prevent a part of or the whole Kit from working properly. To be honest, we do not know which of the following changes are -essential to the functioning of our kit. +essential to the functioning of our Kit. .PP The file "doc/v7bugs.doc" gives for each of the following bugs a small test program and a diff listing of the source files that have to be @@ -546,12 +911,12 @@ and to check if the modifications are effective. .NH Testing .PP -Test sets are available in Pascal, C and EM assembly. +Test sets are available in Pascal, C, Basic and EM assembly. .IP em 8 .br The directory emtest contains a few EM test programs. The EM assembly files in these tests must be transformed into -load files, thereby avoiding use of the EM optimizer. +load files. These tests use the LIN and NOP instructions to mark the passing of each test. The NOP instruction prints the current line number during the @@ -563,9 +928,24 @@ In all other cases a bug showed its existence. .IP Pascal .br -The directory lang/pc/test contains a few pascal test programs. +The directory lang/pc/test contains a few Pascal test programs. All these programs print the number of errors found and a identification of these errors. +.sp 1 +.ti +4 +We also tested Pascal with the Validation Suite. +The Validation Suite is a collection of more than 200 Pascal programs, +designed by Brian Wichmann and Arthur Sale to test Pascal compilers. +We are not allowed to distribute it, but you may +request a copy from +.DS +Richard J. Cichelli +A.N.P.A. +1350 Sullivan Trail +P.O. Box 598 +Easton, Pennsylvania 18042 +USA +.DE .IP C .br The sub-directories in lang/cem/ctest contain C test programs. @@ -581,6 +961,18 @@ The differences will be presented on standard output. The contents of the result files depend on the wordsize, the xx.cem.g files on the distribution are intended for a 16-bit machine. +.IP Basic +.br +The directory lang/basic/test contains some forty basic programs. +Not all of these programs are correct, some have syntactic errors, +some simply don't work. +The Makefile in that directory attempts to compile and run +these tests. +If it compiles its output is compared to a file with suffix .g +which contains the output to be expected. +The make should be started with its standard input diverted +to /dev/null. +An example of the output od a make is present in the file Out.std. .NH Documentation .PP @@ -593,29 +985,26 @@ make install .DE .LP Several documents are provided: -.DS -doc/toolkit.doc: a general overview -doc/pcref.doc: the Pascal-frontend reference manual -doc/val.doc: the results of running the Pascal Validation Suite -doc/cref.doc: the C-frontend manual -doc/em.doc: a description of the EM machine architecture -doc/peep.doc: internal documentation for the peephole optimizer -doc/cg.doc: documentation for backend writers and maintainers -doc/regadd.doc: addendum to previous document describing register variables -doc/install.doc: this document -.DE -.LP -The Validation Suite is a collection of more than 200 Pascal programs, -designed by Brian Wichmann and Arthur Sale to test Pascal compilers. -We are not allowed to distribute it, but you may -request a copy from -.DS -Richard J. Cichelli -A.N.P.A. -1350 Sullivan Trail -P.O. Box 598 -Easton, Pennsylvania 18042 -USA -.DE +.TS +l l. +doc/toolkit.doc general overview +doc/em.doc description of the EM machine architecture +doc/ack.doc format of machine description files (lib/*/descr) +doc/basic.doc Basic reference manual +doc/pcref.doc Pascal-frontend reference manual +doc/val.doc results of running the Pascal Validation Suite +doc/cref.doc C-frontend manual +doc/LLgen.doc description of the LL(1) parser generator. +doc/peep.doc internal documentation for the peephole optimizer +doc/cg.doc documentation for backend writers and maintainers +doc/regadd.doc addendum to previous document describing register variables +doc/ncg.doc documentation for the newest backends +doc/v7bugs.doc bugs in the V7 system and how to fix them +doc/6500.doc MSC 6500 backend description. +doc/i80.doc Intel 8080 backend description. +doc/z80.doc Zilog Z80 backend description. +doc/install.doc this document +doc/install.pr this document (formatted) +.TE .LP Good luck.