*** IN TESTING ***
If you have received this copy of GCC from a CD of fetched your copy from the Internet yourself some time ago, 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 RISC OS GCC port.
This is the RISC OS port of GCC (GNU Compiler Collection) and supporting binaries allowing you to start developing RISC OS applications and modules straight away. So you get a compiler for one or more languages, an linker, an assembler, a RISC OS module header and veneer generator, the UnixLib C runtime library and headers and stubs for the SharedCLibrary module (as found in the RISC OS ROMs).
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), RISC OS 5 (32-bit version) and RISC OS 6 (26-bit and 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 C and C++ languages. Later releases of GCCSDK might have support for Ada, Fortran, Java, Pascal and/or Objective C/C++ but this will be largely dependant on available GCCSDK developer resources, interest and of course that all technical issues can be reasonably solved.
The following is a short introduction to GCC. It does not provide an introduction to programming, for that you will have to get a text book on the language you are interested in.
To install GCC, copy the contents of !GCC 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.
This completes installation, and GCC may be used simply by typing 'gcc' at the CLI prompt. In order to verify which version of 'gcc' you are using, specify the --version switch:
*gcc --version
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', C++ programs are stored in 'cc', assembler files in 's' and CMunge/CMHG files in 'cmhg'.
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 SharedCLibrary stubs which will result in using the RISC OS SharedCLibrary module routines at runtime. 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' inside !GCC.
*gcc -mlibscl -o file.o -c file.c *gcc -mlibscl -o mybinary file.o
Module code must be compiled and linked with the SharedCLibrary as UnixLib is not suitable for this purpose. The switch -mmodule needs to be specified to make sure that global data can be properly relocated at runtime. Specifying -mmodule implicitly specifies -mlibscl so it is not really necessary to specify it yourself however if you want your build script (or Makefile) reasonably backwards compatible with GCCSDK 3.4 you better specify it as it was not the case before.
*gcc -mlibscl -mmodule -c module.c -O2 *gcc -mlibscl -mmodule module.o header.o -o mymodule
*gcc -o file.o -c file.c *gcc -static -o mybinary file.o
This is a list of the simpler, standard switches for GCC. Full details can be obtained from the GNU C/C++ 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.
The ARM specific switches are documented in GNU C/C++ manual, section "ARM Options". The most important ones are:
This option is disabled by default.
Turning 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 when a backtrace is generated.
In the RISC OS port, options -msoft-float and -mhard-float are mutually exclusive.
Note that APCS-R mode (option -mapcs-26) is deprecated and is no longer working nor supported in this version of GCCSDK.
Switch -mmodule will implicitly select -mlibscl as well.
The following switches are mutually exclusive:
This is a short list of the most interesting and useful predefines set:
GCCSDK 3 defines the predefine __aof__ which is no longer the case in GCCSDK 4 as it is now fully ELF based. So this can be used to distingues between AOF and ELF compilations.
More common predefines are documented in the section "Common Predefined Macros" of the GNU C preprocessor manual.
Note that these predefines can also be used in handwritten assembler code when making sure that the preprocessor is firstly invoked before the assembling faze:
*gcc -xassembler-with-cpp -o file.o -c file.s
with e.g. file.s:
@ Returns 1 when running with UnixLib, 0 when running with SharedCLibrary. .global using_unixlib .type using_unixlib, %function using_unixlib: #ifdef __TARGET_UNIXLIB__ MOV r0, #1 #else MOV r0, #0 #endif MOV pc, r14 .size using_unixlib, . - using_unixlib
When you want to distribute your compiled program it might be necessary to accompagn it with an ELF loader and possibly also a set of shared libraries used by your program. This is not necessary when your program is using SharedCLibrary as runtime library, i.e. when your program is an Absolute (filetype &ff8) file with AIF header or a RISC OS module (filetype &ffa).
The ELF loader and the default set of shared libraries (UnixLib, libgcc and the dynamic loader) are bundled in the form of the !DSO-libs application. In the download area of the GCCSDK website there is separate 'core' !DSO-libs ZIP file available (also containing a !System holding the most recent modules required by UnixLib) which can be downloaded by the users of your program. In case your program is a C++ program, an additional 'g++' !DSO-libs ZIP needs to be downloaded and its contents copied on top of the 'core' !DSO-libs application as this will add the necessary C++ shared libraries.
We strongly recommend that you instruct your users to download !DSO-libs ZIP file(s) themselves instead of providing a copy of a possibly outdated version together with your program.
Over time we anticipate that a more managed download and upgrade facility will be used like RiscPkg but details and instructions are not available at the time of writing.
Here are described some common problems users have with gcc and the GNU compilers. Possible solutions are provided for the known problems.
GCCSDK 4 requires at least SharedUnixLibrary version 1.11. This error is because you have a version loaded in memory which is prior to that version and still currently in use by one or more UnixLib compiled programs.
Loading a newer version of the SharedUnixLibrary is not possible until all those UnixLib compiled programs have been stopped.
You should quit all those UnixLib compiled programs and again double click on !GCC filer icon.
You have no or a not up-to-date version of the SharedUnixLibrary module in your !System. Use the GCCSDK supplied !System and use the System merge utility provided by Configure to merge this with your !System.
This is usually caused by a lack of memory. To see how far through compilation a file has gone, try compiling with the '-v' switch. '-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 6000K.
When the compiler runs out of memory during compilation, an error 'virtual memory exhausted' is usually reported.
This is caused by insufficient memory memory and can be fixed by increasing the wimpslot to similar values as above.
Each RISC OS module needs a module header which can be created using CMunge. See CMunge documentation 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.
Modules often have their data (Messages, Sprites, etc) stored in ResourceFS. mkresfs can be used to create a C file representing the intended ResourceFS data allowing easy (de)registration with ResourceFS. In GCCSDK 3.4 this functionality was covered with the 'resgen' program but as its code was very thightly AOF based, a new program (and approach) was chosen.
List of known problems or missing features compared to GCCSDK 3.4.6:
GCCSDK 4 produces ELF object files, libraries and binaries while in GCCSDK 3 this was AOF/AIF based. Currently there is no support to mix AOF object or library files with ELF object files.
For each GCCSDK release an overview of the most important changes are made in its Changes file.
More details on the changes made in particular areas can be found in:
GNU GCC/binutils documentation:
Runtime documentation:
Shared library support on RISC OS:
RISC OS related documentation:
The GCCSDK website contains more information like how you can log bugs, addressing the GCCSDK development itself and related RISC OS development aspects. Currently the GCCSDK website is Wiki based so your input in the form of changes and/or additional input is greatly appreciated.
Most importantly, you can also find details how you can join the GCCSDK mailing which has been setup for discussions on GCCSDK, including its development work. We strongly recommend to join this mailing list.
This port of GCC is:
Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001 Nick Burrett Copyright (c) 2002, 2003, 2004, 2005, 2006, 2007 GCCSDK Developers
The GCCSDK releases made by the GCCSDK Developers consists of several binaries and sources which do not necessary have the same licenses. The following overview can help to identify those licenses more easily but is in no way an authoritative statement on behalf of the GCCSDK Developers:
As with all GNU programs, THERE IS NO WARRANTY OF ANY SORT.
Primary GCCSDK Developers today are:
An enormous amount of porting and testing work was done by Nick Burrett. Without his past contribution GCCSDK wouldn't exist.
The following people have also made contributions over the last four years (in alphabetic order) :
Ben Avison, John-Mark Bell, Stefan Bellon, Alan Buckley, James Bursa, Steve Ellacott, Rich Hudson, Rob Kendrick, Jeffrey Lee, Adrian Lees, Christian Ludlam, Alex Macfarlane Smith, Theo Markettos, David Marston, Philip Pemberton, Graham Shaw, Tony van der Hoff, Simon Wilson, Martin Wuerthner.
Special thanks to the following people having written programs which are used in the GCCSDK project :
Thanks also to all the testers and bug reporters.
And last but not least, all the GCC and binutils contributers.