1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
|
<!-- 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>
|
