ARM Club 3/TheARMClub_PDCD3.iso/hensa/programming/gcc/cc1plus/!gcc/docs/c++/!Readme

Text File | 1996-11-10 | 8.6 KB | 282 lines

The GNU C++ compiler
====================

Introduction
------------

This is a port of the GNU C++ compiler (version 2.7.2) for the C++
programming language to the Acorn range of ARM based machines, running
under RISC OS. As such, this package is covered by the FSF General
Public License (see the files docs.COPYING and docs.COPYINGLIB for details).

This port is © 1996 Nick Burrett

As with GNU programs, THERE IS NO WARRANTY OF ANY SORT

This compiler requires a minimum 3200Kb of free RAM for compilations.


Files
-----

This is a binary distribution only and consists of the following files:

  bin.cc1plus           The C++ compiler
  bin.g++               The C++ compiler front end
  docs.c++.!Readme    This C++ compiler introduction document

The compiler sources (about 27Mb) can be obtained from the sites listed at
the end of docs.!Intro.

Installation
------------

Before attempting to use GNU C, it should be noted that this distribution
will require the GCC front end files stored in the archive gccmain.zip.
If you do not have a copy of this, it can be retrieved from
  ftp://micros.hensa.ac.uk/micros/arch/riscos/b/b013/gccmain.zip
and relevant mirrors.

GNU C++ 2.7.2 also requires UnixLib 3.7a or later, but not UnixLib 4.0.
GNU C++ will not work with UnixLib 3.6e or earlier.


Compiling C++ source
--------------------

C++ source files can be kept in either the 'cc', 'c++' or 'cxx' directories.
Headers files are stored in the 'h' directory.

C++ comes with an extra file called g++. g++ is a front end binary for the
C++ compiler, and will automatically include the necessary run-time library
needed by C++ whenever the compilation needs it.

Typing:
    gcc -c cc.test
or  g++ -c cc.test

will compile the C++ file, test, into an AOF file and store it in the 'o'
directory.

Typing:
  gcc cc.test -o test -lg++

is equivalent to:
  g++ cc.test -o test

All GNU compilers require the library gcc:o.libgcc to operate. So separate
compile and link operations must include this.


Compiling and running the example programs
------------------------------------------

The following example programs are to be found in the directory !gcc.files.
For each program, there is a list of the necessary command lines for how
to compile, link and run the program.


hellow
^^^^^^
The standard C program.

Source:     cc.hellow
Compile using:     gcc cc.hellow -o hellow
Run using:     hellow


Dhrystone 2.1
^^^^^^^^^^^^^
This is a C++ derivative of the standard integer benchmark.
You will probably need 4000K of WimpSlot on a non-RISC PC machine to
compile this.

Source:        cc.dhrystone, h.Int, h.Char

Compile using:    gcc cc.dhrystone -o dhrystone -O2 -DQUICK

Run using:    dhrystone

When prompted for the number of iterations, use any number in the range
10000 to 200000.

There are several derivatives of this program that can be activated
by adding certain command line options to gcc:


To get standard integers and characters
compile using:    gcc cc.dhrystone -o dhrystone -DBUILTIN

To use function calls instead of inlined function calls
compile using:    gcc cc.dhrystone -o dhrystone -DCALLS

To make all class members virtual
compile using:    gcc cc.dhrystone -o dhrystone -DVIRT

To use call-by-value, not by-reference
compile using:    gcc cc.dhrystone -o dhrystone -DBYVAL

To eliminate mixed mode functions that avoid constructors
compile using:    gcc cc.dhrystone -o dhrystone -DCONVERT

To eliminate the use of named return values
compile using:    gcc cc.dhrystone -o dhrystone -DNO_NRV

To get one pointer per object padding:
compile using:    gcc cc.dhrystone -o dhrystone -DFAKEVPTR

To make =, +=, etc. return *this, not void
compile using:    gcc cc.dhrystone -o dhrystone -DRETREF


C++ Template handling
---------------------

C++ templates are the first language feature to require more intelligence
from the environment than one usually finds on a UNIX system. Somehow the
compiler and linker have to make sure that each template instance occurs
exactly once in the executable if it is needed, and not at all otherwise.

The AT&T C++ translator, Cfront, solved the template instantiation problem
by creating the notion of a template repository, an automatically maintained
place where template instances are stored.  As individual object files are
built, notes are placed in the repository to record where templates and
potential type arguments were seen so that the subsequent instantiation
step knows where to find them.  At link time, any needed instances are
generated and linked in.

G++ uses a similar mechanism to Cfront's template repository. Source code
using templates should be compiled with the extra switch '-frepo'.
Repository information will then be placed in the directory 'rpo' (provided
you have already created it).  Compiling the source code once with the
'-frepo' flag does not automatically mean that all your template problems
are cured. The source will need to be compiled again so that G++ knows (by
looking in the rpo directory) that certain template functions need compiling.
Only after the second compilation (or maybe third or fourth) should the full
code be produced.

The linker front end, ld, also supports the template repository. LD will
look through the rpo directory for files that are relevant to any object
code being linked, check the error messages produced by drlink and decide
whether a recompilation of some of the source is necessary.

Supplied is a C++ source called cc.template.  A successful compilation
will need to use the template repository features. There are two methods
to compiling this:

First ensure that the directories 'o' and 'rpo' have been created.

Method 1
^^^^^^^^

Initially compile the source, g++ will create the object file, o.template
and the repository file, rpo.template. Note that the '-c' switch must
always be used with '-frepo'.

*gcc -c cc.template -frepo

Use LD, to link the source.

*ld -o template o.template gcc:o.libgcc unix:o.unixlib

The first link stage will fail because some of the template functions have
not been instantiated. LD will read rpo.template and determine that
cc.template will need a recompilation.

On the second compilation, the C++ compiler will use the information in
rpo.template to decide which functions will need compiling.

LD will then try and re-link o.template and should complete successfully.


Method 2
^^^^^^^^

For users who do not trust the facility provided by LD, the process can
be done by hand - we simply compile each source twice:

*gcc -c cc.template -frepo
*gcc -c cc.template -frepo
*drlink -o template o.template gcc:o.libgcc unix:o.unixlib

You should notice that o.template grows between the first and second
compilations of cc.template.


However, using LD does have the additional side effect that undefined
symbols are automatically demangled before being display on screen.


C++ name demangler
------------------

To avoid link problems with overloaded functions, C++ consistently mangles
function names. However, it is not always obvious what the original name
was.

The program, 'demangle' should solve this problem. Usage is fairly simple:
   *demangle <symbol> [<symbol>...]
each symbol you wish to have demangled, you pass on the command line. For
example:

  *demangle __aml__7IntegerRC7Integer _substr__9BitStringii
returns the output:
  Integer::operator*=(Integer const &)
  BitString::_substr(int, int)

Constructors and destructors:

  *demangle _GLOBAL_.D.__rtti_get_node_type__C9type_info
returns the output:
  global destructors keyed to type_info::__rtti_get_node_type(void) const


Functions compile with Run-Time Type Identification are also properly
demangled:

  *demangle __17__class_type_infoPCcPP9type_infoPiT3PQ217__class_type_info11access_modei

returns the output:
  __class_type_info::__class_type_info(char const *, type_info **, int *,
int *, __class_type_info::access_mode *, int)


As said previously, the front end linker 'ld' also contains the demangler
software. Output from drlink or link will be presented in a demangled form.


Predefines
----------

In addition to the ones defined by the GCC front end, GNU C++ also
supplies '__GNUG__'.


Known problems
--------------

If you find a bug then please read the file docs.bugs for what to do if
you have found a bug.

Here is a list of all problems that I know of:

G++ 2.4.5 produces incompatible code with 2.7.2 and that is simply that.


Known Restrictions
------------------

Non-local gotos are not implemented for functions within functions. This is
being worked on, when I have the time.

Exception handling is not supported.


Contacting me
-------------

I can be contacted by e-mail at: [e-mail]

However, if there is no response from that address I can be contacted
through Simon Callan: [e-mail].