doc/install.doc

   1 .\" $Id: install.doc,v 1.38 1994/06/24 10:01:58 ceriel Exp $
   2 .if n .nr PD 1v
   3 .if n .nr LL 78m
   4 .if n .ll 78m
   5 .TL
   6 Amsterdam Compiler Kit Installation Guide
   7 .AU
   8 Ed Keizer
   9 (revised for 3rd, 4th and 5th distribution by Ceriel Jacobs)
  10 .AI
  11 Vakgroep Informatica
  12 Vrije Universiteit
  13 Amsterdam
  14 .NH
  15 Introduction
  16 .PP
  17 This document
  18 describes the process of installing the Amsterdam Compiler Kit (ACK).
  19 It depends on the combination of hard- and software how
  20 hard it will be to install the Kit.
  21 This description is intended for a Sun-3 or SPARC workstation.
  22 Installation on VAXen running Berkeley
  23 .UX
  24 or Ultrix,
  25 Sun-2 systems and most System V
  26 .UX
  27 systems should be easy.
  28 As of this distribution, installation on PDP-11's or other
  29 systems with a small address space is no longer supported.
  30 See section 8 for installation on other systems.
  31 .NH
  32 The ACK installation process
  33 .PP
  34 In the ACK installation process, three directory trees are used:
  35 .IP "-"
  36 the ACK source tree. This is the tree on the ACK distribution medium.
  37 For the rest of this document, we will refer to this directory
  38 as $SRC_HOME;
  39 .IP "-"
  40 a configuration tree. This tree is built by the installation process and
  41 is used to do compilations in. Its structure reflects that of the source tree,
  42 but this tree will mostly contain Makefiles and relocatable objects.
  43 For the rest of this document, we will refer to this directory
  44 as $CONFIG;
  45 .IP "-"
  46 an ACK users tree. This tree is also built by the installation process.
  47 For the rest of this document, we will refer to this directory
  48 as $TARGET_HOME;
  49 .LP
  50 After installation,
  51 the directories in $TARGET_HOME contain the following information:
  52 .if n .sp 1
  53 .if n .nr PD 0
  54 .IP "bin" 14
  55 the few utilities that knot things together.
  56 See the section about "Commands".
  57 .IP "lib"
  58 root of a tree containing almost all libraries used by
  59 commands.
  60 Files specific to a certain machine are collected in one subtree
  61 per machine. E.g. "lib/pdp", "lib/z8000".
  62 The names used here are the same names as used for subtrees
  63 of "$SRC_HOME/mach".
  64 .IP "lib/descr"
  65 command descriptor files used by the program ack.
  66 .IP "lib/LLgen"
  67 files used by the LL(1) parser generator.
  68 .IP "lib/flex"
  69 files used by the lexical analyzer generator Flex.
  70 .IP "lib/m2"
  71 definition modules for Modula-2.
  72 .IP "lib.bin"
  73 root of a tree containing almost all binaries used by
  74 commands.
  75 All programs specific to a certain machine are collected in one subtree
  76 per machine. E.g. "lib.bin/pdp", "lib.bin/z8000".
  77 The names used here are the same names as used for subtrees
  78 of "$SRC_HOME/mach".
  79 .IP "lib.bin/ego"
  80 files used by the global optimizer.
  81 .IP "lib.bin/lint"
  82 binaries for the lint passes and lint libraries.
  83 .IP "lib.bin/ceg"
  84 files used by the code-expander-generator.
  85 .IP "etc"
  86 contains the file "ip_spec.t" needed for EM interpreters and EM documentation.
  87 .IP "config"
  88 contains two include files:
  89 .TS
  90 l l.
  91 em_path.h       path names used by \fIack\fP, intended for all utilities
  92 local.h various definitions for local versions
  93 .TE
  94 These include files are specific for the current machine, so they
  95 are in a separate directory.
  96 .IP "include/_tail_cc"
  97 .br
  98 include files needed by modules
  99 in the C library from lang/cem/libcc.
 100 .IP "include/tail_ac"
 101 .br
 102 include files for ANSI C.
 103 .IP "include/occam"
 104 include files for occam.
 105 .IP "include/_tail_mon"
 106 .br
 107 more or less system independent include files needed by modules
 108 in the library lang/cem/libcc/mon.
 109 .IP "h"
 110 the #include files for:
 111 .TS
 112 l l.
 113 arch.h  definition of the ACK archive format
 114 as_spec.h       used by EM assembler and interpreters
 115 bc_io.h used by the Basic run-time system
 116 bc_string.h     used by the Basic run-time system
 117 cg_pattern.h    used by the backend program "cg" and its bootstrap
 118 cgg_cg.h        used by the backend program "ncg" and its bootstrap
 119 em_abs.h        contains trap numbers and address for lin and fil
 120 em_ego.h        definition of names for some global optimizer
 121         messages
 122 em_flag.h       definition of bits in array em_flag in
 123         $TARGET_HOME/lib.bin/em_data.a. Describes parameters
 124         effect on flow of instructions
 125 em_mes.h        definition of names for mes pseudo numbers
 126 em_mnem.h       instruction => compact mapping
 127 em_pseu.h       pseudo instruction => compact mapping
 128 em_ptyp.h       useful for compact code reading/writing,
 129         defines classes of parameters
 130 em_reg.h        definition of mnemonics indicating register type
 131 em_spec.h       definition of constants used in compact code
 132 ip_spec.h       used by programs that read e.out files
 133 m2_traps.h      used by the Modula-2 run-time system
 134 ocm_chan.h      used by the occam run-time system
 135 ocm_parco.h     used by the occam run-time system
 136 ocm_proc.h      used by the occam run-time system
 137 out.h   defines the ACK a.out format
 138 pc_err.h        definitions of error numbers in Pascal
 139 pc_file.h       macro's used in file handling in Pascal
 140 pc_math.h       used by the Pascal runtime system
 141 ranlib.h        defines symbol table format for archives
 142 stb.h   defines debugger symbol table types
 143 .TE
 144 .IP "modules"
 145 root of a tree containing modules for compiler writers.
 146 .IP "modules/man"
 147 manual pages for all modules.
 148 .IP "modules/lib"
 149 contains module objects.
 150 .IP "modules/h"
 151 include files for some of the modules.
 152 .IP "modules/pkg"
 153 include files for some of the modules.
 154 .IP "doc"
 155 this directory contains the unformatted documents for the Kit.
 156 A list of the available documents can be found in the last section.
 157 These documents must be processed by [nt]roff.
 158 .IP "man"
 159 man files for various utilities.
 160 .if n .nr PD 1v
 161 .LP
 162 When installing ACK on several types of machines with a shared file system,
 163 it may be useful to know that the "doc", "etc", "h",
 164 "include", "lib" and "man" sub-directories do not depend on this
 165 particular installation. They do not contain binaries or path-dependent
 166 information. These directories can therefore be shared between the
 167 ACK installations. This can be accomplished by creating the tree and
 168 suitable symbolic links before starting the installation process.
 169 .LP
 170 For instance, let us say there is a file-system that is accessible from
 171 the different machines as "/usr/share/local", and the ACK binary tree
 172 must be installed in "/usr/local/ack". In this case, proceed as follows:
 173 .IP \-
 174 create a directory "/usr/share/local/ack", with subdirectories
 175 "doc", "etc", "h", "include", "lib" and "man".
 176 .IP \-
 177 create a directory "/usr/local/ack" and
 178 then create symbolic links "doc" to "/usr/share/local/ack/doc", etc.
 179 .LP
 180 If this is done on all machines on which ACK will be installed, the
 181 machine-independent part only has to be installed once, preferably
 182 on the fastest processor (it takes a long time to install all libraries).
 183 .LP
 184 The directories in the source tree contain the following information:
 185 .if n .sp 1
 186 .if n .nr PD 0
 187 .IP "bin" 14
 188 source of some shell-scripts.
 189 .IP "lib"
 190 mostly description files for the "ack" program.
 191 .IP "etc"
 192 the main description of EM sits here.
 193 Files (e.g. em_table) describing
 194 the opcodes and pseudos in use,
 195 the operands allowed, effect in stack etc. etc.
 196 .IP "mach"
 197 just there to group the directories with all sources for each machine.
 198 The section about "Machines" of this manual indicates which subdirectories
 199 are used for which systems.
 200 .br
 201 These directories have subdirectories named:
 202 .in +3n
 203 .TS
 204 l l.
 205 cg      the backend   (*.m => *.s)
 206 ncg     the new backend   (*.m => *.s)
 207 as      the assembler (*.s => *.o) or
 208         assembler/linker (*.s + libraries => a.out)
 209 cv      conversion programs for a.out files
 210 dl      down-load programs
 211 top     the target optimizer
 212 int     source for an interpreter
 213
 214 libbc   to create Basic run-time system and libraries
 215 libcc   to create C run-time system and libraries
 216 libcc.ansi      to create ANSI C run-time system and libraries
 217 libpc   to create Pascal run-time system and libraries
 218 libf77  to create Fortran run-time system and libraries
 219 libm2   to create Modula-2 run-time system and libraries
 220 liboc   to create occam run-time system and libraries
 221 libem   EM runtime system, only depending on CPU type
 222 libend  library defining end, edata, etext
 223 libfp   to create floating point library
 224 libdb   to create debugger support library
 225 libsys  system-dependent EM library
 226 libce   fast cc-compatible C compiler library support
 227
 228 ce      code expander (fast back-end)
 229
 230 test    various tests
 231 .TE
 232 .in -3n
 233 Actually, some of these directories will only appear in the configuration tree.
 234 .br
 235 The directory proto contains files used by most machines,
 236 like machine-independent sources and Makefiles.
 237 .in +3n
 238 .TS
 239 l l.
 240 mach/proto/cg   current backend sources
 241 mach/proto/ncg  new backend sources
 242 mach/proto/as   assembler sources
 243 mach/proto/top  target optimizer sources
 244 mach/proto/fp   floating point package sources
 245 mach/proto/libg makefiles for compiling libraries
 246 mach/proto/grind        machine-independent debugger support
 247 .TE
 248 .IP "emtest"
 249 contains prototype of em test set.
 250 .IP "lang"
 251 just there to group the directories for all front-ends.
 252 .IP "lang/pc"
 253 the Pascal front-end.
 254 .IP "lang/pc/libpc"
 255 .br
 256 source of Pascal run-time system (in EM or C).
 257 .IP "lang/pc/test"
 258 some test programs written in Pascal.
 259 .IP "lang/pc/comp"
 260 the Pascal compiler proper.
 261 .IP "lang/cem"
 262 the C front-end.
 263 .IP "lang/cem/libcc"
 264 .br
 265 directories with sources of C runtime system, libraries (in EM or C).
 266 .IP "lang/cem/libcc/gen"
 267 .br
 268 sources for routines in chapter III of
 269 .UX
 270 programmers manual,
 271 excluding stdio.
 272 .IP "lang/cem/libcc/stdio"
 273 .br
 274 stdio sources.
 275 .IP "lang/cem/libcc/math"
 276 .br
 277 sources for mathematical routines, normally available with the
 278 \fB-lm\fP option to \fIcc\fP.
 279 .IP "lang/cem/libcc/mon"
 280 .br
 281 sources for routines in chapter II, mostly written in EM.
 282 .IP "lang/cem/cemcom"
 283 .br
 284 the compiler proper.
 285 .IP "lang/cem/cemcom.ansi"
 286 .br
 287 the ANSI C compiler proper.
 288 .IP "lang/cem/cpp.ansi"
 289 .br
 290 the ANSI C preprocessor.
 291 .IP "lang/cem/libcc.ansi"
 292 .br
 293 the ANSI C library sources.
 294 .IP "lang/cem/ctest"
 295 .br
 296 the C test set.
 297 .IP "lang/cem/ctest/cterr"
 298 .br
 299 programs developed for pinpointing previous errors.
 300 .IP "lang/cem/ctest/ct*"
 301 .br
 302 the test programs.
 303 .IP "lang/cem/lint"
 304 a C program checker.
 305 .IP "lang/cem/lint/lpass1"
 306 .br
 307 the first pass of lint.
 308 .IP "lang/cem/lint/lpass1.ansi"
 309 .br
 310 the first pass of lint, this time for ANSI C.
 311 .IP "lang/cem/lint/lpass2"
 312 .br
 313 the second pass of lint, shared between ANSI C and "old-fashioned" C.
 314 .IP "lang/cem/lint/llib"
 315 .br
 316 programs for producing lint libraries.
 317 .IP "lang/basic"
 318 the Basic front-end.
 319 .IP "lang/basic/src"
 320 .br
 321 the compiler proper.
 322 .IP "lang/basic/lib"
 323 .br
 324 the Basic run-time library source.
 325 .IP "lang/basic/test"
 326 .br
 327 various Basic programs.
 328 .IP "lang/occam"
 329 the occam front-end.
 330 .IP "lang/occam/comp"
 331 .br
 332 the compiler proper.
 333 .IP "lang/occam/lib"
 334 .br
 335 source of occam run-time system (in EM or C).
 336 .IP "lang/occam/test"
 337 .br
 338 some occam programs.
 339 .IP "lang/m2"
 340 the Modula-2 front-end.
 341 .IP "lang/m2/comp"
 342 the compiler proper.
 343 .IP "lang/m2/libm2"
 344 source of Modula-2 run-time system (in EM, C and Modula-2).
 345 .IP "lang/m2/m2mm"
 346 the Modula-2 makefile generator.
 347 .IP "lang/m2/test"
 348 some Modula-2 example programs.
 349 .IP "lang/fortran"
 350 the Fortran front-end (translates Fortran into C). This compiler is not
 351 a part of ACK, but is included because it adds another language.
 352 The Fortran system carries the following copyright notice:
 353 .IP ""
 354 .nf
 355 /**************************************************************
 356 Copyright 1990, 1991 by AT&T Bell Laboratories and Bellcore.
 357
 358 Permission to use, copy, modify, and distribute this software
 359 and its documentation for any purpose and without fee is hereby
 360 granted, provided that the above copyright notice appear in all
 361 copies and that both that the copyright notice and this
 362 permission notice and warranty disclaimer appear in supporting
 363 documentation, and that the names of AT&T Bell Laboratories or
 364 Bellcore or any of their entities not be used in advertising or
 365 publicity pertaining to distribution of the software without
 366 specific, written prior permission.
 367
 368 AT&T and Bellcore disclaim all warranties with regard to this
 369 software, including all implied warranties of merchantability
 370 and fitness.  In no event shall AT&T or Bellcore be liable for
 371 any special, indirect or consequential damages or any damages
 372 whatsoever resulting from loss of use, data or profits, whether
 373 in an action of contract, negligence or other tortious action,
 374 arising out of or in connection with the use or performance of
 375 this software.
 376 **************************************************************/
 377 .fi
 378 .IP "lang/fortran/comp"
 379 .br
 380 the compiler proper.
 381 .IP "lang/fortran/lib"
 382 .br
 383 source of Fortran runtime system and libraries.
 384 .IP "fast"
 385 contains sub-directories for installing the fast ACK compatible compilers.
 386 .IP "fast/driver"
 387 .br
 388 contains the sources of the fast ACK compatible compiler drivers.
 389 .IP "fcc"
 390 contains the fast cc-compatible C compiler for SUN-3 and VAX.
 391 .IP "util"
 392 contains directories with sources for various utilities.
 393 .IP "util/ack"
 394 the program used for translation with the Kit.
 395 .IP "util/opt"
 396 the EM peephole optimizer (*.k => *.m).
 397 .IP "util/ego"
 398 the global optimizer.
 399 .IP "util/topgen"
 400 the target optimizer generator.
 401 .IP "util/misc"
 402 decode (*.[km] => *.e) + encode (*.e => *.k).
 403 .IP "util/data"
 404 the C-code for $TARGET_HOME/lib.bin/em_data.a.
 405 These sources are created by the Makefile in `etc`.
 406 .IP "util/ass"
 407 the EM assembler (*.[km] + libraries => e.out).
 408 .IP "util/arch"
 409 the archivers to be used for all EM utilities.
 410 .IP "util/cgg"
 411 a program needed for compiling backends.
 412 .IP "util/ncgg"
 413 a program needed for compiling the newest backends.
 414 .IP "util/cpp"
 415 the C preprocessor.
 416 .IP "util/shf"
 417 various shell files.
 418 .IP "util/LLgen"
 419 the extended LL(1) parser generator.
 420 .IP "util/amisc"
 421 contains some programs handling ACK a.out format, such as anm, asize.
 422 .IP "util/cmisc"
 423 contains some programs to help in resolving name conflicts, and
 424 a dependency generator for makefiles.
 425 .IP "util/led"
 426 the ACK link-editor, reading ACK relocatable a.out format, and writing
 427 ACK a.out format.
 428 .IP "util/int"
 429 an EM interpreter, written in C. Very useful for checking out software,
 430 but slow.
 431 .IP "util/ceg"
 432 code expander generator.
 433 .IP "util/grind"
 434 a symbolic debugger.
 435 .IP "util/byacc"
 436 this is Berkeley yacc, in the public domain.
 437 .IP "util/flex"
 438 this is a replacement for lex. It carries the following copyright notice:
 439 .IP ""
 440 .nf
 441 Copyright (c) 1990 The Regents of the University of California.
 442 All rights reserved.
 443
 444 This code is derived from software contributed to Berkeley by
 445 Vern Paxson.
 446
 447 The United States Government has rights in this work pursuant
 448 to contract no. DE-AC03-76SF00098 between the United States
 449 Department of Energy and the University of California.
 450
 451 Redistribution and use in source and binary forms are permitted
 452 provided that: (1) source distributions retain this entire
 453 copyright notice and comment, and (2) distributions including
 454 binaries display the following acknowledgement:  ``This product
 455 includes software developed by the University of California,
 456 Berkeley and its contributors'' in the documentation or other
 457 materials provided with the distribution and in all advertising
 458 materials mentioning features or use of this software.  Neither the
 459 name of the University nor the names of its contributors may be
 460 used to endorse or promote products derived from this software
 461 without specific prior written permission.
 462
 463 THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
 464 IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
 465 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 466 PURPOSE.
 467 .fi
 468 .ne 4
 469 .if n .nr PD 1v
 470 .LP
 471 All path names mentioned in the text of this document are relative to
 472 $SRC_HOME, unless they start with '/' or one of $SRC_HOME,
 473 $TARGET_HOME or $CONFIG.
 474 .NH
 475 Restoring the ACK tree
 476 .PP
 477 The process of installing the Amsterdam Compiler Kit is quite simple.
 478 The first step is to restore the Amsterdam Compiler Kit
 479 distribution tree structure.
 480 Proceed as follows
 481 .IP "  \-" 10
 482 Create a directory, for example /usr/share/local/src/ack, on a device
 483 with at least 15 Megabytes left. This directory will be $SRC_HOME.
 484 .IP "  \-"
 485 Change to that directory (cd ...).
 486 .IP "  \-"
 487 Extract all files from the distribution medium, for instance
 488 magtape:
 489 \fBtar x\fP.
 490 .IP "  \-"
 491 Keep a copy of the original distribution to be able to repeat the process
 492 of installation in case of disasters.
 493 This copy is also useful as a reference point for diff-listings.
 494 .NH
 495 Adapting ACK to the local system
 496 .PP
 497 Before compiling the sources in the Kit some installation dependent
 498 actions have to be taken.
 499 Most of these are performed by an interactive shell script in the file
 500 .I $SRC_HOME/first/first.
 501 Calling this script should be done
 502 from another directory, for instance an empty directory which will later
 503 become $CONFIG.
 504 .LP
 505 The actions of the
 506 .I first
 507 script are:
 508 .if n .sp 1
 509 .if n .nr PD 0
 510 .IP \-
 511 Asking for the path names of the ACK source directory ($SRC_HOME), the
 512 configuration directory ($CONFIG), and the ACK users directory ($TARGET_HOME).
 513 About 5M are needed for the configuration tree. The disk space needed
 514 for the ACK users tree depends on which front-ends and back-ends are to be
 515 installed.
 516 For instance, on our SPARC systems
 517 we have installed all languages and 6 back-ends, including the
 518 system-independent part. This amounts to about 16M.
 519 On our SUN-3 systems, we have installed all front-ends and 5 back-ends,
 520 but only the machine-dependent part. The machine-independent directories are
 521 symbolic links to the SPARC ACK users tree.
 522 We also have the fast ACK compilers
 523 installed on the SUN-3's.
 524 The total amount of disk-space used is less than 8M.
 525 .IP \-
 526 Asking for what type of system the binary tree must be produced for
 527 and creating the shell script "ack_sys" in the Kit's bin directory.
 528 Several utilities make use of "ack_sys" to determine the type of
 529 system.
 530 The current choice is between:
 531 .TS
 532 c c c
 533 l l l.
 534 answer  system type     default machine
 535 vax_bsd4_1a     VAX11 + BSD4.1a vax4
 536 vax_bsd4_2      VAX11 + BSD4.2  vax4
 537 vax_sysV_2      VAX11 + System V.2      vax4
 538 i386    Intel 80386 system + Xenix System V     i386
 539 sun3    Sun-3 Motorola 68020 workstation        sun3
 540 sun2    Sun-2 Motorola 68010 workstation        sun2
 541 m68_sysV_0      68000 + Uniplus System V.0      mantra
 542 m68020  Motorola 68020 VME131 + System V/68 R2V2.1      m68020
 543 sparc   Sun-4 or SPARC workstation running SunOs 4      sparc
 544 sparc_solaris   Sun-4 or SPARC workstation running Solaris 2    sparc_solaris
 545 ANY     Neither of the above    ???
 546 .TE
 547 For some of these, the installation procedure has not been tested, as
 548 we don't have them.
 549 For others, the installation procedure has only been tested with earlier
 550 distributions, as we don't have those systems anymore.
 551 However, the sun3 and sparc systems are known to behave reasonably.
 552 The sparc_solaris system has only been tested with the GNU C compiler,
 553 because we don't have the SUN C compiler (it is unbundled in Solaris 2).
 554 The Sun systems should run SunOs Release 3.0 or newer.
 555 The i386 choice may also be used for Intel 80386 or 80486 systems
 556 running
 557 .UX
 558 System V Release 4. These systems are also able to run Xenix System V
 559 binaries.
 560 If the target system is not on this list, choose one that comes close.
 561 If none of them come close, use the "ANY" choice.
 562 For ANY, any name can be used,
 563 but the Kit will not be able to compile programs for the target system.
 564 See the section about "compilation
 565 on a different machine".
 566 .IP \-
 567 Setting the default machine for which code is
 568 produced to the local type of system according to the table above.
 569 This in done in the file "$TARGET_HOME/config/local.h".
 570 See also section 9.1.
 571 .IP \-
 572 Asking for things that don't have to be installed.
 573 .IP \-
 574 Producing a shell script called "INSTALL" that will take care of the
 575 ACK installation process.
 576 .NH
 577 Compiling the Kit
 578 .PP
 579 The next step in the installation process is to run the "INSTALL"
 580 shell-script. When using a Bourne-shell, type:
 581 .DS
 582 sh INSTALL > INSTALL.out 2>&1 &
 583 .DE
 584 When using a C-shell, type:
 585 .DS
 586 sh INSTALL >& INSTALL.out &
 587 .DE
 588 This shell-script performs the following steps:
 589 .if n .sp 1
 590 .if n .nr PD 0
 591 .IP \-
 592 Produce a configuration tree ($CONFIG), reflecting the structure of the
 593 source tree.
 594 .IP \-
 595 Produce Makefiles in $CONFIG.
 596 As mentioned before, compilations
 597 will be done in the configuration tree, not in the source tree.
 598 Most configuration directories will have Makefiles
 599 used to compile and install the programs in that
 600 directory.
 601 All programs needed for compilation and/or cross compilation
 602 with the Kit are installed in $TARGET_HOME by these Makefiles.
 603 These Makefiles are produced from corresponding files called
 604 "proto.make" in the source tree. In fact, the "proto.make" files
 605 are almost complete Makefiles, except for some macro definitions that
 606 are collected by the \fIfirst\fP script.
 607 The Makefiles adhere to a standard which is described in the
 608 section 9.
 609 .IP \-
 610 Copy "Action" files to the configuration tree and editing them to
 611 reflect the choices concerning the parts of ACK that have to be
 612 installed.  "Action" files are described below.
 613 .IP \-
 614 Copy part of the source tree to the ACK users tree (include files,
 615 manual pages, documentation, et cetera).
 616 .IP \-
 617 Calling the "TakeAction" script.
 618 All these Makefiles do not have to be called separately.
 619 We wrote a shell script calling the make's needed to install
 620 the whole Kit.
 621 This script consists of the file $SRC_HOME/TakeAction
 622 and a few files called Action in some configuration directories.
 623 The Action files describe in a very simple form which actions
 624 have to be performed in which directories.
 625 The default action is to start "make install && make clean".
 626 The output of each make is diverted to a file called "Out"
 627 in the same directory as the make was started in.
 628 If the make was successful (return code 0) the Out file is removed
 629 and the script TakeAction produces a small message indicating
 630 that it succeeded in fulfilling its goal.
 631 If the make was not successful (any other return code) the Out file
 632 is left alone for further examination and the script TakeAction
 633 produces a small message indicating that it failed.
 634 .br
 635 For some programs the scripts already know they can't be
 636 installed on the local type of system.
 637 In that case they produce a message "Sorry, ....." and
 638 happily proceed with further installation commands.
 639 .if n .sp 1
 640 .if n .nr PD 1v
 641 .LP
 642 Installation of the Kit might take anything from a few
 643 hours to more than a day, depending on the speed of the local machine and
 644 what must be installed.
 645 .LP
 646 If the installation succeeded, the Kit is ready to be used.
 647 Read section 6 and the manuals provided
 648 with the Kit (in the $TARGET_HOME/man directory) on how to use it.
 649 .NH 2
 650 Problems
 651 .NH 3
 652 on Unisoft m68000 systems.
 653 .PP
 654 The Unisoft C compiler has a bug which impedes the correct
 655 translation of the peephole optimizer.
 656 For a more detailed description of this phenomenon see
 657 the file "$SRC_HOME/mach/m68k2/Unisoft_bug".
 658 (This observation was made in 1985 or so, so it is probably
 659 no longer true).
 660 .NH 3
 661 with backends
 662 .PP
 663 The backends for the PDP11, VAX, Motorola 68000 and 68020,
 664 SPARC, Intel 8086, and Intel 80386
 665 have been heavily used by ourselves and are well tested.
 666 The backends for the other machines are known to run our own
 667 test programs,
 668 but might reveal errors when more heavily used.
 669 .NH 2
 670 An example output of TakeAction.
 671 .LP
 672 .sp 1
 673 .nf
 674     System definition -- done
 675     EM definition library -- done
 676     C utilities -- done
 677     Flex lexical analyzer generator -- done
 678     Yacc parser generator -- done
 679     system-call interface module -- done
 680         .
 681         .
 682         .
 683     EM Global optimizer -- done
 684     ACK archiver -- done
 685     Program 'ack' -- done
 686     Bootstrap for backend tables -- done
 687     Bootstrap for newest form of backend tables -- done
 688         .
 689         .
 690         .
 691     C frontend -- done
 692     ANSI-C frontend -- done
 693     ANSI-C preprocessor -- done
 694     ANSI-C header files -- done
 695     Failed for LINT C program checker, see lang/cem/lint/Out
 696     Pascal frontend -- done
 697     Basic frontend -- done
 698         .
 699         .
 700         .
 701     Vax 4-4 assembler -- done
 702     Vax 4-4 backend -- done
 703     Vax target optimizer -- done
 704     ACK a.out to VAX a.out conversion program -- done
 705     Sorry, Vax code expander library can only be made on vax* systems
 706     Vax 4-4 EM library -- done
 707     Vax 4-4 debugger support library -- done
 708     Vax 4-4 etext,edata,end library -- done
 709     Vax 4-4 systemcall interface -- done
 710         .
 711         .
 712         .
 713 .sp 1
 714 .fi
 715 .LP
 716 The lines starting with "Sorry, " indicate that certain programs cannot
 717 be translated on the local machine.
 718 The lines starting with "Failed for" indicate
 719 that certain programs/libraries were expected to,
 720 but did not compile.
 721 In this example, the installation of LINT failed.
 722 To repeat a certain part of the installation, look in
 723 the Action file, which resides in the root of the configuration tree,
 724 for the directory in which that part is to be found.
 725 If that directory contains an Action file issue the command
 726 "sh $CONFIG/bin/TakeAction", otherwise type "make install".
 727 .NH
 728 Commands
 729 .PP
 730 The following commands are available in the $TARGET_HOME/bin directory after compilation
 731 of the Kit:
 732 .IP "\fIack\fP, \fIacc\fP, \fIabc\fP, \fIapc\fP, \fIocm\fP, \fIm2\fP, \fIf2c\fP  and their links" 14
 733 .br
 734 the names mentioned here can be used to compile Pascal, C, etc... programs.
 735 Most of the links can be used to generate code for a particular
 736 machine.
 737 See also the section about "Machines".
 738 .IP \fIarch\fP
 739 the archiver used for the EM- and universal assembler/loader.
 740 .IP \fIaal\fP
 741 the archiver used for ACK objects.
 742 .IP \fIem\fP
 743 this program selects a interpreter to execute an e.out file.
 744 Interpreters exist for PDP-11 and Motorola 68000 systems.
 745 .IP \fIeminform\fP
 746 the program to unravel the post-mortem information of
 747 the EM interpretator for the PDP-11.
 748 .IP \fILLgen\fP
 749 the LL(1) parser generator.
 750 .IP \fIack_sys\fP
 751 a shell script producing an identification of the target system.
 752 Used by some utilities to determine what is, and what is
 753 not feasible on the target system.
 754 .IP \fImarch\fP
 755 a shell script used while compiling libraries.
 756 .IP "\fIasize\fP, \fIanm\fP, \fIastrip\fP"
 757 .br
 758 do the same as \fIsize\fP, \fInm\fP and \fIstrip\fP, but for ACK object format.
 759 .IP \fImkdep\fP
 760 a dependency generator for makefiles.
 761 .IP "\fIcid\fP, \fIprid\fP, \fIcclash\fP"
 762 .br
 763 some utilities for handling name clashes in C programs. Some
 764 systems have C-compilers with only 7 or 8 characters significant in
 765 identifiers.
 766 .IP \fItabgen\fP
 767 a utility for generating character tables for C-programs.
 768 .IP \fIint\fP
 769 an EM interpreter. This one is written in C, and is very useful for checking
 770 out programs.
 771 .IP \fIgrind\fP
 772 a source level debugger for C, ANSI-C, Modula-2 and Pascal.
 773 .IP "\fIafcc\fP, \fIafm2\fP, \fIafpc\fP"
 774 .br
 775 these are ACK-compatible fast C, Modula-2 and Pascal compilers,
 776 available for M68020, VAX and Intel 80386 systems. They compile very fast,
 777 but produce slow code.
 778 .IP \fIfcc\fP
 779 this is a cc-compatible fast C compiler, available on SUN-3 and VAX
 780 systems. It compiles very fast, but produces slow code.
 781 .LP
 782 We currently make the Kit available to our users by telling
 783 them that they should include the $TARGET_HOME/bin directory in
 784 their PATH shell variable.
 785 The programs will still work when moved to a different
 786 directory or linked to.
 787 Copying should preferably be done with tar, since links are
 788 heavily used.
 789 Renaming of the programs linked to \fIack\fP will not always
 790 produce the desired result.
 791 This program uses its call name as an argument.
 792 Any call name not being \fIcc\fP, \fIacc\fP, \fIabc\fP, \fIpc\fP, \fIf2c\fP,
 793 \fIocm\fP, \fIm2\fP, or \fIapc\fP will be
 794 interpreted as the name of a 'machine description' and the
 795 program will try to find a description file with that name.
 796 The installation process will only touch the utilities in the $TARGET_HOME/bin
 797 directory, not copies of these utilities.
 798 .NH
 799 Machines
 800 .PP
 801 Below is a table with entries for all commands in
 802 the bin directory used to (cross)compile for a particular machine.
 803 The name in the first column gives the name in the bin directory.
 804 The column headed dir indicates which subdirectories of
 805 $TARGET_HOME/lib and/or $TARGET_HOME/lib.bin are needed for compilation.
 806 The column head i/p contains the integer and pointer size used in units of
 807 bytes.
 808 The subdirectories with the same name in mach contain the sources.
 809 A * in the column headed 'fp' indicates that floating point can be used
 810 for that particular machine. A + in that column indicates that floating
 811 point is available under the '-fp' option. In this case, software
 812 floating point emulation is used.
 813 .TS
 814 l l l l l l l.
 815 command system  i/p     languages       fp      dir     remarks
 816
 817 pdp     PDP/UNIX V7     2/2     C       *       pdp
 818                         Pascal
 819                         Basic
 820                         occam
 821                         Modula-2
 822
 823 vax4    VAX/BSD 4.?     4/4     C       *       vax4
 824         System V.2              Pascal
 825                         Basic
 826                         occam
 827                         Modula-2
 828                         Fortran
 829
 830 sparc   Sun-4   4/4     C       *       sparc
 831                         Pascal
 832                         Basic
 833                         occam
 834                         Modula-2
 835                         Fortran
 836
 837 sparc_solaris   Sun-4   4/4     C       *       sparc_solaris
 838                         Pascal
 839                         Basic
 840                         occam
 841                         Modula-2
 842                         Fortran
 843
 844 m68k2   M68000/ 2/4     C       +       m68k2
 845         Unisoft         Pascal
 846                         Basic
 847                         occam
 848                         Modula-2
 849
 850 m68k4   M68000/ 4/4     C       +       m68k4
 851         Unisoft         Pascal          m68k2
 852                         Basic
 853                         occam
 854                         Modula-2
 855                         Fortran
 856
 857 pmds    M68000/ 2/4     C       +       pmds    Philips Micro
 858         PMDS            Pascal          m68k2   Devel. System
 859                         Basic
 860                         occam
 861                         Modula-2
 862
 863 pmds4   M68000/ 4/4     C       +       pmds4   Philips Micro
 864         PMDS            Pascal          m68k2   Devel. System
 865                         Basic           m68k4
 866                         occam
 867                         Modula-2
 868                         Fortran
 869
 870 mantra  M68000/ 4/4     C       +       mantra
 871         Sys V.0         Pascal          m68k2
 872                         Basic           m68k4
 873                         occam
 874                         Modula-2
 875                         Fortran
 876
 877 m68020  M68020/ 4/4     C       +       m68020
 878         Sys V/68 R2V2.1         Pascal
 879                         Basic
 880                         occam
 881                         Modula-2
 882                         Fortran
 883
 884 sun3    Sun-3 R4.1      4/4     C       +       sun3
 885                         Pascal          m68020
 886                         Basic
 887                         occam
 888                         Modula-2
 889                         Fortran
 890
 891 sun2    Sun-2 R3.0      4/4     C       +       sun2
 892                         Pascal          m68k4
 893                         Basic           m68k2
 894                         occam
 895                         Modula-2
 896                         Fortran
 897
 898 i86     IBM PC/IX       2/2     C       +       i86     IBM PC with PC/IX
 899                         Pascal                  Causes kernel crashes
 900                         Basic
 901                         occam
 902                         Modula-2
 903
 904 xenix3  Microsoft       2/2     C       +       xenix3  IBM AT with Xenix
 905         Xenix V3                Pascal          i86
 906                         Basic
 907                         occam
 908                         Modula-2
 909
 910 i386    SCO Xenix       4/4     C       +       i386    Intel 80386
 911         System V                Pascal                  Xenix System V
 912                         Basic
 913                         occam
 914                         Modula-2
 915                         Fortran
 916
 917 minix   Minix PC        2/2     C       +       minix   IBM PC running Minix
 918                         Pascal          i86
 919                         Basic
 920                         occam
 921                         Modula-2
 922
 923 minixST ST Minix        2/4     C       +       minixST Atari ST running Minix
 924                         Pascal          m68k2
 925                         Basic
 926                         occam
 927                         Modula-2
 928
 929 z8000   Zilog 8000      2/2     C               z8000   Central Data
 930                         Pascal                  CPU board
 931                         Basic                   Assembler/loader
 932                         occam
 933                         Modula-2
 934
 935 em22    EM machine      2/2     C       *       em22    Needs interpreter
 936                         Pascal
 937                         Basic
 938                         occam
 939                         Modula-2
 940
 941 em24    EM machine      2/4     C       *       em24    Needs interpreter
 942                         Pascal
 943                         Basic
 944                         occam
 945                         Modula-2
 946
 947 em44    EM machine      4/4     C       *       em44    Needs interpreter
 948                         Pascal
 949                         Basic
 950                         occam
 951                         Modula-2
 952                         Fortran
 953
 954 6500    6502/BBC        2/2     C               6500    Assembler/loader
 955                         Pascal
 956                         Basic
 957                         occam
 958                         Modula-2
 959
 960 6800    Bare 6800                               6800    Assembler only
 961
 962 6805    Bare 6805                               6805    Assembler only
 963
 964 6809    Bare 6809                               6809    Assembler only
 965
 966 ns      Bare NS16032    4/4     C               ns
 967                         Pascal
 968                         Basic
 969                         occam
 970                         Modula-2
 971                         Fortran
 972
 973 i80     Hermac/z80      2/2     C               i80
 974                         Pascal
 975                         Basic
 976                         occam
 977                         Modula-2
 978
 979 z80     Hermac/z80      2/2     C               z80     \fIi80\fP is faster
 980                         Pascal
 981                         Basic
 982                         occam
 983                         Modula-2
 984
 985 s2650   Signetics                               s2650   Assembler only
 986
 987 arm     Acorn   4/4     C       *       arm     Assembler/loader
 988         Archimedes              Pascal
 989                         Basic
 990                         occam
 991                         Modula-2
 992                         Fortran
 993 .TE
 994 .LP
 995 The commands \fBem22\fP, \fBem24\fP and \fBem44\fP
 996 produce e.out files with EM machine code which must be interpreted.
 997 The Kit contains three interpreters: one running under PDP 11/V7 UNIX,
 998 one for the M68000, running under the PMDS system, Sun systems,
 999 the Mantra system, etc, and a portable one, written in C.
1000 The first one can only interpret 2/2 e.out files,
1001 the second takes 2/4 and 4/4 files,
1002 and the last one takes 2/2, 2/4 and 4/4.
1003 The PDP 11 interpreter executes floating point instructions.
1004 .LP
1005 The program \fB$TARGET_HOME/bin/em\fP calls the appropriate
1006 interpreter.
1007 The interpreters are looked for in the em22, em24 and em44
1008 subdirectories of $TARGET_HOME/lib.bin.
1009 The third interpreter is available as the program \fB$TARGET_HOME/bin/int\fP
1010 in the bin directory.
1011 .NH
1012 Compilation on a different machine.
1013 .PP
1014 The installation mechanism of the Kit is supposed to be portable across
1015 .UX
1016 machines, so
1017 the Kit can be installed and used as a cross-compiler
1018 for the languages it supports on any
1019 .UX
1020 machine.
1021 The presence of most
1022 .UX
1023 utilities is essential for compilation.
1024 A few of the programs certainly needed are: sh, C-compiler, sed, ed,
1025 make, and awk.
1026 .NH 2
1027 Backend
1028 .PP
1029 The existence of a backend with a system call library
1030 for the target system is essential
1031 for producing executable files for that system.
1032 Rewriting the system call library if the one supplied does
1033 not work on the target system is fairly straightforward.
1034 If no backend exists for the target CPU type, a new backend has to be written
1035 which is a major undertaking.
1036 .NH 2
1037 Universal assembler/loader, link editor
1038 .PP
1039 For most machines, the description files in $TARGET_HOME/lib/*/descr use our
1040 universal assembler and our link editor.
1041 The load file produced is not directly
1042 usable in any system known to us,
1043 but has to be converted before it can be put to use.
1044 The \fIcv\fP programs convert our a.out format into
1045 executable files.
1046 The \fIdl\fP programs present for some machines unravel
1047 our a.out files and transmit commands to load memory
1048 to a microprocessor over a serial line.
1049 The file $TARGET_HOME/man/man5/ack.out.5 contains a description of the format of
1050 the universal assembler load file.
1051 It might be useful to those who wish or need to write their
1052 own conversion programs.
1053 Also, a module is included to read and write our a.out format.
1054 See $TARGET_HOME/man/man3/object.3.
1055 .NH
1056 Options
1057 .NH 2
1058 Default machine
1059 .PP
1060 There is one important option in $TARGET_HOME/config/local.h.
1061 The utility \fIack\fP uses a default machine name when called
1062 as \fIacc\fP, \fIcc\fP, \fIabc\fP, \fIapc\fP, \fIpc\fP, \fIocm\fP,
1063 \fIm2\fP, \fIf2c\fP, or \fIack\fP.
1064 The machine name used by default is determined by the
1065 definition of ACKM in $TARGET_HOME/config/local.h.
1066 The Kit is distributed with "sun3" as the default machine,
1067 but the shell script "first" in the directory "first" alters this
1068 to suit the target system.
1069 There is nothing against using the Kit as a cross-compiler
1070 and by default produce code that can't run on the local system.
1071 .NH 2
1072 Pathnames
1073 .PP
1074 Absolute path names are concentrated in "$TARGET_HOME/config/em_path.h".
1075 Only the utilities \fIack\fP, \fIflex\fP, and \fILLgen\fP use
1076 absolute path names to access files in the Kit.
1077 The tree is distributed with /usr/em as the working
1078 directory.
1079 The definition of EM_DIR in em_path.h should be altered to
1080 specify the root
1081 directory for the Compiler Kit binaries on the local system ($TARGET_HOME).
1082 This is done automatically by the shell script "first" in the
1083 directory "first".
1084 Em_path.h also specifies which directory should be used for
1085 temporary files.
1086 Most programs from the Kit do indeed use that directory
1087 although some remain stubborn and use /tmp or /usr/tmp.
1088 .LP
1089 The shape of the tree should not be altered lightly because
1090 most Makefiles and the
1091 utility \fIack\fP know the shape of the ACK tree.
1092 The knowledge of the utility \fIack\fP about the shape of the tree is
1093 concentrated in the files in the directory $TARGET_HOME/lib/*/descr and $TARGET_HOME/lib/descr/*.
1094 .NH
1095 Makefiles
1096 .PP
1097 Most directories contain a "proto.make", from which a Makefile is derived.
1098 Apart from commands applying to that specific directory these
1099 files all recognize a few special commands.
1100 When called with one of these they will apply the command to
1101 their own directory.
1102 The special commands are:
1103 .sp 1
1104 .IP "install" 20
1105 recompile and install all binaries and libraries.
1106 .br
1107 Some Makefiles allow errors to occur in the programs they call.
1108 They ignore such errors and notify the user with the message
1109 "~....... error code n: ignored".
1110 Whenever such a message appears in the output it can be ignored.
1111 .IP "cmp"
1112 recompile all binaries and libraries and compare them to the
1113 ones already installed.
1114 .IP pr
1115 print the sources and documentation on the standard output.
1116 .IP opr
1117 make pr | opr
1118 .br
1119 Opr should be an off-line printer daemon.
1120 On some systems it exists under another name e.g. lpr.
1121 The easiest way to call such a spooler is using a shell script
1122 with the name opr that calls lpr.
1123 This script should be placed in /usr/bin or $TARGET_HOME/bin or
1124 one of the directories in the PATH environment variable.
1125 .IP clean
1126 remove all files not needed for day-to-day use,
1127 that is binaries not in $TARGET_HOME/bin or $TARGET_HOME/lib.bin, object files etc.
1128 .LP
1129 Example:
1130 .DS
1131 make install
1132 .DE
1133 given as command in a configuration directory will cause
1134 compilation of all programs in the directory and copying of the results
1135 to the $TARGET_HOME/bin and $TARGET_HOME/lib.bin directories.
1136 .NH
1137 Testing
1138 .PP
1139 Test sets are available in Pascal, C, Basic and EM assembly:
1140 .IP EM 8
1141 the directory $SRC_HOME/emtest contains a few EM test programs.
1142 The EM assembly files in these tests must be transformed into
1143 load files.
1144 These tests use the LIN and NOP instructions to mark the passing of each
1145 test.
1146 The NOP instruction prints the current line number during the
1147 test phase.
1148 Each test notifies its correctness by calling LIN with a unique
1149 number followed by a NOP which prints this line number.
1150 The test finishes normally with 0 as the last number printed
1151 In all other cases a bug showed its
1152 existence.
1153 .IP Pascal
1154 the directory $SRC_HOME/lang/pc/test contains a few Pascal test programs.
1155 All these programs print the number of errors found and a
1156 identification of these errors.
1157 .sp 1
1158 .ti +4
1159 We also tested Pascal with the Validation Suite.
1160 The Validation Suite is a collection of more than 200 Pascal programs,
1161 designed by Brian Wichmann and Arthur Sale to test Pascal compilers.
1162 We are not allowed to distribute it, but a copy may
1163 be requested from
1164 .DS
1165 Richard J. Cichelli
1166 A.N.P.A.
1167 1350 Sullivan Trail
1168 P.O. Box 598
1169 Easton, Pennsylvania 18042
1170 USA
1171 .DE
1172 .IP C
1173 the sub-directories in $SRC_HOME/lang/cem/ctest contain C test programs.
1174 The idea behind these tests is:
1175 if there is a program called xx.c, compile it into xx.cem.
1176 Run it with standard output to xx.cem.r, compare this file to
1177 xx.cem.g, a file containing the 'ideal' output.
1178 Any differences will point to implementation differences or
1179 bugs.
1180 Giving the command "run gen" or plain "run" starts this
1181 process.
1182 The differences will be presented on standard output.
1183 The contents of the result files depend on the word size,
1184 the xx.cem.g files on the distribution are intended for a
1185 32-bit machine.
1186 .IP Basic
1187 the directory $SRC_HOME/lang/basic/test contains some forty Basic programs.
1188 Not all of these programs are correct, some have syntactic errors,
1189 some simply don't work.
1190 The Makefile in that directory attempts to compile and run
1191 these tests.
1192 If it compiles its output is compared to a file with suffix .g
1193 which contains the output to be expected.
1194 The make should be started with its standard input diverted
1195 to /dev/null.
1196 An example of the output of a make is present in the file Out.std.
1197 .NH
1198 Documentation
1199 .PP
1200 After installation, the manual pages for Amsterdam Compiler Kit can be found
1201 in the $TARGET_HOME/man directory. Also, the following documents are provided
1202 in the $TARGET_HOME/doc directory:
1203 .TS
1204 l l.
1205 toolkit.doc     general overview (CACM article)
1206 em.doc  description of the EM machine architecture
1207 ack.doc format of machine description files (lib/*/descr)
1208 ansi_C.doc      ANSI C implementation description
1209 basic.doc       Basic reference manual
1210 pcref.doc       Pascal-frontend reference manual
1211 val.doc results of running the Pascal Validation Suite
1212 crefman.doc     C-frontend description
1213 LLgen   description of the LL(1) parser generator
1214 peep.doc        internal documentation for the peephole optimizer
1215 cg.doc  documentation for backend writers and maintainers
1216 regadd.doc      addendum to previous document describing register variables
1217 ncg.doc documentation for the newest backends
1218 v7bugs.doc      bugs in the V7 system and how to fix them
1219 6500.doc        MSC 6500 backend description
1220 i80.doc Intel 8080 backend description
1221 z80.doc Zilog Z80 backend description
1222 m68020.doc      Motorola M68000/M68020 backend description
1223 sparc.doc       SPARC code expander description
1224 occam.doc       occam-frontend description
1225 ego.doc Global Optimizer description
1226 top.doc Target Optimizer description
1227 int.doc description of the EM interpreter written in C
1228 ceg.doc documentation for code-expander writers and maintainers
1229 lint.doc        documentation of LINT
1230 m2ref.doc       Modula-2 frontend description
1231 install.doc     this document
1232 install.pr      this document (formatted for a simple line printer)
1233 .TE
1234 .LP
1235 Use the Makefile to get readable copies.
1236 .LP
1237 Good luck.