The Datafile PD-CD 5/DATAFILE_PDCD5.iso/utilities/f/fortran/GCCmain/!gcc/docs/!Intro

Text File | 1996-11-25 | 20.4 KB | 559 lines

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


This is a short introduction to GCC. Information concerning a specific
compiler can be found elsewhere. The documents supplied with each GCC
compatible compiler do not provide an introduction to programming in that
particular language, for that you will have to get a text book on the language.

GCC is a small program providing a simple and consistent front end to many
compilers. Currently, the compilers supported are GNU C, GNU C++,
GNU Objective-C, GNU Fortran, GNU GNAT Ada and GNU Pascal. As more compilers
are released, GCC will support those too.

GCC is covered by the FSF General Public License (see the files docs.COPYING
and docs.COPYINGLIB for details).

This port of GCC is © Copyright 1996 Nick Burrett

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

The GCC distribution is a support archive providing the files common to all
of the above compilers. This includes:
  - an assembler (as)
  - a linker front end (ld)
  - the compiler front end (gcc)
  - a C preprocessor (cpp)
  - a runtime library (gcc.o.libgcc)
  - gcc specific header files (gcc.h)
  - this document and others (gcc.docs)

An Acorn Object Format linker is not provided but there exists a Public
Domain linker called Drlink. Details on where to obtain this are detailed
at the end of this document.

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

Peter Burwood for bug fixes, enhancements, testing, suggestions and more...
Niklas RÖjemo, for the assembler 'as'
Huw Rogers and Simon Callan, for UnixLib.
Jochen Scharrlach for the RISC OS GCC FAQ.
Cy Brooker for the DDEUtilsCy module.


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

To install GCC just copy the contents of this archive onto your hard disc.
Running !gcc will setup Run$Path to automatically search for the compiler
tools.

If you wish to separate the distribution, the files in !gcc.bin should be
copied so that they are in your run path, while GCC$Path and GPP$Path should
point to where the GCC and GPP directories are respectively.

Note, there is no linker or run-time library supplied, but Drlink and
Unixlib 3.7a are useable with GCC and their location is given below.

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

To add GNU compilers to the GCC front end, simply merge the directories
together on your hard disc i.e. by dragging the compiler's !gcc directory
over the gcc front end's !gcc directory.

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.

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'.

GCC supports both RISC OS and UNIX format filenames.

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).

To compile a C program just type:

   gcc c.hello

This will compile, assemble and link the source 'c.hello' 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 c.hello -o hello

This will comple, assemble and link the source 'c.hello' to produce an
executable called 'hello', 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 c.file1 c.file2 c.file3 c.file4

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 c.file

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

Switches
--------

This is a list of the simpler, standard switches for GCC. Full details can
be obtained from the docs.gccuser 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.

 -mapcs, -mapcs-frame
   target for ARM Procedure Call Standard stack frames.

 -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.
   Using it's opposite will reduce code size by about 3.5%.

 -mfpe
   prevents instruction scheduling of floating point instructions since it
   increases compile time and the benefits acheived make no difference through
   the FPE.

 -mapcs-32
   target the APCS-32 bit standard. Condition flags are assumed to be corrupted
   by function calls in this mode.

 -mapcs-stack-check
   provide explicit stack checking on entry to each function which allocates
   temporary variables on the stack.

 -mapcs-strict
   make the compiler conform strictly to the APCS even in the cases where
   stack frames do not need to be set up.

 -mshort-load-bytes, -mno-short-load-words
   if the MMU traps unaligned word accesses, shorts must be loaded
   byte-at-a-time so this flag should be set.

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.

 -mstubs
   compiles to target SharedCLibrary and tells the linker to link with
   stubs instead of UnixLib.

 -munixlib
   tell the linker to target UnixLib instead of the SharedCLibrary

 -mamu
   Generate the file !Depend which contains a list of all the source
   files that the produced object depend on. This is intended for use
   with amu, which edit the makefile to include these after the
   '# Dynamic Dependencies' line.


At the time of release the use of -munique-areas is not guaranteed to work
in all cases. -mapcs-strict is an option used for internal compiler
debugging.


LD
--

LD is a front end to Link, which converts the LD as generated by gcc to the
Acorn Image Format. LD only recognises a few options, the rest are passed
directly through to Link. LD also attempts to convert Unix format names to
RISC OS format. The options that LD recognises 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 object filename.

-M
  Print a link map to stderr.

-Map <file>
  Print a link map to <file>.

-t
  Print the names of the input files as the linker processes them.

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

-version
  Print the version number of 'ld'.


The sequence '-Lgcc: -LC: -lgcc -lstubs' will cause LD to look for the files
gcc:o.gcc, c:o.gcc, gcc:o.stubs 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__',
   '__GNUC_MINOR__', '__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.


Search paths
------------

The default search paths for GCC are as follows and searched in the
specified order.
   GCC$Path        GCC specific include files.
   Unix$Path       Unixlib header files.


<varargs.h>, <assert.h>, <stdarg.h>
-----------------------------------

GCC supplies it's own versions of these header files since they are not
compatible with the headers supplied with Acorn C and UnixLib.  However,
this feature is invisible to the user.


GCC and Compatibility
---------------------

As of release 1.0.7 and later, GCC is now compatible with StrongARM
processors. Code produced by GCC will also be usable with StrongARM
provided a version of UnixLib 3.7b or later is used.

Unfortunately, GCC has become unusable on any release of RISC OS prior to
release 3.10 because the module CallASWI is now used.


GCC and Virtual Memory
----------------------

GNU compilers use a lot of memory and nothing can be done about that. For
the Risc PC, UnixLib has been modified to make use of dynamic areas. So
users with small memory machines can use Clares' Virtualise to provide a
working virtual memory envionment for them. See the section *Dynamic Areas*
below.

Users of older machines, the Archimedes and A5000, can use the program
!Virtual. Currently the version is 0.37 and there exists a few small problems
with running gcc 2.7.2 compilers (or any UnixLib 3.7a and later programs)
under this environment.

UnixLib 3.7a has been heavily modified and uses some unsupported SWI calls
notably, XOS_RemoveTickerEvent, an XOS_Byte call and OS_PlatformFeatures.
Until a later version of !Virtual is released, it is safe to answer 'Y' to
all the questions related to Unknown SWIs.

Users of !Virtual can disregard the information contained within the
specific compiler documentation concerning wimp slot size. Under the
virtual memory environment, the wimp slot will need to be set to a size
approximately 32K greater than the largest binary likely to be executed, the
compiler. For example, if the size of cc1 is 700K, then setting the wimp slot
to 732K should ensure that a successful compilation can be made

It should be noted that the greater amount of wimp slot that can be given
to a virtual memory task, a smaller number of page swaps will be needed and
a significant improvement in compile times should result.


Dynamic areas
-------------

Peter Burwood has 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, Peter Burwood or
(hopefully) anyone else providing they have used UnixLib 3.7a or later. A
description of using dynamic areas is included with UnixLib 3.7a and some
of it is duplicated here:

UnixLib 3.7a has a facility to use Dynamic Areas, found in RISC OS 3.5
and above, for the program's heap. The heap is another name for the
malloc area. The advantages of using a dynamic area for the program's
heap include :-

   * the WimpSlot of the program can be limited to the code and stack
     requirements of the program. This helps alleviate the cost of RISC
     OS task switching which slows down dramatically as the WimpSlot
     grows in size.

   * Dynamic Areas provide a means of Virtual Memory when used with a
     product such as Virtualise[1]. Virtual Memory allows programs to
     use more data space than is available with just physical memory.

If any problems are encountered with the implementation or use of the
dynamic area UnixLib heap then please contact Peter Burwood via e-mail at
[e-mail]. Please do not contact Peter with general
UnixLib problems, but see the UnixLib ReadMe file for a contact address.

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 a compiler 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 ""

As a user, you should not really need to worry about these details as the
!gcc.!run file already contains the relevant lines. Please read the !run
file if you are a Risc PC user, since some lines will need to be uncommented.

[1] Virtualise is a commercial product available from Clares. Peter Burwood
has no connection with Clares or the Virtualise product other than being a
user of Virtualise. If other similar products become available then UnixLib
should work transparently since the UnixLib startup code does not use
any Virtualise features.


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

Here are describled 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:

  a) When not using dynamic areas i.e. when gcc_heap isn't set or you
     don't have a RiscPC
      2500 or more for GNU C
      2600 or more for GNU Objective-C
      3000 or more for GNU C++
      6000 or more for GNAT Ada

  b) When using dynamic areas (RiscPC's only) and *set gcc_heap "" has been
     performed.
      1500 or more for GNU C
      1500 or more for GNU Objective-C
      1900 or more for GNU C++
      3200 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

  This is due to a lack of memory and will be rectified by increasing the
  wimpslot to similar values as above.

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

As said earlier, GCC is a compiler front end. Proper compilers can be
obtained from the following places:

GNU C, Objective-C and C++:
  ftp://micros.hensa.ac.uk/micros/arch/riscos/b/b013

GNU GNAT Ada:
  ftp://micros.hensa.ac.uk/micros/arch/riscos/e/e095

GNU Fortran (G77):
  ftp://micros.hensa.ac.uk/micros/arch/riscos/e/e167

GNU Pascal (GPC):
  ftp://micros.hensa.ac.uk/micros/arch/riscos/e/e168


Other compiler related utilities
--------------------------------

Listed below is a small set of utilities you might find a useful
complement to the GNU compilers.

Drlink (an AOF linker):
  ftp://micros.hensa.ac.uk/micros/arch/riscos/b/b071/drlink.arc

UnixLib (a library emulating BSD, System V and POSIX functions):
  ftp://micros.hensa.ac.uk/micros/arch/riscos/a/a042/unixlib.arc

 The latest snapshot of UnixLib may be obtained from:
  http://www.callan.demon.co.uk/unixlib

Bison (a yacc parser):
  ftp://ftp.demon.co.uk/pub/archimedes/gnu/bison124.spk

Diffutils (file difference and patch programs):
  ftp://ftp.demon.co.uk/pub/archimedes/gnu/diffdist.spk

Flex (a lexical analyser: Unix Lex equivalent):
  ftp://ftp.demon.co.uk/pub/archimedes/gnu/flex252.spk

Indent (C source code formatter):
  ftp://ftp.demon.co.uk/pub/archimedes/gnu/indent.spk

Sed (batch stream editor):
  ftp://ftp.demon.co.uk/pub/archimedes/gnu/sed.spk

!Virtual (virtual memory for early Archimedes, A5000 and before):
  ftp://micros.hensa.ac.uk/micros/arch/riscos/a/a277/a277.arc


Mirrors of hensa/micros
-----------------------

Imperial College:
 ftp://src.doc.ic.ac.uk/computing/systems/archimedes/collections/hensa/riscos/

Demon Internet Services
 ftp://ftp.demon.co.uk/pub/mirrors/hensa/micros/arch/riscos/


Porting compilers
-----------------

The above compilers are all called front ends. They provide a mechanism
for translating the relevant source code format (C, C++, Fortran etc.) into
relevant information for the back-end. The back-end converts this information
into a register transfer language and performs most of the optimisation
techniques. This register transfer language is then applied to a processor
back-end which will apply further optimisation (processor specific) and then
output assembler instructions.  The compiler backend can support many
different processors and operating systems, ARM and RISC OS are just two of
them.

The job of actually porting new compilers has been made very easy due to the
hard work of the compiler development teams. Nick Burrett wrote the RISC OS
port of the ARM processor backend with a little help from Peter Burwood.
Simon Callan and Huw Rodgers wrote UnixLib without which the job of porting
the compiler would probably never have surfaced.

The actual ARM backend used to create the RISC OS port is, for the moment,
unavailable on mainstream release in the GCC distribution. The alterations
made to make the compilers actually work under RISC OS are very involved,
and procedures are slowly underway to merge changes. Fortunately, the ARM
backend for RISC OS is only going to be of interest to any future language
compiler porters. If anybody wishes to port a new compiler then they should
talk to Nick Burrett who will then send the changes through on request.

The main GCC compiler sources can be obtained from the sites listed described
below. Sources are approximately 7.5Mb compressed, 27Mb uncompressed.


Contacting Nick Burrett
-----------------------

I can only be contacted by e-mail at [e-mail].

However, if there is no response from this address I can be contacted
through Simon Callan: [e-mail].


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

  Most GNU software is packed using the GNU `gzip' compression program.
  Source code is available on most sites distributing GNU software.

  For information on how to order GNU software on tape, floppy or cd-rom, or
  printed GNU manuals, check the file etc/ORDERS in the GNU Emacs
  distribution, ftp the file /pub/gnu/GNUinfo/ORDERS on prep, or
  e-mail a request to: [e-mail]

  By ordering your GNU software from the FSF, you help us continue to
  develop more free software.  Media revenues are our primary source of
  support.  Donations to FSF are deductible on US tax returns.

  thanx [e-mail]

        ASIA: ftp.cs.titech.ac.jp, utsun.s.u-tokyo.ac.jp:/ftpsync/prep,
  cair-archive.kaist.ac.kr:/pub/gnu, ftp.nectec.or.th:/pub/mirrors/gnu
        AUSTRALIA: archie.au:/gnu (archie.oz or archie.oz.au for ACSnet)
        AFRICA: ftp.sun.ac.za:/pub/gnu
        MIDDLE-EAST: ftp.technion.ac.il:/pub/unsupported/gnu
        EUROPE: irisa.irisa.fr:/pub/gnu, ftp.univ-lyon1.fr:pub/gnu,
  ftp.mcc.ac.uk, unix.hensa.ac.uk:/mirrors/uunet/systems/gnu,
  src.doc.ic.ac.uk:/gnu, ftp.ieunet.ie:pub/gnu, ftp.eunet.ch,
  nic.switch.ch:/mirror/gnu, ftp.informatik.rwth-aachen.de:/pub/gnu,
  ftp.informatik.tu-muenchen.de, ftp.win.tue.nl:/pub/gnu, ftp.nl.net,
  ftp.etsimo.uniovi.es:/pub/gnu ftp.funet.fi:/pub/gnu, ftp.denet.dk,
  ftp.stacken.kth.se, isy.liu.se, ftp.luth.se:/pub/unix/gnu,
  ftp.sunet.se:/pub/gnu, archive.eu.net
        SOUTH AMERICA: ftp.inf.utfsm.cl:/pub/gnu, ftp.unicamp.br:/pub/gnu
        WESTERN CANADA: ftp.cs.ubc.ca:/mirror2/gnu
        USA: wuarchive.wustl.edu:/systems/gnu, labrea.stanford.edu,
  ftp.digex.net:/pub/gnu, ftp.kpc.com:/pub/mirror/gnu,
  f.ms.uky.edu:/pub3/gnu,
  jaguar.utah.edu:/gnustuff, ftp.hawaii.edu:/mirrors/gnu,
  uiarchive.cso.uiuc.edu:/pub/gnu, ftp.cs.columbia.edu:/archives/gnu/prep,
  col.hp.com:/mirrors/gnu, gatekeeper.dec.com:/pub/GNU,
  ftp.uu.net:/systems/gnu