Go to most recent revision | Blame | Compare with Previous | Last modification | View Log | RSS feed
<!-- Crown Copyright (c) 1998 -->
<HTML>
<HEAD>
<TITLE>
C++ Producer Guide
</TITLE>
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000FF" VLINK="#400080" ALINK="#FF0000">
<H1><A NAME="top">C++ Producer Guide</A></H1>
<H3>March 1998</H3>
<A HREF="man.html"><IMG SRC="../images/next.gif" ALT="next section"></A>
<IMG SRC="../images/no_prev.gif" ALT="previous section">
<IMG SRC="../images/no_top.gif" ALT="current document">
<A HREF="../index.html"><IMG SRC="../images/home.gif" ALT="TenDRA home page">
</A>
<IMG SRC="../images/no_index.gif" ALT="document index"><P>
<HR>
<DL>
<DT><A HREF="#intro"><B>1</B> - Introduction</A><DD>
<DL>
<DT><A HREF="#update"><B>1.1</B> - Updated introduction</A><DD>
</DL>
<DT><A HREF="#interface"><B>2</B> - Interface descriptions</A><DD>
<DL>
<DT><A HREF="man.html"><B>2.1</B> - Invocation</A><DD>
<DT><A HREF="pragma.html"><B>2.2</B> - Compiler configuration</A><DD>
<DT><A HREF="token.html"><B>2.3</B> - Token syntax</A><DD>
<DT><A HREF="dump.html"><B>2.4</B> - Symbol table dump</A><DD>
<DT><A HREF="link.html"><B>2.5</B> - Intermodule analysis</A><DD>
<DT><A HREF="lib.html"><B>2.6</B> - Implementation details</A><DD>
<DT><A HREF="std.html"><B>2.7</B> - Standard library</A><DD>
</DL>
<DT><A HREF="#program"><B>3</B> - Program overview</A><DD>
<DL>
<DT><A HREF="style.html"><B>3.1</B> - Source code organisation</A><DD>
<DT><A HREF="alg.html"><B>3.2</B> - Type system</A><DD>
<DT><A HREF="error.html"><B>3.3</B> - Error database</A><DD>
<DT><A HREF="parse.html"><B>3.4</B> - Parsing C++</A><DD>
<DT><A HREF="tdf.html"><B>3.5</B> - TDF generation</A><DD>
</DL>
<DT><A HREF="#reference">References</A><DD>
<DT><A HREF="pragma1.html">Annexes</A><DD>
<DL>
<DT><A HREF="pragma1.html"><B>A</B> - <CODE>#pragma</CODE> directive
syntax</A><DD>
<DT><A HREF="dump1.html"><B>B</B> - Symbol table dump syntax</A><DD>
<DT><A HREF="error1.html"><B>C</B> - Error catalogue syntax</A><DD>
</DL>
</DL>
<HR>
<H1><A NAME="intro">1. Introduction</A></H1>
<P>
This document is designed as a technical overview of the TenDRA C++
to TDF/ANDF producer. It is divided into two broad areas; descriptions
of the <A HREF="#interface">public interfaces</A> of the producer,
and an overview of the producer <A HREF="#program">source code</A>.
</P>
<P>
Whereas the interface description contains most of the information
which would be required in a users' guide, it is not necessarily in
a readily digestible form. The C++ producer is designed to complement
the existing TenDRA C to TDF producer; although they are completely
distinct programs, the same design philosophy underlies both and they
share a number of common interfaces. There are no radical differences
between the two producers, besides the fact that the C++ producer
covers a vastly larger and more complex language. This means that
much of the <A HREF="#tdfc">existing documentation on the C producer</A>
can be taken as also applying to the C++ producer. This document tries to
make clear where the C++ producer extends the C producer's interfaces,
and those portions of these interfaces which are not directly applicable
to C++.
</P>
<P>
A familiarity with both C++ and TDF is assumed. The version of C++
implemented is that given by the <A HREF="#cplusplus">draft ISO C++
standard</A>. All references to "ISO C++" within the document
should strictly be qualified using the word "draft", but
for convenience this has been left implicit. The C++ producer has
a number of switches which allow it to be configured for older dialects
of C++. In particular, the version of C++ described in the <A HREF="#arm">ARM
(Annotated Reference Manual)</A> is fully supported.
</P>
The <A HREF="#tdf">TDF specification</A> (version 4.0) may be consulted
for a description of the compiler intermediate language used. The
paper
<A HREF="#port"><I>TDF and Portability</I></A> provides a useful (if
slightly old) introduction to some of the ideas relating to static
program analysis and interface checking which underlie the whole TenDRA
compilation system.
<P>
The warning sign:
<CENTER>
<IMG SRC="../images/warn.gif" ALT="warning">
</CENTER>
is used within the document to indicate areas where the implementation
is currently incomplete or incorrect.
</P>
<P>
<H2><A NAME="update">1.1. Updated introduction</A></H2>
<P>
Since this document was originally written, the old C producer,
<I>tdfc</I>, has been replaced by a new C producer, <I>tdfc2</I>, which
is just a modified version of the C++ producer, <I>tcpplus</I>. All
C producer documentation continues to apply to the new C producer,
but the new C producer also has many of the features described in this
document as only applying to the C++ producer.
</P>
<HR>
<H1><A NAME="interface">2. Interface descriptions</A></H1>
<P>
The most important public interfaces of the C++ producer are the ISO
C++ standard and the TDF 4.0 specification; however there are other
interfaces, mostly common to both the C and C++ producers, which are
described in this section.
</P>
<P>
An important design criterion of the C++ producer was that it should
be strictly ISO conformant by default, but have a method whereby dialect
features and extra static program analysis can be enabled. This compiler
configuration is controlled by the
<A HREF="pragma.html"><CODE>#pragma TenDRA</CODE> directives</A>
described in the first section.
</P>
<P>
The requirement that the C and C++ producers should be able to translate
portable C or C++ programs into target independent TDF requires a
mechanism whereby the target dependent implementations of APIs can
be represented. This mechanism, the <A HREF="token.html"><CODE>#pragma
token</CODE> syntax</A>, is described in the following section. Note
that at present this mechanism only contains support for C APIs; it
is considered that the C++ language itself contains sufficient interface
mechanisms for C++ APIs to be described.
</P>
<P>
The C and C++ producers provide two mechanisms whereby type and declaration
information derived from a translation unit can be stored to a file
for post-processing by other tools. The first is the
<A HREF="dump.html">symbol table dump</A>, which is a public interface
designed for use by third party tools. The second is the
<A HREF="link.html">C/C++ spec file</A>, which is designed for ease
of reading and writing by the producers themselves, and is used for
intermodule analysis.
</P>
<P>
The mapping from C++ to TDF implemented by the C++ producer is largely
straightforward. There are however target dependencies arising within
the language itself which require special handling. These are represented
by certain <A HREF="lib.html">standard tokens</A> which the producer
requires to be defined on the target machine. These tokens are also
used to describe the interface between the producer and the run-time
system. Note that the C++ producer is primarily concerned with the
C++ language, not with the standard C++ library. An example implementation
of those library components which are required as an integral part
of the language (memory allocation, exception handling, run-time type
information etc.) is provided. Otherwise, libraries should be obtained
from third parties. A number of hints on <A HREF="std.html">integrating
such libraries</A> with the C++ producer are given.
</P>
<HR>
<H1><A NAME="program">3. Program overview</A></H1>
<P>
The C++ producer is a large program (over 200000 lines, including
automatically generated code) written in C. A description of the
<A HREF="style.html#language">coding conventions</A> used, the
<A HREF="style.html#api">API</A> observed and the basic organisation
of the <A HREF="style.html#src">source code</A> are described in the
first section.
</P>
<P>
One of the design methods used in the C++ producer is the extensive
use of automatic code generation tools. The type system is based
around the <CODE>calculus</CODE> tool, which allows complex type systems
to be described in a simple format. The interface generated by <CODE>calculus
</CODE> allows for rigorous static type checking, generic type constructors
for lists, stacks etc., encapsulation of the operations on the types
within the system, and optional run-time checking for null pointers
and discriminated union tags. An overview is given of the <A HREF="alg.html">type
system</A> used as the basis of the C++ producer design. Also see
the
<A HREF="../utilities/calc.html"><CODE>calculus</CODE> users' guide</A>.
</P>
<P>
The other general purpose code generation tool used in the C++ producer
is the parser generator, <CODE>sid</CODE>. A brief description of
the problems in writing a <A HREF="parse.html">C++ parser</A> is given.
Also see the <A HREF="../utilities/sid.html"><CODE>sid</CODE> users'
guide</A>.
</P>
<P>
The other code generation tools used were written specifically for
the C++ producer. The error reporting routines within the producer
are based on an <A HREF="error.html">error catalogue</A>, from which
code for constructing and printing errors is generated. The
<A HREF="tdf.html">TDF output routines</A> are based on primitives
automatically generated from a standard database describing the TDF
specification.
</P>
<P>
The program itself is well commented, so no lower level program documentation
has been provided. When performing development work the producer
should be compiled with the <CODE>DEBUG</CODE> macro defined. This
enables the <CODE>calculus</CODE> run-time checks, along with other
assertions, and makes available the debugging routines,
<CODE>DEBUG_</CODE><I>type</I>, which can be used to print an object
from the internal type system.
</P>
<HR>
<H1><A NAME="reference">References</A></H1>
<OL>
<LI><A NAME="cplusplus"><B>Working paper for Draft Proposed Internation
Standard for Information Systems - Programming Language C++</B></A>,
X3J16/96-0225, December 1996:
<A HREF="http://www.cygnus.com/misc/wp/dec96pub/">
<CODE>http://www.cygnus.com/misc/wp/dec96pub/</CODE></A> or
<A HREF="http://www.maths.warwick.ac.uk/c++/pub/wp/html/cd2/">
<CODE>http://www.maths.warwick.ac.uk/c++/pub/wp/html/cd2/</CODE></A>.
<P>
<LI><A NAME="arm"><B>The Annotated C++ Reference Manual</B></A>,
Margaret Ellis and Bjarne Stroustrup, ISBN 0-201-51459-1, Addison-Wesley,
1990:
<A HREF="http://heg-school.aw.com/cseng/authors/ellis/annocpp/annocpp.html">
<CODE>http://heg-school.aw.com/cseng/authors/ellis/annocpp/annocpp.html</CODE>
</A>
<P>
<LI><A NAME="tdf"><B>TDF Specification, Issue 4.0</B></A>:
<A HREF="../tdf/spec1.html">attached</A>.
<P>
<LI><A NAME="tdfc"><B>C Checker Reference Manual</B></A>:
<A HREF="../tdfc/tdfc1.html">attached</A>.
<P>
<LI><A NAME="port"><B>TDF and Portability</B></A>:
<A HREF="../port/port1.html">attached</A>.
<P>
<LI><A NAME="cstyle"><B>C Coding Standards</B></A>, DRA/CIS(SE2)/WI/94/57/2.0
(OSSG internal document).
</OL>
<P>
<HR>
<P><I>Part of the <A HREF="../index.html">TenDRA Web</A>.<BR>Crown
Copyright © 1998.</I></P>
</BODY>
</HTML>