RISC OS-GCC FAQ
===============

Last updated: 10.11.1996, Jochen Scharrlach (jscharrl@ba-stuttgart.de),
                          Nick Burrett (nickb@digibank.demon.co.uk) and
                          Peter Burwood (pjb@arcangel.dircon.co.uk)

Posting: irregularly, every time when there are major changes. I am not
         sure where to put this FAQ at the moment, but I'll make it
         available via:
         http://www.uni-stuttgart.de/Archive/acorn/

Throughout this document, when we refer to GCC we collectively mean
GNU C, GNU C++, GNU Objective-C, GNU Fortran-77, GNU GNAT Ada and
GNU Pascal.

* This FAQ is relevant to all GNU compilers on RISC OS. *

The following FAQ does not try to explain internals of GCC nor does it
provide a language tutorial. It only tries to explain how to handle the Acorn
port of GCC. It is not a classic selection of questions and answers,
it's more like a brief manual. Unless you are an experienced Acorn-GCC
programmer, this document might be very helpful.

Other GNU languages, such as Ada, Fortran and Pascal have their own FAQ,
but common aspects of GNU compilers are discussed here. Parts of this
FAQ may be overridden by language specific FAQs.

Disclaimer: Acorn, FSF or the GCC porters are not responsible for this FAQ.
  Be aware that this FAQ wasn't written by one almighty guru, there were
  several people helping me.

This FAQ describes the port: GCC 2.7.2 (and equivalent compiler versions)
with ARM/RISC OS backend version 1.0.7. If you have an older version try
to get this one, if you have a newer version please tell me where I can get
it from...

Please help me on stuff marked with "(?)". If you find any mistakes (even
grammar or spelling mistakes) or have any updates or suggestions, drop me
an email.

Contents
--------

1. Availability
 1.1 FTP
 1.2 CD-ROM
 1.3 other
 1.4 Source
2. Installation
3. Libraries
 3.1 C++
 3.2 UnixLib
 3.3 gststubs
 3.4 DeskLib
 3.5 OSLib
 3.6 Toolbox
4. Using GCC
 4.1 Memory requirements
  4.1.1 Archimedes
  4.1.2 RiscPC
 4.2 Directories
 4.3 Filename translation
 4.4 Commandline options
 4.5 Compiling C++ sources
 4.6 Compiling Objective-C sources
 4.7 Using <varargs.h>
 4.8 Compiling other languages
5. Problems
 5.1 General
 5.2 Not enough memory
 5.3 Failure to link
 5.4 Fatal error: 2, System variable 'SHELL' not found
 5.5 Compiler bugs
 5.6 Dynamic Areas not deleted
6. Related Information
 6.1 GCC documentation
 6.2 Other FAQs
 6.3 Interactive help
 6.4 Books
  6.4.1 C
  6.4.2 C++
  6.4.3 Object-Oriented Analysis and Design
  6.4.4 Objective-C

***************************

---------------
1. Availability
---------------

 1.1 FTP

  * ftp://micros.hensa.ac.uk/micros/arch/riscos/b/b013
  * ftp://src.doc.ic.ac.uk/systems/archimedes/collections/hensa/b/b013
  * ftp://ftp.demon.co.uk/pub/mirrors/hensa/micros/arch/riscos/b/b013

 1.2 CD-ROM
 
  * No details available at time of release

 1.3 Other

  * No details available at time of release

 1.4 Source
 
  * The source changes for the RISC OS port are in the process of being
    merged into the standard gcc distribution. Source for the RISC OS port
    will currently only be available direct from Nick Burrett. Installation
    help can also be obtained from him.

(?) - anything else?

---------------
2. Installation
---------------

  You will find several archives which you'll have to unpack into the same
  directory. Additionally you'll need a linker, e.g. DRLink. Install it into
  a directory that is listed in Run$Path, e.g. !GCC.bin.

------------
3. Libraries
------------

  The easiest way to use a C-library is to put the path into GCC$Path.
  The path must point to the location where the subdirectories "o"
  (contains the library itself) and "h" (contains the include files) reside.
  C++-libraries have to be listed in GPP$Path. The other method would be to
  tell gcc where to find the headers with -I<path> and the library with
  -L<path>.

 3.1 C++

  If you want to compile C++-programs you'll also need the C++ library,
  you should be able to get it where you found gcc. To use it, GPP$Path has
  to point to the location you installed the lib. The C++ libraries supplied
  with GCC 2.7.2 are C++ iostream, GNU C++ library and GNU ANSI C++.

 3.2 UnixLib

  UnixLib 3.7a or later work with gcc. In fact, gcc is configured to use
  UnixLib as the preferred library. UnixLib provides Unix-style headers
  which seem to work with gststubs (see below), but you may run into
  trouble with it.

  *Note 1*. All GNU compilers based around GCC 2.7.2 require UnixLib 3.7a,
  not 3.6e.
  
  *Note 2*. For StrongARM compatibility, it is recommended that problems be
  compiled with UnixLib 3.7b or later.

 3.3 gststubs

  This one is a PD-replacement for Acorn's stubs. It's much smaller than
  UnixLib, because it uses the SharedCLib, though it comes with no
  header files. If you don't have the Acorn-C headers you'll have to try
  it with UnixLib's headers, but it is not guaranteed that this will work
  correctly.

 3.4 DeskLib

  Official versions above 2.16 should work fine with gcc. DeskLib provides
  many WIMP- and other RISC OS-specific commands, but you'll need to link
  with (gst)stubs (try -mstubs). As for whether GCC can compile DeskLib,
  this has not been tested.

 3.5 OSLib

  Acorn's unofficial PD library. Should work with gcc, but it also needs
  (gst)stubs. There are known problems when using C++ (OSLib uses C++
  keywords) and you may need to use the "-ansi"-option.

 3.6 Toolbox

  Acorn's toolbox libraries for programming the toolbox modules from C.
  Should work with gcc, but it also needs (gst)stubs. This is untested.

------------
4. Using GCC
------------

 4.1 Memory requirements

  GCC needs between 3 and 8 Mb to compile C-programs and more than 4MB for
  C++-progs, so it is very hard to use it on a 4MB machine without "tricks":

  4.1.1 Archimedes

  You can use !Virtual (current version 0.37), which gives you up to 24MB
  of "virtual memory", i.e. your harddisc will be used to simulate this.
  You still need at least 1.5MB of real memory, otherwise compiling will
  take ages!

  4.1.2 RiscPC

  !Virtual doesn't work on a RiscPC, so you'll need to get enough RAM, i.e.
  about 6-12MB.  Modifications have been made to UnixLib to allow usage
  of dynamic areas for the compiler's heap and stack space. This is
  compatible with Clares' Virtualise product which provides virtual
  memory for dynamic areas. Other VM products will hopefully be
  supported if and when they become available.

 4.2 Directories

  Because RiscOS doesn't use file extenders, the files are stored in
  different subdirectories:

  * c    C source code
  * cc   C++ source code (the way it was supposed to be)
  * c++  C++ source code (the way Acorn wanted it to be...)
  * ads  Ada specification source code
  * adb  Ada body source code
  * ali  Ada library files
  * f    Fortran 77 source code
  * m    Objective-C source code
  * p    Pascal source code
  * pas  Pascal source code
  * s    Assembler-source
  * o    object files
  * h    header files

 4.3 Filename translation

  GCC works correctly with both Unix format filenames and RISC OS format
  filenames.

  If you want to compile the file dir.c.myprog, you can either say:
    gcc dir.c.myprog
  or:
    gcc dir/myprog.c

 4.4 Commandline options

  I don't want to list all possible options, there are sh**loads of them.
  The most important are:

  * -o <file>
   redirect the output into <file>.
  * -c
   stop after compiling, i.e. no linking.
  * -E
   stop after preprocessing. If you don't specify an output file, the
   output will be sent to stdout.
  * -S
   stop before assembling, i.e. generates Assembler-output.
  * -I<path>
   specify an additional path to search for include files.
  * -L<path>
   specify an additional path to search for libraries.
  * -l<lib>
   link with the library <lib>. You don't need to specify the path if
   you either do this with the "-L"-option or specify it in GCC$Path.
  * -O<n>
   optimise, <n> is the degree how much should be done. "-O2" is the best
   possible optimisation at the moment. "-O1" is the same as "-O", "-O0"
   means no optimisation (default).
   -O2 can significantly increase compilation time and is probably best used
   during the final compilation of the program.
  * -Wall
   gives more warnings.


  ARM dependant stuff, i.e. don't try this on other platforms:

  The opposite effect of these options can be utilised by pre-pending
  -mno- to the option i.e. -mno-poke-function-name will prevent function
  names from being compiled into the code.

  * -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% for C code and
   about 10% for Ada code. Note, code size reductions are very dependant
   upon function sizes and function names. Reductions for other
   languages are not known, but they will be similar.
  * -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'.
  * -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.

  For GCC on RISC OS, the options set on as default are:
    -mapcs-frame
    -mpoke-function-name
    -mapcs-stack-check

 4.5 Compiling C++-sources

  GCC also compiles C++-code, you only have to put the source into the
  correct subdirectory. To link C++-programs you can either explicitly
  link with the C++-library, e.g.
    gcc -o hello cc.hello -lc++
  or:
    gcc -c hello.cc
    gcc -o hello o.hello -lc++
  
  or use the front end, g++, e.g.
    g++ -o hello cc.hello
  or:
    g++ -c hello.cc

 4.6 Compiling Objective-C sources
 
   GCC also compiles Objective-C code, again source code just needs to be
   placed in the correct subdirectory, m. To compile an Objective-C source
   just typing:
     gcc -o hello m.hello
   or
     gcc -c hello.m

   will be quite sufficient.

 4.7 Using <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 Norcroft C and UnixLib.  However,
  this feature is invisible to the user.

 4.8 Compiling other languages
 
   Please read the documentation that comes with the other languages.

----------------------
5. Problems
----------------------

 If a problem is encountered, be it unable to compile, link, compiler
 crash or something else then this section should be read before
 contacting the porters for advice.
 
 5.1 General

  If you are new to using GNU compilers then try following the
  !gcc.docs.gccuser instruction manual which contains helpful advice in
  using them. If you believe the problem is specific to the RISC OS port,
  then you will probably get more help from the comp.sys.acorn.programmer
  newsgroup.

 5.2 Not enough memory
 
  All of the GNU compilers are memory hungry, some more than others.
  This is often a problem with on a system with 4MB or less. Section 4.1
  covers some ways to overcome this. To determine what the compiler is
  trying to do when it runs out of memory, use the -v switch on gcc.
  This will report what programs are being run to compile the source.
  See also the section 5.6 about Dynamic Areas.

 5.3 Failure to link
 
  If you can compile the source to object files but not generate an
  executable, then this probably means a linker program was not found.
  Another cause is due to missing symbols, though this error will be
  reported as such. Ensure the libraries specified with the link command
  provide the symbols that are reported missing. Use the gcc command to
  link rather than `link' or `drlink' since it adds some GNU specific
  libraries.
 
  If you get `___main' undefined then you are trying to link a main unit
  compiled with GCC 2.4.5 with the GCC 2.7.2 libgcc library. In this
  case recompile the main unit with 2.7.2 or provide an assembler veneer
  for ___main to branch to __gccmain and cross your fingers.
  
  Please note that GCC 2.4.5 is incompatible with GCC 2.7.2. We do not
  recommend that object files, between the compilers, are intermixed.
 
 5.4 Fatal error: 2, System variable 'SHELL' not found
 
  Sometimes an error of the form `SHELL not found' is printed by the
  compiler. This is a confusing error report and the true error is
  normally reported just before this line. Typically, this is reported
  when a file the program was looking for was not found. Use -v with gcc
  to determine which program was not found and then check your Run$Path
  and make sure the program exists. Run$Path should include gcc:bin.

 5.5 Compiler bugs

  All programs are susceptible to bugs and the GNU compilers are no
  different. Your bug reports play an essential role in making the GNU
  compilers reliable.
  
  When you encounter a problem, the first thing to do is to see if it is
  already known. Known bugs are usually reported in one of the readme
  files supplied with the compiler distribution. If the bug isn't known,
  then you should report the problem.
  
  Reporting a bug may help you by bring a solution to your problem, or it
  may not. In any case, the principal function of a bug report is to help
  the entire community by making the next version of a GNU compiler work
  better. Bug reoirts are your contribution to the maintenance of any GNU
  compiler.
  
  In order for a bug report to serve its purpose, you must include the
  information that makes for fixing the bug.
  
  If a bug is encountered in the compiler then contact the maintainer of
  that particular compiler with the bug report produced by the compiler.
  Do not send any source code in the first instance.
  
  All the GNU compilers use a common backend, which includes the ARM
  backend and are under continuous development. New versions of the
  compilers will be made available when they have been ported to RISC OS.

  More detailed information for reporting bugs can be found in the file
  !gcc.docs.Bugs as supplied in the distribution.

 5.6 Dynamic Areas not deleted
 
  This is Risc PC specific. The GNU compiler can use dynamic areas as
  detailed in section 4.1.2. If the dynamic area persists after the
  compiler has finished, then it will never be deleted and it is not
  reused by subsquent compilations. There is a utility program that
  allows you to delete a Dynamic Area and this is explained in the
  ReadMe that comes with the common components of the compiler and with
  UnixLib.

----------------------
6. Related Information
----------------------

 6.1 GCC documentation

  The original GCC documentation is written in Texinfo, which can either be
  printed via TeX and be converted into a hypertext format ("info"). You
  can also get a version for !StrongHlp v2:

  ftp://ftp.uni-stuttgart.de/pub/systems/acorn/riscos/docs/gnu/gcc-docs.zip

  CAUTION: this beast is 2MB (unpacked 7MB) big! Be aware that the given
  information belongs to GCC 2.6.3, so not every listed feature will work.

 6.2 Other FAQs

  * comp.sys.acorn.announce: if you have trouble with your Acorn
  * gnu.g++.help (g++-FAQ): GNU-C/C++ questions
  * comp.lang.c: system independent questions about C
  * comp.lang.c++: system independent questions about C++
  * comp.lang.objective-c: system independent questions about Objective-C
  * comp.lang.ada: system independent questions about Ada

 6.3 Interactive help

  * e-mail: nickb@digibank.demon.co.uk (Nick Burrett)
            gcc@callan.demon.co.uk (Simon Callan)
    providing support for any problems with the ARM/RISC OS GCC compiler
    for the languages C, C++, Objective-C, Pascal and Fortran.
    
    email: gnat@arcangel.dircon.co.uk (Peter Burwood) providing support
    for any problems with the ARM/RISC OS or ARM/RiscBSD GNAT compiler.
    
  * The "C Acorn User Group" (CAUG) supports C and C++ users on RISC
    OS machines. For more information, send an email to caug@accu.org.
    Their parent organisation ACCU has web pages at:
    http://bach.cis.temple.edu/accu

 6.4 Books

  6.4.1 C

  * Kernighan, B. W. and Ritchie, D. M. (1988), The C Programming Language
    (second edition). Prentice-Hall, Englewood Cliffs, NJ, USA.
    ISBN 0-13-110362-8. (The original C 'bible'. Written by the designers
    of C.)

  6.4.2 C++

  * Bjarne Stroustrup (1991), The C++ Programming Language (second
    edition). At&T Bell Telephone Laboratories, Inc. ISBN 0-201-53992-6
    (Written by the 'father' of C++)

  * Murray, Robert B. (1993), C++ Strategies and Tactics,
    Addison-Wesley, ISBN 0-201-56382-7

  * Cargill, Tom (1992), C++ Programming Style, Addison-Wesley, ISBN
    0-201-56365-7. This is a good 'second' C++ book showing you why
    and how you should be using C++ features.

  6.4.3 Object-Oriented Analysis and Design

  * Booch, Grady (1994), Object-Oriented Analysis and Design with
    Applications (2nd Edition), Benjamin/Cummings, ISBN
    0-8053-5340-2. Complete coverage of the well-known Booch method of
    OOAD.

  * White, Iseult (1994), Using the Booch Method, Benjamin/Cummings,
    ISBN 0-8053-0614-5. A practical example of the Booch method. More
    accessible but less complete than Booch's book.

   6.4.4 Objective-C
   
  * http://www.next.com/Pubs/Documents/OPENSTEP/ObjectiveC/objctoc.htm
    The official NeXT Objective-C introduction document.

(?) - Any other books, FAQs, etc. worth mentioning?
