The GNU C compiler
==================

Introduction
------------

This is a port of the GNU C compiler (version 2.7.2) for the C programming
language to the Acorn range of ARM based machines, running under RISC OS.
As such, this package is covered by the FSF General Public License (see the
files docs.COPYING and docs.COPYINGLIB for details).

This port is © Copyright 1996 Nick Burrett

As with GNU programs, THERE IS NO WARRANTY OF ANY SORT

This compiler requires a minimum 2300Kb of free RAM for compilations.

Thanks go to various people for the help and assistance that they have
given me during the creation of this port. These are:

Richard Earnshaw, Pieter Schoenmakers and Martin Simmons for most of
the hard work involved in the RISCiX ARM backend.

Peter Burwood for additional problem solving and testing abilities.

Files
-----

This is a binary distribution only and consists of the following files:

  bin.cc1        	C compiler
  docs.c.!Readme        This documentation

The compiler sources (about 27Mb) can be obtained from the sites listed at
the end of docs.!Intro.

Installation
------------

Before attempting to use GNU C, it should be noted that this distribution
will require the GCC front end files stored in the archive gccmain.zip.
If you do not have a copy of this, it can be retrieved from
  ftp://micros.hensa.ac.uk/micros/arch/riscos/b/b013/gccmain.zip

GNU C 2.7.2 also requires UnixLib 3.7a or later, but not UnixLib 4.0.
GNU C will not work with UnixLib 3.6e or earlier.


Compiling C source
------------------

C source files are kept in the 'c' directory. Header files are stored in
the 'h' directory.

Simply type:
  gcc -c c.test

will compile the C file, test, into an AOF file and store it in the 'o'
directory.

Automatically compiling and linking is simple:
  gcc c.test -o test

will compile and link the file c.test and store the resultant binary in the
current directory and call it test.

All GNU compilers require the library gcc:o.libgcc to operate. So separate
compile and link operations must include this.


Compiling and running the example programs
------------------------------------------

The following example programs are to be found in the directory !gcc.files.
For each program, there is a list of the necessary command lines for how
to compile, link and run the program.


hellow
^^^^^^
The standard C program.

Source: 	c.hellow
Compile using: 	gcc c.hellow -o hellow
Run using: 	hellow


ackermann
^^^^^^^^^
A benchmark program, used to indicate the coding efficiency of procedures.
Also illustrates how to receive arguments passed on the command line.

Source:		c.ackermann
Compile using:	gcc c.ackermann -o ackermann
Run using:	ackermann 3 4

Try using different numbers instead of 3 and 4.


Dhrystone 2.1
^^^^^^^^^^^^^
Used as the standard integer benchmark. This program consists of two
source files which will need linking together. The best solution is to
compile each file separately, for which the resultant Acorn Object Format
files will be placed in the 'o' directory, and then link with the necessary
libraries to create an executable.

Source:		c.dhry_1, c.dhry_2, h.dhry_2

Compile using:	gcc -c c.dhry_1
		gcc -c c.dhry_2

Link using:	drlink -o dhry o.dhry_1 o.dhry_2 gcc:o.libgcc unix:o.unixlib

Run using:	dhry

When prompted for the number of iterations, use any number in the range
10000 to 200000.  It might be worth adding the command line option '-O2'
when compiling to measure the difference achieved between no optimisation
and full optimisation.


Interworking with Acorn C
-------------------------

Code compiled with GCC can be linked with code produced by the Acorn C
compiler, and probably other APCS-R conformant compilers, with no major
problems.

However, experience has showed that there are minor incompatibilities between
Acorn C and GNU C in the way structures are implemented. These
incompatibilities are very minor and should not affect the general user.


Predefines
----------

In addition to the ones defined by the GCC front end, GNU C also supplies
'__GNUC__'.


Known problems
--------------

If you find a bug then please read the file docs.bugs for what to do if
you have found a bug.

Here is a list of all problems that I know of:

GCC 2.4.5 produces incompatible code with 2.7.2 and that is simply that.


Known Restrictions
------------------

Non-local gotos are not implemented for functions within functions. This is
being worked on, when I have the time.


Contacting me
-------------

I can be contacted by e-mail at: nickb@digibank.demon.co.uk

However, if there is no response from that address I can be contacted
through Simon Callan: gcc@callan.demon.co.uk.
