                          GNAT
                        ~~~~~~~~

This is a port of the GNAT (GNU/NYU Ada Translator) compiler (version
3.0.1) for the Ada 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 gnat.Copying and
gnat.CopyingLib, and later for details).

This port is  1995, 1996 Peter Burwood

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

IMPORTANT: GNAT REQUIRES A LOT OF MEMORY. The wimpslot needs to be at
least 6000K in size. GNAT is NOT capable of grabbing extra memory, so
the initial WimpSlot sets the maximum memory available. GNAT can use
dynamic areas on the Risc PC for the heap and stack and in this mode the
wimpslot needs to be at least 3000K in size (though running from AMU can
increase this). See Dynamic Areas below for further details.

Thanks go to various people for the help and assistance that they have
given me. These are :

The GNAT development team for writing GNAT.

Nick Burrett, Simon Callen, Richard Earnshaw, Michael Ben-Gershon and
Pietr Schonmaker, for most of the hard work involved in the ARM backend.

Niklas Rjemo, for the assembler `as'

Huw Rogers and Simon Callen, for Unixlib.


Files
=====

There are over 900 files in the GNAT binary distribution, so I won't
list them all, but the overall contents of this archive is as follows :-

   !gcc.adainc...        - Ada 95 standard library and GNAT extensions
   !gcc.bin...           - GNAT binaries (see gnatinfo) and gcc binary
   !gcc.gcc.adalib...    - object files for Ada library
   !gcc.gcc.o.libgnat    - support library for GNAT using UnixLib
   !gcc.gcc.o.libgnat_cc - support library for GNAT using SharedCLibrary
   !gcc.gcc.o.libm       - empty maths library to stop complaints
                           the functions are in UnixLib and stubs
   !gcc.gnat             - documentation for GNAT
   !gcc.gnat.examples    - examples from standard GNAT distribution
                           included is a utility that works like Unix's
                           rm command which is used by the makefile.


Installation
============

Before attempting to use GNAT, it should be noted that this distribution
of GNAT is not standalone, consisting of only the GNAT compiler, tools
and library.

GNAT 3.01 requires GCC 2.7.2, as supplied by Nick Burrett and available
from Acorn ftp sites such as Hensa, to be installed. Unpack this
complete archive into the GCC 2.7.2 directory. Double click on !GCC to
ensure the environment is correctly set for the compiler.

There is an replacement binary for !gcc.bin.gcc called !gcc.bin.gcc-gnat
which should be copied over the original !gcc.bin.gcc file from the GCC
2.7.2 distribution (after taking a backup of the original file). This
maybe necessary if the version from GCC 2.7.2 fails to work properly, by
which I mean that running the makefile in the examples directory fails.
This alternative binary is included because Nick Burrett sent me some
changes for the gcc binary and I have just tried them and I can't get
gcc working now. The version in this archive understands C, C++, Fortran
and Ada filenames, so should work with those GNU compilers.

GNAT 3.01 also requires UnixLib 3.7a or later, but not UnixLib 4.0. GNAT
will not work with UnixLib 3.6e. The following commands should be part
of the !Run file that comes with GCC 2.7.2, but if not, then please add
them before trying to use GNAT.

  | Set search paths for the Ada run time library files
  *Set GNATada$Path <Obey$Dir>.adainc.
  *Set GNATInc$Path gnatada:1.,gnatada:2.,gnatada:3.,gnatada:4.,gnatada:5.,gnatada:6.,gnatada:7.
  *Set GNATlib$Path gcc:adalib.1.,gcc:adalib.2.,gcc:adalib.3.,gcc:adalib.4.,gcc:adalib.5.,gcc:adalib.6.,gcc:adalib.7.

  | Set search path for gnatbl
  *SetMacro path "<Run$Path>"

GNAT uses the following filename extensions :-

   .ads   - Ada specifications (similar to C .h files).
   .adb   - Ada bodies (similar to C .c files).
   .adc   - The file gnat.adc can be used to override the normal file
            naming convention (see !gcc.gnat.gnatinfo).
   .ali   - GNAT's source code library support files (these are
            generated by the compiler).
   .xrs   - cross reference file for corresponding .ads file
   .xrb   - cross reference file for corresponding .adb file

and these extensions must be included in the UnixFS$sfix environment
variable. GCC 2.7.2's !Run file should already include these, but if not
then change the '*Set UnixFS$sfix ...' to something like this :-

  *Set UnixFS$sfix "a:c:f:h:i:l:o:p:s:y:ads:adb:ali:adc:xrb:xrs"


Using GNAT
==========

See the gnatinfo file in the gnat directory and the GCC-FAQ which is in
the GCC 2.7.2 archive. Also look at the makefile in the gnat.examples
directory which can be executed with amu. Ensure that you have a large
enough WimpSlot, otherwise AMU will exit with a fatal error.


Using the SharedCLibrary
========================

It is actually possible to use GNAT without UnixLib by using the
SharedCLibrary and linking against Acorn's stubs. Do not try to use
UnixLib and Acorn's stubs together in the same program - it will not
work.

To use Acorn's stubs you will need Acorn's C compiler or a copy of
gstubs from ftp sites such as Hensa. You must link with the libgnat_cc
library instead of the libgnat library (these files are in !GCC.gcc.o).
This can be accomplished by either replacing libgnat with libgnat_cc
(after you have made a safe copy of libgnat) or by using
"-mstubs -lgnat_cc" with gnatbl. The makefile in the examples directory
has a line commented out which illustrates this method of using the
SharedCLibrary. Simply uncomment this line and build the example
programs with the makefile.


File Name Rules
===============

The gnatinfo file explains how GNAT expects to find files. This naming
convention is necessary for GNAT to find `with'ed units. Under RISC OS,
the file name is crunched to 10 characters rather than 8 characters as
with DOS. gnatk8 can be used to find out what the krunched name of a
file should be by using `10' as the second argument to gnatk8.

File name rules can be overridden with the pragma Source_File_Name as
described in gnatinfo.


Dynamic Areas
=============

I have modified UnixLib to use dynamic areas on the Risc PC and these
modifications have been included in UnixLib 3.7a. This section applies
to all GNU compilers supplied by either Nick Burrett, myself or
(hopefully) anyone else providing they have used UnixLib 3.7a. A
description of using dynamic areas is included with UnixLib 3.7a.
Basically, use

  *Set GCC_Heap ""

to enable dynamic areas for the compiler and

  *UnSet GCC_Heap

to disable dynamic areas for the compiler.

Before running a program set the wimpslot in the normal way, but it only
needs to be large enough to hold the sum of the largest executables that
can be run concurrently. e.g., with gcc, use the unsqueezed size of gcc
plus cc1. When running from a command line amu remember to allow
additional space for the amu executable and amu's workspace (though this
is tricky to estimate!).

If other programs that form part of GNAT are run directly from the
command line, e.g., gnatmake, then separate environment variables must
be set to allow these programs to use dynamic areas for the program's
heap. So, with gnatmake,

   *Set gnatmake_heap ""


Speeding up compilation
=======================

If you have plenty of ram, then moving the Ada library units onto a ram
disc should speed up compilations which "with" a lot of standard library
units. This will require a ram disc of nearly 3MB, so is best done only
if you have more than 20MB of ram. If the standard libraries are placed
on the ram disc, then the GNATada$Path should be redefined to point to
the ram disc. The Ada library units are the !gcc.adainc directory.

Placing the main compiler, gnat1, on the ram disc will also help,
providing you have enough free ram. If gnat1 is put on the ram disc,
then ensure that the ram location appears earlier in the run path.


Known problems
==============

Known, damn if I'd known about them, I'd have fixed them. Please tell me
all that you find and see below for how to contact me and the file
!gcc.gnat.Bugs for what to do if you have found a bug.

Actually AMU behaviour is fun, see the examples directory for a working
makefile.

RISC OS specific documentation is also lacking (i.e., no Intro file). It
will improve soon.

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


Known Restrictions
==================

No tasking for RISC OS version, yet!

No interfaces specifications for the Wimp, though I am working on
providing libraries. For the time being, implement a tight interface to
the wimp with some high level C functions and write your own interface
file.


Pointers to Ada related items on the Web
========================================

The main GNAT ftp site is ftp://ftp.cs.nyu.edu:/pub/gnat.

Here are some WWW URL's for Ada. You can get to many other sites that
have Ada related information from the first two pointers.

  Ada meta sites
    http://www.cera.com/ada.htm
  Home of the Brave Ada programmers
    http://lglwww.epfl.ch/Ada/
  Ada Lovelace tutorials
    http://lglwww.epfl.ch/Ada/Tutorials/Lovelace/lovelace.html
  AdaBasis - reusable component repository
    http://www.informatik.uni-stuttgart.de/ifi/ps/ada-software/ada-software.html
  Reusable Component Library
    http://lglwww.epfl.ch/Components

See the end of the file !gcc.gnat.gnatinfo for some other pointers.


Contacting me
=============

If you wish to contact me, then I can be contacted as follows:

Peter Burwood
205 Masons Avenue
Harrow
Middlesex
HA3 5AZ

Email: gnat@arcangel.demon.co.uk for gnat related queries
       pjb@arcangel.demon.co.uk for anything else
