GCC tutorial

RISC OS GCC Tutorial

Written by James Bursa and Peter Naulls.

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

Follow the instructions under GCC for RISC OS

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:

• Double-click on the gcc application.
• The compiler is memory hungry, so open the Task Manager, and drag the Next slot up to at least 6MB, and ensure there are another 6MB free.
• Press Ctrl-F12 to start a TaskWindow.
• Type the command gcc -v (enter at end) at the * prompt. The output should be something like

Using built-in specs.
Target: arm-unknown-riscos
Configured with: ./configure riscos
Thread model: posix
gcc version 4.1.1 (GCCSDK GCC 4.1.1 Release 2)

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 subdirectory. There you find small examples for C, C++ and assembler code.

Compiling

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.C subdirectory containing the source file.

This can be done by opening a menu over the directory window and choosing >Set Directory.

Or you can use the 'Dir' command, by typing:-

Dir ADFS::HardDisc.$.Tools.!GCC.Examples.C

giving the path to the Examples.C 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 helloworld.c

In a few moments, a file called 'a/out' will appear in the Examples.C 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 helloworld.c

This is equivalent to

gcc helloworld.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:

• gcc -- the compiler frontend. Most of the time, this is the only one you will use: it then controls the other programs.
• cpp -- the c preprocessor, expands #include directives and macros.
• cc1 -- the actual compiler, converts C to assembly code.
• as -- the assembler, turns assembly to an object file.
• ld -- the linker, links object files and libraries to create an executable.

gcc acts as frontend for most of these other programs and it is recommended not to invoke the preprocessor, assembler, linker, etc. directly.

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 contains, 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:

• the directory containing the source file
• a directory containing standard C headers (inside !GCC)
• directories specified after the gcc command with the option -I.

For example, the command

gcc -IMyLibrary: example.c

(where MyLibrary$Path points somewhere)

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 the MyLibrary: path.

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 -IMyLibrary: -LMyLibrary: -lMyLibrary example.c

(note that -LMyLibrary: -lMyLibrary actually refers to the library file libMyLibrary/a which is to be found in the MyLibrary: path).

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.
-Llibrarypath
    add the specified directory to the set of library directories where libraries can be found.
-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.

A more comprehensive list of options likely to be of interest to RISC OS users can be found in GCC common switches.

The C Library

GCC can use two different standard C libraries:

• The RISC OS Shared C Library. Using this gives smaller programs. To use the Shared C library, pass -mlibscl to gcc.
• UnixLib. This version of the standard library includes additional functions to make compiling unix programs easier. This is the default used by gcc.

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.

C++ programs often require additional libraries to be linked in, but the g++ frontend takes care of these.

For example, to compile the helloworld program in Examples.CC, which uses the iostream classes:

 g++ helloworld.cc

It is also possible to use C++ with the SharedCLibrary.

Links

• GCCSDK/GCC Home
• GCC for beginners

GCC and GCCSDK pages

GCC under RISC OS GCC for RISC OS, GCC tutorial, GCC common switches, GCC for beginners, UnixLib, ELFLoader GCCSDK and Unix porting GCCSDK, GCCSDK Releases, GCCSDK Development, Using GCCSDK, Autobuilder Development and Packaging Cygwin setup, Accelerating autobuilder with apt-proxy, ChoX11, Developer help wanted