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 5MB, and ensure there are another 5MB 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 builtin specs. gcc version 2.95.4 20010319 (prerelease) [gccsdk 20010912]
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:
- 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.
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: MyLibrary:mylibrary.o example.c
(note that this actually refers to the library file 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 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.
