From d394fe5dda519b8a097cc13a5591585c9f1159f9 Mon Sep 17 00:00:00 2001 From: keie Date: Fri, 12 Apr 1985 11:20:15 +0000 Subject: [PATCH] Just newer. --- doc/install.doc | 1051 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 720 insertions(+), 331 deletions(-) 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 +.sp 1 +.nr PD 0 +.IP "bin" 14 .br -almost all binaries and shell files used by commands and -library em_data.a from misc/data -.IP "lib/ack" +the few utilities that knot things together. +See the section about "Commands". +.IP "lib" .br -The command descriptor files used by the program ack. -.nr PD 0 -.IP "bin" +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,210 +250,537 @@ 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 '/'. +ACK home directory, unless they start with '/'. +.sp 1 +.NH +Adapting ACK to your system .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). +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 -Pathnames +Compiling the Kit .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. -The tree is distributed with /usr/em as the working +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. -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. -Em_path.h also specifies which directory should be used for -temporary files. -Most programs from the kit do indeed use that directory -although some remain stubborn and use /tmp or /usr/tmp. +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 -The shape of the tree should not be altered lightly because -most Makefiles and the -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. +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 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" +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 -They are used to compile the Pascal, C, etc... programs. +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 and \fIeminform\fP" +.IP \fIem\fP .br -The EM interpretator for the PDP-11 and the program to unravel -its post-mortem information. +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 +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 +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, \fIpc\fP or \fIapc\fP will be +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. -All recompilations will only touch the utilities in the bin +The installation process will only touch the utilities in the Kit's bin directory, not your own copies. .NH -Options +Machines .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. +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 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. +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 -Recompilation +Compilation on a different machine. .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. +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 -Almost all directories contain a "Makefile" or a shell command file called -"make". -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: -.IP "install" 20 -recompile and install all binaries and libraries. -.br -Some Makefiles allow errors to occur in the programs they call. -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. -.IP pr -print the sources and documentation on the standard output. -.IP opr -make pr | opr -.br -Opr should be an off-line printer daemon. -On some systems it exists under another name e.g. lpr. -The easiest way to call such a spooler is using a shell script -with the name opr that calls lpr. -This script should be placed in /usr/bin or EM_DIR/bin or -one of the directories in your PATH. -.IP clean -remove all files not needed for day-to-day use, -that is binaries not in bin or lib, object files etc. -.LP -Example: -.nf -.sp 1 - make install -.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. +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 -Recompilation on a different machine. +Backend .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 +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. -When the backend exists it is also possible to boot the Pascal +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, -that is written in Pascal itself. -The kit contains the compact code files for the 2/2 and 2/4 +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/ack for other systems use our +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 load files and transmit commands to load memory +these our a.out 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. +.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 -Recompiling libraries +Compiling 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 +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. @@ -520,12 +794,103 @@ 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 -Fixes to the UNIX V7 system +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. +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 +although some remain stubborn and use /tmp or /usr/tmp. +.LP +The shape of the tree should not be altered lightly because +most Makefiles and the +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/*/descr and lib/descr/*. +.NH +Makefiles +.PP +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 +Some Makefiles allow errors to occur in the programs they call. +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. +.IP "cmp" +recompile all binaries and libraries and compare them to the +ones already installed. +.IP pr +print the sources and documentation on the standard output. +.IP opr +make pr | opr +.br +Opr should be an off-line printer daemon. +On some systems it exists under another name e.g. lpr. +The easiest way to call such a spooler is using a shell script +with the name opr that calls lpr. +This script should be placed in /usr/bin or EM_DIR/bin or +one of the directories in your PATH. +.IP clean +remove all files not needed for day-to-day use, +that is binaries not in bin or lib, object files etc. +.LP +Example: +.nf +.sp 1 + make install +.sp 1 +.fi +given as command in the home directory will cause +compilation of all programs in the directory and copying of the results +to the bin and lib directories. +.NH +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. -- 2.34.1