123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149 |
- .\" $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 subtrees
- 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 "lib/ego"
- .br
- Files used by the global optimizer.
- .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 \-
- Discovering how to call
- .I cc
- to get it to include the
- .I lex
- library.
- .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.
- The Sun systems should run Release 3.0 or later.
- 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.
- The same problem occurs for the m68k2 backend and the m68020 backend,
- and the same solution is chosen.
- .IP \-
- On machines with a 16-bit address space, the C-compiler has no
- builtin preprocessor. Arangements are made to this effect.
- .IP \-
- On the PDP,
- .I ranlib
- is not used, because it does not work properly,
- at least, on our 2.9 BSD system it does'nt.
- This is done by creating a dummy shell script
- .I ranlib
- in the ACK bin directory.
- If you are sure that your
- .I ranlib
- does work properly, you can just remove the shell script before
- installing the Kit.
- .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.
- .PP
- You may also have to change /usr/src/cmd/cc.c (/bin/cc) to pass the
- .B -i
- flag to
- .I ld.
- Also, /usr/src/cmd/ld.c (/bin/ld) may have to be changed to increase the
- number of library positions it can hold.
- On our (2.9 BSD) version, this is the constant
- .I NROUT.
- It must be at least 400.
- This may require separate I&D.
- Also, our version does not check that the table does not overflow.
- .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.
|