1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252 |
- .\" $Header$
- .if n .nr PD 1v
- .if n .nr LL 78m
- .if n .ll 78m
- .TL
- Amsterdam Compiler Kit Installation Guide
- .AU
- Ed Keizer
- (revised for 3rd and 4th distribution by Ceriel Jacobs)
- .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-2 or Sun-3 systems running Release 3.0 or newer, 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.
- .PP
- On small machines, like the PDP-11, the Modula-2 front-end is only available
- for 2 byte integer, 2 byte pointer machines, so you can not cross-compile
- Modula-2 programs for f.i. a MC68000, on a PDP-11.
- .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 "include/_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
- m2_traps.h Used by the Modula-2 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
- libm2 Used to create Modula-2 run-time system and libraries
- libfp Used to create floating point library
- libsys Sources for system-dependent EM library
- test Various tests
- int Source for an interpreter
- ce code expander (fast back-end producing either .s or .o files)
- .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/fp Floating point package 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/math"
- .br
- Sources for mathematical routines, normally available with the
- \fB-lm\fP option to \fIcc\fP.
- .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 "lang/m2"
- .br
- Modual-2 front-end.
- .IP "lang/m2/comp"
- .br
- The compiler proper.
- .IP "lang/m2/libm2"
- .br
- Source of Modula-2 run-time system (in EM, C and Modula-2).
- .IP "lang/m2/m2mm"
- .br
- Modula-2 makefile generator.
- .IP "lang/m2/test"
- .br
- Some Modula-2 example 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.
- .IP "util/int"
- .br
- An EM interpreter, written in C. Very useful for checking out software.
- Unfortunately not available for small machines.
- .IP "util/ceg"
- .br
- Code expander 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
- .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
- xenix3 IBM AT with Microsoft Xenix V3.2 xenix3
- i386 Intel 80386 system running Xenix System V i386
- 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
- SMALL Neither of the above, small address space i86
- 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.
- For others, the installation procedure has only been tested with earlier
- distributions, as we don't have those systems anymore.
- However,
- the pdp_v7, vax_bsd4_1a, sun3 and m68 systems are known to behave
- reasonably.
- The Sun systems should run Release 3.0 or newer.
- 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 the VAX the Kit uses the native assembler and linker.
- The description file lib/vax4/descr has to be altered to prevent
- attempts to assemble programs with unsuitable assemblers.
- The original descr file is 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 need 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 && make clean".
- 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 comment out the relevant entries.
- Lines starting with a '!' are comments.
- .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, \fIm2\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.
- .IP "\fItabgen\fP
- .br
- A utility for generating character tables for C-programs.
- .IP \fIint\fP
- .br
- An EM interpreter. This one is written in C, and is very useful for checking
- out programs.
- .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,
- \fIocm\fP, \fIm2\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 that floating point can be used
- for that particular machine. A + in that column indicates that floating
- point is only available under the '-fp' option. In this case, software
- floating point emulation is used.
- .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
- Modula-2
- vax4 VAX/BSD 4.? 4/4 C * vax4 No assembler
- System V.2 Pascal
- Basic
- Occam
- Modula-2
- m68k2 M68000/Unisoft 2/4 C + m68k2
- Pascal
- Basic
- Occam
- Modula-2
- m68k4 M68000/Unisoft 4/4 C + m68k4
- Pascal m68k2
- Basic
- Occam
- Modula-2
- pmds M68000/PMDS 2/4 C + pmds Philips Micro
- Pascal m68k2 Devel. System
- Basic
- Occam
- Modula-2
- pmds4 M68000/PMDS 4/4 C + pmds4 Philips Micro
- Pascal m68k2 Devel. System
- Basic m68k4
- Occam
- Modula-2
- mantra M68000/SysV.0 4/4 C + mantra
- Pascal m68k2
- Basic m68k4
- Occam
- Modula-2
- m68020 M68020/V/68 4/4 C + m68020
- R2V2.1 Pascal
- Basic
- Occam
- Modula-2
- sun3 SUN 3 R3.0 4/4 C + sun3
- Pascal m68020
- Basic
- Occam
- Modula-2
- sun2 SUN 2 R3.0 4/4 C + sun2
- Pascal m68k4
- Basic m68k2
- Occam
- Modula-2
- i86 IBM PC/IX 2/2 C + i86 IBM PC with PC/IX
- Pascal Causes kernel crashes
- Basic
- Occam
- Modula-2
- xenix3 Microsoft Xenix V3 2/2 C + xenix3 IBM AT with Xenix
- Pascal i86
- Basic
- Occam
- Modula-2
- i386 SCO Xenix System V 4/4 C + i386 Intel 80386 system with Xenix System V
- Pascal
- Basic
- Occam
- Modula-2
- minix Minix PC 2/2 C + minix IBM PC running Minix
- Pascal i86
- Basic
- Occam
- Modula-2
- minixST ST Minix 2/4 C + minixST Atari ST running Minix
- Pascal m68k2
- Basic
- Occam
- Modula-2
- z8000 Zilog 8000 2/2 C z8000 Central Data
- Pascal CPU board
- Basic Uses assembler/loader
- Occam
- Modula-2
- em22 EM machine 2/2 C * em22 Needs interpreter
- Pascal
- Basic
- Occam
- Modula-2
- em24 EM machine 2/4 C * em24 Needs interpreter
- Pascal
- Basic
- Occam
- Modula-2
- em44 EM machine 4/4 C * em44 Needs interpreter
- Pascal
- Basic
- Occam
- Modula-2
- 6500 6502/BBC 2/2 C 6500 Uses assembler/loader
- Pascal
- Basic
- Occam
- Modula-2
- 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
- Modula-2
- i80 Hermac/z80 2/2 C i80
- Pascal
- Basic
- Occam
- Modula-2
- z80 Hermac/z80 2/2 C z80 \fIi80\fP is faster
- Pascal
- Basic
- Occam
- Modula-2
- s2650 Signetics 2650 s2650 Assembler only
- .TE
- .PP
- The commands \fBem22\fP, \fBem24\fP and \fBem44\fP
- produce e.out files with EM machine code which must be interpreted.
- The Kit contains three interpreters: one running under PDP 11/V7 UNIX,
- one for the M68000, running under the PMDS system, SUN systems,
- the Mantra system, etc, and one, written in C and running on large machines.
- The first one can only interpret 2/2 e.out files,
- the second takes 2/4 and 4/4 files,
- and the last one takes 2/2, 2/4 and 4/4.
- The PDP 11 interpreter executes floating point instructions.
- The interpreter for the M68000 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 em22, em24 and em44
- subdirectories of lib.
- The third interpreter is available on large machines as the program \fIint\fP
- in the bin directory.
- .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,
- \fIm2\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/int description of the EM interpreter written in C
- doc/ceg documentation for code-expander writers and maintainers
- doc/m2ref.doc Modula-2 frontend 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.
|