Browse Source

Updated for the new release.

dtrg 17 years ago
parent
commit
c74f9cc2e9
1 changed files with 129 additions and 157 deletions
  1. 129 157
      README

+ 129 - 157
README

@@ -1,162 +1,142 @@
 # $Source$
 # $State$
+# $Revision$
 
-Installing the ACK on a modern platform
-=======================================
-
-This document provides some very quick and dirty instructions for installing
-the ACK on a modern platform. It is not intended as a substitute for the
-real instructions, which can be found in doc/install.pr.
-
-Let me repeat myself:
-
-THE FULL INSTALLATION INSTRUCTIONS ARE IN doc/install.pr.
-
-The ACK is a very large and complex package and has received minimal
-maintenance for the best part of a decade. During that time, the Unix
-world has moved on, and many APIs have changed. It compiles cleanly on
-my, dtrg's, test machine, which is a Debian Ubuntu Linux system. Your
-mileage may vary.
-
-All disclaimers now done, now on to the good stuff:
-
-Building the ACK
-----------------
-
-I'm assuming you're using Linux here, because that's what I use. If you
-don't use Linux, please let me know if you have any trouble and I'll update
-the instructions.
-
-1. Prerequisites
-   
-   The ACK wants to be built with a C compiler called cc. From what I've seen
-   so far of the build system, this can be changed, but not easily.
-   
-   Most platforms have their compiler set up so that 'cc' invokes it, whatever
-   it is; however, some don't. So far the only one I've met that doesn't do
-   this is Solaris with gcc installed, but without the Sun native compiler.
-   
-   If this is the case, the simplest thing to do is to place a symlink to gcc
-   (or your favourite C compiler) in your path somewhere. For example:
-   
-      ln -s /usr/bin/gcc ~/bin/cc
-   
-2. Configure the build.
-
-   To do this, run the first/first script. You will be asked several
-   questions.
-   
-   * What is the root of the ACK source tree?
-   
-     This is the directory that you have unpacked the distribution into.
-     For example, /home/dg/src/Ack-5.6.
-     
-   * What is the root of the configuration tree?
-   
-     This is the directory that the build process will use for temporary
-     files. You'll only need this during the compilation process; it can
-     be removed afterwards.
-     For example, /tmp/ack-conf
-     
-   * What is the root of the ACK binaries?
-   
-     This is the ACK's installation path; where the binaries will live.
-     This needs to be writable during the build process --- if you want
-     to install in /usr/local, you either have to make /usr/local
-     writable or compile as root. Sorry!
-     
-   * What is your system type?
-   
-     Linux isn't on the list. Choose ANY.
-     
-   * Is this the system you are running on?
-   
-     Yes.
-     
-   * Are you satisfied?
-   
-     Yes.
-     
-   * What default machine do you wish to compile for?
-   
-     The ACK wants to know what architecture to target if you don't manually
-     specify an architecture. Unfortunately, it can't generate runnable
-     binaries for Linux or any other modern system (except possible Solaris
-     on Sparc). I'd recommend you choose em44. This will produce portable
-     binaries using the ACK's intermediate format, which you can run using
-     the int interpreter.
-     
-   * What kind of Unix are you running?
-   
-     Linux is a mixture, but I pick SYS_5 and it works.
-     
-   * Do you wish to limit the installation?
-   
-     No. If you pick Yes, the script will ask detailed questions about
-     exactly what you want to build. Modern systems are fast enough that
-     we may as well build everything.
-     
-   * Which system call library do you wish to use on the VAX?
-   
-     I don't have a VAX; the only person I know who has one uses it to vacuum
-     his carpets. I pick libsysV_2 with no ill effects.
-     
-   If the configuration script is happy, it will generate a script called
-   INSTALL.
-   
-3. Do the compilation.
-
-   The configuration script will recommend a command line. Execute this. On
-   modern systems, the compilation doesn't take long.
-   
-   Check the output of the configuration script for "Failed" lines. On my
-   system there are two:
-   
-     $ grep Failed INSTALL.out
-     Failed for Intel 8080 download programs, see dl/Out
-     Failed for Intel 8080 support
-   
-   You can ignore these. They aren't important.
-   
-4. Use the ACK.
-
-   Ensure that the ACK's binary directory is on your path; this is /bin in
-   the directory you specified during the configuration process. In my
-   example, this is /usr/local/bin. The /man subdirectory should go on your
-   manpath.
-
-   To test your path, do: ack
-   
-   This should return silently.
-   
-   To test your manpath, do: man ack
-      
-   This will produce the documentation for the main compiler driver.
-   
-   If this works, you can remove the conf tree (/tmp/ack-conf in my example).
-   
-Gotchas
--------
+                     THE AMSTERDAM COMPILER KIT V6.0pre1
+                     ===================================
+
+                  © 1987-2005 Vrije Universiteit, Amsterdam
+
+
+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, K&R C, Pascal, Modula 2, Occam 1, and a Basic variant.
+
+Platforms:
+
+pc86          produces bootable floppy disk images for 8086 PCs
+
+
+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.
+  
+- Run:
+
+    ./pm install
+    
+  ...from the command line. 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.
+
+
+GOTCHAS
+=======
 
 There are some things you should be aware of.
 
-* The ACK's archiver tool is called 'arch'. This conflicts on Linux platforms
-  with a utility that displays the current architecture. If your compilation
-  occasionally fails obscurely and displays something like 'i686', you are
-  running afoul of this. As a workaround, rearrange your path so the ACK's
-  bin directory comes first --- but do be aware that some Linux system
-  tools may stop working.
+- The only platform supported so far is pc86, which generates 8086 tiny mode
+  executables that will work as floppy disk boot images. So, to run, simply dd
+  the output file (pc86.img by default) onto a floppy disk and boot from it.
+  Be aware that very little functionality is supported and that the entire
+  program, heap and stack and code and all, must fit within 64kB. See
+  plat/pc86/README for more information.
   
-* By default, the ack tool will compile K&R C. Practically all C source these
+- By default, the ack tool will compile K&R C. Practically all C source these
   days is ANSI C --- use the -ansi switch to enable ANSI mode. No, the ACK is
   not C99 compatible.
   
-* Not all combinations of optimisation and architectures work. This is
-  perfectly normal, but the combinations are not well documented. Everything
-  supports -O.
+- 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.
+
   
-Disclaimer
-----------
+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
@@ -179,12 +159,4 @@ Please enjoy.
 
 David Given (dtrg on Sourceforge)
 dg@cowlark.com
-2005-06-24, 23:53
-
-# Revision history
-# $Log$
-# Revision 2.3  2006-07-18 17:21:34  dtrg
-# Added comment about the use of 'cc' rather than 'gcc'.
-#
-# Revision 2.2  2005/06/24 23:20:41  dtrg
-# Added some new readmes at the top level.
+2007-02-25