RISC DISC 1/RISC_DISC_1.iso/pd_share/code/gcc/!GCC/!Intro

Text File | 1994-10-06 | 12.4 KB | 390 lines

                GCC on the Archimedes - An introduction
                =======================================

Following a number of justifiable complaints I have received about the GCC
documentation, this is an attempt to explain how to use GCC. Note this is
mainly about the RISC OS specifics of GCC - if you don't know C, C++ or RISC
OS, get youself a good book - you WILL need it.

IMPORTANT: GCC REQUIRES A LOT OF MEMORY. The wimpslot needs to be at least
3044K in size.. GCC is NOT capable of grabbing extra memory, so the initial
WimpSlot sets the maximum memory available.

This document is not the same as the version posted on the comp.sys.acorn
newsgroup - there are some significant differences.

Index
~~~~~

1)      Installing GCC
2)      Filenames
3)      Simple usage
4)      More complicated usage
5)      Using other libraries
6)    AMU and other bits
7)      Example programs



1)      Installing GCC
        ~~~~~~~~~~~~~~

Before installing GCC, it should be noted that the standard GCC distribution
is not complete, and only consists of the C and C++ compilers and a few
support programs.

In addition to GCC, you will need the following :

    *   Linker
        GCC may be used with either the Acorn linker supplied with the
        Norcroft C compiler or with the DRLink linker, which is the default
        linker.

    *   Runtine Library
        Again GCC may be used with the Norcroft libraries (Stubs, AnsiLib)
        or with UnixLib, the default library, available from your favorite
        FTP site.



    *   Virtual
        This may not be needed, if you have a lot of RAM (i.e 8M+),
        otherwise it is almost essential.

libg++ is included in the distribution.

The (default) installation of GCC is relatively simple :

    *   Copy the !GCC directory, and its files, onto your hard disc.
    *   If you using the Acorn linker,Shift-double click on the !GCC icon,
        and again on the file '!Boot', to load it into an editor. Find the
        line '|Set GCC$Linker link', and remove the leading '|' character.
        Save the file back to its original place. Repeat with the !Run file
    *   Ensure that the file !Gcc.!boot is run during your boot up
        procedure. This will setup all the paths required by GCC.

Note that the first stage will differ slightly, depending on where you
obtained GCC, and the distribution format. Accompanying each distribution
should be a file called !GCCUnpack with more specific instructions.

If you wish to separate the distribution (not recommended), the files in
!Gcc.bin should be copied so that they are in your run path, while GCC$Path
and GPP$Path should point to the GCC and GPP directories respectively.

When installing UnixLib, follow the instructions supplied with them.

libg++ is installed by copying the file 'c++' to the directory '!GCC.gpp.o',
while the 'h' directory is copied to the '!GCC.gpp' directory.

If you have an old version of GCC, which you are using with DRLink, the old
installation required 'drlink' to be renamed to 'link'. GCC now defaults to
using DRLink, and the file should be renamed back to DRLink.

This completes the installation of GCC.



2)      Filenames
        ~~~~~~~~~

Due to the naming conventions used on UNIX systems, and the use of '.' as
the directory seperator in RISC OS, the filenames used for sources are a
little odd.

On UNIX system, the type of a file (C, C++, header file etc) is indicated by
postfixing a file extension. For C and C++ programs, these extensions are :

        .c      C sources
        .cc     C++ sources
        .h      header files
        .o      object files (compiled sources)

Due to the way that ADFS works, it is not possible to use these extensions
as the '.' causes problems. The work around is to store the files in
subdirectories of the same name ('c', 'cc', 'h' and 'o').

Thus the source file 'HelloW.c' would be stored as the file 'HelloW' in the
directory 'c'. See the following table for more examples.

        UNIX name       Actual name
        ~~~~~~~~~       ~~~~~~~~~~~

        HelloW.c        c.HelloW
        include.h       h.include
        HelloW.cc       cc.HelloW
        object.o        o.object
        asm.s           s.asm

Despite this arrangement, all the files are still referred to by their UNIX
names.



3)      Simple usage
        ~~~~~~~~~~~~

For simple usage, programs may be compiled and linked simply by invoking GCC
with the sources listed as part of the command line. For example, the
program 'HelloW.c' can be compiled and linked by typing :

        gcc -v HelloW.c

This will produce the file !RunImage, which can be run immediately. Reember
you will need 3M+ of memory in the CURRENT wimpslot.

If the program is split over several source files, these may be compiled and
linked with a similar command :

        gcc -v Example1a.c Example1b.c Example1c.c

Which will again produce !RunImage.

When compiling C++ programs that use the IOSTREAM library, the switch
'-lc++' should be appended to the command line:

    gcc -v HelloW++.cc -lc++

The -v switch can be omitted if you dont want the extraneous information.

4)      More complicated usage
        ~~~~~~~~~~~~~~~~~~~~~~

GCC's behaviour can be controlled by various switches on the command line.
The following switches are those most likely to be useful.

    -S  Compile to assembler code. By default, the output is placed in the
        's' directory.

    -c  Compile, but do not link. By default, the object file is placed into
        the 'o' directory.

    -mamu
        This is intended for use with 'amu'. It generates the !Depend file
        that AMU uses for its 'dynamic dependencies'. This is now deprecated,
        though I don't yet know what will replace it - my first option
        failed badly.

    -mstubs
        This causes GCC to use the norcroft C header files and the shared C
        library stubs. To use this, they must be set up as for norcroft,
        with C$Path pointing to the appropriate directory. This is now
        deprecated - see 'Using other Libraries' for the recommended
        procedure.

    -o <file>
        This directs GCC to place the output file in <file>

    -O/-O2
        Optimise the generated code. -O2 does more optimsations, but
        requires more memory, and more time.

It should be noted that the -mstubs and -mamu switches are likely disappear
in the 2.6.x version. There may be a change over period in which they still
exist.

There are some other, more specialised, switches, but these are only likely
to be useful under very rare circumstances, and you should contact me for
more details.

    -mno-apcs
        Do not use the APCS-R calling standard.

    -mno-function-name
        Do not embed function names in the code.

    -mfpa
        Perform some scheduling of floating point instructions.

    -mno-stack-check
        Do not perform stack checking.



5)      Using other libraries
        ~~~~~~~~~~~~~~~~~~~~~

By default, GCC uses the UnixLib run-time library, but other libraries can
be used.

Libraries can be split into two types :

Language support libraries, which supply the basic functions for the
language, such as I/O and maths routines. The currently available libraries
of this type are UnixLib and the Norcroft libraries (Stubs and ANSILib). One
of these libraries MUST be used.

'Application' libraries. These provide extra facilities to the language but
are not part of the language. Examples are RISC_OSLib, DeskLib, Spirit and
OSLib

To use an application library, the '-I', '-l', and '-L' switches are used:

    -I<dir>
        This tell GCC where to find the header ('.h') files for the library.
        This should be the directory ABOVE the 'h' directory that the header
        files are kept in. I.e -IOSLib: tells GCC to look in the OSLIB:h
        directory for header files.

    -l<lib>
        This specifies the name of a library to link against. This may
        either be the complete path to the library (ie. '-lOSLib:o.OSLib')
        or, in conjunction with -L, just the leaf name of the library (ie.
        '-lOSLib').

    -L<dir>
        This specifes a directory that GCC should examine while looking for
        libraries. Note, this should be the directory ABOVE the 'o'
        directory that the library resides in. I.e '-LOSLib:' tell GCC to
        look in the 'OSLib:o' directory for library files.

Multiple '-I', '-l' and '-L' switches may be used, and GCC will search
through these to find the appropriate header files and libraries. GCC will
search the directories in the specified order.

Ie. the switches '-IA: -IB: -LA: -LB: -la -lb' will cuase GCC to look in the
'A:h' and 'B:h' directories for header files until it finds the specified
file, and it will search for the libraries 'A:o.A' 'B:o.A' 'A:o.B' 'B:o.B'

As an example, the OSLib library would, assumeing OSLib$Path points to the
OSLib directory, be used as follows.

        gcc <prog> -IOSLib: -lOSLIB:o.OSLib

or

        gcc <prog> -IOSLIB: -lOSLib -LOSLib:

If you wish to replace the language support library (UnixLib), the procedure
is slightly more complicated. If you are using the 'libg++' IOSTEAMS library,
you MUST link against UnixLib, therefore this procedure should only be used
for C programs, not C++.

To replace the language library, the following switches are used:

  -nostdinc -I<app> -IGCC: -I<lang> -nostdlib -lGCC:o.gcc <lib-specs>

the '-I<app>' and '-I<lang>' should be replaced by the appropriate '-I'
switches for the application and language libraries respectively. Note, the
'-I<lang>' MUST go after the '-IGCC:'

<lib-specs> should be the appropriate '-l' and '-L' switches. As an example,
when using the shared C library, the following command line is appropriate.

        gcc <prog> -nostdinc -IGCC: -IC: -nostdlib -lGCC:o.gcc -lC:o.stubs

This assumes that C$Path is set up correctly.

Note, that when specifing include paths and libraries, you have to be very
careful with the ordering. For include paths, the order is mentioned above,
while for libraries the ordering is :

        Application library
        IOSTREAM library (if used)
        gcc library (gcc:o.gcc)
        language library (Unix:o.Unixlib, etc)

If you with to use other libraries with GCC, there are a couple of points
that have to be looked at.

For GCC and G++, there are few extra keywords, that cannot be used for
variable names - these are 'new', 'delete', 'this', 'template', 'asm' (and
probably a few others I've messed). You will soon notice if these are used.

To provide type safe linkage, C++ 'mangles' function names to include the
types of the parameters. To prevent C++ from mangling C function names, the
dunction is declared as a C function by preceding the declaration with
'extern "C"', ie.

extern "C" fred(int jim);

For header files, the standard technique is to bracket the declarations by
the following:

#ifdef __cplusplus
extern "C" {
#endif

...

#ifdef __cplusplus
        }
#endif

It is possible that you library does not have these in the header files, but
these may be easily added.


The normal format of header files is :

#ifndef GUARD
#define GUARD

#include <...>

<declarations>

#endif

This should be changed to:

#ifndef GUARD
#define GUARD

#include <...>

#ifdef __cplusplus
extern "C" {
#endif

<declarations>

#ifdef __cplusplus
        }
#endif

#endif




6)    AMU and other bits
    ~~~~~~~~~~~~~~~~~~

GCC works quite well with AMU, though there are a few problems - AMU does not
properly handle the '.cc' extension, and in the dependencies lists, you have
to specify the 'cc' as a prefix - see the example Makefile.

If you are doing seperate compilation / link stages, there are two ways to do
the linking. You can either let GCC work it out, or use the LD program.

To use GCC, all need to type is

    gcc -o <output-name> <file1>.o <file2>.o ...

possibly with the -lc++ switch if using iostreams.

Alternatively, you can directly use the 'ld' command. This is a front end to
link / Drlink which converts the '-L' and '-l' switch to the format required
by link.

For an example of using ld, see the example makefile.

In addition, there is a program called 'demangle' which converts mangled C++
names to their unmangled versions.



7)      Example programs
        ~~~~~~~~~~~~~~~~


There are three example programs supplied with this distribution - two
versions of the classic Hello world program (C and C++), and a three part
program. The command lines for compiling these are

    gcc -v -o HelloW HelloW.c

    gcc -v -o HelloW++.cc HelloW++.cc -lc++

    gcc -v -o Example1 Example1a.c Example1b.c Example1c.c