| 2 |
7u83 |
1 |
<!-- Crown Copyright (c) 1998 -->
|
|
|
2 |
<HTML>
|
|
|
3 |
<HEAD>
|
|
|
4 |
<TITLE>tcc User's Guide: The Component of the TDF System</TITLE>
|
|
|
5 |
</HEAD>
|
|
|
6 |
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000FF" VLINK="#400080" ALINK="#FF0000">
|
|
|
7 |
<A NAME=S20>
|
|
|
8 |
<H1>tcc User's Guide</H1>
|
|
|
9 |
<H3>January 1998</H3>
|
|
|
10 |
<A HREF="tcc7.html"><IMG SRC="../images/next.gif" ALT="next section"></A>
|
|
|
11 |
<A HREF="tcc5.html"><IMG SRC="../images/prev.gif" ALT="previous section"></A>
|
|
|
12 |
<A HREF="tcc1.html"><IMG SRC="../images/top.gif" ALT="current document"></A>
|
|
|
13 |
<A HREF="../index.html"><IMG SRC="../images/home.gif" ALT="TenDRA home page">
|
|
|
14 |
</A>
|
|
|
15 |
<IMG SRC="../images/no_index.gif" ALT="document index"><P>
|
|
|
16 |
<HR>
|
|
|
17 |
<DL>
|
|
|
18 |
<DT><A HREF="#S21"><B>5.1</B> - The C to TDF Producer</A><DD>
|
|
|
19 |
<DL>
|
|
|
20 |
<DT><A HREF="#S22"><B>5.1.1</B> - Include File Directories</A><DD>
|
|
|
21 |
<DT><A HREF="#S23"><B>5.1.2</B> - Start-up Files and End-up Files</A><DD>
|
|
|
22 |
<DT><A HREF="#S24"><B>5.1.3</B> - Compilation Modes and Portability
|
|
|
23 |
Tables</A><DD>
|
|
|
24 |
<DT><A HREF="#S25"><B>5.1.4</B> - Description of Compilation Modes</A><DD>
|
|
|
25 |
</DL>
|
|
|
26 |
<DT><A HREF="#S26"><B>5.2</B> - The TDF Linker</A><DD>
|
|
|
27 |
<DL>
|
|
|
28 |
<DT><A HREF="#S27"><B>5.2.1</B> - The Linker and TDF Libraries</A><DD>
|
|
|
29 |
<DT><A HREF="#S28"><B>5.2.2</B> - Combining TDF Capsules</A><DD>
|
|
|
30 |
<DT><A HREF="#S29"><B>5.2.3</B> - Constructing TDF Libraries</A><DD>
|
|
|
31 |
<DT><A HREF="#S30"><B>5.2.4</B> - Useful tld Options</A><DD>
|
|
|
32 |
</DL>
|
|
|
33 |
<DT><A HREF="#S31"><B>5.3</B> - The TDF to Target Translator</A><DD>
|
|
|
34 |
<DL>
|
|
|
35 |
<DT><A HREF="#S32"><B>5.3.1</B> - tcc Options Affecting the Translator</A><DD>
|
|
|
36 |
<DT><A HREF="#S33"><B>5.3.2</B> - Useful trans Options</A><DD>
|
|
|
37 |
<DT><A HREF="#S34"><B>5.3.3</B> - Optimisation in TDF Translators</A><DD>
|
|
|
38 |
<DT><A HREF="#S35"><B>5.3.4</B> - The Mips Translator and Assembler</A><DD>
|
|
|
39 |
</DL>
|
|
|
40 |
<DT><A HREF="#S36"><B>5.4</B> - The System Assembler</A><DD>
|
|
|
41 |
<DT><A HREF="#S37"><B>5.5</B> - The System Linker</A><DD>
|
|
|
42 |
<DL>
|
|
|
43 |
<DT><A HREF="#S38"><B>5.5.1</B> - The System Linker and tcc Environments</A><DD>
|
|
|
44 |
<DT><A HREF="#S39"><B>5.5.2</B> - The Effect of Command-Line Options
|
|
|
45 |
on the System Linker</A><DD>
|
|
|
46 |
</DL>
|
|
|
47 |
<DT><A HREF="#S40"><B>5.6</B> - The C Preprocessor</A><DD>
|
|
|
48 |
<DT><A HREF="#S41"><B>5.7</B> - The TDF Pretty Printer</A><DD>
|
|
|
49 |
<DT><A HREF="#S42"><B>5.8</B> - The TDF Archiver</A><DD>
|
|
|
50 |
</DL>
|
|
|
51 |
|
|
|
52 |
<HR>
|
|
|
53 |
<H1>5. The Components of the TDF System</H1>
|
|
|
54 |
<A NAME=S21>
|
|
|
55 |
<HR><H2>5.1. The C to TDF Producer</H2>
|
|
|
56 |
We now turn to the individual components of the TDF system. Most of
|
|
|
57 |
the command-line options to <CODE>tcc</CODE> so far discussed have
|
|
|
58 |
been concerned with controlling the behaviour of <CODE>tcc</CODE>
|
|
|
59 |
itself. Another, even more important, class of options concern the
|
|
|
60 |
ways in which the behaviour of the components can be specified. The
|
|
|
61 |
<B>-W</B><I>tool</I><B>, </B><I>opt</I><B>,</B> ... command-line option
|
|
|
62 |
for communicating directly with the components has already been mentioned.
|
|
|
63 |
This however is not recommended for normal purposes; the other <CODE>tcc</CODE>
|
|
|
64 |
command-line options give a more controlled access to the components.<P>
|
|
|
65 |
The first component to be considered is the C --> TDF producer,
|
|
|
66 |
<CODE>tdfc</CODE>. This translates an input C source file (a <CODE>.c</CODE>
|
|
|
67 |
file or a <CODE>.i</CODE> file) into a output target independent TDF
|
|
|
68 |
capsule (a <CODE>.j</CODE> file).<P>
|
|
|
69 |
<A NAME=S22>
|
|
|
70 |
<H3>5.1.1. Include File Directories</H3>
|
|
|
71 |
The most important producer options are those which tell it where
|
|
|
72 |
to search for files included using a <CODE>#include</CODE> preprocessing
|
|
|
73 |
directive. As with <CODE>cc</CODE>, the user can specify a directory,
|
|
|
74 |
<I>dir</I>, to search for these files using the <B>-I</B><I>dir</I>
|
|
|
75 |
command-line option. However, unlike <CODE>cc</CODE>, the producer
|
|
|
76 |
does not search <CODE>/usr/include</CODE> as default. Instead, the
|
|
|
77 |
default search directories are those containing the target independent
|
|
|
78 |
headers for the API selected, as given by the <CODE>INCL</CODE> identifier
|
|
|
79 |
in the environment describing the API. In addition, the directories
|
|
|
80 |
to search for the default start-up files (see below), as given by
|
|
|
81 |
the <CODE>STARTUP_DIR</CODE> environmental identifier, are also passed
|
|
|
82 |
to the producer.<P>
|
|
|
83 |
If the <B>-H</B> option is passed to <CODE>tcc</CODE> then it will
|
|
|
84 |
cause the producer to print the name of each file it opens. This is
|
|
|
85 |
often helpful if a multiplicity of <B>-I</B> options leads to confusion.<P>
|
|
|
86 |
<A NAME=S23>
|
|
|
87 |
<H3>5.1.2. Start-up Files and End-up Files</H3>
|
|
|
88 |
The producer has a useful feature of start-up and end-up files. The
|
|
|
89 |
<CODE>tcc</CODE> command-line option <B>-f</B><I>file</I> is equivalent
|
|
|
90 |
to inserting the line:<P>
|
|
|
91 |
<PRE>
|
|
|
92 |
#include "file"
|
|
|
93 |
</PRE>
|
|
|
94 |
at the start of each input C source file. Similarly <B>-e</B><I>file</I>
|
|
|
95 |
is equivalent to inserting this line at the end of each such file.
|
|
|
96 |
These included files are searched for along the directories specified
|
|
|
97 |
by the <B>-I</B> options in the normal manner.<P>
|
|
|
98 |
<CODE>tcc</CODE> generates a producer start-up file, called <CODE>tcc_startup.h
|
|
|
99 |
</CODE>, in order to implement certain command-line options. The <CODE>cc</CODE>-compatible
|
|
|
100 |
options:<P>
|
|
|
101 |
<PRE>
|
|
|
102 |
<B>-D</B><I>name
|
|
|
103 |
</I><B>-D</B><I>name</I><B>=</B><I>value
|
|
|
104 |
</I><B>-U</B><I>name
|
|
|
105 |
</I><B>-A</B><I>str</I>
|
|
|
106 |
</PRE>
|
|
|
107 |
are translated into the lines:<P>
|
|
|
108 |
<PRE>
|
|
|
109 |
#define name 1
|
|
|
110 |
#define name value
|
|
|
111 |
#undef name
|
|
|
112 |
#assert str
|
|
|
113 |
</PRE>
|
|
|
114 |
respectively. <CODE>tcc</CODE> does not check that these lines are
|
|
|
115 |
valid C preprocessing directives since this will be done by the producer.
|
|
|
116 |
So any producer error message referring to <CODE>tcc_startup.h</CODE>
|
|
|
117 |
is likely actually to refer to the <B>-D</B>, <B>-U</B> and <B>-A</B>
|
|
|
118 |
command-line options. In case of difficulties, <CODE>tcc_startup.h</CODE>
|
|
|
119 |
can be preserved for closer examination using the <B>-Ph</B> option
|
|
|
120 |
to <CODE>tcc</CODE>.<P>
|
|
|
121 |
There may be default start-up options specified by the <CODE>STARTUP</CODE>
|
|
|
122 |
environmental identifier. The purpose of these is discussed below.
|
|
|
123 |
The order the start-up options are passed to the producer is: firstly,
|
|
|
124 |
the default start-up options; secondly, the start-up option for the
|
|
|
125 |
<CODE>tcc</CODE> built-in start-up file, <CODE>tcc_startup.h</CODE>;
|
|
|
126 |
thirdly, any command-line start-up options. (For technical reasons,
|
|
|
127 |
a <B>-no_startup_options</B> command-line option is provided which
|
|
|
128 |
causes no start-up or end-up options to be passed to <CODE>tdfc</CODE>.
|
|
|
129 |
This is not likely to prove useful in normal use.<P>
|
|
|
130 |
<A NAME=S24>
|
|
|
131 |
<H3>5.1.3. Compilation Modes and Portability Tables</H3>
|
|
|
132 |
We have already described how one aspect of the compilation environment,
|
|
|
133 |
the API, is specified to the producer by means of the default <B>-I</B>
|
|
|
134 |
options. But another aspect, the control of the syntax and portability
|
|
|
135 |
checks applied by the producer, can also be specified in a fairly
|
|
|
136 |
precise manner.<P>
|
|
|
137 |
The producer accepts a number of <CODE>#pragma</CODE> statements which
|
|
|
138 |
tell it which portability checks to apply and which syntactic extensions
|
|
|
139 |
to ISO/ANSI C to allow (see [3] and [2]). These can be inserted into
|
|
|
140 |
the main C source, but the ideal place for them is in a start-up file.
|
|
|
141 |
This is the purpose of the <CODE>STARTUP</CODE> environmental identifier,
|
|
|
142 |
to give a list of default start-up files containing <CODE>#pragma</CODE>
|
|
|
143 |
statements which specify the default behaviour of the producer.<P>
|
|
|
144 |
In fact not all the information the producer requires is obtained
|
|
|
145 |
through start-up files. The basic information on the minimum sizes
|
|
|
146 |
which can be assumed for the basic integer types is passed to the
|
|
|
147 |
producer by means of another type of file, the portability table.
|
|
|
148 |
This is specified by means of the <CODE>PORTABILITY</CODE> environmental
|
|
|
149 |
identifier. There are in fact only two portability tables provided,
|
|
|
150 |
<CODE>Ansi_Max.pf</CODE>, which specifies the minimum sizes permitted
|
|
|
151 |
by the ISO/ANSI standard, and <CODE>Common.pf</CODE>, which specifies
|
|
|
152 |
the minimum sizes found on most 32-bits machines. The main difference
|
|
|
153 |
between the two is that in ISO/ANSI it is stated that <CODE>int</CODE>
|
|
|
154 |
is only guaranteed to have 16 bits, whereas on 32-bits machines it
|
|
|
155 |
has at least 32 bits.<P>
|
|
|
156 |
A number of <CODE>tcc</CODE> command-line options are concerned with
|
|
|
157 |
specifying the compilation environment to the producer. The main option
|
|
|
158 |
for setting the compilation mode is <B>-X</B><I>mode</I>. A number
|
|
|
159 |
of different modes are available:<P>
|
|
|
160 |
<UL>
|
|
|
161 |
<LI><B>-Xs</B> specifies strict ISO/ANSI C with extra portability
|
|
|
162 |
checks,<P>
|
|
|
163 |
<LI><B>-Xp</B> specifies strict ISO/ANSI C with minimal portability
|
|
|
164 |
checks,<P>
|
|
|
165 |
<LI><B>-Xc</B> specifies strict ISO/ANSI C with no extra portability
|
|
|
166 |
checks,<P>
|
|
|
167 |
<LI><B>-Xa</B> specifies ISO/ANSI C with various syntactic extensions,<P>
|
|
|
168 |
<LI><B>-Xt</B> specifies "traditional" C.<P>
|
|
|
169 |
</UL>
|
|
|
170 |
The default is <B>-Xc</B>. For a precise description of each of these
|
|
|
171 |
modes, see [3] (<CODE>tchk</CODE> is just <CODE>tcc</CODE> in disguise).
|
|
|
172 |
In addition the command-line options <B>-not_ansi</B> and <B>-nepc</B>
|
|
|
173 |
can be used to modify the basic compilation modes. <B>-not_ansi</B>
|
|
|
174 |
specifies that certain non-ANSI syntactic constructions should be
|
|
|
175 |
allowed. <B>-nepc</B> switches off the producer's extra portability
|
|
|
176 |
checks (it also suppresses certain constant overflow checks in the
|
|
|
177 |
TDF translators). All these options are implemented by start-up files.<P>
|
|
|
178 |
The portability table to be used is specified separately by means
|
|
|
179 |
of an environment. The default is the ISO/ANSI portability table,
|
|
|
180 |
but <B>-Y32bit</B> or <B>-Ycommon</B> can be used to specify 32-bit
|
|
|
181 |
checking. <B>-Y16bit</B> will restore the portability table to the
|
|
|
182 |
default. Note that all checks involving the portability table are
|
|
|
183 |
switched off by the <B>-nepc</B> command-line option, so in this case
|
|
|
184 |
no portability table is specified to the producer.<P>
|
|
|
185 |
<A NAME=S25>
|
|
|
186 |
<H3>5.1.4. Description of Compilation Modes</H3>
|
|
|
187 |
Let us briefly describe the compilation modes introduced in the previous
|
|
|
188 |
section. The following tables describe some of the main features of
|
|
|
189 |
each mode. The list of pre-defined macros is complete (other than
|
|
|
190 |
the built-in macros, <CODE>__FILE__</CODE>, <CODE>__LINE__</CODE>,
|
|
|
191 |
<CODE>__DATE__</CODE> and <CODE>__TIME__</CODE>; because the producer
|
|
|
192 |
is designed to be target independent it does not define any of the
|
|
|
193 |
machine name macros which are built into <CODE>cc</CODE>. The <CODE>cc</CODE>-compatible
|
|
|
194 |
option, <B>-A-</B>, which is meant to cause all pre-defined macros
|
|
|
195 |
(other than those beginning with <CODE>__</CODE>) to be undefined,
|
|
|
196 |
and all pre-assertions to be unasserted, is ignored by <CODE>tcc</CODE>.
|
|
|
197 |
In the standard compilation modes there are no such macros and no
|
|
|
198 |
such assertions. The integer promotion rules are either the arithmetic
|
|
|
199 |
rules specified by ISO/ANSI or the "traditional" signed
|
|
|
200 |
promotion rules. The precise set of syntactic relaxations to the ISO/ANSI
|
|
|
201 |
standard allowed by each mode varies. For a complete list see [3].
|
|
|
202 |
The <B>-not_ansi</B> command-line option can be used to allow further
|
|
|
203 |
relaxations. The extra prototype checks cause the producer to construct
|
|
|
204 |
a prototype for procedures which are actually traditionally defined.
|
|
|
205 |
This is very useful for getting prototype-like checking without having
|
|
|
206 |
to use prototypes in function definitions. This, and other portability
|
|
|
207 |
checks, are switched off by the <B>-nepc</B> option. Finally, the
|
|
|
208 |
additional checks are <CODE>lint</CODE>-like checks which are useful
|
|
|
209 |
in detecting possible portability problems.<P>
|
|
|
210 |
<PRE>
|
|
|
211 |
compilation mode: <B>-Xs
|
|
|
212 |
</B>description: strict ISO/ANSI with additional checks
|
|
|
213 |
pre-defined macros: __STDC__ = 1, __ANDF__ = 1, __TenDRA__ = 1
|
|
|
214 |
integer promotions: ISO/ANSI
|
|
|
215 |
syntactic relaxations: no
|
|
|
216 |
extra prototype checks: yes
|
|
|
217 |
additional checks: yes
|
|
|
218 |
|
|
|
219 |
compilation mode: <B>-Xp
|
|
|
220 |
</B>description: strict ISO/ANSI with minimal extra checks
|
|
|
221 |
pre-defined macros: __STDC__ = 1, __ANDF__ = 1, __TenDRA__ = 1
|
|
|
222 |
integer promotions: ISO/ANSI
|
|
|
223 |
syntactic relaxations: no
|
|
|
224 |
extra prototype checks: yes
|
|
|
225 |
additional checks: some
|
|
|
226 |
|
|
|
227 |
compilation mode: <B>-Xc
|
|
|
228 |
</B>description: strict ISO/ANSI with no extra checks
|
|
|
229 |
pre-defined macros: __STDC__ = 1, __ANDF__ = 1, __TenDRA__ = 1
|
|
|
230 |
integer promotions: ISO/ANSI
|
|
|
231 |
syntactic relaxations: no
|
|
|
232 |
extra prototype checks: no
|
|
|
233 |
additional checks: no
|
|
|
234 |
|
|
|
235 |
compilation mode: <B>-Xa</B> (default)
|
|
|
236 |
description: lenient ISO/ANSI with no extra checks
|
|
|
237 |
pre-defined macros: __STDC__ = 1, __ANDF__ = 1, __TenDRA__ = 1
|
|
|
238 |
integer promotions: ISO/ANSI
|
|
|
239 |
syntactic relaxations: yes
|
|
|
240 |
extra prototype checks: no
|
|
|
241 |
additional checks: no
|
|
|
242 |
|
|
|
243 |
compilation mode: <B>-Xt
|
|
|
244 |
</B>description: traditional C
|
|
|
245 |
pre-defined macros: __STDC__ = 0, __ANDF__ = 1, __TenDRA__ = 1
|
|
|
246 |
integer promotions: signed
|
|
|
247 |
syntactic relaxations: yes
|
|
|
248 |
extra prototype checks: no
|
|
|
249 |
additional checks: no
|
|
|
250 |
</PRE>
|
|
|
251 |
The choice of compilation mode very much depends on the level of checking
|
|
|
252 |
required. <B>-Xa</B> is suitable for general compilation, and <B>-Xc</B>.
|
|
|
253 |
<B>-Xp</B> and <B>-Xs</B> for serious program checking (although some
|
|
|
254 |
may find the latter <CODE>Xs</CODE>-ive). <B>-Xt</B> is provided for
|
|
|
255 |
<CODE>cc</CODE> compatibility only; its use is discouraged.<P>
|
|
|
256 |
The recommended method of proceeding is to define your own compilation
|
|
|
257 |
mode. In this way any choices about syntax and portability checking
|
|
|
258 |
are made into conscious decisions. One still needs to select a basic
|
|
|
259 |
mode to form the basis for this user-defined mode. <B>-Xc</B> is probably
|
|
|
260 |
best; it is a well-defined mode (the definition being the ISO/ANSI
|
|
|
261 |
standard) and so forms a suitable baseline. Suppose that, on examining
|
|
|
262 |
the program to be compiled, we decide that we need to do the following:<P>
|
|
|
263 |
<UL>
|
|
|
264 |
<LI>allow the <CODE>#ident</CODE> directive,<P>
|
|
|
265 |
<LI>allow through unknown escape sequences with a warning,<P>
|
|
|
266 |
<LI>warn of uses of undeclared procedures,<P>
|
|
|
267 |
<LI>warn of incorrect uses of simple <CODE>return</CODE> statements.<P>
|
|
|
268 |
</UL>
|
|
|
269 |
The first two of these are syntactic in nature. The third is more
|
|
|
270 |
interesting. ISO/ANSI says that any undeclared procedures are assumed
|
|
|
271 |
to return <CODE>int</CODE>. However for strict API checking we really
|
|
|
272 |
need to know about these undeclared procedures, because they may be
|
|
|
273 |
library routines which are not part of the declared API. The fourth
|
|
|
274 |
condition is a simple <CODE>lint</CODE>-like check that no procedure
|
|
|
275 |
which is declared to return a value contains a simple <CODE>return</CODE>
|
|
|
276 |
statement (without a return value).<P>
|
|
|
277 |
To tell the producer about these options, it is necessary to have
|
|
|
278 |
them included in every source file. The easiest way of doing this
|
|
|
279 |
is by using a start-up file, <CODE>check.h</CODE> say, containing
|
|
|
280 |
the lines:<P>
|
|
|
281 |
<PRE>
|
|
|
282 |
#pragma TenDRA begin
|
|
|
283 |
#pragma TenDRA directive ident allow
|
|
|
284 |
#pragma TenDRA unknown escape warning
|
|
|
285 |
#pragma TenDRA implicit function declaration warning
|
|
|
286 |
#pragma TenDRA incompatible void return warning
|
|
|
287 |
</PRE>
|
|
|
288 |
The second, third, fourth and fifth lines correspond to the statements
|
|
|
289 |
above (see [3]). The first line indicates that this file is defining
|
|
|
290 |
a new checking scope.<P>
|
|
|
291 |
Once the compilation mode has been described in this way, it needs
|
|
|
292 |
to be specified to <CODE>tcc</CODE> in the form of the command-line
|
|
|
293 |
options <B>-Xc</B> <B>-f</B><CODE>check.h</CODE>.<P>
|
|
|
294 |
<A NAME=S26>
|
|
|
295 |
<HR><H2>5.2. The TDF Linker</H2>
|
|
|
296 |
The next component of the system to be considered is the TDF linker,
|
|
|
297 |
<CODE>tld</CODE>. This is used to combine several TDF capsules or
|
|
|
298 |
TDF libraries into a single TDF capsule. It is put to two distinct
|
|
|
299 |
purposes in the <CODE>tcc</CODE> compilation scheme. Firstly, in the
|
|
|
300 |
main compilation path, it is used in the installer half to combine
|
|
|
301 |
a target independent TDF capsule (a <CODE>.j</CODE> file) with the
|
|
|
302 |
TDF libraries representing the API implementation on the target machine,
|
|
|
303 |
to form a target dependent TDF capsule (a <CODE>.t</CODE> file). Secondly,
|
|
|
304 |
if the <B>-M</B> option is given to <CODE>tcc</CODE>, it is used in
|
|
|
305 |
the producer half to combine all the target independent TDF capsules
|
|
|
306 |
(<CODE>.j</CODE> files) into a single target independent capsule.
|
|
|
307 |
Let us consider these two cases separately.<P>
|
|
|
308 |
<A NAME=S27>
|
|
|
309 |
<H3>5.2.1. The Linker and TDF Libraries</H3>
|
|
|
310 |
In the main TDF linking phase, combining target independent capsules
|
|
|
311 |
with TDF libraries to form target dependent capsules, two pieces of
|
|
|
312 |
information need to be specified to <CODE>tld</CODE>. Firstly, the
|
|
|
313 |
TDF libraries to be linked with, and, secondly, the directories to
|
|
|
314 |
search for these libraries. For standard APIs, the location of the
|
|
|
315 |
TDF libraries describing the API implementation is given in the environment
|
|
|
316 |
corresponding to the API. The <CODE>LIB</CODE> identifier gives the
|
|
|
317 |
names of the TDF libraries, and the <CODE>LINK</CODE> identifier the
|
|
|
318 |
directories to be searched for these libraries. The user can also
|
|
|
319 |
specify libraries and library directories by means of command-line
|
|
|
320 |
options to <CODE>tcc</CODE>. The option <B>-j</B><I>str</I> indicates
|
|
|
321 |
that the TDF library <I>str</I><CODE>.tl</CODE> should be used for
|
|
|
322 |
linking (<CODE>.tl</CODE> is the standard suffix for TDF libraries).
|
|
|
323 |
The option <B>-J</B><I>dir</I> indicates that the directory <I>dir</I>
|
|
|
324 |
should be added to the TDF library search path. Libraries and directories
|
|
|
325 |
specified by command-line options are searched before those given
|
|
|
326 |
in the API environment.<P>
|
|
|
327 |
There is a potential source of confusion in that the <CODE>tld</CODE>
|
|
|
328 |
options specifying the TDF library <I>str</I><CODE>.tl</CODE> and
|
|
|
329 |
the library directory <I>dir</I> are respectively <B>-l</B><I>str</I>
|
|
|
330 |
and <B>-L</B><I>dir</I>. <CODE>tcc</CODE> automatically translates
|
|
|
331 |
command-line <B>-j</B> options into <CODE>tld</CODE> <B>-l</B> options,
|
|
|
332 |
and command-line <B>-J</B> options into <CODE>tld</CODE> <B>-L</B>
|
|
|
333 |
options. However the <CODE>LIB</CODE> and <CODE>LINK</CODE> identifiers
|
|
|
334 |
are actually lists of <CODE>tld</CODE> options, so they should use
|
|
|
335 |
the <B>-l</B> and <B>-L</B> forms.<P>
|
|
|
336 |
<A NAME=S28>
|
|
|
337 |
<H3>5.2.2. Combining TDF Capsules</H3>
|
|
|
338 |
The second use of <CODE>tld</CODE> is to combine all the <CODE>.j</CODE>
|
|
|
339 |
files in the producer half of the compilation into a single capsule.
|
|
|
340 |
This is specified by means of the <B>-M</B> ("merge") command-line
|
|
|
341 |
option to <CODE>tcc</CODE> described in section 3.5.4</A>. By default,
|
|
|
342 |
the resultant capsule is called <CODE>a.j</CODE>. If the <B>-M</B>
|
|
|
343 |
option is used to merge all the <CODE>.j</CODE> files from a very
|
|
|
344 |
large program, the resultant TDF capsule can in turn be very large.
|
|
|
345 |
It may in fact become too large for the installer to handle. Interesting
|
|
|
346 |
it is often the system assembler rather than TDF translator which
|
|
|
347 |
has problems.<P>
|
|
|
348 |
The <B>-MA</B> ("merge all") option is similar to <B>-M</B>,
|
|
|
349 |
but will in addition "hide" all the external tag and token
|
|
|
350 |
names in the resultant capsule, except for the token names required
|
|
|
351 |
for linking with the TDF libraries and the tag names required for
|
|
|
352 |
linking with the system libraries (plus <CODE>main</CODE>). In effect,
|
|
|
353 |
all the names which are internal to the program are removed. This
|
|
|
354 |
means that the <B>-MA</B> option should only be used to merge complete
|
|
|
355 |
programs. For details on how to use <CODE>tld</CODE> for more selective
|
|
|
356 |
name hiding, see below.<P>
|
|
|
357 |
<A NAME=S29>
|
|
|
358 |
<H3>5.2.3. Constructing TDF Libraries</H3>
|
|
|
359 |
There is a final use of the TDF linker supported by <CODE>tcc</CODE>
|
|
|
360 |
which has not so far been mentioned, namely the construction of TDF
|
|
|
361 |
libraries. As has been mentioned, TDF libraries are an indexed set
|
|
|
362 |
of TDF capsules. <CODE>tld</CODE>, in addition to its linking mode,
|
|
|
363 |
also has routines for constructing and manipulating TDF libraries.
|
|
|
364 |
The library construction mode is supported by <CODE>tcc</CODE> by
|
|
|
365 |
means of the <CODE>makelib</CODE> environment. This tells <CODE>tcc</CODE>
|
|
|
366 |
to merge all the <CODE>.j</CODE> files and then to stop. But it also
|
|
|
367 |
passes an option to <CODE>tld</CODE> which causes the merged file
|
|
|
368 |
to be, not a TDF capsule, but a TDF library. Thus the command-line
|
|
|
369 |
options:<P>
|
|
|
370 |
<PRE>
|
|
|
371 |
> tcc -Ymakelib -o a.tl a.j b.j c.j
|
|
|
372 |
</PRE>
|
|
|
373 |
cause the TDF capsules <CODE>a.j</CODE>, <CODE>b.j</CODE> and <CODE>c.j</CODE>
|
|
|
374 |
to be combined into a TDF library, <CODE>a.tl</CODE>.<P>
|
|
|
375 |
<A NAME=S30>
|
|
|
376 |
<H3>5.2.4. Useful tld Options</H3>
|
|
|
377 |
<CODE>tld</CODE> has a number of options which may be useful to the
|
|
|
378 |
general user. The <B>-w</B> option, which causes warnings to be printed
|
|
|
379 |
about undefined tags and tokens, can often provide interesting information;
|
|
|
380 |
other options are concerned with the hiding of tag and token names.
|
|
|
381 |
These options can be passed directly to <CODE>tld</CODE> by means
|
|
|
382 |
of the <B>-WL, </B><I>opt</I><B>,</B> ... command-line option to <CODE>tcc
|
|
|
383 |
</CODE>. The <CODE>tld</CODE> options are fully documented on the
|
|
|
384 |
appropriate manual page.<P>
|
|
|
385 |
<A NAME=S31>
|
|
|
386 |
<HR><H2>5.3. The TDF to Target Translator</H2>
|
|
|
387 |
The next compilation tool to be considered is the TDF translator.
|
|
|
388 |
This translates an input target dependent TDF capsule (<CODE>.t</CODE>
|
|
|
389 |
file) into an assembly source file (<CODE>.s</CODE>) file for the
|
|
|
390 |
appropriate target machine. This is the main code generation phase
|
|
|
391 |
of the compilation process; most of the optimisation of code which
|
|
|
392 |
occurs happens in the translator (some machines also have optimising
|
|
|
393 |
assemblers).<P>
|
|
|
394 |
Although referred to by the generic name of <CODE>trans</CODE>, the
|
|
|
395 |
TDF translators for different target machines in fact have different
|
|
|
396 |
names. The main division between translators is in the supported processor.
|
|
|
397 |
However, operating system dependent features such as the precise form
|
|
|
398 |
of the assembler input, and the symbolic debugger to be supported,
|
|
|
399 |
may also cause different versions of the basic translator to be required
|
|
|
400 |
for different machines of the same processor group. The current generation
|
|
|
401 |
of translators includes the following:<P>
|
|
|
402 |
<OL>
|
|
|
403 |
<LI>The TDF --> i386/i486 translator is called <CODE>trans386</CODE>.
|
|
|
404 |
This exists in two versions, one running on SVR4.2 and one on SCO.
|
|
|
405 |
The two versions differ primarily in the symbolic debugger they support.
|
|
|
406 |
<CODE>trans386</CODE> has also been ported to several other i386-based
|
|
|
407 |
machines, including MS-DOS.<P>
|
|
|
408 |
<LI>The TDF --> Sparc (Version 7) translator is called <CODE>sparctrans
|
|
|
409 |
</CODE>. This again exists in two versions, one running on SVR4.2
|
|
|
410 |
and one on SunOS and Solaris 1. These versions again differ primarily
|
|
|
411 |
in the symbolic debugger supported.<P>
|
|
|
412 |
<LI>The TDF --> Mips (R2000/R3000, little-endian) translator is
|
|
|
413 |
called <CODE>mipstrans</CODE>. This differs from the other translators
|
|
|
414 |
in that instead of outputting a single <CODE>.s</CODE> file, it outputs
|
|
|
415 |
two files, a binasm file (with a <CODE>.G</CODE> suffix) and a symbol
|
|
|
416 |
table file (with a <CODE>.T</CODE> suffix). This is discussed in more
|
|
|
417 |
detail below. <CODE>mipstrans</CODE> runs on Ultrix, but again has
|
|
|
418 |
two versions. One runs on Ultrix 4.1 and earlier, the other on 4.2
|
|
|
419 |
and later. This necessary because of a change in the format of the
|
|
|
420 |
binasm file between these two releases.<P>
|
|
|
421 |
<LI>The TDF --> 68030/68040 translator also exists in two versions.
|
|
|
422 |
One runs on HP-UX and is called <CODE>hptrans</CODE>; the other runs
|
|
|
423 |
on NeXTStep and is called <CODE>nexttrans</CODE> (however the NeXT
|
|
|
424 |
is not a supported platform because of its lack of standard API coverage).
|
|
|
425 |
These differ, not only in the symbolic debugger supported, but also
|
|
|
426 |
in the format of the assembly source output.<P>
|
|
|
427 |
</OL>
|
|
|
428 |
This list is not intended to be definitive. Development work is proceeding
|
|
|
429 |
on new translators all the time. Existing translators are also updated
|
|
|
430 |
to support new operating systems releases when this is necessary.<P>
|
|
|
431 |
<A NAME=S32>
|
|
|
432 |
<H3>5.3.1. tcc Options Affecting the Translator</H3>
|
|
|
433 |
A number of <CODE>tcc</CODE> command-line options are aimed at controlling
|
|
|
434 |
the behaviour of the TDF translator. The <CODE>cc</CODE>-compatible
|
|
|
435 |
option <B>-K</B><I>item</I><B>,</B> ... specifies the behaviour indicated
|
|
|
436 |
by the argument <I>item</I>. Possible values for <I>item</I>, together
|
|
|
437 |
with the behaviour they specify, include:<P>
|
|
|
438 |
<PRE>
|
|
|
439 |
PIC causes position independent code to be produced,
|
|
|
440 |
ieee causes strict conformance to the IEEE floating point standard,
|
|
|
441 |
noieee allows non-strict conformance to the IEEE standard,
|
|
|
442 |
frame specifies that a frame pointer should always be used,
|
|
|
443 |
no_frame specifies that frame pointers need not always be used,
|
|
|
444 |
i386 causes code generation to be tuned for the i386 processor,
|
|
|
445 |
i486 causes code generation to be tuned for the i486 processor,
|
|
|
446 |
P5 causes code generation to be tuned for the P5 processor.
|
|
|
447 |
</PRE>
|
|
|
448 |
Obviously not all of these options are appropriate for all versions
|
|
|
449 |
of <CODE>trans</CODE>. Therefore all <B>-K</B> options are implemented
|
|
|
450 |
by means of environments which translate <I>item</I> into the appropriate
|
|
|
451 |
<CODE>trans</CODE> options. If a certain <I>item</I> is not applicable
|
|
|
452 |
on a particular target machine then the corresponding environment
|
|
|
453 |
will not exist, and <CODE>tcc</CODE> will print a warning to this
|
|
|
454 |
effect.<P>
|
|
|
455 |
The <CODE>cc</CODE>-compatible <B>-Z</B><I>str</I> option is similarly
|
|
|
456 |
implemented by means of environments. On those machines which support
|
|
|
457 |
this option it can be used to specify the packing of structures. If
|
|
|
458 |
<I>str</I> is <CODE>p1</CODE> then they are tightly packed, with no
|
|
|
459 |
padding. Values of <CODE>p2</CODE> and <CODE>p4</CODE> specify padding
|
|
|
460 |
to 2 or 4 byte boundaries when appropriate.<P>
|
|
|
461 |
Finally, the <CODE>tcc</CODE> command-line option <B>-wsl</B> causes
|
|
|
462 |
the translator to make all string literals writable. Again, this is
|
|
|
463 |
implemented by an environment. For many machines this behaviour is
|
|
|
464 |
default; for others it requires an option to be passed to the translator.<P>
|
|
|
465 |
<A NAME=S33>
|
|
|
466 |
<H3>5.3.2. Useful trans Options</H3>
|
|
|
467 |
For further specifying the behaviour of <CODE>trans</CODE> it may
|
|
|
468 |
be necessary to pass options to it directly. The command-line options
|
|
|
469 |
implemented by <CODE>trans</CODE> vary from machine to machine. The
|
|
|
470 |
following options are however common to all translators and may prove
|
|
|
471 |
useful:<P>
|
|
|
472 |
<PRE>
|
|
|
473 |
<B>-E</B> switches off certain constant overflow checks,
|
|
|
474 |
<B>-X</B> switches off most optimisations,
|
|
|
475 |
<B>-Z</B> prints the version number(s) of the input capsule.
|
|
|
476 |
</PRE>
|
|
|
477 |
These options may be passed directly to <CODE>trans</CODE> by means
|
|
|
478 |
of the <B>-Wt, </B><I>opt</I><B>,</B> ... command-line option to <CODE>tcc
|
|
|
479 |
</CODE>. The <B>-E</B> option is also automatically invoked when the
|
|
|
480 |
<B>-nepc</B> command-line option to <CODE>tcc</CODE> is used. The
|
|
|
481 |
manual page for the appropriate version of <CODE>trans</CODE> should
|
|
|
482 |
be consulted for more details on these and other, machine dependent,
|
|
|
483 |
options.<P>
|
|
|
484 |
<A NAME=S34>
|
|
|
485 |
<H3>5.3.3. Optimisation in TDF Translators</H3>
|
|
|
486 |
As has been mentioned, the TDF translator is the main optimising phase
|
|
|
487 |
of the TDF compilation scheme. All optimisations are believed to be
|
|
|
488 |
correct and are switched on by default. Thus the standard <CODE>cc</CODE>
|
|
|
489 |
<B>-O</B> option, which is intended to switch optimisations on, has
|
|
|
490 |
no effect in <CODE>tcc</CODE> except to cancel any previous <B>-g</B>
|
|
|
491 |
option. If, due to a translator bug, a certain piece of code is being
|
|
|
492 |
optimised incorrectly, then the optimisations can be switched off
|
|
|
493 |
by means of the <B>-Wt, -X</B> option mentioned above. However this
|
|
|
494 |
should not normally be necessary.<P>
|
|
|
495 |
<A NAME=S35>
|
|
|
496 |
<H3>5.3.4. The Mips Translator and Assembler</H3>
|
|
|
497 |
As has been mentioned, the TDF --> Mips translator, <CODE>mipstrans</CODE>
|
|
|
498 |
is genuinely exceptional in that it outputs a pair of files for each
|
|
|
499 |
input TDF capsule, rather than a single assembly source file. The
|
|
|
500 |
general scheme is shown in Fig. 5.<P>
|
|
|
501 |
FIGURE 5. Mips Compilation Path<BR>
|
|
|
502 |
<CENTER>
|
|
|
503 |
<IMG SRC="../images/mips_files.gif">
|
|
|
504 |
</CENTER>
|
|
|
505 |
<P>
|
|
|
506 |
<CODE>mipstrans</CODE> translates each input target dependent TDF
|
|
|
507 |
capsule, <CODE>a.t</CODE>, into a binasm source file, <CODE>a.G</CODE>,
|
|
|
508 |
and an assembler symbol table file, <CODE>a.T</CODE>. It may optionally
|
|
|
509 |
output an assembly source file, <CODE>a.s</CODE>, which combines all
|
|
|
510 |
the information from <CODE>a.G</CODE> with part of the information
|
|
|
511 |
from <CODE>a.T</CODE> (it is the remainder of the information in <CODE>a.T
|
|
|
512 |
</CODE> which is the reason why this scheme has to be adopted). The
|
|
|
513 |
<CODE>.s</CODE> file is only produced if <CODE>tcc</CODE> is explicit
|
|
|
514 |
told to preserve <CODE>.s</CODE> files by means of one of the command-line
|
|
|
515 |
options, <B>-Ps</B>, <B>-Pa</B>, <B>-Fs</B> or <B>-S</B>. The two
|
|
|
516 |
main <CODE>mipstrans</CODE> output files, <CODE>a.G</CODE> and <CODE>a.T</CODE>,
|
|
|
517 |
are then transformed by the auxiliary Mips assembler, <CODE>as1</CODE>,
|
|
|
518 |
into a binary object file, <CODE>a.o</CODE>.<P>
|
|
|
519 |
Although they can be preserved for examination, the <CODE>.G</CODE>
|
|
|
520 |
and <CODE>.T</CODE> files output by <CODE>mipstrans</CODE> cannot
|
|
|
521 |
subsequently be processed using <CODE>tcc</CODE>. If a break in compilation
|
|
|
522 |
is required at this stage, a <CODE>.s</CODE> file should be produced,
|
|
|
523 |
and then entered as a <CODE>tcc</CODE> input file in the normal way.
|
|
|
524 |
The information lost from the symbol table in this process is only
|
|
|
525 |
important when symbolic debugging information is required. Input <CODE>.s</CODE>
|
|
|
526 |
files are translated into binary object files by the main Mips assembler,
|
|
|
527 |
<CODE>as</CODE>, in the normal way.<P>
|
|
|
528 |
So, in addition to the main assembler, which is given by the <CODE>AS</CODE>
|
|
|
529 |
environmental identifier, the location of the auxiliary assembler
|
|
|
530 |
also needs to be specified to <CODE>tcc</CODE>. This is done using
|
|
|
531 |
the <CODE>AS1</CODE> environmental identifier, which is normally defined
|
|
|
532 |
in the <CODE>default</CODE> environment. There is a further piece
|
|
|
533 |
of information required for the compilation scheme to operate correctly:
|
|
|
534 |
<CODE>mipstrans</CODE> needs to know the <CODE>as1</CODE> version
|
|
|
535 |
number. This number can be specified by means of the <CODE>VERSION</CODE>
|
|
|
536 |
environmental identifier.<P>
|
|
|
537 |
<A NAME=S36>
|
|
|
538 |
<HR><H2>5.4. The System Assembler</H2>
|
|
|
539 |
The system assembler is the stage in the <CODE>tcc</CODE> compilation
|
|
|
540 |
path which is likely to be of least interest to normal users. The
|
|
|
541 |
assembler translates an assembly source (or <CODE>.s</CODE>) file
|
|
|
542 |
into a binary object (or <CODE>.o</CODE>) file. (The exception to
|
|
|
543 |
this is the Mips auxiliary assembler discussed above.) Most assemblers
|
|
|
544 |
are straight translation phases, although some also offer peephole
|
|
|
545 |
optimisation and scheduling facilities. No <CODE>tcc</CODE> command-line
|
|
|
546 |
options are directly concerned with the assembler, however options
|
|
|
547 |
can be passed to it directly by means of the <B>-Wa, </B><I>opt</I><B>,</B>
|
|
|
548 |
... command-line option.<P>
|
|
|
549 |
<A NAME=S37>
|
|
|
550 |
<HR><H2>5.5. The System Linker</H2>
|
|
|
551 |
The final stage in the main <CODE>tcc</CODE> compilation path is the
|
|
|
552 |
system linking. The system linker, <CODE>ld</CODE>, combines all the
|
|
|
553 |
binary object files with the system libraries to form a final executable
|
|
|
554 |
image. By default this executable is called <CODE>a.out</CODE>, although
|
|
|
555 |
this can be changed using the <B>-o</B> command-line option to <CODE>tcc</CODE>.
|
|
|
556 |
In terms of the differences between target machines, the system linker
|
|
|
557 |
is the most complex of the tools which are controlled by <CODE>tcc</CODE>.
|
|
|
558 |
Our discussion can be divided between those aspects of the linker's
|
|
|
559 |
behaviour which are controlled by <CODE>tcc</CODE> environments, and
|
|
|
560 |
those which are controlled by command-line options.<P>
|
|
|
561 |
<A NAME=S38>
|
|
|
562 |
<H3>5.5.1. The System Linker and tcc Environments</H3>
|
|
|
563 |
The general form of <CODE>tcc</CODE>'s calls to <CODE>ld</CODE> are
|
|
|
564 |
as follows:<P>
|
|
|
565 |
<PRE>
|
|
|
566 |
ld (linker options) -o (output file)
|
|
|
567 |
(initial .o files) (binary object files)
|
|
|
568 |
(final .o files) (default system library directories)
|
|
|
569 |
(default system libraries) (default standard libraries)
|
|
|
570 |
</PRE>
|
|
|
571 |
The linker may require certain default binary object files to be linked
|
|
|
572 |
into every executable created. These are divided between the initial
|
|
|
573 |
<CODE>.o</CODE> files, which come before the main list of binary object
|
|
|
574 |
files, and the final <CODE>.o</CODE> files, which come after. For
|
|
|
575 |
technical reasons, the list of initial <CODE>.o</CODE> files is split
|
|
|
576 |
into two; the first list is given by the <CODE>CRT0</CODE> environmental
|
|
|
577 |
identifier, and the second by <CODE>CRT1</CODE>. The list of final
|
|
|
578 |
<CODE>.o</CODE> files is given by the <CODE>CRTN</CODE> environmental
|
|
|
579 |
identifier.<P>
|
|
|
580 |
The information on the default system libraries the linker requires
|
|
|
581 |
is given by three environmental identifiers. <CODE>SYS_LINK</CODE>
|
|
|
582 |
gives a list of directories to be searched for system libraries. This
|
|
|
583 |
will exclude <CODE>/lib</CODE> and <CODE>/usr/lib</CODE> which are
|
|
|
584 |
usually built into <CODE>ld</CODE>. These directories will be given
|
|
|
585 |
as a list of options of the form <B>-L</B><I>dir</I>. The default
|
|
|
586 |
system libraries are divided into two lists. The environmental identifier
|
|
|
587 |
<CODE>SYS_LIBC</CODE> gives the "standard" library options
|
|
|
588 |
(usually just <B>-lc</B>), and <CODE>SYS_LIB</CODE> gives any other
|
|
|
589 |
default library options. Both of these are given by lists of options
|
|
|
590 |
of the form <B>-l</B><I>str</I>. This option specifies that the linker
|
|
|
591 |
should search for the library <CODE>lib</CODE><I>str</I><CODE>.a</CODE>
|
|
|
592 |
if linking statically, or <CODE>lib</CODE><I>str</I><CODE>.so</CODE>
|
|
|
593 |
if linking dynamically.<P>
|
|
|
594 |
So the main target dependencies affecting the system linker are described
|
|
|
595 |
in these six environmental variables: <CODE>CRT0</CODE>, <CODE>CRT1</CODE>,
|
|
|
596 |
<CODE>CRTN</CODE>, <CODE>SYS_LINK</CODE>, <CODE>SYS_LIB</CODE> and
|
|
|
597 |
<CODE>SYS_LIBC</CODE>. For a given machine these will be given once
|
|
|
598 |
and for all in the <CODE>default</CODE> environment. Standard API
|
|
|
599 |
environments may modify <CODE>SYS_LINK</CODE> and <CODE>SYS_LIB</CODE>
|
|
|
600 |
to specify the location of the system libraries containing the API
|
|
|
601 |
implementation, although at present this has not been done.<P>
|
|
|
602 |
<A NAME=S39>
|
|
|
603 |
<H3>5.5.2. The Effect of Command-Line Options on the System Linker</H3>
|
|
|
604 |
The most important <CODE>tcc</CODE> command-line options affecting
|
|
|
605 |
the system linker are those which specify the use of certain system
|
|
|
606 |
libraries. The option <B>-l</B><I>str</I> indicates that the system
|
|
|
607 |
libraries <CODE>lib</CODE><I>str</I><CODE>.a</CODE> (or <CODE>lib</CODE><I>str
|
|
|
608 |
</I><CODE>.so</CODE>) should be searched for. The option <B>-L</B><I>dir</I>
|
|
|
609 |
indicates that the directory <I>dir</I> should be added to the list
|
|
|
610 |
of directories searched for system libraries. Both these options are
|
|
|
611 |
position dependent. They are passed to the system linker in exactly
|
|
|
612 |
the same position relative to the input files as they were given on
|
|
|
613 |
the command-line. Thus normally <B>-l</B> (and to a lesser extent
|
|
|
614 |
<B>-L</B>) options should be the final command-line options given.<P>
|
|
|
615 |
The following <CODE>tcc</CODE> command-line options are passed directly
|
|
|
616 |
to <CODE>ld</CODE>. A brief description is given of the purpose of
|
|
|
617 |
each option, however whether or not <CODE>ld</CODE> supports this
|
|
|
618 |
option depends on the target machine. The local <CODE>ld</CODE> manual
|
|
|
619 |
page should be consulted for details.<P>
|
|
|
620 |
<PRE>
|
|
|
621 |
<B>-B</B><I>str</I> sets library type: <I>str</I> can be dynamic or static,
|
|
|
622 |
<B>-G</B> causes a shared object rather than an executable to be produced,
|
|
|
623 |
<B>-dn</B> causes dynamic linking to be switched off,
|
|
|
624 |
<B>-dy</B> causes dynamic linking to be switched on,
|
|
|
625 |
<B>-h</B><I>str</I> causes <I>str</I> to be marked as dynamic in a shared object,
|
|
|
626 |
<B>-s</B> causes the resultant executable to be stripped,
|
|
|
627 |
<B>-u</B><I>str</I> causes <I>str</I> to be marked as undefined,
|
|
|
628 |
<B>-z</B><I>str</I> specifies error behaviour, depending on <I>str</I>.
|
|
|
629 |
</PRE>
|
|
|
630 |
The position of any <B>-B</B><I>str</I> options on the command-line
|
|
|
631 |
is significant. These positions are therefore preserved. The position
|
|
|
632 |
of the other options is not significant. In addition to these options,
|
|
|
633 |
the <B>-b</B> command-line option causes the default standard system
|
|
|
634 |
libraries (i.e. those given by the <CODE>SYS_LIBC</CODE> environmental
|
|
|
635 |
identifier) not to be passed to <CODE>ld</CODE>.<P>
|
|
|
636 |
Other command-line options may affect the system linker indirectly.
|
|
|
637 |
For example, the <B>-g</B> option may require different default <CODE>.o</CODE>
|
|
|
638 |
files and system libraries, the precise details of which are target
|
|
|
639 |
dependent. Such options will be implemented by means of environments
|
|
|
640 |
which will change the values of the environmental identifiers controlling
|
|
|
641 |
the linker.<P>
|
|
|
642 |
<A NAME=S40>
|
|
|
643 |
<HR><H2>5.6. The C Preprocessor</H2>
|
|
|
644 |
The TDF C preprocessor, <CODE>tdfcpp</CODE>, is invoked only when
|
|
|
645 |
<CODE>tcc</CODE> is passed the <B>-E</B> or <B>-P</B> command-line
|
|
|
646 |
option, as described in section 3.5.1</A>. These both cause all input
|
|
|
647 |
<CODE>.c</CODE> files to be preprocessed, but in the former case the
|
|
|
648 |
output is send to the standard output, whereas in the latter it is
|
|
|
649 |
send to the corresponding <CODE>.i</CODE> files.<P>
|
|
|
650 |
The TDF system differs from most C compilation systems in that preprocessing
|
|
|
651 |
is an integral part of the producer, <CODE>tdfc</CODE>, rather than
|
|
|
652 |
a preliminary textual substitution phase. This is because of difficulties
|
|
|
653 |
involved with trying to perform the preprocessing in a target independent
|
|
|
654 |
manner. Therefore <CODE>tdfcpp</CODE> is merely a modified version
|
|
|
655 |
of <CODE>tdfc</CODE> which halts after the preprocessing phase and
|
|
|
656 |
prints what it has read. This means that the <CODE>tdfcpp</CODE> output,
|
|
|
657 |
while being equivalent to its input, will not correspond at the textual
|
|
|
658 |
level to the degree which is normal in C preprocessors.<P>
|
|
|
659 |
<A NAME=S41>
|
|
|
660 |
<HR><H2>5.7. The TDF Pretty Printer</H2>
|
|
|
661 |
The TDF pretty printer, <CODE>disp</CODE>, and the TDF notation compiler,
|
|
|
662 |
<CODE>tnc</CODE>, have already been discussed in some detail in section
|
|
|
663 |
3.5.3</A>. The TDF decoding command-line options, <B>-disp</B> and
|
|
|
664 |
<B>-disp_t</B>, cause respectively all <CODE>.j</CODE> files and all
|
|
|
665 |
<CODE>.t</CODE> files to be decoded into <CODE>.p</CODE> files. This
|
|
|
666 |
decoding is done using <CODE>disp</CODE> by default, and with <CODE>tnc</CODE>
|
|
|
667 |
<B>-p</B> if the <B>-Ytnc</B> command-line option is specified. The
|
|
|
668 |
<B>-Ytnc</B> option also causes any input <CODE>.p</CODE> files to
|
|
|
669 |
be encoded into <CODE>.j</CODE> files by <CODE>tnc</CODE>.<P>
|
|
|
670 |
The pretty printer, <CODE>disp</CODE>, can be used as a useful check
|
|
|
671 |
that a given <CODE>.j</CODE> or <CODE>.t</CODE> file is a legal TDF
|
|
|
672 |
capsule. The TDF decoding routines in the TDF linker and the TDF translator
|
|
|
673 |
assume that their input is a legal capsule. The pretty printer performs
|
|
|
674 |
more checks and has better diagnostics for illegal capsules. By default
|
|
|
675 |
<CODE>disp</CODE> only decodes capsule units which belong to "core"
|
|
|
676 |
TDF. Options to decode other unit types can be passed directly to
|
|
|
677 |
<CODE>disp</CODE> by means of the <B>-Wd, </B><I>opt</I><B>,</B> ...
|
|
|
678 |
command-line option to <CODE>tcc</CODE>. The potentially useful <CODE>disp
|
|
|
679 |
</CODE> options include:<P>
|
|
|
680 |
<PRE>
|
|
|
681 |
<B>-A</B> causes all known unit types to be decoded,
|
|
|
682 |
<B>-g</B> causes diagnostic information units to be decoded,
|
|
|
683 |
<B>-D</B> causes a binary dump of the capsule to be printed,
|
|
|
684 |
<B>-U</B> causes link information units to be decoded,
|
|
|
685 |
<B>-V</B> causes the input not to be rationalised,
|
|
|
686 |
<B>-W</B> causes a warning to be printed if a token is used before it is declared.
|
|
|
687 |
</PRE>
|
|
|
688 |
The manual page for <CODE>disp</CODE> should be consulted for more
|
|
|
689 |
details.<P>
|
|
|
690 |
The TDF notation compiler, <CODE>tnc</CODE>, is fully documented in
|
|
|
691 |
[4].<P>
|
|
|
692 |
<A NAME=S42>
|
|
|
693 |
<HR><H2>5.8. The TDF Archiver</H2>
|
|
|
694 |
A TDF archive is a <CODE>tcc</CODE>-specific form intended for software
|
|
|
695 |
distribution. It consists of a set of target independent TDF capsules
|
|
|
696 |
(<CODE>.j</CODE> files) and a set of <CODE>tcc</CODE> command-line
|
|
|
697 |
options. It is intended that a TDF archive can be produced on one
|
|
|
698 |
machine, and distributed to, and installed on, a number of target
|
|
|
699 |
machines.<P>
|
|
|
700 |
If a TDF archive is given as an input file to <CODE>tcc</CODE> (it
|
|
|
701 |
will be recognised by its <CODE>.ta</CODE> suffix), then it is split
|
|
|
702 |
into its constituent capsules and options. The options are interpreted
|
|
|
703 |
as if they had been given on the command-line (unless the <B>-WJ,
|
|
|
704 |
-no_options</B> flag is specified), and the capsules are treated as
|
|
|
705 |
input files in the normal way. The archive splitting and archive building
|
|
|
706 |
routines are both built into <CODE>tcc</CODE>; there is no separate
|
|
|
707 |
TDF archiver tool. Options passed to the archiver using <B>-WJ, </B><I>opt</I>
|
|
|
708 |
are interpreted by <CODE>tcc</CODE>.<P>
|
|
|
709 |
In order to specify that a TDF archive should be created, the <B>-prod</B>
|
|
|
710 |
flag should be used. This specifies that all target independent capsules
|
|
|
711 |
(<CODE>.j</CODE> files) and all options <I>opt</I> given by a <CODE>tcc</CODE>
|
|
|
712 |
option of the form <B>-WI, </B><I>opt</I><B>,</B> ... should be combined
|
|
|
713 |
into a TDF archive. The compilation process halts after producing
|
|
|
714 |
this archive. By default the TDF archive created is called <CODE>a.ta</CODE>,
|
|
|
715 |
but this can be changed using the <B>-o</B> option. Normally the names
|
|
|
716 |
of the capsules comprising the archive are inserted into the archive,
|
|
|
717 |
but this may be suppressed by the use of the <B>-WJ, -no_names</B>
|
|
|
718 |
option.<P>
|
|
|
719 |
As an example of the kind of option that might be included in an archive,
|
|
|
720 |
suppose that the production has been done using the POSIX API. Then
|
|
|
721 |
the installation should also be done using this same API. Alternatively
|
|
|
722 |
expressed, if a TDF archive has been constructed using the <CODE>posix</CODE>
|
|
|
723 |
environment, then the <B>-Yposix</B> flag should be included in the
|
|
|
724 |
archive to ensure that the installation also takes place in this same
|
|
|
725 |
environment. In fact the environments describing the standard APIs
|
|
|
726 |
have been set up so that this happens automatically. For example,
|
|
|
727 |
the <CODE>posix</CODE> environment contains the line:<P>
|
|
|
728 |
<PRE>
|
|
|
729 |
+FLAG "-WI,-Yposix"
|
|
|
730 |
</PRE>
|
|
|
731 |
Another kind of option that it might be useful to include in an archive
|
|
|
732 |
is a <B>-l</B><I>str</I> option. In this way all the information on
|
|
|
733 |
the install-time options can be specified at produce-time.<P>
|
|
|
734 |
A final example of an option which might be included in an archive
|
|
|
735 |
is the <B>-message</B> option. The command-line option <B>-message</B>
|
|
|
736 |
<I>str</I> causes <CODE>tcc</CODE> to print the message <I>str</I>
|
|
|
737 |
with any <CODE>@</CODE> characters in <I>str</I> replaced by spaces
|
|
|
738 |
(there are problems with escaping spaces). So, by using the command-line
|
|
|
739 |
option:<P>
|
|
|
740 |
<PRE>
|
|
|
741 |
<B>-WI,-message"Installing@TDF@archive@..."</B>
|
|
|
742 |
</PRE>
|
|
|
743 |
one can produce an archive which prints a message as it is installed.
|
|
|
744 |
This option is also useful in environments. By inserting the line:<P>
|
|
|
745 |
<PRE>
|
|
|
746 |
+FLAG "-message Reading@tcc@environment@..."
|
|
|
747 |
</PRE>
|
|
|
748 |
one can produce an environment which prints a message whenever it
|
|
|
749 |
is read.<P>
|
|
|
750 |
<HR>
|
|
|
751 |
<P><I>Part of the <A HREF="../index.html">TenDRA Web</A>.<BR>Crown
|
|
|
752 |
Copyright © 1998.</I></P>
|
|
|
753 |
</BODY>
|
|
|
754 |
</HTML>
|