Introduction to GCC 3.4 for RISC OS
===================================

This is a short introduction to GCC, the GNU Compiler Collection or RISC OS.
This document does not provide an introduction to programming, for that you
will have to get a text book on the language you are interested in.

IMPORTANT NOTE 1: The GCC compiler binaries are at least 4000K, so you must
ensure that a large enough Wimpslot has been allocated. Please refer to the
`Troubleshooting' section later in this document, if you are getting
`Address exception' and `No writable memory at this address' errors.

IMPORTANT NOTE 2: If you have received this copy of GCC from a CD, then it is
likely there is a more up-to-date version obtainable from
http://gccsdk.riscos.info/ which is also the homepage of this GCC port.

IMPORTANT NOTE 3: GCC requires a minimum of 16MB RAM.

IMPORTANT NOTE 4: This GCC port itself and the code produced using this GCC
version is targeted and tested for RISC OS 4 (26-bit and 32-bit version) and
RISC OS 5 (32-bit version).


The RISC OS GNU Compiler Collection consists of a generic front end program
`gcc' that provides a consistent interface to the compilers themselves.
Currently compilers are supported for the languages C, C++ and Fortran.

GCC is covered by the FSF General Public License (see the files docs.COPYING
and docs.COPYINGLIB for details).  Note that a GCCSDK release can contain
other binaries and/or source code covered by other licenses (see docs
directory for more information).

This port of GCC is Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001 Nick Burrett
Copyright (c) 2002, 2003, 2004, 2005, 2006 GCCSDK Developers

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

The standard RISC OS distribution contains GCC and supporting binaries
allowing you to start developing applications and modules straight away. So
you get a C compiler, a C++ compiler, an AOF linker, an AOF assembler,
a module header and veneer generator, the UnixLib C runtime library and
headers and stubs for the SharedCLibrary (as found in the RISC OS ROMs).


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

To install GCC, copy the contents of this archive onto your hard disc.
Other compilers can be installed by copying the contents of their
archives into the same directory as where you install GCC - RISC OS will
automatically combine the !gcc directories together. Running !gcc will
setup Run$Path to automatically search for the compiler tools.

As compilers are installed, sub-directories named according to the language
they support will be placed within !gcc.docs. These sub-directories will
contain specific information for the language compiler, including its
usage and environment requirements.

GCC uses a linker front end, LD. This will search for both drlink and link
on the current Run$Path and in that order.

This completes installation, and GCC may be used simply by typing
'gcc' at the CLI prompt.


Simple compilations
-------------------

This assumes you have actually installed a compiler. Please note that the
instructions below are generic and the ideas presented can be applied to all
GNU compilers. The usage of C source files is merely for example purposes.

Source files are stored in the standard ASCII text format and kept in a
directory that is relevant for the language of your program. For example,
C programs are stored in directory 'c' and C++ programs are stored in 'cc'.

For simple use, all that is needed is to set up a command line prompt and
ensure there is enough free memory to run the compiler (details of memory
requirements vary between compilers and can be found in the specific
compiler documentation).

To compile a C program just type:

   *gcc hellow.c

This will compile, assemble and link the source 'c.hellow' to produce an
executable called '!RunImage', which can be run immediately.

Adding the switch '-o' to the command line, it's possible to specify a
place to store the resultant file:

   *gcc hellow.c -o hellow

This will compile, assemble and link the source 'hellow.c' to produce an
executable called 'hellow', which can be run immediately.

It is possible to compile several sources at one go, mixing C sources in
the same program, using a command line of:

   *gcc file1.c file2.c file3.c file4.c

Again, this will compile, assemble and link all the sources to produce the
'!RunImage' executable.

To compile to the object form, use the -c switch. i.e.

   gcc -c file.c

will compile and assemble 'file.c' to 'file.o'.

To compile the same files but using the SharedCLibrary as the target
run-time library instead of UnixLib, add the switch '-mlibscl' to the
command line. For example:

  gcc hellow.c -mlibscl

will compile and link the hellow.c source file, using header files
from the SharedCLibrary, and linking against the library C:o.stubs.
The output file will still be called '!RunImage' and can be run
in the same way.

Support has been provided for both RISC OS and UNIX format filenames. GCC
will translate any UNIX filenames into their RISC OS equivalent. For example:

  ../include/stdio.h	is translated to	^.include.h.stdio
  /work/gcc/hello.c	is translated to	$.work.gcc.c.hello
  stdlib.h		is translated to	h.stdlib

but
  tree.def		is translated to	tree/def

For further examples of compilation procedures, please look at `Examples'
in !gcc.

The full GCC manual can be referred to at !gcc.docs.gcc.


Switches
--------

This is a list of the simpler, standard switches for GCC. Full details can
be obtained from the !gcc.docs.gcc manual. Please see below for the ARM
specific switches since these have altered from the original gcc version.

The switches described below are useable with any GNU compiler.

-c              compile and assemble the source to the object file
-S              compile the source to assembler code
-E              preprocess the source file
-o <file>       put the resulting output into <file>
-O              apply some optimisations to the output
-O2             apply full optimisation.
-O3             full optimisation and inline small functions as well.


There are some additional ARM specific switches.  These are documented in
!gcc.docs.gcc, section "ARM Options".  The most important one is:

 -mpoke-function-name
   place the name of the current function before the start of the function
   to allow the post mortem debugger to print a readable backtrace.
   This option is disabled by default.
   Turing this option on can increase code size by about 3.5% for C programs
   and as much as 10% for C++. However, it should be noted that the
   performance of the generated application will not be slower. It is useful
   to turn this option on when developing applications as it can lead to a
   clear indication of where a program is failing.

Note that APCS-R mode (option -mapcs-26) is deprecated and will be removed
from future GCC versions.  Given that the supplied runtime libraries UnixLib
and SharedCLibrary stubs are only APCS-32 compliant, specifying -mapcs-26
means that you have to provide an alternative APCS-R compliant runtime library.


RISC OS specific options

 -mthrowback
   send errors to a text editor capable of receiving 'throwbacks'.
   Error throwbacks will only occur when the DDEUtils module has previously
   been loaded.

 -mlibscl
   build and link source code against the SharedCLibrary headers and
   library files.

 -munixlib (default)
   build and link source code against the UnixLib headers and library
   files.

   -mlibscl and -munixlib are mutually exclusive.  -munixlib is the
   default.

 -mamu
   Generate the file !Depend which contains a list of all the source
   files that the produced object depends on. This is intended for use
   with Acorn's Make Utility (AMU), which edits the makefile to include
   these after the '# Dynamic Dependencies' line.

 -mmodule
   Generate code suitable for a RISC OS module.  You must use this alongside
   -mlibscl.
 
 -mlibrary-static-data-offset
   Only relevant when compiling a RISC OS module (option -mmodule set).
   This specifies to use the library static data offset (at sl-540) instead
   of the client static data offset (sl-536).  This is only to be used in very
   rare cases.

 -mclient-static-data-offset (default)
   Only relevant when compiling a RISC OS module (option -mmodule set).
   This specifies to use the client static data offset (at sl-536) instead
   of the library static data offset (sl-540).

   -mlibrary-static-data-offset and -mclient-static-data-offset are mutually
   exclusive.  -mclient-static-data-offset is the default.


LD
--

LD is a front end program that converts the linker command line as generated
by gcc to a format recognised by Drlink and Link. LD also attempts to
convert Unix format names to RISC OS format.  Only in unusual cases should
you call LD directly: instead, for almost all instances, call GCC to perform
the linking since this will supply the correct libraries and options.

The following reference is provided for completeness, and the options recognised
are:

 -L<dir>
   This specifies a directory/path that LD is to use when searching
   for libraries. <dir> must be either a path (i.e gcc:, etc), or it
   must be a valid Unix/RISC OS directory name, ending in either '/'
   or '.'. Directories are searched in the order that they are
   specified.

 -l<file>
   This specifies the name of a library file which LD will search the
   library directories for. This may either be a complete filename (i.e
   C:o.stubs) or just the leaf name, in which case, LD will search
   though the specified library directories for the file o.lib<file>
   and o.<file> if the former isn't found.

 -o <file>
   This specifies the filename to which the resultant executable will
   be stored.

 -via <file>
   <file> contains a list of object files to be included in the link process.

 -version
   Print the version number of 'ld'.

 -help
   Display a brief summary of LD and its command line arguments.


The following Drlink linker commands are recognised:
  -acornmap, -area[map] <file>, -aif, -aof, -bin, -case,
  -leave[weak], -map, -no[unused], -output, -res[can],
  -throwback, -via <file>, -verbose

The following Acorn Link linker commands are recognised:
  -aif, -aof, -bin, -map, -via <file>, -nounused[areas], -verbose

Unrecognised commands are flagged as an error and LD will not perform the
link process. Characters with square brackets are optional.

The sequence '-Lgcc: -LC: -lgcc -lstubs' will cause LD to look for the files
gcc:o.libgcc, gcc:o.gcc, c:o.libgcc, c:o.gcc, gcc:o.libstubs, gcc:o.stubs,
c:o.libstubs and c:o.stubs, taking the first gcc and stubs files that it finds.

Linker options can be passed from GCC to link using -Wl and -XLinker options.

The linker must be in the default Run$Path, as LD does not handle the -B
command. Please note that it is best to define GCC$Linker in the !gcc.!run
file to point to the linker you want to use. e.g.
  Set GCC$Linker "link"
will make LD use the program 'link' for linking.


Predefines
----------

The following preprocessor constants are defined by GCC:
   '__arm', '__arm__', '__riscos', '__riscos__', '__aof__'
   '__GNUC__', '__GNUC_MAJOR__', '__JMP_BUF_SIZE'

To implement dynamic allocations within a function, it is necessary to add
an extra field to jmpbuf. Fortunately the setjmp.h header files recognise
__JMP_BUF_SIZE and can alter their jmpbuf array appropriately.

When targeting the SharedCLibrary (i.e. -mlibscl switch is supplied on
gcc command line) then an additional preprocessor constant is defined,
namely `__TARGET_SCL__'.


Troubleshooting
---------------

Here are described some common problems users have with gcc and the GNU
compilers. Possible solutions are provided for the known problems.

1. The compiler fails to compile anything but no error message is reported.

  This is usually caused by a lack of memory. To see how far through
  compilation a file has gone, try compiling with the '-v' flag. '-v' gives
  verbose output and will show the programs gcc is executing.

  A lack of memory will be shown up by an almost instantaneous return from
  any program executed. If this happens, try increasing the wimpslot,
  using *wimpslot -min nnnK, where nnn is as follows:

      4000K or more for GNU C, Objective-C, C++, Fortran and Pascal.
      6000K or more for GNAT Ada.

  When the compiler runs out of memory during compilation, an error
  'virtual memory exhausted' is usually reported.

2. Abort on data transfer errors are displayed during compilation

  Insufficient memory has been allocated to the program. Increase
  the wimpslot.

3. The error 'No writable memory at this address' is returned.

  This is caused by insufficient memory memory and can be fixed by
  increasing the wimpslot to similar values as above.

4. ld fatal error: drlink returned exit status 12

  This is caused by insufficient memory during the linking stage.
  Increase the wimpslot to fix this.


AOF files, Libraries, Linkers etc.
----------------------------------

The following is a brief introduction to the world of compiling source
code, object files and linking.

Taking the C compiler as an example. Language C source files are stored
within a directory called 'c'.

Typing
  *gcc -c hello.c -o hello.o

will tell gcc to run the C compiler on the source file c.hello. The resultant
output will be stored in the directory 'o' as hello. Files in 'o' are called
Acorn Object Format (AOF) files.

During multistage compilation (i.e. where a program is made up from several
source files), the compiler will compile one file at a time and this will
produce several AOF files.

Each source file might contain references to variables and functions that are
not defined within its own scope. For an executable to be created, these
references must be resolved and that is the purpose of the Linker.

The Linker takes AOF files and attempts to resolve references between them.
Not all references are defined within AOF files, some (like printf) are
defined within libraries - called Acorn Library Format (ALF) files. So the
Linker will also look at ALF files to match unresolved symbols.

For example, below is a list of C source files that will be compiled to make
the program called Harry. Along with each source file is a list of the
symbols that are defined within that source, and a list of symbols that
are not defined (i.e. referenced) by that source.

    C source: fred.c
      Symbols defined: foo, bar, pint
      Symbols referenced: printf, puts, food

    C source: bob.c
      Symbols defined: fags, beer, food
      Symbols referenced: bar, pint

    C source: harry.c
      Symbols defined: main
      Symbols referenced: foo

Using gcc to compile fred.c, bob.c, harry.c will produce three AOF files,
fred.o, bob.o and harry.o.

harry.c contains a reference to 'foo' which is defined within c.fred. So
the Linker must combine harry.o and fred.c to resolve a reference.

fred.c contains a reference to 'printf', 'puts' and 'food'. 'food' is
defined by bob.c so bob.o will also be combined with harry.o and fred.o
to resolve further references.

'printf' and 'puts' are defined by the C library, therefore the linker will
need to combine the ALF file with harry.o, fred.o and bob.o to finally
generate an executable.


RISC OS module support
----------------------

For a very long time, GCC was unable to generate code for RISC OS modules.
Support was recently added, and is possible using correct switches.  Module
code must be compiled and linked with the SharedCLibrary since UnixLib
is not suitable for this purpose.  e.g.:

  *gcc -mlibscl -mmodule -c module.c -O2
  *gcc -mlibscl -mmodule module.o header.o -o mymodule

Each RISC OS module needs a module header which can be created using CMunge.
See !gcc.docs.CMunge for more information.  CMunge can also be used to create
veneer code acting as glue code for RISC OS callbacks into your C/C++ coded
module.

The examples directory contains a basic module example using GCC.


Obtaining compilers
-------------------

As said earlier, GCC is a compiler front end. The compilers themselves
can be found at http://gccsdk.riscos.info/.


GCCSDK mailing list
-------------------

A mailing list has been setup for discussions on GCC, including development
work.  Details on how you can join the GCCSDK mailing list can be found
at http://gccsdk.riscos.info/.


Location of the main GCC sources
--------------------------------

The official GCC website is http://gcc.gnu.org
The official GNU website is http://www.gnu.org

-EOF-
