622 lines
20 KiB
Plaintext
622 lines
20 KiB
Plaintext
.\" $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.
|