123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011 |
- .\" $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.
|