12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232 |
- .\" $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, 4th and 5th distribution by Ceriel Jacobs)
- .AI
- Vakgroep Informatica
- Vrije Universiteit
- Amsterdam
- .NH
- Introduction
- .PP
- This document
- describes the process of installing the Amsterdam Compiler Kit (ACK).
- It depends on the combination of hard- and software how
- hard it will be to install the Kit.
- This description is intended for a Sun-3 or SPARC workstation.
- Installation on VAXen running Berkeley
- .UX
- or Ultrix,
- Sun-2 systems and most System V
- .UX
- systems should be easy.
- As of this distribution, installation on PDP-11's or other
- systems with a small address space is no longer supported.
- See section 8 for installation on other systems.
- .NH
- The ACK installation process
- .PP
- In the ACK installation process, three directory trees are used:
- .IP "-"
- the ACK source tree. This is the tree on the ACK distribution medium.
- For the rest of this document, we will refer to this directory
- as $SRC_HOME;
- .IP "-"
- a configuration tree. This tree is built by the installation process and
- is used to do compilations in. Its structure reflects that of the source tree,
- but this tree will mostly contain Makefiles and relocatable objects.
- For the rest of this document, we will refer to this directory
- as $CONFIG;
- .IP "-"
- an ACK users tree. This tree is also built by the installation process.
- For the rest of this document, we will refer to this directory
- as $TARGET_HOME;
- .LP
- After installation,
- the directories in $TARGET_HOME contain the following information:
- .if n .sp 1
- .if n .nr PD 0
- .IP "bin" 14
- the few utilities that knot things together.
- See the section about "Commands".
- .IP "lib"
- root of a tree containing almost all libraries used by
- commands.
- 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 "$SRC_HOME/mach".
- .IP "lib/descr"
- command descriptor files used by the program ack.
- .IP "lib/LLgen"
- files used by the LL(1) parser generator.
- .IP "lib/flex"
- files used by the lexical analyzer generator Flex.
- .IP "lib/m2"
- definition modules for Modula-2.
- .IP "lib.bin"
- root of a tree containing almost all binaries used by
- commands.
- All programs specific to a certain machine are collected in one subtree
- per machine. E.g. "lib.bin/pdp", "lib.bin/z8000".
- The names used here are the same names as used for subtrees
- of "$SRC_HOME/mach".
- .IP "lib.bin/ego"
- files used by the global optimizer.
- .IP "lib.bin/lint"
- binaries for the lint passes and lint libraries.
- .IP "lib.bin/ceg"
- files used by the code-expander-generator.
- .IP "etc"
- contains the file "ip_spec.t" needed for EM interpreters and EM documentation.
- .IP "config"
- contains two include files:
- .TS
- l l.
- em_path.h path names used by \fIack\fP, intended for all utilities
- local.h various definitions for local versions
- .TE
- These include files are specific for the current machine, so they
- are in a separate directory.
- .IP "include/_tail_cc"
- .br
- include files needed by modules
- in the C library from lang/cem/libcc.
- .IP "include/tail_ac"
- .br
- include files for ANSI C.
- .IP "include/occam"
- include files for occam.
- .IP "include/_tail_mon"
- .br
- more or less system independent include files needed by modules
- in the library lang/cem/libcc/mon.
- .IP "h"
- 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_ego.h definition of names for some global optimizer
- messages
- em_flag.h definition of bits in array em_flag in
- $TARGET_HOME/lib.bin/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_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
- ip_spec.h used by programs that read e.out files
- m2_traps.h used by the Modula-2 run-time system
- 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
- out.h defines the ACK a.out format
- pc_err.h definitions of error numbers in Pascal
- pc_file.h macro's used in file handling in Pascal
- pc_math.h used by the Pascal runtime system
- ranlib.h defines symbol table format for archives
- stb.h defines debugger symbol table types
- .TE
- .IP "modules"
- root of a tree containing modules for compiler writers.
- .IP "modules/man"
- manual pages for all modules.
- .IP "modules/lib"
- contains module objects.
- .IP "modules/h"
- include files for some of the modules.
- .IP "modules/pkg"
- include files for some of the modules.
- .IP "doc"
- this directory contains the unformatted documents for the Kit.
- A list of the available documents can be found in the last section.
- These documents must be processed by [nt]roff.
- .IP "man"
- man files for various utilities.
- .if n .nr PD 1v
- .LP
- When installing ACK on several types of machines with a shared file system,
- it may be useful to know that the "doc", "etc", "h",
- "include", "lib" and "man" sub-directories do not depend on this
- particular installation. They do not contain binaries or path-dependent
- information. These directories can therefore be shared between the
- ACK installations. This can be accomplished by creating the tree and
- suitable symbolic links before starting the installation process.
- .LP
- For instance, let us say there is a file-system that is accessible from
- the different machines as "/usr/share/local", and the ACK binary tree
- must be installed in "/usr/local/ack". In this case, proceed as follows:
- .IP \-
- create a directory "/usr/share/local/ack", with subdirectories
- "doc", "etc", "h", "include", "lib" and "man".
- .IP \-
- create a directory "/usr/local/ack" and
- then create symbolic links "doc" to "/usr/share/local/ack/doc", etc.
- .LP
- If this is done on all machines on which ACK will be installed, the
- machine-independent part only has to be installed once, preferably
- on the fastest processor (it takes a long time to install all libraries).
- .LP
- The directories in the source tree contain the following information:
- .if n .sp 1
- .if n .nr PD 0
- .IP "bin" 14
- source of some shell-scripts.
- .IP "lib"
- mostly description files for the "ack" program.
- .IP "etc"
- 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.
- .IP "mach"
- 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
- int source for an interpreter
- libbc to create Basic run-time system and libraries
- libcc to create C run-time system and libraries
- libcc.ansi to create ANSI C run-time system and libraries
- libpc to create Pascal run-time system and libraries
- libf77 to create Fortran run-time system and libraries
- libm2 to create Modula-2 run-time system and libraries
- liboc to create occam run-time system and libraries
- libem EM runtime system, only depending on CPU type
- libend library defining end, edata, etext
- libfp to create floating point library
- libdb to create debugger support library
- libsys system-dependent EM library
- libce fast cc-compatible C compiler library support
- ce code expander (fast back-end)
- test various tests
- .TE
- .in -3n
- Actually, some of these directories will only appear in the configuration tree.
- .br
- 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 makefiles for compiling libraries
- mach/proto/grind machine-independent debugger support
- .TE
- .IP "emtest"
- contains prototype of em test set.
- .IP "lang"
- just there to group the directories for all front-ends.
- .IP "lang/pc"
- the Pascal front-end.
- .IP "lang/pc/libpc"
- .br
- source of Pascal run-time system (in EM or C).
- .IP "lang/pc/test"
- some test programs written in Pascal.
- .IP "lang/pc/comp"
- the Pascal compiler proper.
- .IP "lang/cem"
- the 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
- .UX
- 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, mostly written in EM.
- .IP "lang/cem/cemcom"
- .br
- the compiler proper.
- .IP "lang/cem/cemcom.ansi"
- .br
- the ANSI C compiler proper.
- .IP "lang/cem/cpp.ansi"
- .br
- the ANSI C preprocessor.
- .IP "lang/cem/libcc.ansi"
- .br
- the ANSI C library sources.
- .IP "lang/cem/ctest"
- .br
- the 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/cem/lint"
- a C program checker.
- .IP "lang/cem/lint/lpass1"
- .br
- the first pass of lint.
- .IP "lang/cem/lint/lpass1.ansi"
- .br
- the first pass of lint, this time for ANSI C.
- .IP "lang/cem/lint/lpass2"
- .br
- the second pass of lint, shared between ANSI C and "old-fashioned" C.
- .IP "lang/cem/lint/llib"
- .br
- programs for producing lint libraries.
- .IP "lang/basic"
- the Basic front-end.
- .IP "lang/basic/src"
- .br
- the compiler proper.
- .IP "lang/basic/lib"
- .br
- the Basic run-time library source.
- .IP "lang/basic/test"
- .br
- various Basic programs.
- .IP "lang/occam"
- the 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"
- the Modula-2 front-end.
- .IP "lang/m2/comp"
- the compiler proper.
- .IP "lang/m2/libm2"
- source of Modula-2 run-time system (in EM, C and Modula-2).
- .IP "lang/m2/m2mm"
- the Modula-2 makefile generator.
- .IP "lang/m2/test"
- some Modula-2 example programs.
- .IP "lang/fortran"
- the Fortran front-end (translates Fortran into C). This compiler is not
- a part of ACK, but is included because it adds another language.
- The Fortran system carries the following copyright notice:
- .IP ""
- .nf
- /**************************************************************
- Copyright 1990, 1991 by AT&T Bell Laboratories and Bellcore.
- Permission to use, copy, modify, and distribute this software
- and its documentation for any purpose and without fee is hereby
- granted, provided that the above copyright notice appear in all
- copies and that both that the copyright notice and this
- permission notice and warranty disclaimer appear in supporting
- documentation, and that the names of AT&T Bell Laboratories or
- Bellcore or any of their entities not be used in advertising or
- publicity pertaining to distribution of the software without
- specific, written prior permission.
-
- AT&T and Bellcore disclaim all warranties with regard to this
- software, including all implied warranties of merchantability
- and fitness. In no event shall AT&T or Bellcore be liable for
- any special, indirect or consequential damages or any damages
- whatsoever resulting from loss of use, data or profits, whether
- in an action of contract, negligence or other tortious action,
- arising out of or in connection with the use or performance of
- this software.
- **************************************************************/
- .fi
- .IP "lang/fortran/comp"
- .br
- the compiler proper.
- .IP "lang/fortran/lib"
- .br
- source of Fortran runtime system and libraries.
- .IP "fast"
- contains sub-directories for installing the fast ACK compatible compilers.
- .IP "fast/driver"
- .br
- contains the sources of the fast ACK compatible compiler drivers.
- .IP "fcc"
- contains the fast cc-compatible C compiler for SUN-3 and VAX.
- .IP "util"
- contains directories with sources for various utilities.
- .IP "util/ack"
- the program used for translation with the Kit.
- .IP "util/opt"
- the EM peephole optimizer (*.k => *.m).
- .IP "util/ego"
- the global optimizer.
- .IP "util/topgen"
- the target optimizer generator.
- .IP "util/misc"
- decode (*.[km] => *.e) + encode (*.e => *.k).
- .IP "util/data"
- the C-code for $TARGET_HOME/lib.bin/em_data.a.
- These sources are created by the Makefile in `etc`.
- .IP "util/ass"
- the EM assembler (*.[km] + libraries => e.out).
- .IP "util/arch"
- the archivers to be used for all EM utilities.
- .IP "util/cgg"
- a program needed for compiling backends.
- .IP "util/ncgg"
- a program needed for compiling the newest backends.
- .IP "util/cpp"
- the C preprocessor.
- .IP "util/shf"
- various shell files.
- .IP "util/LLgen"
- the extended LL(1) parser generator.
- .IP "util/amisc"
- contains some programs handling ACK a.out format, such as anm, asize.
- .IP "util/cmisc"
- contains some programs to help in resolving name conflicts, and
- a dependency generator for makefiles.
- .IP "util/led"
- the ACK link-editor, reading ACK relocatable a.out format, and writing
- ACK a.out format.
- .IP "util/int"
- an EM interpreter, written in C. Very useful for checking out software,
- but slow.
- .IP "util/ceg"
- code expander generator.
- .IP "util/grind"
- a symbolic debugger.
- .IP "util/byacc"
- this is Berkeley yacc, in the public domain.
- .IP "util/flex"
- this is a replacement for lex. It carries the following copyright notice:
- .IP ""
- .nf
- Copyright (c) 1990 The Regents of the University of California.
- All rights reserved.
- This code is derived from software contributed to Berkeley by
- Vern Paxson.
- The United States Government has rights in this work pursuant
- to contract no. DE-AC03-76SF00098 between the United States
- Department of Energy and the University of California.
- Redistribution and use in source and binary forms are permitted
- provided that: (1) source distributions retain this entire
- copyright notice and comment, and (2) distributions including
- binaries display the following acknowledgement: ``This product
- includes software developed by the University of California,
- Berkeley and its contributors'' in the documentation or other
- materials provided with the distribution and in all advertising
- materials mentioning features or use of this software. Neither the
- name of the University nor the names of its contributors may be
- used to endorse or promote products derived from this software
- without specific prior written permission.
- THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
- IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
- WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
- PURPOSE.
- .fi
- .ne 4
- .if n .nr PD 1v
- .LP
- All path names mentioned in the text of this document are relative to
- $SRC_HOME, unless they start with '/' or one of $SRC_HOME,
- $TARGET_HOME or $CONFIG.
- .NH
- Restoring the ACK tree
- .PP
- The process of installing the Amsterdam Compiler Kit is quite simple.
- The first step is to restore the Amsterdam Compiler Kit
- distribution tree structure.
- Proceed as follows
- .IP " \-" 10
- Create a directory, for example /usr/share/local/src/ack, on a device
- with at least 15 Megabytes left. This directory will be $SRC_HOME.
- .IP " \-"
- Change to that directory (cd ...).
- .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.
- .NH
- Adapting ACK to the local 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 $SRC_HOME/first/first.
- Calling this script should be done
- from another directory, for instance an empty directory which will later
- become $CONFIG.
- .LP
- The actions of the
- .I first
- script are:
- .if n .sp 1
- .if n .nr PD 0
- .IP \-
- Asking for the path names of the ACK source directory ($SRC_HOME), the
- configuration directory ($CONFIG), and the ACK users directory ($TARGET_HOME).
- About 5M are needed for the configuration tree. The disk space needed
- for the ACK users tree depends on which front-ends and back-ends are to be
- installed.
- For instance, on our SPARC systems
- we have installed all languages and 6 back-ends, including the
- system-independent part. This amounts to about 16M.
- On our SUN-3 systems, we have installed all front-ends and 5 back-ends,
- but only the machine-dependent part. The machine-independent directories are
- symbolic links to the SPARC ACK users tree.
- We also have the fast ACK compilers
- installed on the SUN-3's.
- The total amount of disk-space used is less than 8M.
- .IP \-
- Asking for what type of system the binary tree must be produced for
- 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.
- The current choice is between:
- .TS
- c c c
- l l l.
- answer system type default machine
- vax_bsd4_1a VAX11 + BSD4.1a vax4
- vax_bsd4_2 VAX11 + BSD4.2 vax4
- vax_sysV_2 VAX11 + System V.2 vax4
- i386 Intel 80386 system + Xenix System V i386
- sun3 Sun-3 Motorola 68020 workstation sun3
- sun2 Sun-2 Motorola 68010 workstation sun2
- m68_sysV_0 68000 + Uniplus System V.0 mantra
- m68020 Motorola 68020 VME131 + System V/68 R2V2.1 m68020
- sparc Sun-4 or SPARC workstation running SunOs 4 sparc
- sparc_solaris Sun-4 or SPARC workstation running Solaris 2 sparc_solaris
- ANY Neither of the above ???
- .TE
- 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 sun3 and sparc systems are known to behave reasonably.
- The Sun systems should run SunOs Release 3.0 or newer.
- The i386 choice may also be used for Intel 80386 or 80486 systems
- running
- .UX
- System V Release 4. These systems are also able to run Xenix System V
- binaries.
- If the target system is not on this list, choose one that comes close.
- If none of them come close, use the "ANY" choice.
- For ANY, any name can be used,
- but the Kit will not be able to compile programs for the target system.
- See the section about "compilation
- on a different machine".
- .IP \-
- Setting the default machine for which code is
- produced to the local type of system according to the table above.
- This in done in the file "$TARGET_HOME/config/local.h".
- See also section 9.1.
- .IP \-
- Asking for things that don't have to be installed.
- .IP \-
- Producing a shell script called "INSTALL" that will take care of the
- ACK installation process.
- .NH
- Compiling the Kit
- .PP
- The next step in the installation process is to run the "INSTALL"
- shell-script. When using a Bourne-shell, type:
- .DS
- sh INSTALL > INSTALL.out 2>&1 &
- .DE
- When using a C-shell, type:
- .DS
- sh INSTALL >& INSTALL.out &
- .DE
- This shell-script performs the following steps:
- .if n .sp 1
- .if n .nr PD 0
- .IP \-
- Produce a configuration tree ($CONFIG), reflecting the structure of the
- source tree.
- .IP \-
- Produce Makefiles in $CONFIG.
- As mentioned before, compilations
- will be done in the configuration tree, not in the source tree.
- Most configuration directories will 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 $TARGET_HOME by these Makefiles.
- These Makefiles are produced from corresponding files called
- "proto.make" in the source tree. In fact, the "proto.make" files
- are almost complete Makefiles, except for some macro definitions that
- are collected by the \fIfirst\fP script.
- The Makefiles adhere to a standard which is described in the
- section 9.
- .IP \-
- Copy "Action" files to the configuration tree and editing them to
- reflect the choices concerning the parts of ACK that have to be
- installed. "Action" files are described below.
- .IP \-
- Copy part of the source tree to the ACK users tree (include files,
- manual pages, documentation, et cetera).
- .IP \-
- Calling the "TakeAction" script.
- All these Makefiles do not have to be called separately.
- We wrote a shell script calling the make's needed to install
- the whole Kit.
- This script consists of the file $SRC_HOME/TakeAction
- and a few files called Action in some configuration 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 indicating
- 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 the script TakeAction
- produces a small message indicating that it failed.
- .br
- For some programs the scripts already know they can't be
- installed on the local type of system.
- In that case they produce a message "Sorry, ....." and
- happily proceed with further installation commands.
- .if n .sp 1
- .if n .nr PD 1v
- .LP
- Installation of the Kit might take anything from a few
- hours to more than a day, depending on the speed of the local machine and
- what must be installed.
- .LP
- If the installation succeeded, the Kit is ready to be used.
- Read section 6 and the manuals provided
- with the Kit (in the $TARGET_HOME/man directory) on how to use it.
- .NH 2
- Problems
- .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 phenomenon see
- the file "$SRC_HOME/mach/m68k2/Unisoft_bug".
- (This observation was made in 1985 or so, so it is probably
- no longer true).
- .NH 3
- with backends
- .PP
- The backends for the PDP11, VAX, Motorola 68000 and 68020,
- SPARC, Intel 8086, and Intel 80386
- 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.
- .LP
- .sp 1
- .nf
- System definition -- done
- EM definition library -- done
- C utilities -- done
- Flex lexical analyzer generator -- done
- Yacc parser generator -- done
- system-call interface module -- done
- .
- .
- .
- EM Global optimizer -- done
- ACK archiver -- done
- Program 'ack' -- done
- Bootstrap for backend tables -- done
- Bootstrap for newest form of backend tables -- done
- .
- .
- .
- C frontend -- done
- ANSI-C frontend -- done
- ANSI-C preprocessor -- done
- ANSI-C header files -- done
- Failed for LINT C program checker, see lang/cem/lint/Out
- Pascal frontend -- done
- Basic frontend -- done
- .
- .
- .
- Vax 4-4 assembler -- done
- Vax 4-4 backend -- done
- Vax target optimizer -- done
- ACK a.out to VAX a.out conversion program -- done
- Sorry, Vax code expander library can only be made on vax* systems
- Vax 4-4 EM library -- done
- Vax 4-4 debugger support library -- done
- Vax 4-4 etext,edata,end library -- done
- Vax 4-4 systemcall interface -- done
- .
- .
- .
- .sp 1
- .fi
- .LP
- The lines starting with "Sorry, " indicate that certain programs cannot
- be translated on the local machine.
- The lines starting with "Failed for" indicate
- that certain programs/libraries were expected to,
- but did not compile.
- In this example, the installation of LINT failed.
- To repeat a certain part of the installation, look in
- the Action file, which resides in the root of the configuration tree,
- for the directory in which that part is to be found.
- If that directory contains an Action file issue the command
- "sh $CONFIG/bin/TakeAction", otherwise type "make install".
- .NH
- Commands
- .PP
- The following commands are available in the $TARGET_HOME/bin directory after compilation
- of the Kit:
- .IP "\fIack\fP, \fIacc\fP, \fIabc\fP, \fIapc\fP, \fIocm\fP, \fIm2\fP, \fIf2c\fP and their links" 14
- .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
- the archiver used for the EM- and universal assembler/loader.
- .IP \fIaal\fP
- the archiver used for ACK objects.
- .IP \fIem\fP
- this program selects a interpreter to execute an e.out file.
- Interpreters exist for PDP-11 and Motorola 68000 systems.
- .IP \fIeminform\fP
- the program to unravel the post-mortem information of
- the EM interpretator for the PDP-11.
- .IP \fILLgen\fP
- the LL(1) parser generator.
- .IP \fIack_sys\fP
- a shell script producing an identification of the target system.
- Used by some utilities to determine what is, and what is
- not feasible on the target system.
- .IP \fImarch\fP
- 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
- 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
- a utility for generating character tables for C-programs.
- .IP \fIint\fP
- an EM interpreter. This one is written in C, and is very useful for checking
- out programs.
- .IP \fIgrind\fP
- a source level debugger for C, ANSI-C, Modula-2 and Pascal.
- .IP "\fIafcc\fP, \fIafm2\fP, \fIafpc\fP"
- .br
- these are ACK-compatible fast C, Modula-2 and Pascal compilers,
- available for M68020, VAX and Intel 80386 systems. They compile very fast,
- but produce slow code.
- .IP \fIfcc\fP
- this is a cc-compatible fast C compiler, available on SUN-3 and VAX
- systems. It compiles very fast, but produces slow code.
- .LP
- We currently make the Kit available to our users by telling
- them that they should include the $TARGET_HOME/bin directory 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, \fIf2c\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 $TARGET_HOME/bin
- directory, not copies of these utilities.
- .NH
- Machines
- .PP
- Below is 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 gives the name in the bin directory.
- The column headed dir indicates which subdirectories of
- $TARGET_HOME/lib and/or $TARGET_HOME/lib.bin 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 available under the '-fp' option. In this case, software
- floating point emulation is used.
- .TS
- l l l l l l l.
- command system i/p languages fp dir remarks
- pdp PDP/UNIX V7 2/2 C * pdp
- Pascal
- Basic
- occam
- Modula-2
- vax4 VAX/BSD 4.? 4/4 C * vax4
- System V.2 Pascal
- Basic
- occam
- Modula-2
- Fortran
- sparc Sun-4 4/4 C * sparc
- Pascal
- Basic
- occam
- Modula-2
- Fortran
- sparc_solaris Sun-4 4/4 C * sparc_solaris
- Pascal
- Basic
- occam
- Modula-2
- Fortran
- m68k2 M68000/ 2/4 C + m68k2
- Unisoft Pascal
- Basic
- occam
- Modula-2
- m68k4 M68000/ 4/4 C + m68k4
- Unisoft Pascal m68k2
- Basic
- occam
- Modula-2
- Fortran
- pmds M68000/ 2/4 C + pmds Philips Micro
- PMDS Pascal m68k2 Devel. System
- Basic
- occam
- Modula-2
- pmds4 M68000/ 4/4 C + pmds4 Philips Micro
- PMDS Pascal m68k2 Devel. System
- Basic m68k4
- occam
- Modula-2
- Fortran
- mantra M68000/ 4/4 C + mantra
- Sys V.0 Pascal m68k2
- Basic m68k4
- occam
- Modula-2
- Fortran
- m68020 M68020/ 4/4 C + m68020
- Sys V/68 R2V2.1 Pascal
- Basic
- occam
- Modula-2
- Fortran
- sun3 Sun-3 R4.1 4/4 C + sun3
- Pascal m68020
- Basic
- occam
- Modula-2
- Fortran
- sun2 Sun-2 R3.0 4/4 C + sun2
- Pascal m68k4
- Basic m68k2
- occam
- Modula-2
- Fortran
- i86 IBM PC/IX 2/2 C + i86 IBM PC with PC/IX
- Pascal Causes kernel crashes
- Basic
- occam
- Modula-2
- xenix3 Microsoft 2/2 C + xenix3 IBM AT with Xenix
- Xenix V3 Pascal i86
- Basic
- occam
- Modula-2
- i386 SCO Xenix 4/4 C + i386 Intel 80386
- System V Pascal Xenix System V
- Basic
- occam
- Modula-2
- Fortran
- 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 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
- Fortran
- 6500 6502/BBC 2/2 C 6500 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
- Fortran
- 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 s2650 Assembler only
- arm Acorn 4/4 C * arm Assembler/loader
- Archimedes Pascal
- Basic
- occam
- Modula-2
- Fortran
- .TE
- .LP
- 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 a portable one, written in C.
- 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.
- .LP
- The program \fB$TARGET_HOME/bin/em\fP calls the appropriate
- interpreter.
- The interpreters are looked for in the em22, em24 and em44
- subdirectories of $TARGET_HOME/lib.bin.
- The third interpreter is available as the program \fB$TARGET_HOME/bin/int\fP
- in the bin directory.
- .NH
- Compilation on a different machine.
- .PP
- The Kit be installed and used as a cross-compiler
- for the languages it supports on
- .UX
- machine.
- The presence of most
- .UX
- utilities is essential for compilation.
- A few of the programs certainly needed are: C-compiler, sed,
- make, and awk.
- .NH 2
- Backend
- .PP
- The existence of a backend with a system call library
- for the target system is essential
- for producing executable files for that system.
- Rewriting the system call library if the one supplied does
- not work on the target system is fairly straightforward.
- If no backend exists for the target CPU type, a new backend has to be written
- which is a major undertaking.
- .NH 2
- Universal assembler/loader, link editor
- .PP
- For most machines, the description files in $TARGET_HOME/lib/*/descr use our
- universal assembler and 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 $TARGET_HOME/man/man5/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 $TARGET_HOME/man/man3/object.3.
- .NH
- Options
- .NH 2
- Default machine
- .PP
- There is one important option in $TARGET_HOME/config/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, \fIf2c\fP, or \fIack\fP.
- The machine name used for default is determined by the
- definition of ACKM in $TARGET_HOME/config/local.h.
- The Kit is distributed with "sun3" as the default machine,
- but the shell script "first" in the directory "first" alters this
- to suit the target system.
- There is nothing against using the Kit as a cross-compiler
- and by default produce code that can't run on the local system.
- .NH 2
- Pathnames
- .PP
- Absolute path names are concentrated in "$TARGET_HOME/config/em_path.h".
- Only the utilities \fIack\fP, \fIflex\fP, and \fILLgen\fP use
- absolute path names 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 binaries on the local system ($TARGET_HOME).
- This is done automatically by 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.
- The knowledge of the utility \fIack\fP about the shape of the tree is
- concentrated in the files in the directory $TARGET_HOME/lib/*/descr and $TARGET_HOME/lib/descr/*.
- .NH
- Makefiles
- .PP
- Most directories contain a "proto.make", from which a Makefile is derived.
- 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.
- 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 it can be ignored.
- .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 $TARGET_HOME/bin or
- one of the directories in the PATH environment variable.
- .IP clean
- remove all files not needed for day-to-day use,
- that is binaries not in $TARGET_HOME/bin or $TARGET_HOME/lib.bin, object files etc.
- .LP
- Example:
- .DS
- make install
- .DE
- given as command in a configuration directory will cause
- compilation of all programs in the directory and copying of the results
- to the $TARGET_HOME/bin and $TARGET_HOME/lib.bin directories.
- .NH
- Testing
- .PP
- Test sets are available in Pascal, C, Basic and EM assembly:
- .IP EM 8
- the directory $SRC_HOME/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
- the directory $SRC_HOME/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 a copy may
- be requested from
- .DS
- Richard J. Cichelli
- A.N.P.A.
- 1350 Sullivan Trail
- P.O. Box 598
- Easton, Pennsylvania 18042
- USA
- .DE
- .IP C
- the sub-directories in $SRC_HOME/lang/cem/ctest contain C test programs.
- The idea behind these tests is:
- if there is 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 word size,
- the xx.cem.g files on the distribution are intended for a
- 32-bit machine.
- .IP Basic
- the directory $SRC_HOME/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
- After installationm manual pages for Amsterdam Compiler Kit can be found
- in the $TARGET_HOME/man directory. Also, the following documents are provided
- in the $TARGET_HOME/doc directory:
- .TS
- l l.
- toolkit.doc general overview (CACM article)
- em.doc description of the EM machine architecture
- ack.doc format of machine description files (lib/*/descr)
- ansi_C.doc ANSI C implementation description
- basic.doc Basic reference manual
- pcref.doc Pascal-frontend reference manual
- val.doc results of running the Pascal Validation Suite
- crefman.doc C-frontend description
- LLgen description of the LL(1) parser generator
- peep.doc internal documentation for the peephole optimizer
- cg.doc documentation for backend writers and maintainers
- regadd.doc addendum to previous document describing register variables
- ncg.doc documentation for the newest backends
- v7bugs.doc bugs in the V7 system and how to fix them
- 6500.doc MSC 6500 backend description
- i80.doc Intel 8080 backend description
- z80.doc Zilog Z80 backend description
- m68020.doc Motorola M68000/M68020 backend description
- sparc.doc SPARC code expander description
- occam.doc occam-frontend description
- ego.doc Global Optimizer description
- top.doc Target Optimizer description
- int.doc description of the EM interpreter written in C
- ceg.doc documentation for code-expander writers and maintainers
- lint.doc documentation of LINT
- m2ref.doc Modula-2 frontend description
- install.doc this document
- install.pr this document (formatted for a simple line printer)
- .TE
- .LP
- Use the Makefile to get readable copies.
- .LP
- Good luck.
|