README

   1                      THE AMSTERDAM COMPILER KIT V6.1pre1
   2                      ===================================
   3
   4                   � 1987-2005 Vrije Universiteit, Amsterdam
   5                                 2018-02-23
   6
   7
   8 INTRODUCTION
   9 ============
  10
  11 The Amsterdam Compiler Kit is a complete compiler toolchain consisting of
  12 front end compilers for a number of different languages, code generators,
  13 support libraries, and all the tools necessary to go from source code to
  14 executable on any of the platforms it supports.
  15
  16 This is an early prerelease of the apocryphal version 6.1 release. Not a
  17 lot is supported, the build mechanism needs work, and a lot of things are
  18 probably broken. However, what's there should be sufficient to get things
  19 done and to evaluate how the full 6.1 release should work.
  20
  21
  22
  23 SUPPORT
  24 =======
  25
  26 Languages:
  27
  28 ANSI C, B, Pascal, Modula 2, Basic. K&R is supported via the ANSI C compiler.
  29
  30 Platforms:
  31
  32 pc86          produces bootable floppy disk images for 8086 PCs
  33 linux386      produces ELF executables for PC Linux systems
  34 linux68k      produces ELF executables for m68020 Linux systems
  35 linuxppc      produces ELF executables for PowerPC Linux systems
  36 linuxmips     produces ELF executables for little-endian MIPS32r2 Linux systems
  37 cpm           produces i80 CP/M .COM files
  38 rpi           produces Raspberry Pi GPU binaries
  39 pdpv7         produces PDP/11 V7 Unix binaries
  40
  41
  42
  43 INSTALLATION
  44 ============
  45
  46 The version 5.0 build mechanism has been completely rewritten. Installation
  47 ought to be fairly straightforward.
  48
  49 Requirements:
  50
  51 - an ANSI C compiler. This defaults to gcc. You can change this by setting
  52   the CC make variable.
  53
  54 - flex and yacc.
  55
  56 - GNU make.
  57
  58 - (optionally) ninja; if you've got this, this will be autodetected and give
  59   you faster builds.
  60
  61 - (optionally) the qemu suite: if you have this installed, the build system
  62   will detect it automatically and run the test suites for the supported
  63   architectures. Get both the qemu-system-* platform emulators and the qemu-*
  64   userland emulators (only works on Linux).
  65
  66 - about 115MB free in /tmp (or some other temporary directory).
  67
  68 - about 15MB in the target directory.
  69
  70 Instructions:
  71
  72 - edit the Makefile. There's a small section at the top where you can change
  73   the configuration. Probably the only one you may want to edit is PREFIX,
  74   which changes where the ACK installs to.
  75
  76 - Run:
  77
  78     make
  79
  80   ...from the command line. This will do the build.
  81
  82   The make system is fully parallelisable. If you have a multicore system,
  83   install ninja and it'll use all your cores. If you don't have ninja, you
  84   can still use make for parallel builds with:
  85
  86     make -r -j8   # or however many cores you have
  87
  88   ...but frankly, I recommend ninja.
  89
  90 - Run:
  91
  92     sudo make install
  93
  94   ...from the command line. This will install the ACK in your PREFIX
  95   directory (by default, /usr/local).
  96
  97 The ACK should now be ready to use.
  98
  99
 100
 101 USAGE
 102 =====
 103
 104 Currently I haven't sorted out all the documentation --- it's supplied in the
 105 distribution, but not all of it gets installed yet --- so here is a quickstart
 106 guide.
 107
 108 The main command to use is 'ack'. This invokes the compiler and the linker.
 109 Some useful options include:
 110
 111   -m<platform>     build for the specified platform
 112   -o <file>        specifies the output file
 113   -c               produce a .o file
 114   -c.s             produce a .s assembly file
 115   -O               enable optimisation (optimisation levels go up to 6)
 116   -ansi            compile ANSI C (when using the C compiler)
 117   -v               be more verbose (repeatable)
 118   <file>           build file
 119
 120 ack figures out which language to use from the file extension:
 121
 122   .c               C (ANSI or K&R)
 123   .b               the PDP-11 dialect of B
 124   .bas             Basic
 125   .mod             Modula-2
 126   .ocm             Occam 1
 127   .p               Pascal
 128   .o               object files
 129   .s               assembly files
 130   .e               ACK intermediate code assembly files
 131
 132 For further information, see the man page (which actually does get
 133 installed, but is rather out of date).
 134
 135 There are some (known working) example programs in the 'examples' directory.
 136 A sample command line is:
 137
 138 ack -mlinux386 -O examples/paranoia.c
 139
 140
 141
 142 GOTCHAS
 143 =======
 144
 145 There are some things you should be aware of.
 146
 147 - Look at plat/<PLATFORMNAME>/README for information about the supported
 148   platforms.
 149
 150 - The library support is fairly limited; for C, it's at roughly the ANSI C
 151   level, and for the other languages it's similar.
 152
 153 - When compiling languages other than C, the ACK will usually look at the
 154   first character of the file. If it's a #, then the file will be run through
 155   the C preprocessor anyway.
 156
 157 - BSD systems may need to up the number of file descriptors (e.g.
 158   'ulimit -n 200') before the ACK will compile.
 159
 160 - The ACK uses its own .o format. You won't be able to mix the ACK's object
 161   files and another compiler's.
 162
 163 - When compiling together multiple B source files, you need to do some extra
 164   work to initialise them properly otherwise your program will crash on
 165   startup; see the ack(1) and abmodules(1) man pages.
 166
 167 - The distribution contains *everything*, including the weird, ancient,
 168   archaic stuff that doesn't work any more and never will, such as the int EM
 169   interpreter and the assembler-linkers. Only some of it builds. Look for
 170   build.lua files.
 171
 172
 173
 174 DISCLAIMER
 175 ==========
 176
 177 The ACK is mature, well-tested software, but the environment in which it was
 178 developed for and tested under is rather different from that available on
 179 today's machines. There will probably be little in the way of logical bugs,
 180 but there may be many compilation and API bugs.
 181
 182 If you wish to use the ACK, *please* join the mailing list. We are interested
 183 in any reports of success and particularly, failure. If it does fail for you,
 184 we would love to know why, in as much detail as possible. Bug fixes are even
 185 more welcome.
 186
 187 The ACK is licensed under a BSD-like license. Please see the 'Copyright' file
 188 for the full text.
 189
 190 You can find the mailing list on the project's web site:
 191
 192         http://tack.sourceforge.net/
 193
 194 Please enjoy.
 195
 196 David Given (davidgiven on Github)
 197 dg@cowlark.com
 198 2018-09-18