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: Invocation
</TITLE>
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000FF" VLINK="#400080" ALINK="#FF0000">
<H1>C++ Producer Guide</H1>
<H3>March 1998</H3>
<A HREF="pragma.html"><IMG SRC="../images/next.gif" ALT="next section"></A>
<A HREF="index.html"><IMG SRC="../images/prev.gif" ALT="previous section"></A>
<A HREF="index.html"><IMG SRC="../images/top.gif" ALT="current document"></A>
<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="#compile"><B>2.1.1</B> - Compilation scheme</A><DD>
<DT><A HREF="#option"><B>2.1.2</B> - Producer options</A><DD>
</DL>
<HR>
<H2>2.1. Invocation</H2>
<P>
In this section it is described how the C++ to TDF producer,
<CODE>tcpplus</CODE>, fits into the overall compilation scheme controlled
by the TenDRA compiler front-end, <CODE>tcc</CODE>, or the TenDRA
checker front-end, <CODE>tchk</CODE>. While it is possible to use
<CODE>tcpplus</CODE> as a stand-alone program, it is recommended that
it should be invoked via <CODE>tcc</CODE> or <CODE>tchk</CODE>. The
<CODE>tcc</CODE> users' guide should be consulted for more details.
</P>
<P>
<CODE>tcc</CODE> and <CODE>tchk</CODE> require the <CODE>-Yc++</CODE>
command-line option in order to enable their C++ capabilities. Files
with a <CODE>.C</CODE> suffix are recognised as C++ source files and
passed to <CODE>tcpplus</CODE> for processing (see
<A HREF="#compile">below</A>). It is possible to change the suffix
used for C++ source files; for example <CODE>-sC:cc</CODE> causes
<CODE>.cc</CODE> files to be recognised as C++ source files. An interesting
variation is <CODE>-sC:c</CODE> which causes C source files to be
processed by the C++ producer. Similarly <CODE>.I</CODE> files are
recognised as preprocessed C++ source files and <CODE>.K</CODE>
files are recognised as C++ spec files.
</P>
<P>
Most of the command-line option handling for <CODE>tcpplus</CODE>
is done by <CODE>tcc</CODE> and <CODE>tchk</CODE>, however it is possible
to pass the option <I>opt</I> directly to <CODE>tcpplus</CODE> using
the option <CODE>-Wx,</CODE><I>opt</I> to <CODE>tcc</CODE> or <CODE>tchk</CODE>.
Similarly <CODE>-Wg,</CODE><I>opt</I> and <CODE>-WS,</CODE><I>opt</I>
can be used to pass options to the C++ preprocessor and the C++ spec
linker (both of which are actually <CODE>tcpplus</CODE> invoked with
different options) respectively.
</P>
<HR>
<H3><A NAME="compile">2.1.1. Compilation scheme</A></H3>
<P>
The overall compilation scheme controlled by <CODE>tcc</CODE>, as
it relates to the C++ producer, can be represented as follows:
<CENTER>
<IMG SRC="../images/compile.gif" ALT="compilation scheme">
</CENTER>
Each C++ source file, <CODE>a.C</CODE> say, is processed using
<CODE>tcpplus</CODE> to give an output TDF capsule, <CODE>a.j</CODE>,
which is passed to the installer phase of <CODE>tcc</CODE>. The capsule
is linked with any target dependent token definition libraries, translated
to assembler and assembled to give a binary object file,
<CODE>a.o</CODE>. The various object files comprising the program
are then linked with the system libraries to give a final executable,
<CODE>a.out</CODE>.
</P>
<P>
In addition to this main compilation scheme, <CODE>tcpplus</CODE>
can additionally be made to output a <A HREF="link.html">C++ spec
file</A>
for each C++ source file, <CODE>a.K</CODE> say. These C++ spec files
can be linked, using <CODE>tcpplus</CODE> in its spec linker mode,
to give an additional TDF capsule, <CODE>x.j</CODE> say, and a combined
C++ spec file, <CODE>x.K</CODE>. The main purpose of this C++ spec
linking is to perform intermodule checks on the program, however in
the course of this checking exported templates which are defined in
one module and used in another are instantiated. This extra code
is output to <CODE>x.j</CODE>, which is then installed and linked
in the normal way.
</P>
<P>
Note that intermodule checks, and hence intermodule template instantiations,
are only performed if the <CODE>-im</CODE> option is passed to <CODE>tcc</CODE>.
</P>
<P>
The TenDRA checker, <CODE>tchk</CODE>, is similar to <CODE>tcc</CODE>
except that it disables TDF output and has intermodule analysis enabled
by default.
</P>
<HR>
<H3><A NAME="option">2.1.2. Producer options</A></H3>
<P>
The general form for the invocation of <CODE>tcpplus</CODE> is as
follows:
<PRE>
tcpplus [ <I>options</I> ] [ <I>input-file</I> ] .... [ <I>output-file</I> ]
</PRE>
The output file can alternatively be specified using the
<A HREF="#output"><CODE>-o</CODE> option</A>. If no output file is
given, or the output file is <CODE>-</CODE>, the standard output is
used. In general there can be any number of input files. If no input
file is given, or the input file is <CODE>-</CODE>, the standard input
is used.
</P>
<P>
<CODE>tcpplus</CODE> has three modes which determine the form of its
input and output files. The default mode is compilation, in which
a single input C++ source file is translated into an output TDF capsule.
In preprocessing mode, specified using the
<A HREF="#preproc"><CODE>-E</CODE> option</A>, a single input C++
source file is preprocessed into an output C++ source file. Note
that the preprocessor is built into <CODE>tcpplus</CODE>, rather than,
as with most other compilers, being a separate program. The final
mode is
<A HREF="link.html">C++ spec linking</A>, specified using the
<A HREF="#linker"><CODE>-S</CODE> option</A>. Any number of C++ spec
input files are linked and any code generated as a result (for example,
template instantiations) is written to the output TDF capsule.
</P>
<P>
In either compilation or spec linking mode, a C++ spec output file
can be generated, in addition to the TDF capsule, using the
<A HREF="#spec"><CODE>-s</CODE> option</A>. In any mode a symbol
table dump output file can generated using the <A HREF="#dump"><CODE>-d</CODE>
option</A>.
</P>
<P>
Command-line options can appear in any order and can be interspersed
with the input and output files, except following a <CODE>--</CODE>
option. All the multi-part options can be given either as one or
two command-line arguments, so that <CODE>-I</CODE><I>directory</I>
and
<CODE>-I</CODE> <I>directory</I> are equivalent. The recognised options
are as follows:
</P>
<DL>
<DT><B>-A<I>predicate</I>(<I>tokens</I>)</B>
<DD>
Asserts that the given predicate is true, that is to say:
<PRE>
#assert <I>predicate</I> ( <I>tokens</I> )
</PRE>
The special case <CODE>-A-</CODE> undefines all the built-in predicates
(of which there are none). Use of this option automatically enables
support for the <A HREF="pragma.html#ppdir"><CODE>#assert</CODE> and
<CODE>#unassert</CODE> directives</A>.
<P>
<DT><B>-D<I>macro</I></B><DD>
<DT><B>-D<I>macro</I>=<I>tokens</I></B>
<DD>
Defines the given macro to be 1 in the first case, or the given sequence
of preprocessing tokens in the second case, that is to say:
<PRE>
#define <I>macro</I> 1
#define <I>macro tokens</I>
</PRE>
respectively. In fact <CODE>-D</CODE> and <CODE>-U</CODE> options
to
<CODE>tcc</CODE> are not passed as <CODE>-D</CODE> and <CODE>-U</CODE>
options to <CODE>tcpplus</CODE>. Instead a
<A HREF="#start-up">start-up</A> file containing the equivalent
<CODE>#define</CODE> and <CODE>#undef</CODE> directives is used.
<P>
<DT><A NAME="preproc"><B>-E</B></A>
<DD>
Enables preprocessing mode in which the input C++ source file is preprocessed
into the output file.
<P>
<DT><B>-F<I>file</I></B>
<DD>
Causes a list of command-line options to be read from <I>file</I>.
Other than empty lines and lines beginning with <CODE>#</CODE>, each
line in the file is treated as if it had been specified as a separate
command-line option.
<P>
<DT><B>-H</B>
<DD>
Enables verbose inclusion mode in which warnings are printed at the
start and end of each included source file.
<P>
<DT><B>-I<I>directory</I></B>
<DD>
Adds the given directory to the list searched for included source
files. No such directories are built into the producer by default.
<P>
<DT><A NAME="directory"><B>-N<I>name</I>:<I>directory</I></B></A>
<DD>
This is identical to <CODE>-I</CODE><I>directory</I> except that it
also associates the given identifier with the directory. The directory
name can be used to specify a <A HREF="pragma.html#scope">compilation
profile</A> to be used on files included from this directory.
<P>
<DT><A NAME="linker"><B>-S</B></A>
<DD>
Enables C++ spec linker mode, in which any number of C++ spec input
files are linked together.
<P>
<DT><B>-U<I>macro</I></B>
<DD>
Undefines the given macro, that is to say:
<PRE>
#undef <I>macro</I>
</PRE>
The special case <CODE>-U-</CODE> undefines all the built-in macros.
These may be described as follows:
<PRE>
#define __FILE__ <I>(current file)</I>
#define __LINE__ <I>(current line)</I>
#define __TIME__ <I>(current time)</I>
#define __DATE__ <I>(current date)</I>
#define __STDC__ 1
#define __STDC_VERSION__ 199409L
#define __cplusplus 199711L
</PRE>
The actual value of <CODE>__cplusplus</CODE> gives the date of the
draft ISO C++ standard on which the current version of the producer
is based. The value given above gives the expected date of the final
C++ standard.
<P>
<DT><B>-V</B>
<DD>
Causes the name of each function to be printed to the standard output
as it is compiled.
<P>
<DT><B>-W<I>option</I></B>
<DD>
Sets the given <A HREF="pragma.html#low">compiler option</A> to give
a warning, that is to say:
<PRE>
#pragma TenDRA option "<I>option</I>" warning
</PRE>
The special case <CODE>-Wall</CODE> enables a wide range of warnings.
<P>
<DT><B>-X</B>
<DD>
Disables exception handling. The <A HREF="lib.html#except">current
implementation</A> can be a large run-time overhead if not required.
The effect of linking any module compiled with this option with a
module which throws an exception is undefined. This is equivalent
to <A HREF="#output"><CODE>-j-e</CODE></A>.
<P>
<DT><B>-a</B>
<DD>
Causes complete program analysis to be applied. That is to say it
is assumed that no other translation units need to be linked in order
for the program to execute.
<P>
<DT><B>-c</B>
<DD>
Disables TDF output. The output file will still be a valid TDF capsule,
but it will contain no information. This is equivalent to
<A HREF="#output"><CODE>-j-c</CODE></A>.
<P>
<DT><A NAME="dump"><B>-d<I>opt</I>=<I>dump-file</I></B></A>
<DD>
Specifies the given file as a <A HREF="dump.html">symbol table dump</A>
output file. <I>opt</I> will be a series of characters describing
the information to be dumped, as follows:
<P>
<CENTER>
<TABLE BORDER>
<TR><TH>Key</TH>
<TH>Description</TH>
<TR><TD ALIGN=CENTER><CODE>a</CODE></TD>
<TD>equivalent to <CODE>ehlmu</CODE></TD>
<TR><TD ALIGN=CENTER><CODE>c</CODE></TD>
<TD>dump string literals</TD>
<TR><TD ALIGN=CENTER><CODE>e</CODE></TD>
<TD>dump error messages</TD>
<TR><TD ALIGN=CENTER><CODE>h</CODE></TD>
<TD>dump header information</TD>
<TR><TD ALIGN=CENTER><CODE>k</CODE></TD>
<TD>dump keyword identifiers</TD>
<TR><TD ALIGN=CENTER><CODE>l</CODE></TD>
<TD>dump local variables</TD>
<TR><TD ALIGN=CENTER><CODE>m</CODE></TD>
<TD>dump macro identifiers</TD>
<TR><TD ALIGN=CENTER><CODE>s</CODE></TD>
<TD>dump scope information</TD>
<TR><TD ALIGN=CENTER><CODE>u</CODE></TD>
<TD>dump identifier usage information</TD>
</TABLE>
</CENTER>
</P>
<P>
Note that these correspond to the <CODE>tcc -sym</CODE> options.
</P>
<DT><A NAME="end-up"><B>-e<I>file</I></B></A>
<DD>
Specifies the given file as an end-up file. This is equivalent to
adding:
<PRE>
#include "<I>file</I>"
</PRE>
at the end of the input source file. More than one end-up file may
be given; they are processed in the order given.
<P>
<DT><A NAME="start-up"><B>-f<I>file</I></B></A>
<DD>
Specifies the given file as a start-up file. This is equivalent to
adding:
<PRE>
#include "<I>file</I>"
</PRE>
at the start of the input source file. More than one start-up file
may be given; they are processed in the order given.
<P>
<DT><B>-g</B>
<DD>
Specifies that the output TDF capsule should also contain information
to allow for the generation of run-time debugging directives. This
is equivalent to <A HREF="#output"><CODE>-jg</CODE></A>.
<P>
<DT><B>-h</B>
<DD>
Causes a full list of command-line options to be printed. This includes
a number not documented here which are unlikely to prove useful to
the normal user.
<P>
<DT><A NAME="output"><B>-j<I>opt</I></B></A>
<DD>
Sets the TDF output options given by <I>opt</I>. This consists of
a sequence of characters describing the options to be enabled or disabled.
By default, or following a <CODE>+</CODE>, the options are enabled;
following a <CODE>-</CODE> they are disabled. The available options
are as follows:
<P>
<CENTER>
<TABLE BORDER>
<TR><TH>Key</TH>
<TH>Default</TH>
<TH>Description</TH>
<TR><TD ALIGN=CENTER><CODE>a</CODE></TD>
<TD ALIGN=CENTER>off</TD>
<TD>output external names for local objects</TD>
<TR><TD ALIGN=CENTER><CODE>b</CODE></TD>
<TD ALIGN=CENTER>off</TD>
<TD>work round old installer bugs</TD>
<TR><TD ALIGN=CENTER><CODE>c</CODE></TD>
<TD ALIGN=CENTER>on</TD>
<TD>output TDF capsule</TD>
<TR><TD ALIGN=CENTER><CODE>d</CODE></TD>
<TD ALIGN=CENTER>off</TD>
<TD>output termination function</TD>
<TR><TD ALIGN=CENTER><CODE>e</CODE></TD>
<TD ALIGN=CENTER>on</TD>
<TD>output exceptions</TD>
<TR><TD ALIGN=CENTER><CODE>f</CODE></TD>
<TD ALIGN=CENTER>on</TD>
<TD>mangle template function signatures</TD>
<TR><TD ALIGN=CENTER><CODE>g</CODE></TD>
<TD ALIGN=CENTER>off</TD>
<TD>output debugging information</TD>
<TR><TD ALIGN=CENTER><CODE>i</CODE></TD>
<TD ALIGN=CENTER>off</TD>
<TD>output dynamic initialisers as a function</TD>
<TR><TD ALIGN=CENTER><CODE>n</CODE></TD>
<TD ALIGN=CENTER>on</TD>
<TD>mangle object names</TD>
<TR><TD ALIGN=CENTER><CODE>o</CODE></TD>
<TD ALIGN=CENTER>off</TD>
<TD>order class data members by access</TD>
<TR><TD ALIGN=CENTER><CODE>p</CODE></TD>
<TD ALIGN=CENTER>on</TD>
<TD>output partial destructors</TD>
<TR><TD ALIGN=CENTER><CODE>r</CODE></TD>
<TD ALIGN=CENTER>on</TD>
<TD>output run-time type information</TD>
<TR><TD ALIGN=CENTER><CODE>s</CODE></TD>
<TD ALIGN=CENTER>on</TD>
<TD>output shared string literals</TD>
<TR><TD ALIGN=CENTER><CODE>t</CODE></TD>
<TD ALIGN=CENTER>off</TD>
<TD>output token declarations</TD>
<TR><TD ALIGN=CENTER><CODE>u</CODE></TD>
<TD ALIGN=CENTER>on</TD>
<TD>output unused static variables</TD>
<TR><TD ALIGN=CENTER><CODE>v</CODE></TD>
<TD ALIGN=CENTER>off</TD>
<TD>output local virtual function tables</TD>
</TABLE>
</CENTER>
</P>
<DT><A NAME="error"><B>-m<I>opt</I></B></A>
<DD>
Sets the error formatting options given by <I>opt</I>. This consists
of a sequence of characters describing the options to be enabled or
disabled. By default, or following a <CODE>+</CODE>, the options are
enabled; following a <CODE>-</CODE> they are disabled. The available
options are as follows:
<P>
<CENTER>
<TABLE BORDER>
<TR><TH>Key</TH>
<TH>Default</TH>
<TH>Description</TH>
<TR><TD ALIGN=CENTER><CODE>c</CODE></TD>
<TD ALIGN=CENTER>off</TD>
<TD>show source code with error</TD>
<TR><TD ALIGN=CENTER><CODE>e</CODE></TD>
<TD ALIGN=CENTER>off</TD>
<TD>show error name</TD>
<TR><TD ALIGN=CENTER><CODE>f</CODE></TD>
<TD ALIGN=CENTER>on</TD>
<TD>reliable <CODE>fseek</CODE> function</TD>
<TR><TD ALIGN=CENTER><CODE>g</CODE></TD>
<TD ALIGN=CENTER>off</TD>
<TD>record statement locations</TD>
<TR><TD ALIGN=CENTER><CODE>i</CODE></TD>
<TD ALIGN=CENTER>on</TD>
<TD>reliable <CODE>stat</CODE> function</TD>
<TR><TD ALIGN=CENTER><CODE>k</CODE></TD>
<TD ALIGN=CENTER>off</TD>
<TD>enable C++ spec output</TD>
<TR><TD ALIGN=CENTER><CODE>l</CODE></TD>
<TD ALIGN=CENTER>off</TD>
<TD>output full error location</TD>
<TR><TD ALIGN=CENTER><CODE>s</CODE></TD>
<TD ALIGN=CENTER>on</TD>
<TD>output ISO section number</TD>
<TR><TD ALIGN=CENTER><CODE>t</CODE></TD>
<TD ALIGN=CENTER>off</TD>
<TD>use <CODE>typedef</CODE> names in errors</TD>
<TR><TD ALIGN=CENTER><CODE>w</CODE></TD>
<TD ALIGN=CENTER>off</TD>
<TD>disable warnings</TD>
<TR><TD ALIGN=CENTER><CODE>z</CODE></TD>
<TD ALIGN=CENTER>off</TD>
<TD>continue after error</TD>
</TABLE>
</CENTER>
</P>
<DT><A NAME="table"><B>-n<I>port-table</I></B></A>
<DD>
Specifies that the given <A HREF="pragma.html#table">portability table</A>
should be used to specify the basic configuration parameters.
<P>
<DT><A NAME="output"><B>-o<I>output-file</I></B></A>
<DD>
Gives an alternative method of specifying the output file.
<P>
<DT><B>-q</B>
<DD>
Causes the program to quit immediately without processing its input
files. This is useful primarily in version and command-line option
queries.
<P>
<DT><A NAME="spec"><B>-s<I>spec-file</I></B></A>
<DD>
Specifies the given file as a C++ spec output file.
<P>
<DT><B>-t</B>
<DD>
Specifies that token declarations should be included in the output
TDF capsule. While these are strictly unnecessary, they help when
pretty-printing the output. This is equivalent to
<A HREF="#output"><CODE>-jt</CODE></A>.
<P>
<DT><A NAME="unmangle"><B>-u</B></A>
<DD>
The form:
<PRE>
tcpplus -u <I>name</I> .... <I>name</I>
</PRE>
can be used to print the unmangled forms of a list of
<A HREF="lib.html#mangle">mangled identifier names</A> to the standard
output.
<P>
<DT><B>-v</B>
<DD>
Causes the C++ producer version number, plus information on the versions
of C++ and TDF supported, to be printed to the standard error.
<P>
<DT><B>-w</B>
<DD>
Disables all warning messages. This is equivalent to
<A HREF="#error"><CODE>-mw</CODE></A>.
<P>
<DT><B>-z</B>
<DD>
Forces an output file to be created even if compilation errors occur.
The effect of installing a TDF capsule produced using this option
is undefined. This is equivalent to <A HREF="#error"><CODE>-mz</CODE></A>.
<P>
<DT><B>--</B>
<DD>
Marks the last option. Any subsequent arguments are interpreted as
input and output files even if they resemble command-line options.
<P>
</DL>
<HR>
<P><I>Part of the <A HREF="../index.html">TenDRA Web</A>.<BR>Crown
Copyright © 1998.</I></P>
</BODY>
</HTML>