1113 lines
34 KiB
Plaintext
1113 lines
34 KiB
Plaintext
.\" $Header$
|
|
.if n .nr PD 1v
|
|
.if n .nr LL 78m
|
|
.if n .ll 78m
|
|
.TL
|
|
Amsterdam Compiler Kit Installation Guide
|
|
.AU
|
|
Ed Keizer
|
|
.AI
|
|
Vakgroep Informatica
|
|
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 VAX running BSD 4.1
|
|
.UX
|
|
\.
|
|
Installation on VAX BSD4.2/4.3 systems,
|
|
Sun-3 systems, and some System V systems
|
|
should be easy.
|
|
Installation on PDP 11's running
|
|
.UX
|
|
Version 7, BSD 2.8, or 2.9
|
|
should also 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 section 7 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 25 Megabytes 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
|
|
.bp
|
|
The directories in the tree contain the following information:
|
|
.sp 1
|
|
.nr PD 0
|
|
.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
|
|
.IP "etc"
|
|
.br
|
|
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"
|
|
and "util/data".
|
|
This make should only be called when the EM definition is
|
|
changed.
|
|
.IP "include/_tail_cc"
|
|
.br
|
|
Include files needed by modules
|
|
in the C library from lang/cem/libcc.
|
|
Especially needed for "stdio".
|
|
.IP "inlude/_tail_mon"
|
|
.br
|
|
More or less system independent include files needed by modules
|
|
in the library lang/cem/libcc/mon.
|
|
.IP "h"
|
|
.br
|
|
The #include files for:
|
|
.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.
|
|
ocm_chan.h Used by the occam run-time system
|
|
ocm_parco.h Used by the occam run-time system
|
|
ocm_proc.h Used by the occam run-time system
|
|
.TE
|
|
.IP "modules"
|
|
.br
|
|
root of a tree containing modules for compiler writers.
|
|
.IP "modules/man"
|
|
.br
|
|
manual pages for all modules.
|
|
.IP "modules/lib"
|
|
.br
|
|
contains module objects.
|
|
.IP "modules/src"
|
|
.br
|
|
contains sources of the modules, each module in its own directory.
|
|
.IP "modules/h"
|
|
.br
|
|
include files for some of the modules.
|
|
.IP "modules/pkg"
|
|
.br
|
|
include files for some of the modules.
|
|
.IP "doc"
|
|
.br
|
|
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"
|
|
.br
|
|
The EM-manual IR-81
|
|
.IP "doc/em/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.
|
|
This package is in the public domain.
|
|
.IP "mach"
|
|
.br
|
|
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.
|
|
cg the backend (*.m => *.s)
|
|
ncg the new backend (*.m => *.s)
|
|
as the assembler (*.s => *.o) or
|
|
assembler/linker (*.s + libraries => a.out)
|
|
cv Conversion programs for a.out files.
|
|
dl Down-load programs
|
|
top the target optimizer
|
|
|
|
libem Sources for EM runtime system, only depending on CPU type
|
|
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
|
|
liboc Used to create Occam run-time system and libraries
|
|
libsys Sources for system-dependent EM library
|
|
test Various tests
|
|
|
|
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/cg Current backend sources.
|
|
mach/proto/ncg New backend sources.
|
|
mach/proto/as Assembler sources.
|
|
mach/proto/top Target optimizer sources.
|
|
mach/proto/libg Makefile for compiling libraries.
|
|
.TE
|
|
.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 Pascal 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/cemcom"
|
|
.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 "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 "lang/occam"
|
|
.br
|
|
Occam front-end.
|
|
.IP "lang/occam/comp"
|
|
.br
|
|
The compiler proper.
|
|
.IP "lang/occam/lib"
|
|
.br
|
|
Source of Occam run-time system (in EM or C).
|
|
.IP "lang/occam/test"
|
|
.br
|
|
Some Occam programs.
|
|
.IP "util"
|
|
.br
|
|
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).
|
|
.IP "util/ego"
|
|
.br
|
|
The global optimizer.
|
|
.IP "util/topgen"
|
|
.br
|
|
The target optimizer generator..
|
|
.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 archivers 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 C preprocessor.
|
|
.IP "util/shf"
|
|
.br
|
|
Various shell files.
|
|
.IP "util/LLgen"
|
|
.br
|
|
The extended LL(1) parser generator.
|
|
.IP "util/amisc"
|
|
.br
|
|
Contains some programs handling ACK a.out format, such as anm, asize.
|
|
.IP "util/cmisc"
|
|
.br
|
|
Contains some programs to help in resolving name conflicts, and
|
|
a dependency generator for makefiles.
|
|
.IP "util/led"
|
|
.br
|
|
The ACK link-editor, reading ACK relocatable a.out format, and writing
|
|
ACK a.out format.
|
|
.ne 4
|
|
.LP
|
|
All pathnames mentioned in the text of this document are relative to the
|
|
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
|
|
.I 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 vax4
|
|
vax_bsd4_2 VAX11 with BSD4.2 vax4
|
|
vax_sysV_2 VAX11 with System V.2 vax4
|
|
pc_ix IBM PC with PC/IX i86
|
|
m68_unisoft Motorola 68000 with Unisoft UNIX m68k2
|
|
m68_pmds Philips PMDS pmds
|
|
m68_sysV_0 68000 with Uniplus UNIX System V.0 mantra
|
|
sun3 Sun 3 Motorola 68020 workstation sun3
|
|
sun2 Sun 2 Motorola 68010 workstation sun2
|
|
ANY Neither of the above m68k2
|
|
.TE
|
|
.sp 1
|
|
For some of these, the installation procedure has not been tested, as
|
|
we don't have them. However,
|
|
the pdp_v7, vax_bsd4_1a, pc_ix, sun3 and m68 systems are known to behave
|
|
reasonably.
|
|
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 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 \-
|
|
The VAX backend 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 directory mach/vax4/cg.
|
|
These must be copied to tables.h and tables.c
|
|
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 \-
|
|
For the m68k2 backend, the same problem occurs, and the same
|
|
solution is chosen.
|
|
.LP
|
|
.sp 1
|
|
Some actions still have to be done by hand.
|
|
.sp 1
|
|
.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.
|
|
Berkeley 2.8 or 2.9 may also have some of these bugs.
|
|
.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, but only
|
|
.B after
|
|
running the installation of the
|
|
Kit itself.
|
|
.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
|
|
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 TakeAction.
|
|
.PP
|
|
.DS
|
|
System definition -- done
|
|
EM definition -- done
|
|
LL(1) Parser generator -- done
|
|
EM definition library -- done
|
|
C utilities -- done
|
|
system-call interface module -- done
|
|
string routines module -- done
|
|
formatted print module -- done
|
|
assertion module -- done
|
|
memory allocation module -- done
|
|
fast, linear time malloc -- done
|
|
EM messages generation module -- done
|
|
identifier table module -- done
|
|
input module -- done
|
|
ACK-object reading and writing module -- done
|
|
EM-code reading module -- done
|
|
EM code generation module -- done
|
|
Modules -- done
|
|
C preprocessor -- done
|
|
ACK object utilities -- done
|
|
Encode/Decode -- done
|
|
Shell files in bin -- done
|
|
EM assembler -- done
|
|
EM Peephole optimizer -- done
|
|
.
|
|
.
|
|
.
|
|
EM Global optimizer -- done
|
|
ACK archiver -- done
|
|
Program 'ack' -- done
|
|
Bootstrap for backend tables -- done
|
|
Bootstrap for newest form of backend tables -- done
|
|
LED link editor -- done
|
|
TOPGEN target optimizer generator -- done
|
|
C frontend -- done
|
|
Basic frontend -- done
|
|
Occam frontend -- done
|
|
Intel 8086 assembler -- done
|
|
Intel 8086 backend -- done
|
|
Intel 8086 C libraries -- done
|
|
Intel 8086 EM library -- done
|
|
Intel 8086 Pascal library -- done
|
|
Intel 8086 PC/IX systemcall library -- done
|
|
Intel 8086 Basic library -- done
|
|
Intel 8086 Occam library -- done
|
|
Intel 8086 conversion program from ack.out --> PC/IX a.out -- done
|
|
Intel 8086 support -- done
|
|
.
|
|
.
|
|
.
|
|
Motorola 68000 assembler -- done
|
|
Motorola 68000 2-4 backend -- done
|
|
Motorola 68000 2-4 conversion program -- done
|
|
Motorola 68000 target optimizer -- done
|
|
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 Occam library -- done
|
|
Sorry, Motorola 68000 interpreters can only be made on m68* systems
|
|
Motorola 68000 2-4 support -- done
|
|
.
|
|
.
|
|
.
|
|
PDP 11 assembler -- done
|
|
PDP 11 backend -- done
|
|
PDP 11 target optimizer -- done
|
|
Sorry, PDP 11 interpreter can only be made on pdp* systems
|
|
Sorry, PDP 11 C libraries can only be made on pdp* systems
|
|
Sorry, PDP 11 EM library can only be made on pdp* systems
|
|
Sorry, PDP 11 systemcall library can only be made on pdp* systems
|
|
Sorry, PDP 11 Pascal library can only be made on pdp* systems
|
|
Sorry, PDP 11 Basic library can only be made on pdp* systems
|
|
Sorry, PDP 11 Occam library can only be made on pdp* systems
|
|
PDP 11 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 Occam library can only be made on vax* systems
|
|
Sorry, Vax 4-4 Basic library can only be made on vax* systems
|
|
Sorry, Vax 4-4 systemcall interface can only be made on vax* systems
|
|
Vax target optimizer -- done
|
|
Vax 4-4 support -- done
|
|
M68020 assembler -- done
|
|
M68020 backend -- done
|
|
M68020 EM library -- done
|
|
M68020 system call library -- done
|
|
M68020 C libraries -- done
|
|
M68020 PC library -- done
|
|
M68020 Basic library -- done
|
|
M68020 Occam library -- done
|
|
Sorry, M68020 VME131 System V/68 R2V2.1 conversion can only be made on m68020 systems
|
|
M68020 System V/68 support -- done
|
|
Ack.out --> Sun 3 M68020 a.out format conversion program -- done
|
|
Sun 3 M68020 systemcall library -- done
|
|
Sun 3 M68020 C libraries -- done
|
|
Sun 3 M68020 support -- done
|
|
Ack.out --> Sun 2 M68000 a.out format conversion program -- done
|
|
Sun 2 M68000 systemcall library -- done
|
|
Sun 2 M68000 C libraries -- done
|
|
Sun 2 M68000 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 EM_DIR/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, \fIocm\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/loader.
|
|
.IP \fIaal\fP
|
|
.br
|
|
The archiver used for ACK objects.
|
|
.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.
|
|
.IP "\fIasize\fP, \fIanm\fP, \fIastrip\fP"
|
|
.br
|
|
Do the same as \fIsize\fP, \fInm\fP and \fIstrip\fP, but for ACK object format.
|
|
.IP \fImkdep\fP
|
|
.br
|
|
A dependency generator for makefiles.
|
|
.IP "\fIcid\fP, \fIprid\fP, \fIcclash\fP"
|
|
.br
|
|
Some utilities for handling name clashes in C programs. Some
|
|
systems have C-compilers with only 7 or 8 characters significant in
|
|
identifiers.
|
|
.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
|
|
Occam
|
|
|
|
vax4 VAX/BSD 4.? 4/4 C * vax4 No assembler
|
|
System V.2 Pascal
|
|
Basic
|
|
Occam
|
|
|
|
m68k2 M68000/Unisoft 2/4 C m68k2
|
|
Pascal
|
|
Basic
|
|
Occam
|
|
|
|
m68k4 M68000/Unisoft 4/4 C m68k4
|
|
Pascal m68k2
|
|
Basic
|
|
Occam
|
|
|
|
pmds M68000/PMDS 2/4 C pmds Philips Micro
|
|
Pascal m68k2 Devel. System
|
|
Basic
|
|
Occam
|
|
|
|
pmds4 M68000/PMDS 4/4 C pmds4 Philips Micro
|
|
Pascal m68k2 Devel. System
|
|
Basic m68k4
|
|
Occam
|
|
|
|
mantra M68000/SysV.0 4/4 C mantra
|
|
Pascal m68k2
|
|
Basic m68k4
|
|
Occam
|
|
|
|
m68020 M68020/V/68 4/4 C m68020
|
|
R2V2.1 Pascal
|
|
Basic
|
|
Occam
|
|
|
|
sun3 SUN 3 R3.2 4/4 C sun3
|
|
Pascal m68020
|
|
Basic
|
|
Occam
|
|
|
|
sun2 SUN 2 ??? 4/4 C sun2
|
|
Pascal m68k4
|
|
Basic m68k2
|
|
Occam
|
|
|
|
i86 IBM PC/IX 2/2 C i86 IBM PC with PC/IX
|
|
Pascal Causes kernel crashes
|
|
Basic
|
|
Occam
|
|
|
|
z8000 Zilog 8000 2/2 C z8000 Central Data
|
|
Pascal CPU board
|
|
Basic Uses assembler/loader
|
|
Occam
|
|
|
|
int Same as int22
|
|
int22 EM machine 2/2 C * int22 Needs interpreter
|
|
Pascal
|
|
Basic
|
|
Occam
|
|
|
|
int24 EM machine 2/4 C * int24 Needs interpreter
|
|
Pascal
|
|
Basic
|
|
Occam
|
|
|
|
int44 EM machine 4/4 C * int44 Needs interpreter
|
|
Pascal
|
|
Basic
|
|
Occam
|
|
|
|
6500 6502/BBC 2/2 C 6500 Uses assembler/loader
|
|
Pascal
|
|
Basic
|
|
Occam
|
|
|
|
6800 Bare 6800 6800 Assembler only
|
|
|
|
6805 Bare 6805 6805 Assembler only
|
|
|
|
6809 Bare 6809 6809 Assembler only
|
|
|
|
ns Bare NS16032 4/4 C ns
|
|
Pascal
|
|
Basic
|
|
Occam
|
|
|
|
i80 Hermac/z80 2/2 C i80
|
|
Pascal
|
|
Basic
|
|
Occam
|
|
|
|
z80 Hermac/z80 2/2 C z80 \fIi80\fP is faster
|
|
Pascal
|
|
Basic
|
|
Occam
|
|
|
|
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 for the Pascal compiler proper all programs
|
|
can be translated on a normal UNIX system, like V7, BSD4.1.
|
|
.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, 4/4 and 2/4
|
|
versions of the Pascal compiler.
|
|
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/loader, link editor
|
|
.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 and for most machines our link editor.
|
|
The load file produced 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
|
|
our a.out files and transmit commands to load memory
|
|
to a microprocessor over a serial line.
|
|
The file man/ack.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.
|
|
Also, a module is included to read and write our a.out format.
|
|
See modules/man/object.3.
|
|
.NH 2
|
|
Compiling libraries
|
|
.PP
|
|
The Kit contains sources for part II and III of the C-library.
|
|
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 the include files
|
|
it needs.
|
|
An effort has been made to make the part III stuff as system independent as
|
|
possible.
|
|
.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, \fIocm\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 "vax4" 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 utilities \fIack\fP and \fILLgen\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
|
|
from working properly. Berkeley 2.8 and/or 2.9 may also suffer from this
|
|
problem.
|
|
To be honest, we do not know which of the following changes are
|
|
essential to the functioning of our Kit. The change to "ld" is.
|
|
.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, 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.
|
|
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.
|
|
.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.
|
|
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
|
|
32-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 of a make is present in the file Out.std.
|
|
.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
|
|
but do this \fBafter\fR compiling the Kit.
|
|
.LP
|
|
Several documents are provided:
|
|
.TS
|
|
l l.
|
|
doc/toolkit.doc general overview (CACM article)
|
|
doc/em 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/crefman.doc C-frontend description
|
|
doc/LLgen 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/m68020.doc Motorola M68000/M68020 backend description
|
|
doc/occam Occam-frontend description
|
|
doc/ego Global Optimizer description
|
|
doc/top Target Optimizer description
|
|
doc/install.doc this document
|
|
doc/install.pr this document (formatted)
|
|
.TE
|
|
.PP
|
|
The names in this list without a suffix are in fact a subdirectory.
|
|
Use the Makefile to get readable copies.
|
|
.LP
|
|
Good luck.
|