Welcome to GCCSDK GCC 4.1.1 release 1b for RISC OS

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.

1. Introduction

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.

1.1. Installation

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

1.2. Simple compilations

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

When specifying those source files for the compile, assembler or linker, it is recommended to use the 'my_c_program.c' syntax instead of the RISC OS file syntax 'c.my_c_program'.

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 -o hellow

This will compile, assemble and link the source 'c.hellow' in one go to produce an ELF executable (filetype &E1F) called 'hellow'. An ELF executable can make use of static libraries and/or shared libraries (whom the UnixLib runtime library). In GCCSDK GCC 4.1.1 Release 1 however we only include static ELF support and it is anticipated that the next release will support shared library support as well.

ELF executables need support of a loader module in order to be usable under RISC OS and this is provided by the '!SharedLibs' application which containing the SOManager RISC OS module. This means also that when ELF executables are distributed to users, they also need to have access to '!SharedLibs' application in order to be able to run the ELF based program.

Currently it is recommended to distribute Absolute executables instead of ELF static executables as this reduces the installation and distribution efforts of '!SharedLibs' (a next release of GCCSDK supporting shared libraries will need the distribution and management of '!SharedLibs'). This can be done by transforming the ELF executable into a standalone Absolute executable which does not needing the '!SharedLibs' application at runtime:

   *elf2aif hellow

In case you really want to distribute the ELF executable, you make sure your users have access and installed '!SharedLibs' application and you probably want to strip the ELF executables first as well (as this will reduce program size by removing all non-essential information) by adding the switch '-Wl,-s':

   *gcc hellow.c -Wl,-s -o hellow

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 -o myprogram

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

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

   *gcc -c file.c
or
   *gcc -c file.c -o file.o

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

Support has been provided for both RISC OS and UNIX format filenames and we recommend to use the UNIX format style as this is more cross-platform compatible. For example:

   UNIX format (preferred)	RISC OS format

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

but note that

   tree.def			tree/def

For further examples of compilation procedures, please look at `Examples' inside !GCC.

1.3. More advanced compilations

1.3.1. SharedCLibrary

By default UnixLib is used as runtime library. In case it is important to use RISC OS' SharedCLibrary and at expense of a much more reduced API, you can do that by specifying the switch -mlibscl at compile and link time. The linker will produce an Absolute (filetype &FF8) file having an AIF header straight away instead of producing an ELF executable (filetype &E1F):

   *gcc -mlibscl -o file.o -c file.c
   *gcc -mlibscl -o mybinary file.o
1.3.2. RISC OS module support

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) to be backwards compatible with GCCSDK 3.4 you have to specify -mlibscl as well as it was not done by default before.

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

Module code executed in SVC or IRQ mode does not need to do any APCS stack checking (as the RISC OS R13 SVC and IRQ stacks are not chunked) so the switch -mmodule implicitly selects the -mno-apcs-stack-check switch as well. However some pieces of module code can also run in USR mode as e.g. module start code (hence, as application) so the -mapcs-stack-check switch is then exclicitly needed to enforce chunk stack checking for those module object files containing code which is executed in USR mode.

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 tightly AOF based, a new program (and approach) was chosen.

1.4. Switches

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.

1.4.1. General switches

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
Pre-process the source file
-o <file>
Put the resulting output into <file>
-O
Apply some optimizations to the output
-O2
Apply full optimization.
-O3
Full optimization and inline small functions as well.
1.4.2. ARM specific switches

The ARM specific switches are documented in GNU C/C++ manual, section "ARM Options". The most important ones are:

-mpoke-function-name (default) / -mno-poke-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.

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.

-msoft-float (default for when UnixLib runtime library is used)
Select soft-float routines to be used and generated when floating point operations are needed. Unless you have hardware FP support in your ARM processor, soft-float routines result in faster executables.
-mhard-float (default when SharedCLibrary runtime library is used)
Makes that floating point (FP) ARM instructions will be used in the generated code.

In the RISC OS port, options -msoft-float and -mhard-float are mutually exclusive.

1.4.3. RISC OS specific switches
-mthrowback / -mno-throwback (default)
Send errors to a text editor capable of receiving 'throwbacks'. Error throwbacks will only occur when the DDEUtils module has previously been loaded.
-munixlib (default)
Builds and links source code against the UnixLib headers and library files. Note that when used, this needs to be specified during compiling and linking. This defines the preprocessor define __TARGET_UNIXLIB__.
-mlibscl
Builds and links source code against the SharedCLibrary headers and library files. Note that when used, this needs to be specified during compiling and linking. This defines the preprocessor define __TARGET_SCL__.

Switch -mmodule will implicitly select -mlibscl as well.

-mmodule
Generates code suitable for a RISC OS module. This will implicitly select -mlibscl. This also defines the preprocessor define __TARGET_MODULE__.

The -munixlib and -mlibscl switches are mutually exclusive.

1.4.4. Obsolete or not implemented GCCSDK specific switches
-mapcs-26 / -mapcs-32
From GCCSDK 3.3.3 release onwards, APCS-32 became default and APCS-R deprecated. With the releases before you could select between those two ABI's using respectively the mutually exclusive -mapcs-32 and -mapcs-26 switches.

From GCCSDK 4 onwards we don't have any APCS-R support and made the switches -mapcs-32 and -mapcs-26 obsolete.

-mamu
Generates 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.

The use of GNU make is preferred as it allows to write more expressive Makefiles and ensures a better compatibility with or require less differences than Makefiles for cross-compiling.

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

The -mclient-static-data-offset and -mlibrary-static-data-offset switches are mutually exclusive.

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

The -mclient-static-data-offset and -mlibrary-static-data-offset switches are mutually exclusive.

1.5. Binary configurations

As an overview, the following configurations are possible with the native RISC OS release :

1.6. Predefines

This is a short list of the most interesting and useful predefines set:

__arm
__arm__
Always defined in the RISC OS port and can be used to make a difference between ARM specific vs non-ARM code.
__riscos
__riscos__
Always defined in the RISC OS port and can be used to make a difference between RISC OS specific vs non-RISC OS code.
__ELF__
Always defined as GCCSDK 4 is now ELF based.
__SOFTFP__
Defined when soft-float routines are used in the to be generated code in contrast with using floating point (FP) instructions. FP instructions will be used when the SharedCLibrary runtime library is selected (switch -mlibscl and/or -mmodule is selected). When UnixLib runtime library is used, by default soft-float routines are used unless you have -mhard-float specified.
__TARGET_SCL__
Defined when targeting the SharedCLibrary runtime library, i.e. when -mlibscl or -mmodule switches are supplied.
__TARGET_MODULE__
Defined when module code is being generated, i.e. when -mmodule switch is supplied.
__TARGET_UNIXLIB__
Defined when targeting the UnixLib runtime library, i.e. when -mlibscl nor -mmodule switches are supplied (as -munixlib is default switch).

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 distinguish 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

1.7. Migrating projects to GCCSDK 4

The GCCSDK 4 release contains a significant number of changes compared to its previous stable GCCSDK 3.4.6 release and this might require some changes to your project when you want to build it with GCCSDK 4.

1.8. Distributing your programs

When you want to distribute your compiled program it might be necessary to accompany it with an ELF loader. This is not necessary when your program is a static ELF binary which has been converted with elf2aif or when it is using SharedCLibrary as runtime library (as for both cases your program is an Absolute (filetype &FF8) file with AIF header) or when it is 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 !SharedLibs application. In the download area of the GCCSDK website there is separate 'core' !SharedLibs 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++' !SharedLibs ZIP needs to be downloaded and its contents copied on top of the 'core' !SharedLibs application as this will add the necessary C++ shared libraries.

We strongly recommend that you instruct your users to download !SharedLibs 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.

1.9. Troubleshooting

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

2. Known issues or unsupported GCCSDK 3.4.6 features

List of known problems or missing features compared to GCCSDK 3.4.6:

3. Changes

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:

4. Further documentation

GNU GCC/binutils documentation:

Runtime documentation:

Shared library support on RISC OS:

RISC OS related documentation:

5. GCCSDK website, bug reporting & mailing list

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.

6. Licenses and warranty

This port of GCC is:

Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001 Nick Burrett
Copyright (c) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 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.

7. Credits

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.