ack/README

# $Source$
# $State$
# $Revision$

                     THE AMSTERDAM COMPILER KIT V6.0pre3
                     ===================================

                  © 1987-2005 Vrije Universiteit, Amsterdam
                                2007-04-29


INTRODUCTION
============

The Amsterdam Compiler Kit is a complete compiler toolchain consisting of
front end compilers for a number of different languages, code generators,
support libraries, and all the tools necessary to go from source code to
executable on any of the platforms it supports.

This is an early prerelease of the upcoming version 6.0 release. Not a
lot is supported, the build mechanism needs work, and a lot of things are
probably broken. However, what's there should be sufficient to get things
done and to evaluate how the full 6.0 release should work. 


SUPPORT
=======

Languages:

ANSI C, Pascal, Modula 2. K&R is supported via the ANSI C compiler.

Platforms:

pc86          produces bootable floppy disk images for 8086 PCs
linux386      produces ELF executables for PC Linux systems
cpm           produces i80 CP/M .COM files


INSTALLATION
============

The version 6.0 build mechanism has been completely rewritten and is based
around the Prime Mover build tool (see http://primemover.sf.net for more
information). Installation ought to be fairly straightforward.

Requirements:

- an ANSI C compiler. Currently, I'm afraid, it's hard-coded to use gcc.
  To change, try changing the variable definitions in first/c.pm. This also
  needs to be available as 'cc' from the shell.
  
- about 20MB free in /tmp (or some other temporary directory).

- about 6MB in the target directory.

Instructions:

- edit config.pm. There's a small section at the top containing some editable
  variables. Probably the only one you may want to edit is PREFIX, which
  changes where the ACK installs to.
  
- Run:

    ./pm configure
    
  ...from the command line. This will write out a configuration file.
  
- Run:

    ./pm
    
  ...from the command line. This will actually do the build. This takes
  about two minutes on my 1.6GHz Athlon Linux machine and about 30 on my
  166MHz Pentium OpenBSD machine.
  
- Run:

    ./pm install
    
  ...from the command line (possibly with sudo). This will install the built
  ACK into whatever directory you nominated in PREFIX.
  
The ACK should now be ready to use.


USAGE
=====

Currently I haven't sorted out all the documentation --- it's supplied in the
distribution, but not all of it gets installed yet --- so here is a quickstart
guide.

The main command to use is 'ack'. This invokes the compiler and the linker.
Some useful options include:

  -m<platform>     build for the specified platform
  -o <file>        specifies the output file
  -c               produce a .o file
  -c.s             produce a .s assembly file
  -O               enable optimisation
  -ansi            compile ANSI C (when using the C compiler)
  <file>           build file

ack figures out which language to use from the file extension:

  .c               C (ANSI or K&R)
  .b               Basic
  .mod             Modula-2
  .ocm             Occam 1
  .p               Pascal
  .o               object files
  .s               assembly files

For further information, see the man page (which actually does get
installed, but is rather out of date).

There are some (known working) example programs in the 'examples' directory.
A sample command line is:

ack -mlinux386 -O examples/paranoia.c


GOTCHAS
=======

There are some things you should be aware of.

- Look at plat/<PLATFORMNAME>/README for information about the two supported
  platforms.
  
- The library support is fairly limited; for C, it's at roughly the ANSI C
  level, and for the other languages it's similar.
  
- When compiling languages other than C, the ACK will usually look at the
  first character of the file. If it's a #, then the file will be run through
  the C preprocessor anyway.

- BSD systems may need to up the number of file descriptors (e.g.
  'ulimit -n 200') before the ACK will compile.
  
- The ACK uses its own .o format. You won't be able to mix the ACK's object
  files and another compiler's.


DISCLAIMER
==========

The ACK is mature, well-tested software, but the environment in which it was
developed for and tested under is rather different from that available on
today's machines. There will probably be little in the way of logical bugs,
but there may be many compilation and API bugs.

If you wish to use the ACK, *please* join the mailing list. We are interested
in any reports of success and particularly, failure. If it does fail for you,
we would love to know why, in as much detail as possible. Bug fixes are even
more welcome.

The ACK is licensed under a BSD-like license. Please see the 'Copyright' file
for the full text.

You can find the mailing list on the project's web site:

	http://tack.sourceforge.net/
	
Please enjoy.

David Given (dtrg on Sourceforge)
dg@cowlark.com
2007-04-29