.\" $Header$ .nr LL 7.5i .nr PD 1v .TL Amsterdam Compiler Kit installation guide .AU Ed Keizer .AI Wiskundig Seminarium Vrije Universiteit Amsterdam .NH Introduction .PP 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. This description is intended for a PDP 11/44 running .UX Version 7. Installation on other PDP 11's should be easy, as long 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. .NH Restoring tree .PP The process of installing Amsterdam Compiler Kit is quite simple. It is important that the original Amsterdam Compiler Kit 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. .IP " -" Change to that directory (cd ...); it will be the working directory. .IP " -" Extract all files from the distribution medium, for instance magtape: \fBtar x\fP. .IP " -" 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 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. .nr PD 0 .IP "bin" .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 opcodes and pseudos in use, the operands allowed, effect in stack etc. etc. Make in this directory creates most of the files in h .IP "include" .br More or less system independent include files needed by modules in the C library from lang/cem/libcc. 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. .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 .IP "doc/em.doc" .br The EM-manual IR-81 .IP "doc/em.doc/int" .br The EM interpreter written in pascal .IP "mkun" .br The PUBMAC macro package for nroff/troff from the Katholieke Universiteit at Nijmegen. It is used for the EM reference manual, the Makefile installs the macro package in /usr/lib/tmac/tmac.mkun*. 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 .IP "emtest" .br Contains prototype of em test set. .IP "man" .br Man files for various utilities .IP "lang" .br just there to group the directories for all front-ends .IP "lang/pc" .br Pascal front-end .IP "lang/pc/libpc" .br Source of Pascal run-time system ( in EM or C ) .IP "lang/pc/test" .br Some test programs written in Pascal .IP "lang/pc/pem" .br The compiler proper .IP "lang/cem" .br C front-end .IP "lang/cem/libcc" .br 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 .IP "lang/cem/libcc/stdio" .br STDIO sources .IP "lang/cem/libcc/mon" .br Sources for routines in chapter II, written in EM .IP "lang/cem/comp" .br The compiler proper .IP "lang/cem/ctest" .br C test set .IP "lang/cem/ctest/cterr" .br Programs developed for pinpointing previous errors .IP "lang/cem/ctest/ct*" .br The test programs. .IP "util" .br Contains directories with various utilities .IP "util/opt" .br EM peephole optimizer (*.k => *.m) .IP "util/misc" .br Decode (*.[km] => *.e) + encode (*.e => *.k) .IP "util/data" .br The C-code for `lib/em_data.a` These sources are created by the Makefile in `etc` .IP "util/ass" .br The EM assembler ( *.[km] + libraries => e.out ) .IP "util/arch" .br The archiver to be used for ALL EM utilities .IP "util/cgg" .br A program needed for compiling backends. .IP "util/cpp" .br The V7 C preprocessor. .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). .NH 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. 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/ack. .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" .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". 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. .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. .NH Fixes to the UNIX V7 system .PP 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. .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 modified. .IP 1 Bug in the C optimizer for unsigned comparison .nr PD 0 .IP 2 The loader 'ld' fails for large data and text portions .IP 3 Floating point registers are not saved if more memory is needed. .IP 4 Floating point registers are not copied to child in fork(). .nr PD 1v .LP Use the test programs to see if the errors are present in your system and to check if the modifications are effective. .NH Testing .PP Test sets are available in Pascal, C 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. 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 test phase. Each test notifies its correctness by calling LIN with a unique number followed by a NOP which prints this line number. The test finishes normally with 0 as the last number printed In all other cases a bug showed its existence. .IP Pascal .br 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. .IP C .br The sub-directories in lang/cem/ctest contain C test programs. The idea behind these tests is: when you have a program called xx.c, compile it into xx.cem. Run it with standard output to xx.cem.r, compare this file to xx.cem.g, a file containing the 'ideal' output. Any differences will point to implementation differences or bugs. Giving the command "run gen" or plain "run" starts this process. 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. .NH Documentation .PP Manual pages for Amsterdam Compiler Kit can be copied to "/usr/man/man?" by the following commands: .DS cd man 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 .LP Good luck.