ack/doc/install.doc

.\" $Header$
.nr PD 1v
.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 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.
Installation on VAX'en running BSD4.1 should also be easy.
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 15 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"
.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:
.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
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
.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 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 + libraries => a.out )
cv	Conversion programs for a.out files.
dl	Down-load programs

libem	Sources for EM runtime system, intended to depend only 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
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/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/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 "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 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/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/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
ACK home directory, unless they start with '/'.
.sp 1
.NH
Adapting ACK to your system
.PP
Before compiling the sources in the Kit some installation dependent
actions have to be taken.
Most of these are performed by an interactive shell script in the file
first in a directory of the same name.
.LP
These actions are:
.sp 1
.IP \-
Automatically checking whether you included the ACK bin directory in your
shell PATH.
See also the section on "commands".
.IP \-
Automatically setting the pathname of the parent directory in ../h/em_path.h.
See also the section on "pathnames".
.IP \-
Asking you for the type of system you have
and creating the shell script "ack_sys" in the Kit's bin directory.
Several utilities make use of "ack_sys" to determine the type of
system you have.
The current choice is between:
.sp 1
.TS
c c c
l l l.
answer	system type	default machine
pdp_v7	PDP11 with sep I/D and version 7	pdp
vax_bsd4_1a	VAX11 with BSD4.1a	vax2
vax_bsd4_1c	VAX11 with BSD4.1c	vax2
vax_bsd4_2	VAX11 with BSD4.2	vax2
pc_ix	IBM PC with PC/IX	ix
m68_unisoft	Motorola 68000 with Unisoft UNIX	m68k2
m68_pmds	Philips PMDS	pmds
ANY	Neither of the above	m68k2
.TE
.sp 1
As mentioned before the installation on VAX'en and PDP11's should
be easy.
The pc_ix and m68 systems are also known to behave reasonably,
but the installation procedure has not been extensively tested.
For ANY you can use any name you fancy,
but the Kit will not be able to compile programs for your system.
If you want to do that you have to read the section about "compilation
on a different machine".
.IP \-
Automatically setting the default machine for which code is
produced to your own type of system according to the table above.
This in done in the file "h/local.h".
See also the section 8.2.
.IP \-
Automatically editing a few description files that tell
ACK to use your system's assembler.
On both the PDP and the VAX the Kit uses the native assembler and linker.
The description files in lib/pdp/descr, lib/vax2/descr and
lib/vax4/descr have to be altered to prevent
attempts to assemble programs with unsuitable assemblers.
The original descr files are copied to descr.orig.
.IP \-
Automatically installing the special include directory for vax2.
This will only be done on VAX systems.
The shell scripts needed by ACK for the vax2 backend differ slightly
from the one issued by Berkeley.
.br
Note: this has only been tested under BSD4.1a.
.IP \-
Automatically editing the system.h file in mach/vax[24]/libem.
Again, only on VAXen.
These files reflect whether you have BSD4.1a, BSD4.1c or BSD4.2.
.LP
.sp 1
Some actions still have to be done by hand.
.sp 1
.IP \-
The VAX backends cannot be booted on systems
with a 16-bit address space systems.
The program lib/cgg needs more memory than available to transform
the table into files suitable for the C-compiler.
Therefore files tables1.h and tables1.c have been provided in
the directories mach/vax[24]/cg.
These must be copied to tables.h and tables.c on their respective
directories to get working code-generators for the VAX on PDP11's.
You will hardly be able to use these, because the 
code generated by these programs cannot be
assembled and loaded without a native VAX assembler,
but its nice to be able to look at the code produced.
.IP \-
The installation of the PUBMAC macro package is not done
automatically because you needs super-user privileges to do
that on most systems.
This macro package is used with several of the documents
provided in the Kit.
.IP \-
UNIX V7 as originally distributed contains a few bugs that
prevent correct execution of some of the larger programs.
See the section named "Fixes for the UNIX V7 system"
about what to do.
.IP \-
The manual files for the Kit can be copied to their
appropriate place in the system by giving the command "make install"
in the man directory.
.NH
Compiling the Kit
.PP
The next step in the installation process is to compile
the sources in the Kit and install them in their places
in the lib and bin directories.
.PP
Most directories containing sources have Makefiles
used to compile and install the programs in that
directory.
All programs needed for compilation and/or cross compilation
with the Kit are installed in the directories "bin" and "lib"
by these Makefiles.
These Makefiles adhere to a standard which is described in the
section 9.
.LP
You do not have to start all these Makefiles separately.
We wrote a shell script calling the make's needed to install
the whole Kit.
This script consists of the file TakeAction in the Kit's root
directory and a few files called Action in some directories.
The Action files describe in a very simple form which actions
have to be performed in which directories.
The default action is to start "make install".
The output of each make is diverted to a file called "Out"
in the same directory as the make was started in.
If the make was successful (return code 0) the Out file is removed
and the script TakeAction produces a small message telling you
that it succeeded in fulfilling its goal.
If the make was not successful (any other return code) the Out file
is left alone for further examination and a small message telling you
to look at that file is produced by TakeAction.
.LP
For some programs the scripts already know they can't be
installed on your type of system.
In that case they produce a message "Sorry, ....." and
happily proceed with further installation commands.
.PP
Compilation of the whole Kit might take anything from a few
hours to more than a day.
If you do not want to install libraries etc. for a particular
machine you can edit the file Action and remove the relevant entries.
.PP
If this compilation went reasonably successful you should be able
to use the Kit.
Read the next section and the manuals provided
with the Kit (in the man directory) on how to use it.
.NH 2
Problems you may meet
.NH 3
on Unisoft m68000 systems.
.PP
The Unisoft C compiler has a bug which impedes the correct
translation of the peephole optimizer.
For a more detailed description of this phenomenen see
the file "mach/m68k2/Unisoft_bug".
.NH 3
with backends
.PP
The backends for the PDP11, VAX with BSD4.1, Motorola 68000 and
Intel 8086 have been heavily used by ourselves and are well tested.
The backends for the other machines are known to run our own
test programs,
but might reveal errors when more heavily used.
.NH 2
An example output of TakaAction.
.PP
.DS
System definition -- done
EM definition -- done
C preprocessor -- done
EM definition library -- done
Encode/Decode -- done
Shell files in bin -- done
EM assembler -- done
EM Peephole optimizer -- done
ACK archiver -- done
Program 'ack' -- done
Bootstrap for backend tables -- done
LL(1) Parser generator -- done
Bootstrap for newest form of backend tables -- done
C frontend -- done
Basic frontend -- done
Intel 8086 assembler -- done
Intel 8086 backend -- done
Intel 8086 download program(s) -- done
Intel 8086 C libraries -- done
Intel 8086 EM library -- done
Intel 8086 Pascal library -- done
Intel 8086 Stand-alone io library -- done
Intel 8086 Basic library -- done
Intel 8086 support -- done
MSC6500 assembler -- done
MSC6500 backend -- done
MSC6500 download program(s) -- done
MSC6500 C libraries -- done
MSC6500 EM library -- done
MSC6500 Pascal library -- done
MSC6500 Basic library -- done
MSC6500 support -- done
Motorola 6800 assembler -- done
Motorola 6800 support -- done
Motorola 6805 assembler -- done
Motorola 6805 support -- done
Motorola 6809 assembler -- done
Motorola 6809 support -- done
Intel 8080 assembler -- done
Intel 8080 support -- done
2-2 Interpreter C libraries -- done
2-2 Interpreter Pascal library -- done
2-2 Interpreter Basic library -- done
2-2 Interpreter support -- done
2-4 Interpreter C libraries -- done
2-4 Interpreter Pascal library -- done
2-4 Interpreter Basic library -- done
2-4 Interpreter support -- done
4-4 Interpreter C libraries -- done
4-4 Interpreter Pascal library -- done
4-4 Interpreter Basic library -- done
4-4 Interpreter support -- done
Sorry, IBM PC/IX conversion program(s) can only be made on pc_ix systems
IBM PC/IX support -- done
Motorola 68000 2-4 assembler -- done
Motorola 68000 2-4 backend -- done
Sorry, Motorola 68000 interpreters can only be made on m68* systems
Sorry, the m68k? conversion program has to be translated on the target machine
Motorola 68000 2-4 C libraries -- done
Motorola 68000 2-4 EM library -- done
Motorola 68000 2-4 Pascal library -- done
Motorola 68000 2-4 System library -- done
Motorola 68000 2-4 Basic library -- done
Motorola 68000 2-4 support, see mach/m68k2/Out
NS16032 assembler -- done
NS16032 support -- done
PDP 11 assembler -- done
PDP 11 backend -- done
PDP 11 interpreter -- done
PDP 11 C libraries -- done
PDP 11 EM library -- done
PDP 11 Pascal library -- done
PDP 11 Basic library -- done
PDP 11 support -- done
PMDS download program(s) -- done
PMDS EM library -- done
PMDS support -- done
Signetics 6502 assembler -- done
Signetics 2650 support -- done
Vax 2-4 backend -- done
Sorry, Vax 2-4 Basic library can only be made on vax* systems
Sorry, Vax 2-4 C libraries can only be made on vax* systems
Sorry, Vax 2-4 EM library can only be made on vax* systems
Sorry, Vax 2-4 Pascal library can only be made on vax* systems
Vax 2-4 support -- done
Vax 4-4 backend -- done
Sorry, Vax 4-4 C libraries can only be made on vax* systems
Sorry, Vax 4-4 EM library can only be made on vax* systems
Sorry, Vax 4-4 Pascal library can only be made on vax* systems
Sorry, Vax 4-4 Basic library can only be made on vax* systems
Vax 4-4 support, see mach/vax4/Out
Z80 assembler -- done
Z80 support -- done
Zilog Z8000 assembler -- done
Zilog Z8000 backend -- done
Zilog Z8000 C libraries -- done
Zilog Z8000 EM library -- done
Zilog Z8000 Pascal library -- done
Zilog Z8000 Basic library -- done
Zilog Z8000 support -- done
Nascon download program(s) -- done
Nascom support -- done
Failed for Pascal frontend, see lang/pc/pem/Out
.DE
.PP
The lines starting with "Sorry, " tell you that certain programs cannot
be translated on your machine.
The lines starting with "Failed for" tell
you that certain programs/libraries which were expected to,
but did not compile.
Only the Pascal frontend failed to compile in this example.
If you want to repeat a certain part of the installation, look in
the Action file for the directory in which that part is to be found.
If that directory contains an Action file issue the command
"sh EMHOME/TakeAction", otherwise type "make install".
.NH
Commands
.PP
The following commands are available in the bin directory after compilation
of the kit:
.sp 1
.IP "\fIack\fP, \fIacc\fP, \fIabc\fP, \fIapc\fP and their links"
.br
The names mentioned here can be used to compile Pascal, C, etc... programs.
Most of the links can be used to generate code for a particular
machine.
See also the section about "Machines".
.IP \fIarch\fP
.br
The archiver used for the EM- and universal assembler.
.IP \fIem\fP
.br
This program selects a interpreter to execute an e.out file.
Interpreters exist for PDP-11 and Motorola 68000 systems.
.IP \fIeminform\fP
.br
The program to unravel the post-mortem information of
the EM interpretator for the PDP-11.
.IP \fILLgen\fP
.br
The LL(1) parser generator.
.IP \fIack_sys\fP
.br
A shell script producing an identification of your system.
Used by some utilities to determine what is, and what is
not feasible on your system. (Like translating PDP assembly).
.IP \fImarch\fP
.br
A shell script used while compiling libraries.
.sp 1
.LP
We currently make the Kit available to our users by telling
them that they should include the bin directory of the Kit in
their PATH shell variable.
The programs will still work when moved to a different
directory or linked to.
Copying should preferably be done with tar, since links are
heavily used.
Renaming of the programs linked to \fIack\fP will not always
produce the desired result.
This program uses its call name as an argument.
Any call name not being \fIcc\fP, \fIacc\fP, \fIabc\fP, \fIpc\fP or \fIapc\fP will be
interpreted as the name of a 'machine description' and the
program will try to find a description file with that name.
The installation process will only touch the utilities in the Kit's bin
directory, not your own copies.
.NH
Machines
.PP
Underneath you will find a table with entries for all commands in
the bin directory used to (cross)compile for a particular machine.
The name in the first column give the name in the bin directory.
The column headed dir indicates which subdirectories of
lib are needed for compilation.
The column head i/p contains the integer and pointer size used in units of
bytes.
The subdirectories with the same name in mach contain the sources.
A * in the column headed 'fp' indicates whether floating point can be used
for that particular machine.
.TS
c c c c c c c
l l l l l l l.
command	system	i/p	languages	fp	dir	remarks

pdp	PDP/UNIX V7	2/2	C	*	pdp	needs sep. I/D
			Pascal			No assembler
			Basic

vax2	VAX/BSD 4.?	2/4	C	*	vax2	No assembler
			Pascal
			Basic

vax4	VAX/BSD 4.?	4/4	C	*	vax4	No assembler
			Basic

m68k2	M68000/Unisoft	2/4	C		m68k2
			Pascal
			Basic

m68k4	M68000/PMDS	4/4	C		m68k2
			Basic		m68k4

pmds	M68000/PMDS	2/2	C		pmds	Philips Micro
			Pascal		m68k2	Devel. System
			Basic

i86	Bare 8086	2/2	C		i86	For ISBC 86/12A
			Pascal
			Basic

ix	IBM PC/IX	2/2	C		ix	IBM PC with PC/IX
			Pascal		i86	Causes kernel crashes
			Basic

z8000	Zilog 8000	2/2	C		z8000	Central Data
			Pascal			CPU board
			Basic

int						Same as int22
int22	EM machine	2/2	C	*	int22	Needs interpreter
			Pascal
			Basic

int24	EM machine	2/4	C	*	int24	Needs interpreter
			Pascal
			Basic

int44	EM machine	4/4	C	*	int44	Needs interpreter
			Basic

6500	6502/BBC	2/2	C		6500
			Pascal
			Basic

6800	Bare 6800				6800	Assembler only

6805	Bare 6805				6805	Assembler only

6809	Bare 6809				6809	Assembler only

ns	Bare NS16032				ns	Assembler only

i80	Hermac/z80	2/2	C		i80
			Pascal
			Basic

z80	Hermac/z80	2/2	C		z80	\fIi80\fP is faster
			Pascal
			Basic

s2650	Signetics 2650				s2650	Assembler only
.TE
.PP
The commands \fBint\fP, \fBint22\fP, \fBint24\fP and \fBint44\fP
produce e.out files with EM machine code which must be interpreted.
The Kit contains two interpreters one running under PDP 11/V7 UNIX
and the PMDS system.
The first one can only interpret 2/2 e.out files,
the other takes 2/4 and 4/4 files.
The PDP 11 interpreter executes floating point instructions.
The interpreter on the PMDS traps if you try to use floating point.
.LP
The program \fBem\fP in the bin directory calls the appropriate
interpreter.
The interpreters are sought in the int22, int24 and int44
subdirectories of lib.
.NH
Compilation on a different machine.
.PP
The Kit be installed and used as a cross-compiler
for C and Basic programs on any UNIX machine.
The presence of most UNIX utilities is essential for compilation.
A few of the programs you certainly need are: C-compiler, Yacc, sed,
make and lex.
Except the Pascal compiler proper all programs 
can be translated on a normal UNIX system, like V7, BSD4.1.
.PP
We know there are certain problems with System V.
Some of the character/string routines are named differently,
ctype(3) seems to have a different naming scheme.
The most annoying thing is that in printf format strings the
role of the format %03x is taken by something like %.3x.
Several programs suffer from this format change.
.NH 2
Backend
.PP
The existence of a backend with a system call library
for your system is essential
if you wish to produce executable files for that system.
Rewriting the system call library if the one supplied does
not work on your system is fairly straightforward.
If no backend exists for your CPU type you have to write one yourself
which is a major undertaking.
.NH 2
Pascal
.PP
When you can produce executable code it is also possible to boot the Pascal
Compiler,
which is written in Pascal itself.
The Kit contains the compact code files for the 2/2 and 2/4
versions of the Pascal compiler.
The current version of this compiler can only be used on machines
with a 16-bit word size and 16- or 32-bit pointers.
The Makefile automatically tries to boot the Pascal compiler
from one of these compact code files, if the compiler proves
unable to compile itself.
.NH 2
Universal assembler
.PP
The native assemblers and loaders are used on PDP-11 and VAX.
The description files in lib/*/descr for other systems use our
universal assembler.
The load file produced by this assembler is not directly
usable in any system known to us,
but has to be converted before it can be put to use.
The \fIcv\fP programs convert our a.out format into
executable files.
The \fIdl\fP programs present for some machines unravel
these our a.out files and transmit commands to load memory
to a microprocessor over a serial line.
The file man/a.out.5 contains a description of the format of
the universal assembler load file,
it might be useful to those who wish or need to write their
own conversion programs.
.LP
One warning has to be issued here.
The universal assembler a.out files contain integers and/or
longs with the bytes in the order your own system uses.
Copying these files to machines with a different byte order
will not always produce the desired results.
.NH 2
Compiling libraries
.PP
The Kit contains sources for part II and III of the C-library,
they have been grabbed from our V7 system and sometimes
altered in a EM dependent way or replaced altogether when the original
was in assembly.
These files can be used to make libraries for the Ack C-compiler.
The recompilation process uses a few include files.
The include directory in the EM home directory contains a few more
or less system independent include files.
Some backends, like the vax2 backend also need a few include files
of their own, replacing ones in /usr/include.
The include files are sought in lib/*/include.
The system dependent include files are fetched from /usr/include
on the system you use to recompile.
This may lead to several problems.
Sometimes the system differs so much from V7 that certain manifest constants
do not exist any more.
At other times these include files were written for a compiler without
a restriction on name length.
In that case \- I've seen it happen \- people tend to use differing
identifiers that are identical in the first eight characters.
All these problems you have to solve yourself,
the libraries are only included as an extra and too much system
dependent to give any guarantees.
.NH
Options
.NH 2
Default machine
.PP
There is one important option in h/local.h.
The utility \fIack\fP uses a default machine name when called
as \fIacc\fP, \fIcc\fP, \fIabc\fP, \fIapc\fP, \fIpc\fP or \fIack\fP.
The machine name used for default is determined by the
definition of ACKM in h/local.h.
The Kit is distributed with "pdp" as the default machine,
but the shell script "first" in the directory "first" alters this
to suit your own system.
There is nothing against using the Kit as a cross-compiler
and by default produce code that can't run on your own system.
But...., you have to alter the Makefile for the Pascal frontend
in that case.
That Makefile assumes that calling \fBapc\fP and \fBacc\fP will
produce a.out's that can run on your own system.
Change the definitions of ACC and APC in that Makefile according to your
needs.
.NH 2
Pathnames
.PP
Absolute pathnames are concentrated in "h/em_path.h".
Only the Pascal runtime system and the utility \fIack\fP use
absolute pathnames to access files in the Kit.
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.
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, 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
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
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:
.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.