1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237 |
- .\" $Id$
- .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 sparc_solaris system has only been tested with the GNU C compiler,
- because we don't have the SUN C compiler (it is unbundled in Solaris 2).
- 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 installation mechanism of the Kit is supposed to be portable across
- .UX
- machines, so
- the Kit can be installed and used as a cross-compiler
- for the languages it supports on any
- .UX
- machine.
- The presence of most
- .UX
- utilities is essential for compilation.
- A few of the programs certainly needed are: sh, C-compiler, sed, ed,
- 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 by 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 installation, the 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.
|