Amsterdam Compiler Kit Installation Guide

-

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;

-

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;

-

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;

bin

the few utilities that knot things together. See the section about "Commands".

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".

lib/descr

command descriptor files used by the program ack.

lib/LLgen

files used by the LL(1) parser generator.

lib/flex

files used by the lexical analyzer generator Flex.

lib/m2

definition modules for Modula-2.

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".

lib.bin/ego

files used by the global optimizer.

lib.bin/lint

binaries for the lint passes and lint libraries.

lib.bin/ceg

files used by the code-expander-generator.

etc

contains the file "ip_spec.t" needed for EM interpreters and EM documentation.

config

contains two include files:

These include files are specific for the current machine, so they are in a separate directory.

include files needed by modules in the C library from lang/cem/libcc.

include files for ANSI C.

include/occam

include files for occam.

more or less system independent include files needed by modules in the library lang/cem/libcc/mon.

h

the #include files for:

modules

root of a tree containing modules for compiler writers.

modules/man

manual pages for all modules.

modules/lib

contains module objects.

modules/h

include files for some of the modules.

modules/pkg

include files for some of the modules.

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.

man

man files for various utilities.

−

create a directory "/usr/share/local/ack", with subdirectories "doc", "etc", "h", "include", "lib" and "man".

−

create a directory "/usr/local/ack" and then create symbolic links "doc" to "/usr/share/local/ack/doc", etc.

bin

source of some shell-scripts.

lib

mostly description files for the "ack" program.

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.

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.

These directories have subdirectories named:

Actually, some of these directories will only appear in the configuration tree.
The directory proto contains files used by most machines, like machine-independent sources and Makefiles.

emtest

contains prototype of em test set.

lang

just there to group the directories for all front-ends.

lang/pc

the Pascal front-end.

lang/pc/libpc

source of Pascal run-time system (in EM or C).

lang/pc/test

some test programs written in Pascal.

lang/pc/comp

the Pascal compiler proper.

lang/cem

the C front-end.

directories with sources of C runtime system, libraries (in EM or C).

sources for routines in chapter III of UNIX programmers manual, excluding stdio.

stdio sources.

sources for mathematical routines, normally available with the -lm option to cc.

sources for routines in chapter II, mostly written in EM.

the compiler proper.

the ANSI C compiler proper.

the ANSI C preprocessor.

the ANSI C library sources.

the C test set.

programs developed for pinpointing previous errors.

the test programs.

lang/cem/lint

a C program checker.

the first pass of lint.

the first pass of lint, this time for ANSI C.

the second pass of lint, shared between ANSI C and "old-fashioned" C.

programs for producing lint libraries.

lang/basic

the Basic front-end.

the compiler proper.

the Basic run-time library source.

various Basic programs.

lang/occam

the occam front-end.

the compiler proper.

source of occam run-time system (in EM or C).

some occam programs.

lang/m2

the Modula-2 front-end.

lang/m2/comp

the compiler proper.

lang/m2/libm2

source of Modula-2 run-time system (in EM, C and Modula-2).

lang/m2/m2mm

the Modula-2 makefile generator.

lang/m2/test

some Modula-2 example programs.

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:

/**************************************************************
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.
**************************************************************/

the compiler proper.

source of Fortran runtime system and libraries.

fast

contains sub-directories for installing the fast ACK compatible compilers.

fast/driver

contains the sources of the fast ACK compatible compiler drivers.

fcc

contains the fast cc-compatible C compiler for SUN-3 and VAX.

util

contains directories with sources for various utilities.

util/ack

the program used for translation with the Kit.

util/opt

the EM peephole optimizer (*.k => *.m).

util/ego

the global optimizer.

util/topgen

the target optimizer generator.

util/misc

decode (*.[km] => *.e) + encode (*.e => *.k).

util/data

the C-code for $TARGET_HOME/lib.bin/em_data.a. These sources are created by the Makefile in ‘etc‘.

util/ass

the EM assembler (*.[km] + libraries => e.out).

util/arch

the archivers to be used for all EM utilities.

util/cgg

a program needed for compiling backends.

util/ncgg

a program needed for compiling the newest backends.

util/cpp

the C preprocessor.

util/shf

various shell files.

util/LLgen

the extended LL(1) parser generator.

util/amisc

contains some programs handling ACK a.out format, such as anm, asize.

util/cmisc

contains some programs to help in resolving name conflicts, and a dependency generator for makefiles.

util/led

the ACK link-editor, reading ACK relocatable a.out format, and writing ACK a.out format.

util/int

an EM interpreter, written in C. Very useful for checking out software, but slow.

util/ceg

code expander generator.

util/grind

a symbolic debugger.

util/byacc

this is Berkeley yacc, in the public domain.

util/flex

this is a replacement for lex. It carries the following copyright notice:

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.

−

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.

−

Change to that directory (cd ...).

−

Extract all files from the distribution medium, for instance magtape: tar x.

−

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.

−

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.

−

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:

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 UNIX 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".

−

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.

−

Asking for things that don’t have to be installed.

−

Producing a shell script called "INSTALL" that will take care of the ACK installation process.

−

Produce a configuration tree ($CONFIG), reflecting the structure of the source tree.

−

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 first script. The Makefiles adhere to a standard which is described in the section 9.

−

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.

−

Copy part of the source tree to the ACK users tree (include files, manual pages, documentation, et cetera).

−

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.

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.

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".

arch

the archiver used for the EM- and universal assembler/loader.

aal

the archiver used for ACK objects.

em

this program selects a interpreter to execute an e.out file. Interpreters exist for PDP-11 and Motorola 68000 systems.

eminform

the program to unravel the post-mortem information of the EM interpretator for the PDP-11.

LLgen

the LL(1) parser generator.

ack_sys

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.

march

a shell script used while compiling libraries.

do the same as size, nm and strip, but for ACK object format.

mkdep

a dependency generator for makefiles.

some utilities for handling name clashes in C programs. Some systems have C-compilers with only 7 or 8 characters significant in identifiers.

tabgen

a utility for generating character tables for C-programs.

int

an EM interpreter. This one is written in C, and is very useful for checking out programs.

grind

a source level debugger for C, ANSI-C, Modula-2 and Pascal.

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.

fcc

this is a cc-compatible fast C compiler, available on SUN-3 and VAX systems. It compiles very fast, but produces slow code.

install

recompile and install all binaries and libraries.

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.

cmp

recompile all binaries and libraries and compare them to the ones already installed.

pr

print the sources and documentation on the standard output.

opr

make pr | opr

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.

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.

EM

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.

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.

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

     Richard J. Cichelli
     A.N.P.A.
     1350 Sullivan Trail
     P.O. Box 598
     Easton, Pennsylvania 18042
     USA

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.

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.