Note: This tutorial was written for me by James Bursa after a request on the RISC OS Projects Initiative page. You can contact James at james.bursa@strcprstskrzkrk.co.uk.

As GCC is under constant development, this tutorial may change on a regular basis, so please check back.

RISC OS GCC Tutorial

Introduction

This document gives an overview of using the GNU Compiler Collection (GCC) for RISC OS. It assumes some knowledge of the RISC OS environment and programming, but none of compilers. However, it does not contain a C tutorial: get a textbook.

GCC is a command-line tool, unlike most RISC OS programs which have a graphical interface. To use it, you have to type commands into a Taskwindow.

Installation

Download and Extract

You will need at least 25MB of hard disc space.

Get the compiler zip archives from http://hard-mofo.dsvr.net/gcc/. You should get all the archives, except g77.zip (unless you want to use Fortran) and java.zip (unless you want to compile Java). You only need cc1plus.zip if you want to use C++. Each archive contains a !gcc application and they should all be extracted into the same place to merge the contents. If you have a previous version of gcc, do not merge the new version with it, but move it somewhere else.

You may wish to install an editor. Edit is sufficient, but Zap or StrongEd provide additional features (for example code colouring).

Test the Compiler

To check the compiler has been installed correctly, follow these steps:

Compiling a Program

This section walks you through compiling a simple C program using gcc. The text file containing the program is known as a source file.

To get to the example programs, shift-double-click on !gcc, and open the examples directory.

Compiling

Make sure that there's plenty of memory free, and the next slot is at least 5MB, and start a Taskwindow.

RISC OS has the concept of a 'current directory'. This is a directory which is looked in when a program wants a file, and gcc looks there for source files. The first thing to do is to change the current directory to the examples directory containing the source file using the Dir command, so type

Dir ADFS::HardDisc.$.Tools.!gcc.examples

giving the path to the examples directory on your machine (try typing Dir , and dragging the directory into the taskwindow while holding shift to enter the path automatically).

Type Ex to check that you have changed to the correct directory. This command gives a list of the files in the current directory. You should see 'c' in the list.

Now we're ready to compile. Type this command:

gcc hellow.c

In a few moments, a file called '!RunImage' will appear in the examples directory. This is the compiled program, and you can double-click on it to run it.

GCC comes from unix, where extensions are used to identify file types. For example, the extension .c indicates C source. RISC OS can't use extensions, so instead files are kept in a directory named after the extension. C source files are kept in a directory called 'c', and header files are kept in a directory called 'h'.

The gcc command expects to get file names as if they had extensions. It then does the conversion of the extension to a directory name itself. For example, to compile a C source file called 'test' (located in a directory 'c') , you need the command gcc test.c.

Editing

C source files can be edited in any text editor. On RISC OS, you could use Edit from the application suite. You can also download StrongEd or Zap or use a different editor.

Command Options

To control gcc, options are given after the gcc command. Options start with a -, are separated by spaces, and order does not matter. For example, the -v (verbose) option makes gcc give more detail of what it's doing:

gcc -v hellow.c

This is equivalent to

gcc hellow.c -v

Anything that doesn't start with - is the name of a file to compile.

Here's a more complicated example:

gcc -v -W -O test1.c test2.c

This compiles test1 and test2 with verbose output (-v), warnings on (-W), and optimisation enabled (-O).

The Compiler

The compiler is actually a group of programs, which work together to create the final executable. The programs include:

The compilation process

Libraries

Libraries are collections of functions written by someone else, which you can use in your programs. For example, the standard C library contains useful functions needed by most C programs, such as printf. A library consists of a library file which contains the actual functions already compiled, and some header files (or headers) which describe what functions the library file contain, as C declarations.

To use a library, the headers need to be included in the C source using #include statements. The preprocessor will then insert the contents of the header at this point.

GCC looks for included files in the following places:

For example, the command

gcc -IADFS::HardDisc.$.Code.MyLibrary example.c

with the line

#include "test.h"

in c.example, would make gcc look for h.test in the directory containing c, in the standard directory, and in ADFS::HardDisc.$.Code.Extra.

Also, the library needs to be made available to the linker, so that it can include the compiled functions in the program. This is done by giving the pathname of the library file to gcc:

gcc -IADFS::HardDisc.$.Code.MyLibrary ADFS::HardDisc.$.Code.MyLibrary.mylibrary.o example.c

(note that this actually refers to the library file ADFS::HardDisc.$.Code.MyLibrary.o.mylibrary -- gcc converts the last extension to a directory).

The standard C library is automatically used, so doesn't need to be specified like this.

GCC Options

Here is a description of the most useful options to gcc. For a full list of options, read the gcc manual (in !gcc.docs).

-o name
the name for the compiled output. The default name is '!RunImage'.
-v
verbose. Give details of what gcc is doing. Use this to help track down problems.
-Wall
all warnings. This makes the compiler print many helpful warnings which may indicate problems with the code. It's a good idea to use this option.
-c
just compile and assemble the source files, don't do linking. This makes an o file from each c file passed on the command line. You can then link these files by calling gcc again with any mix of o and c files.
-O
optimize. This attempts to make the compiled program run faster, but compiling will take longer. Use this for the final version of a program.
-O2, -O3
optimize more, optimize even more. Compilation will take longer, and the compiled program may be slightly faster.
-Idirectory
look for #include files in this directory. See above.
-llibrary
use the specified library file.
-mthrowback
send errors and warnings to your editor. You can then double-click on them to jump to the line where the error occurred. This works with Zap or StrongEd, but doesn't work with Edit.

The C Library

GCC can use two different standard C libraries:

The Shared C Library is a RISC OS module which can be used by more than one C program simultaneously, saving memory. The compiler will add special code to your program which transparently passes calls to library functions to the module.

There are some differences between the headers for the Shared C Library and UnixLib, so do not mix object files compiled with -mlibscl with those compiled without.

If you don't know which to use, use the Shared C library.

C++

C++ source files are kept in a 'cc' directory (alternatively, 'cpp' or 'c++' also works). Compilation is similar to C.

It is not possible to use the Shared C library with C++; use UnixLib.

Additional command line options need to be specified for some C++ libraries:

For example, to compile the helloworld program in examples.cc, which uses the iostream classes:

gcc -liostream helloworld.cc