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). By default, the shared libraries will be used (use link switch -static if you want static libraries to be used).
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.
It is possible to convert an ELF executable into a standalone AIF binary when the ELF executable is linked when only using static libraries (i.e. when -static link switch has been used). This removes the need to distribute the '!SharedLibs' application together with the produced program but of course defeats the point of using shared libraries. This is done by running:
*elf2aif hellow
When distributing ELF executables you probably want to strip the ELF executables first as well as this will reduce program size by removing all non-essential information. This is done 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
When C based modules are created, you can only make use of the SharedCLibrary as runtime library or no runtime library at all. UnixLib is not suited as runtime library for modules. When you do not make use of SharedCLibrary in your module you're on your own to implement all your memory management, I/O, etc. (when needed) yourself (possibly using RISC OS' or third party modules' SWIs).
CMunge is used to create a RISC OS module header and the necessary setup code for each of the user required module entries, like initialisation, finalisation, service calls, command implementations etc. It can also be used to create veneer code acting as glue code for RISC OS callbacks into your C coded module.
At runtime the module will automatically get a private workspace holding internal state data (currently 3 words) but also all non-constant global variables used in your code. Initial non-zero non-constant global variables are stored in the module code itself and those get copied at startup in the module's private workspace where they can change during runtime. Initial zero global variables are not part of the module code but get a place in the private workspace as well. Constant global variables remain in the module and are not copied to the private workspace.
Typically this is done by:
*cmunge -tgcc -32bit -d modheader.h module.cmhg *cmunge -tgcc -32bit -o modheader.o module.cmhg
The generated modheader.h header file is included by all C code implementing the C functions specified in given .cmhg file.
See CMunge documentation for more information.
For all C compilations and final linking the switch -mmodule needs to be specified. For compiling this is required to make sure that global data can be properly relocated at runtime. For linking this will make sure the output is a valid RISC OS module containing the necessary relocations needed at start up time.
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.
In this example 'modheader.o' is already generated by CMunge before.
*gcc -mlibscl -mmodule -O2 -c module.c -o module.o *gcc -mlibscl -mmodule module.o modheader.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.
Modules created without using SharedCLibrary have the advantage to not be dependent on the SharedCLibrary and have typically a smaller footprint. They are created by specifying the extra CMunge switch "-znoscl" (specifying not to generate code to interface with SharedCLibrary but generate code instead to setup the runtime stack itself) and by the extra linker switches "-nostdlib -lgcc" (specifying not to use any standard library, whom the SharedCLibrary, except the GCC library which contains helper routines possibly used by its generated code).
Note you can still include the standard headers (like stdbool.h, limits.h, stdlib.h, etc) to get some useful type definitions or constants but that does not mean you can make use of any of the functions with their prototypes being defined there. If you want to avoid including any of the standard headers (for whatever reason), you can specify the extra compile switch "-nostdinc".
It might be that GCC generates code which contains memcmp, memset, memcpy and memmove calls. In such a case you need to provide those routines yourself (they are the same routines as the ones defined in standard C).
Calling RISC OS SWIs can be done via inline assembler calls, custom assembler routines or making use of a C library providing SWI level access like OSLib. Note that such libraries can not use the SharedCLibrary as well.
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.
When UnixLib is selected as runtime library, by default it will be the shared UnixLib library. It is possible to use the static UnixLib at link time by specifying the linker switch -static.
*gcc -o file.o -c file.c *gcc -static -o mybinary file.o
Profiling is the art of determining where the CPU spends most of its time when running your program. To enable profiling, the option -pg is passed to GCC during compiling and linking. An example, collatz.c should help to make this clearer:
*gcc -pg -o collatz collatz.c
Now, when ever the program is run, it will be profiled and upon exiting will write a file named gmon/out to the currently selected directory. This is a machine readable file and must be processed by a program called gprof before the results can be made sense of. The simplist way to do this is to pass the executable and the gmon/out file to gprof on the command line:
*gprof collatz gmon/out >gprof-outputNote that the output of the command is written to a file, as the output from gprof contains formfeed characters (ASCII char 12) which cause unwanted effects when printed directly to the screen. For an explanation of the gprof results, please see the gprof manual.
Optimising code (that is, using the -O switch when compiling) can effect how the code is profiled, for example, functions can apparently disappear and fail to be listed in the profiling results. This is most likely due to GCC inlining the function so that it does not exist as a function is its own right but becomes part of another function. One way around this is to tell GCC not to inline such functions by using:
__attribute__ ((noinline))when declaring them.
It's possible to control manually what is and isn't profiled by using the moncontrol function, which is declared in the system header file <sys/gmon.h>. The value passed as the single argument to moncontrol should be 0 to stop profiling and 1 to start profiling, for example, if you have a function a() which calls b(), but you don't want b() to be profiled, then it may look like this:
void b(void)
{
...
}
void a(void)
{
...
moncontrol(0);
b();
moncontrol(1);
...
}
Profiling support requires at least an ARM 600 and RISC OS 4. As only HAL and OS calls are used, it should work on any version of RISC OS with a HAL. For a 26 bit OS, the HAL26 module written by Theo Markettos is required.
Due to the low level nature of the profiling support, this feature is currently deemed experimental, as it is difficult to gauge how it will interact with other programs. It's therefore advisable to save any important work before using the profiler. You should not attempt to profile two programs at the same time, as this will almost certainly fail (a future version may infact take steps to prevent it).
Support for profiling shared libraries is not yet implemented (although we hope to add this in the future), however, this does not prevent the dynamically linked program from being profiled. You should remember though that any functions within shared libraries will not count towards the profile.
Profiling in RISC OS GCCSDK involves two techniques; counting functions calls, recording the relationships between each of them and recording how much time is spent in each. Compiling with -pg has the effect of inserting a function call to mcount at the beginning of every function. mcount is provided by UnixLib (which therefore must be the runtime library), and is responsible for incrementing a count for the current function and recording its caller.
When linking, the use of -pg causes GCC to link against gcrt1-riscos.o instead of crt1-riscos.o. This tells UnixLib that profiling has been enabled and that it should start the profiling hardware timer. The hardware timer is set to generate an interrupt one hundred times every second. Upon each interrupt, the program being profiled is stopped and a small (interrupt) routine is called with the address at which the program stopped passed to it. The interrupt routine increments a counter for this particular address and then returns control back to the point of the interruption and the program continues as if nothing happened. This is called statistical sampling. The counters for each sample point are 16 bits wide which means that each can count to 65535 before overflow occurs. If an overflow of any of the samples is detected, profiling is automatically disabled, however, the result file is still written.
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 switch 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 switch on when developing applications as it can lead to a clear indication of where a program is failing when a backtrace is generated.
The -msoft-float and -mhard-float switches 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.
As the object format is ELF you need to make use of an assembler outputing ELF. There are two options:
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 and in this GNU ARM Assembler Quick Reference.
*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' switch 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 switch '-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 and possibly also a set of shared libraries used by your program. 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 section of the GCC page there is separate 'core' !SharedLibs ZIP file available which can be downloaded by the users of your program. You will also need the C support and possibly also the C++ support additions.
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.
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.12. 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-2012 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 years (in alphabetic order) :
Ben Avison, John-Mark Bell, Stefan Bellon, Alan Buckley, James Bursa, Steve Ellacott, Chris Gransden, Rich Hudson, Rob Kendrick, Jeffrey Lee, Adrian Lees, Christian Ludlam, Duncan Moore, Peter Naulls, Alex Macfarlane Smith, Theo Markettos, David Marston, Philip Pemberton, Graham Shaw, Tony van der Hoff, Alex Waugh, 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.