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'.
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.cor
*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.
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
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.
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:
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.
Switch -mmodule will implicitly select -mlibscl as well.
The -munixlib and -mlibscl switches are mutually exclusive.
From GCCSDK 4 onwards we don't have any APCS-R support and made the switches -mapcs-32 and -mapcs-26 obsolete.
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.
The -mclient-static-data-offset and -mlibrary-static-data-offset switches are mutually exclusive.
The -mclient-static-data-offset and -mlibrary-static-data-offset switches are mutually exclusive.
As an overview, the following configurations are possible with the native RISC OS release :
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 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
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.
Pre GCCSDK 4 releases had as object format AOF (Acorn Object Format) and the AOF based libraries came as ALF (Acorn Library Format). RISC OS Absolute programs (filetype &FF8) came in an AIF file format (Acorn Image Format).
As those formats are not supported by GNU binutils' assembler 'gas' nor linker 'ld', this means that your projects needs to be completely rebuilt as you can not use previously made (or supplied) AOF/ALF files. In case of C or C++ files this is most probably just a case of recompiling. In case of assembler files, the sources need to be changes to make them 'gas' compatible (read further on). In case of creating library, the process can be slightly different (read further on).
Both object files, shared library files and resulting fully linked binary files are in ELF file format (filetype &E1F). There is no native RISC OS support for loading shared libraries and ELF linked binary files so that's why you need an ELF loader such like 'SOManager' (currently part of !SharedLibs application).
There are two ways to create AIF based program files which of course do not need the use of 'SOManager' to run those programs:
Aside: when creating a module (i.e. using '-mmodule' during compilation and linking), the intermediate object files are ELF based but the final binary produced by the linker is a valid RISC OS module which of course does not need the 'SOManager' ELF loader.
In GCCSDK 4 we no longer use the 'as' AOF assembler and are using the 'gas' assembler instead. The syntax used for 'gas' is slightly different and the most important differences are:
So, 'as' assembler code like:
|mylabel1| ADD r0, r0, #1 mylabel2 MOV pc, r14
needs to be changed to:
mylabel1: ADD r0, r0, #1 mylabel2: MOV pc, r14
IMPORT |mylabel1| IMPORT |mylabel2|, WEAK
needs to be changed to:
.weak mylabel2
abc * 0 def * &1234
needs to be changed to:
.set abc, 0 .set def, 0x1234
Or:
abc EQU 0 def EQU &1234
needs to be changed to:
#define abc 0 #define def 0x1234and you assemble the code using:
gcc -xassembler-with-cpp -o file.o -c file.sso that the pre-processor can expand the #define definitions.
% 256
needs to be changed to:
.space 256
Or:
^ 0, ip parentprogname # 4 ; Ptr to program name editname # 12 ; Edit name WSSize * :INDEX: LDR r0, parentprogname ADR r2, editname MOV r3, #WSSize
needs to be changed to:
.struct 0
parentprogname : .skip 4 @ Ptr to program name
editname : .skip 12 @ Edit name
WSSize :
LDR r0, [ip, #parentprogname]
ADD r2, ip, #editname
MOV r3, #WSSize
TEQ r1, #"R"
needs to be changed to:
TEQ r1, #'R'
Integer notation:
TST r0, #2_0101 ; Binary value TEQ r0, #8_12 ; Octal value TEQ r0, #&100 ; Hex value
needs to be changed to:
TST r0, #0b0101 @ Binary value (or 0B0101 can be used) TEQ r0, #012 @ Octal value, notice the extra digit 0 as first character TEQ r0, #0x100 @ Hex value (or 0X100 can be used)
EXPORT |mylabel|
needs to be changed to:
.global mylabel
AREA bla_data, DATA AREA bla_data_noinit, DATA, NOINIT AREA bla_code, CODE DCB &12 DCD &12345678 = "test" = " and another test", 0 END
needs to be changed to:
.data @ A short form of .section + arguments .bss .text @ A short form of .section + arguments .byte 0x12 .word 0x12345678 .ascii "test" .asciz " and another test" .end @ ".end" can be left out and is not required.
More information can be found in GNU assembler as.
*gcc -o myapp object1.o object2.o OSLib:o.OSLib32
which links the object1.o and object2.o object files with the RISC OS OSLib library found as OSLib:o.OSLib32. The binutils' linker needs to have its libraries specified with '-l' option and further assumes that all libraries filenames on disc start with 'lib' (but omitted when specified) and have an 'a' extension instead of 'o' which was usually used in pre-GCCSDK 4 projects. Also it is preferred to specify the directory where the library can be found using an extra option '-L' (in fact, this specifies an additional search directory for the '-l' libraries). So above example needs to be changed for GCCSDK 4 as:
*gcc -o myapp object1.o object2.o -LOSLib: -lOSLib32
and this with the file "libOSLib32/a" stored in the directory defined by the 'OSLib:' path. Note we don't do suffix swapping for 'a' extensions. Of course, it is expected that ELF releases of libraries already have the 'lib' prefix and '/a' extension of the library filename.
This change has hardly any effect on your project when you migrate to GCCSDK 4 except for the improved runtime speed for floating point intensive code.
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.
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.
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, 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.
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.