doc/install.pr

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