From bf01ff880d99826eabdfb4add61d7570d19ef2b9 Mon Sep 17 00:00:00 2001 From: ceriel Date: Wed, 16 Oct 1991 13:33:50 +0000 Subject: [PATCH] Adapted for 5th distribution --- doc/install.doc | 925 ++++++++++++++++++++++++------------------------ 1 file changed, 467 insertions(+), 458 deletions(-) diff --git a/doc/install.doc b/doc/install.doc index 5aa7b7f4a..f8ed15866 100644 --- a/doc/install.doc +++ b/doc/install.doc @@ -6,7 +6,7 @@ Amsterdam Compiler Kit Installation Guide .AU Ed Keizer -(revised for 3rd and 4th distribution by Ceriel Jacobs) +(revised for 3rd, 4th and 5th distribution by Ceriel Jacobs) .AI Vakgroep Informatica Vrije Universiteit @@ -18,156 +18,183 @@ This document describes the process of installing Amsterdam Compiler Kit. It depends on your combination of hard- and software how hard it will be to install the Kit. -This description is intended for a VAX running BSD 4.1 +This description is intended for a Sun-3 workstation. +Installation on VAXen running Berkeley Unix or Ultrix, +Sun-2 or Sun-4 systems and most System V .UX -\. -Installation on VAX BSD4.2/4.3 systems, -Sun-2 or Sun-3 systems running Release 3.0 or newer, and some System V systems -should be easy. -Installation on PDP 11's running -.UX -Version 7, BSD 2.8, or 2.9 -should also be easy, as long -as they have separate instruction and data space. -Installation on machine's without this feature, like PDP 11/34, -PDP 11/60 requires extensive surgery on some programs and is -thought of as impossible. +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 7 for installation on other systems. -.PP -On small machines, like the PDP-11, the Modula-2 front-end is only available -for 2 byte integer, 2 byte pointer machines, so you can not cross-compile -Modula-2 programs for f.i. a MC68000, on a PDP-11. .NH -Restoring tree +The ACK installation process .PP -The process of installing Amsterdam Compiler Kit is quite simple. -It is important that the original Amsterdam Compiler Kit -distribution tree structure is restored. -Proceed as follows -.IP " \-" 10 -Create a directory, for example /usr/em, on a device -with at least 25 Megabytes left. -.IP " \-" -Change to that directory (cd ...); it will be the working directory. -.IP " \-" -Extract all files from the distribution medium, for instance -magtape: -\fBtar x\fP. -.IP " \-" -Keep a copy of the original distribution to be able to repeat the process -of installation in case of disasters. -This copy is also useful as a reference point for diff-listings. +Before starting the installation, you have to know some things about the +installation process. In this 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. 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 -.bp -The directories in the tree contain the following information: -.sp 1 -.nr PD 0 +After installation, +the directories in the ACK users tree contain the following information: +.if n .sp 1 +.if n .nr PD 0 .IP "bin" 14 -.br the few utilities that knot things together. See the section about "Commands". .IP "lib" -.br -root of a tree containing almost all binaries and libraries used by +root of a tree containing almost all libraries used by commands. All files specific to a certain machine are collected in one subtree per machine. E.g. "lib/pdp", "lib/z8000". The names used here are the same names as used for subtrees -of "mach". +of "$SRC_HOME/mach". .IP "lib/descr" -.br Command descriptor files used by the program ack. .IP "lib/LLgen" -.br Files used by the LL(1) Parser-generator. -.br -.IP "lib/ego" -.br +.IP "lib/flex" +Files used by the lexical analyser 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. -.br +.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" -.br -The main description of EM sits here. -Files (e.g. em_table) describing -the opcodes and pseudos in use, -the operands allowed, effect in stack etc. etc. -Make in this directory creates most of the files in "h" -and "util/data". -This make should only be called when the EM definition is -changed. +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 Pathnames 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. Especially needed for "stdio". +.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" -.br The #include files for: .TS l l. -arch.h Definition of the ACK archive format. -as_spec.h Used by EM assembler and interpreters. -bc_io.h Used by the Basic run-time system. -bc_string.h Used by the Basic run-time system. -cg_pattern.h Used by the backend program "cg" and its bootstrap. -cgg_cg.h Used by the backend program "ncg" and its bootstrap. +arch.h Definition of the ACK archive format +as_spec.h Used by EM assembler and interpreters +bc_io.h Used by the Basic run-time system +bc_string.h Used by the Basic run-time system +cg_pattern.h Used by the backend program "cg" and its bootstrap +cgg_cg.h Used by the backend program "ncg" and its bootstrap em_abs.h Contains trap numbers and address for lin and fil -em_flag.h Definition of bits in array em_flag in lib/em_data.a +em_ego.h Definition of names for some global optimizer messages +em_flag.h Definition of bits in array em_flag in 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_path.h Pathnames used by \fIack\fP, intended - for all utilities em_pseu.h pseudo instruction => compact mapping em_ptyp.h Useful for compact code reading/writing, defines classes of parameters -em_reg.h Definition of mnemonics indicating register type. +em_reg.h Definition of mnemonics indicating register type em_spec.h Definition of constants used in compact code -local.h Various definitions for local versions -pc_err.h Definitions of error numbers in Pascal -pc_file.h Macro's used in file handling in Pascal -pc_size.h Sizes of objects used by Pascal compiler and - run-time system. -em_reg.h Definition of names for register types. +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 -m2_traps.h Used by the Modula-2 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_size.h Sizes of objects used by Pascal compiler and + run-time system +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" -.br root of a tree containing modules for compiler writers. .IP "modules/man" -.br manual pages for all modules. .IP "modules/lib" -.br contains module objects. -.IP "modules/src" -.br -contains sources of the modules, each module in its own directory. .IP "modules/h" -.br include files for some of the modules. .IP "modules/pkg" -.br include files for some of the modules. .IP "doc" -.br This directory contains the unformatted documents for the Kit. A list of the available documents can be found in the last section. .IP "doc/em" -.br The EM-manual IR-81. .IP "doc/em/int" -.br The EM interpreter written in Pascal. +.IP "man" +Man files for various utilities +.if n .nr PD 1v +.LP +If you have a shared file system and want to install ACK on several types +of machines, 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 you have a file-system that is accessible from +the different machines as "/usr/share/local". You can then create a +directory "/usr/share/local/ack", and give it subdirectories "doc", "etc", "h", +"include", "lib" and "man". Also, let us assume that you want the +ack binary tree in "/usr/local/ack". You can create this directory and +then create symbolic links "doc" to "/usr/share/local/ack/doc", etc. +.LP +If you do this 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 "mkun" -.br The PUBMAC macro package for nroff/troff from the Katholieke Universiteit at Nijmegen. It is used for the EM reference manual. @@ -175,7 +202,6 @@ The Makefile installs the macro package in /usr/lib/tmac. This package is in the public domain. .IP "mach" -.br just there to group the directories with all sources for each machine. The section about "Machines" of this manual indicates which subdirectories are used for which systems. @@ -198,7 +224,9 @@ libcc Used to create C run-time system and libraries libpc Used to create Pascal run-time system and libraries liboc Used to create Occam run-time system and libraries libm2 Used to create Modula-2 run-time system and libraries +libf77 Used to create Fortran run-time system and libraries libfp Used to create floating point library +libdb Used to create debugger support library libsys Sources for system-dependent EM library test Various tests @@ -207,6 +235,8 @@ int Source for an interpreter ce code expander (fast back-end producing either .s or .o files) .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 @@ -218,37 +248,31 @@ mach/proto/as Assembler sources. mach/proto/top Target optimizer sources. mach/proto/fp Floating point package sources. mach/proto/libg Makefile for compiling libraries. +mach/proto/grind machine-independent debugger support .TE .IP "emtest" -.br Contains prototype of em test set. -.IP "man" -.br -Man files for various utilities .IP "lang" -.br Just there to group the directories for all front-ends .IP "lang/pc" -.br Pascal front-end .IP "lang/pc/libpc" .br Source of Pascal run-time system (in EM or C) .IP "lang/pc/test" -.br Some test programs written in Pascal -.IP "lang/pc/pem" -.br +.IP "lang/pc/comp" The Pascal compiler proper .IP "lang/cem" -.br C front-end .IP "lang/cem/libcc" .br Directories with sources of C runtime system, libraries (in EM or C) .IP "lang/cem/libcc/gen" .br -Sources for routines in chapter III of UNIX programmers manual, +Sources for routines in chapter III of +.UX +programmers manual, excluding Stdio .IP "lang/cem/libcc/stdio" .br @@ -256,13 +280,22 @@ Stdio sources .IP "lang/cem/libcc/math" .br Sources for mathematical routines, normally available with the -\fB-lm\fP option to \fIcc\fP. +\fB-lm\fP option to \fIcc\fP .IP "lang/cem/libcc/mon" .br Sources for routines in chapter II, written in EM .IP "lang/cem/cemcom" .br The compiler proper +.IP "lang/cem/cemcom.ansi" +.br +ANSI C compiler proper +.IP "lang/cem/cpp.ansi" +.br +ANSI C preprocessor +.IP "lang/cem/libcc.ansi" +.br +ANSI C library sources .IP "lang/cem/ctest" .br C test set @@ -271,210 +304,259 @@ C test set Programs developed for pinpointing previous errors .IP "lang/cem/ctest/ct*" .br -The test programs. +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" +Basic front-end .IP "lang/basic/src" .br -The compiler proper. +The compiler proper .IP "lang/basic/lib" .br -Basic run-time library source. +Basic run-time library source .IP "lang/basic/test" .br -Various Basic programs. +Various Basic programs .IP "lang/occam" -.br -Occam front-end. +Occam front-end .IP "lang/occam/comp" .br -The compiler proper. +The compiler proper .IP "lang/occam/lib" .br -Source of Occam run-time system (in EM or C). +Source of Occam run-time system (in EM or C) .IP "lang/occam/test" .br -Some Occam programs. +Some Occam programs .IP "lang/m2" -.br -Modual-2 front-end. +Modual-2 front-end .IP "lang/m2/comp" -.br -The compiler proper. +The compiler proper .IP "lang/m2/libm2" -.br -Source of Modula-2 run-time system (in EM, C and Modula-2). +Source of Modula-2 run-time system (in EM, C and Modula-2) .IP "lang/m2/m2mm" -.br -Modula-2 makefile generator. +Modula-2 makefile generator .IP "lang/m2/test" +Some Modula-2 example programs +.IP "lang/fortran" +Fortran front-end (translates fortran into C). The stuff in this +sub-directory 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 -Some Modula-2 example programs. -.IP "util" +The compiler proper +.IP "lang/fortran/lib" .br +Source of fortran runtime system and libraries. +.IP "util" Contains directories with sources for various utilities .IP "util/ack" -.br -The program used for translation with the Kit. +The program used for translation with the Kit .IP "util/opt" -.br -EM peephole optimizer (*.k => *.m). +EM peephole optimizer (*.k => *.m) .IP "util/ego" -.br -The global optimizer. +The global optimizer .IP "util/topgen" -.br -The target optimizer generator.. +The target optimizer generator .IP "util/misc" -.br Decode (*.[km] => *.e) + encode (*.e => *.k). .IP "util/data" -.br -The C-code for `lib/em_data.a`. +The C-code for `lib.bin/em_data.a`. These sources are created by the Makefile in `etc`. .IP "util/ass" -.br The EM assembler (*.[km] + libraries => e.out). .IP "util/arch" -.br The archivers to be used for ALL EM utilities. .IP "util/cgg" -.br A program needed for compiling backends. .IP "util/ncgg" -.br A program needed for compiling the newest backends. .IP "util/cpp" -.br The C preprocessor. .IP "util/shf" -.br Various shell files. .IP "util/LLgen" -.br The extended LL(1) parser generator. .IP "util/amisc" -.br Contains some programs handling ACK a.out format, such as anm, asize. .IP "util/cmisc" -.br Contains some programs to help in resolving name conflicts, and a dependency generator for makefiles. .IP "util/led" -.br The ACK link-editor, reading ACK relocatable a.out format, and writing ACK a.out format. .IP "util/int" -.br -An EM interpreter, written in C. Very useful for checking out software. -Unfortunately not available for small machines. +An EM interpreter, written in C. Very useful for checking out software, +but slow. .IP "util/ceg" -.br Code expander generator. +.IP "util/grind" +A symbolic debugger. +.IP "util/byacc" +This is Berleley 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 pathnames mentioned in the text of this document are relative to the -ACK home directory, unless they start with '/'. -.sp 1 +ACK source directory, 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/em, on a device +with at least 12 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 your system .PP Before compiling the sources in the Kit some installation dependent actions have to be taken. Most of these are performed by an interactive shell script in the file -.I first -in a directory of the same name. +.I $SRC_HOME/first/first. +If you don't want to write in the $SRC_HOME tree you can call this +script from another directory, f.i. an empty directory which will later +become $CONFIG. .LP -These actions are: -.sp 1 -.IP \- -Automatically checking whether you included the ACK bin directory in your -shell PATH. -See also the section on "commands". -.IP \- -Automatically setting the pathname of the parent directory in ../h/em_path.h. -See also the section on "pathnames". +The actions of the +.I first +script are: +.if n .sp 1 +.if n .nr PD 0 .IP \- -Discovering how to call -.I cc -to get it to include the -.I lex -library. +Asking you for the pathnames of the ACK source directory, the +configuration directory, and the ACK users directory. .IP \- Asking you for the type of system you have and creating the shell script "ack_sys" in the Kit's bin directory. Several utilities make use of "ack_sys" to determine the type of system you have. The current choice is between: -.sp 1 .TS c c c l l l. answer system type default machine -pdp_v7 PDP11 with sep I/D and version 7 pdp vax_bsd4_1a VAX11 with BSD4.1a vax4 vax_bsd4_2 VAX11 with BSD4.2 vax4 vax_sysV_2 VAX11 with System V.2 vax4 -pc_ix IBM PC with PC/IX i86 -xenix3 IBM AT with Microsoft Xenix V3.2 xenix3 i386 Intel 80386 system running Xenix System V i386 -m68_unisoft Motorola 68000 with Unisoft UNIX m68k2 -m68_pmds Philips PMDS pmds +sun3 Sun-3 Motorola 68020 workstation sun3 +sun2 Sun-2 Motorola 68010 workstation sun2 m68_sysV_0 68000 with Uniplus UNIX System V.0 mantra -sun3 Sun 3 Motorola 68020 workstation sun3 -sun2 Sun 2 Motorola 68010 workstation sun2 -SMALL Neither of the above, small address space i86 -ANY Neither of the above m68k2 +m68020 Motorola M68020 VME131 + running Unix System V/68 R2V2.1 m68020 +sparc Sun-4 or SPARC workstation sparc +ANY Neither of the above ??? .TE -.sp 1 For some of these, the installation procedure has not been tested, as we don't have them. For others, the installation procedure has only been tested with earlier distributions, as we don't have those systems anymore. However, -the vax_bsd4_1a, sun3 and m68 systems are known to behave +the vax_bsd4_2, sun3 and sparc systems are known to behave reasonably. -The Sun systems should run Release 3.0 or newer. +The Sun systems should run SunOs Release 3.0 or newer. For ANY you can use any name you fancy, but the Kit will not be able to compile programs for your system. If you want to do that you have to read the section about "compilation on a different machine". .IP \- -Automatically setting the default machine for which code is +Setting the default machine for which code is produced to your own type of system according to the table above. -This in done in the file "h/local.h". -See also the section 8.2. -.IP \- -Automatically editing a few description files that tell -ACK to use your system's assembler. +This in done in the file "$TARGET_HOME/config/local.h". +See also the section 9.1. .IP \- -The VAX backend cannot be booted on systems -with a 16-bit address space systems. -The program lib/cgg needs more memory than available to transform -the table into files suitable for the C-compiler. -Therefore files tables1.h and tables1.c have been provided in -the directory mach/vax4/cg. -These must be copied to tables.h and tables.c -to get working code-generators for the VAX on these small machines. -The same problem occurs for the m68k2 backend and the m68020 backend, -and the same solution is chosen. +Asking you for things that you may not want to install. .IP \- -On machines with a 16-bit address space, the C-compiler has no -builtin preprocessor. Arangements are made to this effect. -.IP \- -On the PDP, -.I ranlib -is not used, because it does not work properly, -at least, on our 2.9 BSD system it did'nt. -This is done by creating a dummy shell script -.I ranlib -in the ACK bin directory. -If you are sure that your -.I ranlib -does work properly, you can just remove the shell script before -installing the Kit. +Producing a shell script called "INSTALL" that will take care of the +ACK installation process. +.if n .sp 1 +.if n .nr PD 1v .LP -.sp 1 Some actions still have to be done by hand. -.sp 1 +.if n .sp 1 +.if n .nr PD 0 .IP \- The installation of the PUBMAC macro package is not done automatically because you need super-user privileges to do @@ -482,39 +564,57 @@ that on most systems. This macro package is used with several of the documents provided in the Kit. .IP \- -UNIX V7 as originally distributed contains a few bugs that -prevent correct execution of some of the larger programs. -See the section named "Fixes for the UNIX V7 system" -about what to do. -Berkeley 2.8 or 2.9 may also have some of these bugs. -.IP \- The manual files for the Kit can be copied to their appropriate place in the system by giving the command "make install" -in the man directory, but only +in the $TARGET_HOME/man directory, but only .B after running the installation of the Kit itself. +.if n .sp 1 +.if n .nr PD 0 .NH Compiling the Kit .PP -The next step in the installation process is to compile -the sources in the Kit and install them in their places -in the lib and bin directories. -.PP -Most directories containing sources have Makefiles +The next step in the installation process is to run the "INSTALL" +shell-script: +.DS +sh INSTALL > INSTALL.out 2>&1 & +.DE +This shell-script performs the following steps: +.if n .sp 1 +.if n .nr PD 0 +.IP \- +it will produce a configuration tree, reflecting the structure of the +source tree. +.IP \- +Produce Makefiles in the configuration tree ($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 the directories "bin" and "lib" -by these Makefiles. -These Makefiles adhere to a standard which is described in the +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. -.LP -You do not have to start all these Makefiles separately. +.IP \- +Copy "Action" files to the configuration tree and editing them to +reflect your choices concerning the parts of ACK that you want +to install. "Action" files are described below. +.IP \- +Copy part of the source tree to de ACK users tree (include files, +manual pages, documentation, et cetera). +.IP \- +Calling the "TakeAction" script. +You do not have to start all the Makefiles separately. We wrote a shell script calling the make's needed to install the whole Kit. -This script consists of the file TakeAction in the Kit's root -directory and a few files called Action in some directories. +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". @@ -526,22 +626,22 @@ that it succeeded in fulfilling its goal. If the make was not successful (any other return code) the Out file is left alone for further examination and a small message telling you to look at that file is produced by TakeAction. -.LP +.br For some programs the scripts already know they can't be installed on your type of system. In that case they produce a message "Sorry, ....." and happily proceed with further installation commands. -.PP +.if n .sp 1 +.if n .nr PD 1v +.LP Compilation of the whole Kit might take anything from a few -hours to more than a day. -If you do not want to install libraries etc. for a particular -machine you can edit the file Action and comment out the relevant entries. -Lines starting with a '!' are comments. -.PP +hours to more than a day, depending on the speed of your machine and +your choices. +.LP If this compilation went reasonably successful you should be able to use the Kit. Read the next section and the manuals provided -with the Kit (in the man directory) on how to use it. +with the Kit (in the $TARGET_HOME/man directory) on how to use it. .NH 2 Problems you may meet .NH 3 @@ -550,182 +650,107 @@ on Unisoft m68000 systems. The Unisoft C compiler has a bug which impedes the correct translation of the peephole optimizer. For a more detailed description of this phenomenen see -the file "mach/m68k2/Unisoft_bug". +the file "$SRC_HOME/mach/m68k2/Unisoft_bug". .NH 3 with backends .PP -The backends for the PDP11, VAX with BSD4.1, Motorola 68000 and -Intel 8086 have been heavily used by ourselves and are well tested. +The backends for the PDP11, VAX, Motorola 68000 and 68020, +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. -.PP -.DS -System definition -- done -EM definition -- done -LL(1) Parser generator -- done -EM definition library -- done -C utilities -- done -system-call interface module -- done -string routines module -- done -formatted print module -- done -assertion module -- done -memory allocation module -- done -fast, linear time malloc -- done -EM messages generation module -- done -identifier table module -- done -input module -- done -ACK-object reading and writing module -- done -EM-code reading module -- done -EM code generation module -- done -Modules -- done -C preprocessor -- done -ACK object utilities -- done -Encode/Decode -- done -Shell files in bin -- done -EM assembler -- done -EM Peephole optimizer -- done - . - . - . -EM Global optimizer -- done -ACK archiver -- done -Program 'ack' -- done -Bootstrap for backend tables -- done -Bootstrap for newest form of backend tables -- done -LED link editor -- done -TOPGEN target optimizer generator -- done -C frontend -- done -Basic frontend -- done -Occam frontend -- done -Intel 8086 assembler -- done -Intel 8086 backend -- done -Intel 8086 C libraries -- done -Intel 8086 EM library -- done -Intel 8086 Pascal library -- done -Intel 8086 PC/IX systemcall library -- done -Intel 8086 Basic library -- done -Intel 8086 Occam library -- done -Intel 8086 conversion program from ack.out --> PC/IX a.out -- done -Intel 8086 support -- done - . - . - . -Motorola 68000 assembler -- done -Motorola 68000 2-4 backend -- done -Motorola 68000 2-4 conversion program -- done -Motorola 68000 target optimizer -- done -Motorola 68000 2-4 C libraries -- done -Motorola 68000 2-4 EM library -- done -Motorola 68000 2-4 Pascal library -- done -Motorola 68000 2-4 System library -- done -Motorola 68000 2-4 Basic library -- done -Motorola 68000 2-4 Occam library -- done -Sorry, Motorola 68000 interpreters can only be made on m68* systems -Motorola 68000 2-4 support -- done - . - . - . -PDP 11 assembler -- done -PDP 11 backend -- done -PDP 11 target optimizer -- done -Sorry, PDP 11 interpreter can only be made on pdp* systems -Sorry, PDP 11 C libraries can only be made on pdp* systems -Sorry, PDP 11 EM library can only be made on pdp* systems -Sorry, PDP 11 systemcall library can only be made on pdp* systems -Sorry, PDP 11 Pascal library can only be made on pdp* systems -Sorry, PDP 11 Basic library can only be made on pdp* systems -Sorry, PDP 11 Occam library can only be made on pdp* systems -PDP 11 support -- done - . - . - . -Vax 4-4 backend -- done -Sorry, Vax 4-4 C libraries can only be made on vax* systems -Sorry, Vax 4-4 EM library can only be made on vax* systems -Sorry, Vax 4-4 Occam library can only be made on vax* systems -Sorry, Vax 4-4 Basic library can only be made on vax* systems -Sorry, Vax 4-4 systemcall interface can only be made on vax* systems -Vax target optimizer -- done -Vax 4-4 support -- done -M68020 assembler -- done -M68020 backend -- done -M68020 EM library -- done -M68020 system call library -- done -M68020 C libraries -- done -M68020 PC library -- done -M68020 Basic library -- done -M68020 Occam library -- done -Sorry, M68020 VME131 System V/68 R2V2.1 conversion can only be made on m68020 systems -M68020 System V/68 support -- done -Ack.out --> Sun 3 M68020 a.out format conversion program -- done -Sun 3 M68020 systemcall library -- done -Sun 3 M68020 C libraries -- done -Sun 3 M68020 support -- done -Ack.out --> Sun 2 M68000 a.out format conversion program -- done -Sun 2 M68000 systemcall library -- done -Sun 2 M68000 C libraries -- done -Sun 2 M68000 support -- done - . - . - . -Failed for Pascal frontend, see lang/pc/pem/Out -.DE -.PP +.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, " tell you that certain programs cannot be translated on your machine. The lines starting with "Failed for" tell -you that certain programs/libraries which were expected to, +you that certain programs/libraries were expected to, but did not compile. -Only the Pascal frontend failed to compile in this example. +In this example, the installation of LINT failed. If you want to repeat a certain part of the installation, look in -the Action file for the directory in which that part is to be found. +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 EM_DIR/TakeAction", otherwise type "make install". +"sh $SRC_HOME/TakeAction", otherwise type "make install". .NH Commands .PP -The following commands are available in the bin directory after compilation +The following commands are available in the $TARGET_HOME/bin directory after compilation of the Kit: -.sp 1 -.IP "\fIack\fP, \fIacc\fP, \fIabc\fP, \fIapc\fP, \fIocm\fP, \fIm2\fP and their links" +.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 -.br The archiver used for the EM- and universal assembler/loader. .IP \fIaal\fP -.br The archiver used for ACK objects. .IP \fIem\fP -.br This program selects a interpreter to execute an e.out file. Interpreters exist for PDP-11 and Motorola 68000 systems. .IP \fIeminform\fP -.br The program to unravel the post-mortem information of the EM interpretator for the PDP-11. .IP \fILLgen\fP -.br The LL(1) parser generator. .IP \fIack_sys\fP -.br A shell script producing an identification of your system. Used by some utilities to determine what is, and what is -not feasible on your system. (Like translating PDP assembly). +not feasible on your system. .IP \fImarch\fP -.br A shell script used while compiling libraries. .IP "\fIasize\fP, \fIanm\fP, \fIastrip\fP" .br Do the same as \fIsize\fP, \fInm\fP and \fIstrip\fP, but for ACK object format. .IP \fImkdep\fP -.br A dependency generator for makefiles. .IP "\fIcid\fP, \fIprid\fP, \fIcclash\fP" .br @@ -733,16 +758,15 @@ Some utilities for handling name clashes in C programs. Some systems have C-compilers with only 7 or 8 characters significant in identifiers. .IP "\fItabgen\fP -.br A utility for generating character tables for C-programs. .IP \fIint\fP -.br An EM interpreter. This one is written in C, and is very useful for checking out programs. -.sp 1 +.IP "\fIgrind\fP +A source level debugger for ANSI-C, Modula-2 and Pascal. .LP We currently make the Kit available to our users by telling -them that they should include the bin directory of the Kit in +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. @@ -751,11 +775,11 @@ 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, +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 Kit's bin +The installation process will only touch the utilities in the $TARGET_HOME/bin directory, not your own copies. .NH Machines @@ -773,11 +797,10 @@ for that particular machine. A + in that column indicates that floating point is only available under the '-fp' option. In this case, software floating point emulation is used. .TS -c c c c c c c l l l l l l l. command system i/p languages fp dir remarks -pdp PDP/UNIX V7 2/2 C * pdp needs sep. I/D +pdp PDP/UNIX V7 2/2 C * pdp Pascal Basic Occam @@ -788,6 +811,14 @@ vax4 VAX/BSD 4.? 4/4 C * vax4 Basic Occam Modula-2 + Fortran + +sparc Sun-4 4/4 C * sparc + Pascal + Basic + Occam + Modula-2 + Fortran m68k2 M68000/Unisoft 2/4 C + m68k2 Pascal @@ -800,6 +831,7 @@ m68k4 M68000/Unisoft 4/4 C + m68k4 Basic Occam Modula-2 + Fortran pmds M68000/PMDS 2/4 C + pmds Philips Micro Pascal m68k2 Devel. System @@ -812,30 +844,35 @@ pmds4 M68000/PMDS 4/4 C + pmds4 Philips Micro Basic m68k4 Occam Modula-2 + Fortran mantra M68000/SysV.0 4/4 C + mantra Pascal m68k2 Basic m68k4 Occam Modula-2 + Fortran m68020 M68020/V/68 4/4 C + m68020 R2V2.1 Pascal Basic Occam Modula-2 + Fortran -sun3 SUN 3 R3.0 4/4 C + sun3 +sun3 Sun-3 R3.0 4/4 C + sun3 Pascal m68020 Basic Occam Modula-2 + Fortran -sun2 SUN 2 R3.0 4/4 C + sun2 +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 @@ -854,6 +891,7 @@ i386 SCO Xenix System V 4/4 C + i386 Intel 80386, Xenix System V Basic Occam Modula-2 + Fortran minix Minix PC 2/2 C + minix IBM PC running Minix Pascal i86 @@ -890,6 +928,7 @@ em44 EM machine 4/4 C * em44 Needs interpreter Basic Occam Modula-2 + Fortran 6500 6502/BBC 2/2 C 6500 Uses assembler/loader Pascal @@ -908,6 +947,7 @@ ns Bare NS16032 4/4 C ns Basic Occam Modula-2 + Fortran i80 Hermac/z80 2/2 C i80 Pascal @@ -922,32 +962,43 @@ z80 Hermac/z80 2/2 C z80 \fIi80\fP is faster Modula-2 s2650 Signetics 2650 s2650 Assembler only + +arm Acorn Archimedes 4/4 C * arm Uses assembler/loader + Pascal + Basic + Occam + Modula-2 + Fortran .TE -.PP +.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 one, written in C and running on large machines. +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 \fBem\fP in the bin directory calls the appropriate +The program \fB$TARGET_HOME/bin/em\fP calls the appropriate interpreter. -The interpreters are sought in the em22, em24 and em44 +The interpreters are looked for in the em22, em24 and em44 subdirectories of lib. -The third interpreter is available on large machines as the program \fIint\fP +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 C and Basic programs on any UNIX machine. -The presence of most UNIX utilities is essential for compilation. -A few of the programs you certainly need are: C-compiler, Yacc, sed, -make and lex. +for the languages it supports on +.UX +machine. +The presence of most +.UX +utilities is essential for compilation. +A few of the programs you certainly need are: C-compiler, sed, +and make. .NH 2 Backend .PP @@ -961,8 +1012,8 @@ which is a major undertaking. .NH 2 Universal assembler/loader, link editor .PP -The description files in lib/*/descr use our -universal assembler and for most machines our link editor. +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. @@ -971,19 +1022,19 @@ executable files. The \fIdl\fP programs present for some machines unravel our a.out files and transmit commands to load memory to a microprocessor over a serial line. -The file man/ack.out.5 contains a description of the format of +The file $TARGET_HOME/man/ack.out.5 contains a description of the format of the universal assembler load file. It might be useful to those who wish or need to write their own conversion programs. Also, a module is included to read and write our a.out format. -See modules/man/object.3. +See $TARGET_HOME/modules/man/object.3. .NH 2 Compiling libraries .PP The Kit contains sources for part II and III of the C-library. These files can be used to make libraries for the ACK C-compiler. The recompilation process uses a few include files. -The include directory in the EM home directory contains the include files +The $TARGET_HOME/include directory contains the include files it needs. An effort has been made to make the part III stuff as system independent as possible. @@ -992,12 +1043,12 @@ Options .NH 2 Default machine .PP -There is one important option in h/local.h. +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, or \fIack\fP. +\fIm2\fP, \fIf2c\fP, or \fIack\fP. The machine name used for default is determined by the -definition of ACKM in h/local.h. +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 your own system. @@ -1006,14 +1057,14 @@ and by default produce code that can't run on your own system. .NH 2 Pathnames .PP -Absolute pathnames are concentrated in "h/em_path.h". -Only the Pascal runtime system and the utilities \fIack\fP and \fILLgen\fP use +Absolute pathnames are concentrated in "$TARGET_HOME/config/em_path.h". +Only the utilities \fIack\fP, \fIflex\fP, and \fILLgen\fP use absolute pathnames to access files in the Kit. The tree is distributed with /usr/em as the working directory. The definition of EM_DIR in em_path.h should be altered to specify the root -directory for the Compiler Kit distribution on your system. +directory for the Compiler Kit distribution on your system ($SRC_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 @@ -1024,14 +1075,12 @@ although some remain stubborn and use /tmp or /usr/tmp. The shape of the tree should not be altered lightly because most Makefiles and the utility \fIack\fP know the shape of the ACK tree. -All pathnames in all Makefiles are relative, that is do not -have "/" as the first character. The knowledge of the utility \fIack\fP about the shape of the tree is -concentrated in the files in the directory lib/*/descr and lib/descr/*. +concentrated in the files in the directory $TARGET_HOME/lib/*/descr and $TARGET_HOME/lib/descr/*. .NH Makefiles .PP -Most directories contain a "Makefile". +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 @@ -1058,65 +1107,25 @@ Opr should be an off-line printer daemon. On some systems it exists under another name e.g. lpr. The easiest way to call such a spooler is using a shell script with the name opr that calls lpr. -This script should be placed in /usr/bin or EM_DIR/bin or +This script should be placed in /usr/bin or $TARGET_HOME/bin or one of the directories in your PATH. .IP clean remove all files not needed for day-to-day use, that is binaries not in bin or lib, object files etc. .LP Example: -.nf -.sp 1 - make install -.sp 1 -.fi -given as command in the home directory will cause +.DS +make install +.DE +given as command in the configuration directory will cause compilation of all programs in the directory and copying of the results -to the bin and lib directories. -.NH -Fixes for the UNIX V7 system -.PP -UNIX System V7 has a few bugs that prevent a part of or the whole Kit -from working properly. Berkeley 2.8 and/or 2.9 may also suffer from this -problem. -To be honest, we do not know which of the following changes are -essential to the functioning of our Kit. The change to "ld" is. -.PP -The file "doc/v7bugs.doc" gives for each of the following bugs -a small test program and a diff listing of the source files that have to be -modified. -.IP 1 -Bug in the C optimizer for unsigned comparison -.nr PD 0 -.IP 2 -The loader 'ld' fails for large data and text portions -.IP 3 -Floating point registers are not saved if more memory is needed. -.IP 4 -Floating point registers are not copied to child in fork(). -.nr PD 1v -.LP -Use the test programs to see if the errors are present in your system -and to check if the modifications are effective. -.PP -You may also have to change /usr/src/cmd/cc.c (/bin/cc) to pass the -.B -i -flag to -.I ld. -Also, /usr/src/cmd/ld.c (/bin/ld) may have to be changed to increase the -number of library positions it can hold. -On our (2.9 BSD) version, this is the constant -.I NROUT. -It must be at least 400. -This may require separate I&D. -Also, our version does not check that the table does not overflow. +to the bin and lib.bin directories. .NH Testing .PP Test sets are available in Pascal, C, Basic and EM assembly. .IP em 8 -.br -The directory emtest contains a few EM test programs. +The 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 @@ -1129,8 +1138,7 @@ The test finishes normally with 0 as the last number printed In all other cases a bug showed its existence. .IP Pascal -.br -The directory lang/pc/test contains a few Pascal test programs. +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 @@ -1149,8 +1157,7 @@ Easton, Pennsylvania 18042 USA .DE .IP C -.br -The sub-directories in lang/cem/ctest contain C test programs. +The sub-directories in $SRC_HOME/lang/cem/ctest contain C test programs. The idea behind these tests is: when you have a program called xx.c, compile it into xx.cem. Run it with standard output to xx.cem.r, compare this file to @@ -1164,8 +1171,7 @@ The contents of the result files depend on the wordsize, the xx.cem.g files on the distribution are intended for a 32-bit machine. .IP Basic -.br -The directory lang/basic/test contains some forty basic programs. +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 @@ -1182,7 +1188,7 @@ Manual pages for Amsterdam Compiler Kit can be copied to "/usr/man/man?" by the following commands: .DS -cd man +cd $TARGET_HOME/man make install .DE but do this \fBafter\fR compiling the Kit. @@ -1193,6 +1199,7 @@ l l. doc/toolkit.doc general overview (CACM article) doc/em description of the EM machine architecture doc/ack.doc format of machine description files (lib/*/descr) +doc/ansi_C.doc ANSI C implementation description doc/basic.doc Basic reference manual doc/pcref.doc Pascal-frontend reference manual doc/val.doc results of running the Pascal Validation Suite @@ -1207,16 +1214,18 @@ doc/6500.doc MSC 6500 backend description doc/i80.doc Intel 8080 backend description doc/z80.doc Zilog Z80 backend description doc/m68020.doc Motorola M68000/M68020 backend description +doc/sparc SPARC code expander description doc/occam Occam-frontend description doc/ego Global Optimizer description doc/top Target Optimizer description doc/int description of the EM interpreter written in C doc/ceg documentation for code-expander writers and maintainers +doc/lint documentation of LINT doc/m2ref.doc Modula-2 frontend description doc/install.doc this document doc/install.pr this document (formatted) .TE -.PP +.LP The names in this list without a suffix are in fact a subdirectory. Use the Makefile to get readable copies. .LP -- 2.34.1