Subversion Repositories tendra.SVN

Rev

Rev 2 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
2 7u83 1 
<!-- Crown Copyright (c) 1998 -->
2 
<HTML>
3 
<HEAD>
4 
<TITLE>tcc User's Guide: The Overall Design of tcc</TITLE>
5 
</HEAD>
6 
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000FF" VLINK="#400080" ALINK="#FF0000">
7 
<A NAME=S3>
8 
<H1>tcc User's Guide</H1>
9 
<H3>January 1998</H3>
10 
<A HREF="tcc5.html"><IMG SRC="../images/next.gif" ALT="next section"></A>
11 
<A HREF="tcc3.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="#S4"><B>3.1</B> - Specifying the API</A><DD>
19 
<DT><A HREF="#S5"><B>3.2</B> - The Main Compilation Path</A><DD>
20 
<DT><A HREF="#S6"><B>3.3</B> - Input File Types</A><DD>
21 
<DT><A HREF="#S7"><B>3.4</B> - Intermediate and Output Files</A><DD>
22 
<DT><A HREF="#S8"><B>3.5</B> - Other Compilation Paths</A><DD>
23 
<DL>
24 
<DT><A HREF="#S9"><B>3.5.1</B> - Preprocessing</A><DD>
25 
<DT><A HREF="#S10"><B>3.5.2</B> - TDF Archives</A><DD>
26 
<DT><A HREF="#S11"><B>3.5.3</B> - TDF Notation</A><DD>
27 
<DT><A HREF="#S12"><B>3.5.4</B> - Merging TDF Capsules</A><DD>
28 
</DL>
29 
<DT><A HREF="#S13"><B>3.6</B> - Finding out what tcc is doing</A><DD>
30 
</DL>
31 
 
32 
<HR>
33 
<H1>3.  The Overall Design of tcc</H1>
34 
Having discussed the compilation strategy <CODE>tcc</CODE> is designed
35 
to implement, let us move on to describe the details of this implementation.
36 
The basic compilation path is shown in Fig. 3, which corresponds to
37 
Fig. 2.<P>
38 
FIGURE 3.  Basic tcc Compilation Path<BR>
39 
<CENTER>
40 
<IMG SRC="../images/tcc_scheme.gif">
41 
</CENTER>
42 
<P>
43 
<A NAME=S4>
44 
<HR><H2>3.1.  Specifying the API</H2>
45 
As we have seen, the API plays a far more concrete role in the TDF
46 
compilation strategy than in the traditional scheme. Therefore the
47 
API needs to be explicitly specified to <CODE>tcc</CODE> before any
48 
compilation takes place. As can be seen from Fig. 3, the API has three
49 
components. Firstly, in the target independent (or production) half
50 
of the compilation, there are the target independent headers which
51 
describe the API. Secondly in the target dependent (or installation)
52 
half, there is the API implementation for the particular target machine.
53 
This is divided between the TDF libraries, derived from the system
54 
headers, and the system libraries. Specifying the API to <CODE>tcc</CODE>
55 
essentially consists of telling it what target independent headers,
56 
TDF libraries and system libraries to use. The precise way in which
57 
this is done is discussed below (in section 4.3</A>).<P>
58 
<A NAME=S5>
59 
<HR><H2>3.2.  The Main Compilation Path</H2>
60 
Once the API has been specified, the actual compilation can begin.
61 
The default action of <CODE>tcc</CODE> is to perform production and
62 
installation consecutively on the same machine; any other action needs
63 
to be explicitly specified. So let us describe the entire compilation
64 
path from C source to executable shown in Fig. 3.<P>
65 
<OL>
66 
<LI>The first stage is production. The C --&gt; TDF producer transforms
67 
each input C source file into a target independent TDF capsule, using
68 
the target independent headers to describe the API in abstract terms.
69 
These target independent capsules will contain tokens to represent
70 
the uses of objects from the API, but these tokens will be left undefined.<P>
71 
<LI>The second stage, which is also the first stage of the installation,
72 
is TDF linking. Each target independent capsule is combined with the
73 
TDF library describing the API implementation to form a target dependent
74 
TDF capsule. Recall that the TDF libraries contain the local definitions
75 
of the tokens left undefined by the producer, so the resultant target
76 
dependent capsule will contain both the uses of these tokens and the
77 
corresponding token definitions.<P>
78 
<LI>The third stage of the compilation is for the TDF translator to
79 
transform each target dependent TDF capsule into an assembly source
80 
file for the appropriate target machine. Some TDF translators output
81 
not an assembly source file, but a binary object file. In this case
82 
the following assembler stage is redundant and the compilation skips
83 
to the system linking.<P>
84 
<LI>The next stage of the compilation is for each assembly source
85 
file to be translated into a binary object file by the system assembler.<P>
86 
<LI>The final compilation phase is for the system linker to combine
87 
all the binary object files with the system libraries to form a single,
88 
final executable. Recall that the system libraries are the final constituent
89 
of the API implementation, so this stage completes the combination
90 
of the program with the API implementation started in stage 2).<P>
91 
</OL>
92 
Let us, for convenience, tabulate these stages, giving the name of
93 
each compilation tool (plus the corresponding executable name), a
94 
code letter which <CODE>tcc</CODE> uses to refer to this stage, and
95 
the input and output file types for the stage (also see 7.2</A>).<P>
96 
<PRE>
97 
	<B>   TOOL					INPUT		OUTPUT</B>
98 
	1. C producer (tdfc)	 	c	C source	target ind. TDF
99 
	2. TDF linker (tld)	 	L	target ind. TDF	target dep. TDF
100 
	3. TDF translator (trans) 	t	target dep. TDF	assembly source
101 
	4. assembler (as) 		a	assembly source	binary object
102 
	5. system linker (ld)	 	l	binary object	executable
103 
</PRE>
104 
The executable name of the TDF translator varies, depending on the
105 
target machine. It will normally start, or end, however, in <CODE>trans</CODE>.
106 
These stages are documented in more detail in sections 5.1</A> to
107 
5.5.<P>
108 
The code letters for the various compilation stages can be used in
109 
the <B>-W</B><I>tool</I><B>, </B><I>opt</I><B>,</B> ... command-line
110 
option to <CODE>tcc</CODE>. This passes the option(s) <I>opt</I> directly
111 
to the executable in the compilation stage identified by the letter
112 
<I>tool</I>. For example, <B>-Wl, -x</B> will cause the system linker
113 
to be invoked with the <B>-x</B> option. Similarly the <B>-E</B><I>tool</I><B>:
114 
</B><I>file</I> allows the executable to be invoked at the compilation
115 
stage <I>tool</I> to be specified as <I>file</I>. This allows the
116 
<CODE>tcc</CODE> user access to the compilation tools in a very direct
117 
manner.<P>
118 
<A NAME=S6>
119 
<HR><H2>3.3.  Input File Types</H2>
120 
This compilation path may be joined at any point, and terminated at
121 
any point. The latter possibility is discussed below. For the former,
122 
<CODE>tcc</CODE> determines, for each input file it is given, to which
123 
of the file types it knows (C source, target independent TDF, etc.)
124 
this file belongs. This determines where in the compilation path described
125 
this file will start. The method used to determine the type of a file
126 
is the normal filename suffix convention:<P>
127 
<UL>
128 
<LI>files ending in <CODE>.c</CODE> are understood to be C source
129 
files,<P>
130 
<LI>files ending in <CODE>.j</CODE> are understood to be target independent
131 
TDF capsules,<P>
132 
<LI>files ending in <CODE>.t</CODE> are understood to be target dependent
133 
TDF capsules,<P>
134 
<LI>files ending in <CODE>.s</CODE> are understood to be assembly
135 
source files,<P>
136 
<LI>files ending in <CODE>.o</CODE> are understood to be binary object
137 
files,<P>
138 
<LI>files whose type cannot otherwise be determined are assumed to
139 
be binary object files,<P>
140 
</UL>
141 
(for a complete list see 7.1</A>). Thus, for example, we speak of
142 
&quot;<CODE>.j</CODE> files&quot; as a shorthand for &quot;target
143 
independent TDF capsules&quot;. Each file type recognised by <CODE>tcc</CODE>
144 
is assigned an identifying letter. For convenience, this corresponds
145 
to the suffix identifying the file type (<CODE>c</CODE> for C source
146 
files, <CODE>j</CODE> for target independent TDF capsules etc.).<P>
147 
There is an alternative method of specifying input files, by means
148 
of the <B>-S</B><I>type</I><B>, </B><I>file</I><B>,</B> ... command-line
149 
option. This specifies that the file <I>file</I> should be treated
150 
as an input file of the type corresponding to the letter <I>type</I>,
151 
regardless of its actual suffix. Thus, for example, <B>-Sc,</B> <I>file</I>
152 
specifies that <I>file</I> should be regarded as a C source (or <CODE>.c</CODE>)
153 
file.<P>
154 
<A NAME=S7>
155 
<HR><H2>3.4.  Intermediate and Output Files</H2>
156 
During the compilation, <CODE>tcc</CODE> makes up names for the output
157 
files of each of the compilation phases. These names are based on
158 
the input file name, but with the input file suffix replaced by the
159 
output file suffix (unless the <B>-make_up_names</B> command-line
160 
option is given, in which case the intermediate files are given names
161 
of the form
162 
<CODE>_tccnnnn.x</CODE>, where <CODE>nnnn</CODE> is a number which
163 
is incremented for each intermediate file produced, and <CODE>x</CODE>
164 
is the suffix corresponding to the output file type). Thus if the
165 
input file <CODE>file.c</CODE> is given, this will be transformed
166 
into <CODE>file.j</CODE> by the producer, which in turn will be transformed
167 
into <CODE>file.t</CODE> by the TDF linker, and so on. The system
168 
linker output file name can not be deduced in the same way since it
169 
is the result of linking a number of <CODE>.o</CODE>
170 
files. By default, as with <CODE>cc</CODE>, this file is called <CODE>a.out
171 
</CODE>.<P>
172 
For most purposes these intermediate files are not required to be
173 
preserved; if we are compiling a single C source file to an executable,
174 
then the only output file we are interested in is the executable,
175 
not the intermediate files created during the compilation process.
176 
For this reason <CODE>tcc</CODE> creates a temporary directory in
177 
which to put these intermediate files, and removes this directory
178 
when the compilation is complete. All intermediate files are put into
179 
this temporary directory except:<P>
180 
<UL>
181 
<LI>those which are an end product of the compilation (such as the
182 
executable),<P>
183 
<LI>those which are explicitly ordered to be preserved by means of
184 
command-line options,<P>
185 
<LI>binary object files, when more than one such file is produced
186 
(this is for compatibility with <CODE>cc</CODE>).<P>
187 
</UL>
188 
<CODE>tcc</CODE> can be made to preserve intermediate files of various
189 
types by means of the <B>-P</B><I>type</I>... command-line option,
190 
which specifies a list of letters corresponding to the file types
191 
to be preserved. Thus for example <B>-Pjt</B> specifies that all TDF
192 
capsules produced, whether target independent or target dependent,
193 
(i.e. all <CODE>.j</CODE> and <CODE>.t</CODE> files) should be preserved.
194 
The special form <B>-Pa</B> specifies that all intermediate files
195 
should be preserved. It is also possible to specify that a certain
196 
file type should not be preserved by preceding the corresponding letter
197 
by <B>-</B> in the <B>-P</B> option. The only really useful application
198 
of this is to use <B>-P-o</B> to cancel the <CODE>cc</CODE> convention
199 
on preserving binary object files mentioned above.<P>
200 
By default, all preserved files are stored in the current working
201 
directory. However the <B>-work</B> <I>dir</I> command-line option
202 
specifies that they should be stored in the directory <I>dir</I>.<P>
203 
The compilation can also be halted at any stage. The <B>-F</B><I>type</I>
204 
option to <CODE>tcc</CODE> tells it to stop the compilation after
205 
creating the files of the type corresponding to the letter <I>type</I>.
206 
Because any files of this type which are produced will be an end product
207 
of the compilation, they will automatically be preserved. For example,
208 
<B>-Fo</B> halts the compilation after the creation of the binary
209 
object, or <CODE>.o</CODE>, files (i.e. just before the system linking),
210 
and preserves all such files produced. A number of other <CODE>tcc</CODE>
211 
options are equivalent to options of the form <B>-F</B><I>type</I>:<P>
212 
<UL>
213 
<LI><B>-i</B> is equivalent to <B>-Fj</B> (i.e. just apply the producer),<P>
214 
<LI><B>-S</B> is equivalent to <B>-Fs</B> (<CODE>cc</CODE> compatibility),<P>
215 
<LI><B>-c</B> is equivalent to <B>-Fo</B> (<CODE>cc</CODE> compatibility).<P>
216 
</UL>
217 
If more than one <B>-F</B> option (including the equivalent options
218 
just listed) is given, then <CODE>tcc</CODE> issues a warning. The
219 
stage coming first in the compilation path takes priority.<P>
220 
If the compilation has precisely one end product output file, then
221 
the name of this file can be specified to be <I>file</I> by means
222 
of the <B>-o</B> <I>file</I> command-line option. If a <B>-o</B> <I>file</I>
223 
option is given when there is more than one end product, then the
224 
first such file produced will be called <I>file</I>, and all such
225 
files produced subsequently will cause <CODE>tcc</CODE> to issue a
226 
warning.<P>
227 
FIGURE 4.  Full tcc Compilation Path<BR>
228 
<CENTER>
229 
<IMG SRC="../images/tcc_files.gif">
230 
</CENTER>
231 
<P>
232 
<A NAME=S8>
233 
<HR><H2>3.5.  Other Compilation Paths</H2>
234 
So far we have been discussing the main <CODE>tcc</CODE> compilation
235 
path from C source to executable. This is however only part of the
236 
picture. The full complexity (almost) of all the possible compilation
237 
paths supported by <CODE>tcc</CODE> is shown in Fig. 4. This differs
238 
from Fig. 3 in that it only shows the left hand, or program, half
239 
of the main compilation diagram. The solid arrows show the default
240 
compilation paths; the shaded arrows are only followed if <CODE>tcc</CODE>
241 
is so instructed by means of command-line options. Let us consider
242 
those paths in this diagram which have not so far been mentioned.<P>
243 
<A NAME=S9>
244 
<H3>3.5.1.  Preprocessing</H3>
245 
The first paths to be considered involve preprocessed C source files.
246 
These form a distinct file type which <CODE>tcc</CODE> recognises
247 
by means of the <CODE>.i</CODE> file suffix. Input <CODE>.i</CODE>
248 
files are treated in exactly the same way as <CODE>.c</CODE> files;
249 
that is, they are fed into the producer.<P>
250 
<CODE>tcc</CODE> can be made to preprocess the C source files it is
251 
given by means of the <B>-P</B> and <B>-E</B> options. If the <B>-P</B>
252 
option is given then each <CODE>.c</CODE> file is transformed into
253 
a corresponding <CODE>.i</CODE> file by the TDF C preprocessor, <CODE>tdfcpp
254 
</CODE>. If the <B>-E</B> option is given then the output of <CODE>tdfcpp</CODE>
255 
is sent instead to the standard output. In both cases the compilation
256 
halts after the preprocessor has been applied. Preprocessing is discussed
257 
further in section 5.6</A>.<P>
258 
<A NAME=S10>
259 
<H3>3.5.2.  TDF Archives</H3>
260 
The second new file type introduced in Fig. 4 is the TDF archive.
261 
This is recognised by <CODE>tcc</CODE> by means of the <CODE>.ta</CODE>
262 
file suffix. Basically a TDF archive is a set of target independent
263 
TDF capsules (this is slightly simplified, see section 5.2.3</A> for
264 
more details). Any input TDF archives are automatically split into
265 
their constituent target independent capsules. These then join the
266 
main compilation path in the normal way.<P>
267 
In order to create a TDF archive, <CODE>tcc</CODE> must be given the
268 
<B>-prod</B> command-line option. It will combine all the target independent
269 
TDF capsules it has into an archive, and the compilation will then
270 
halt. By default this archive is called <CODE>a.ta</CODE>, but another
271 
name may be specified using the <B>-o</B> option.<P>
272 
The routines for splitting and building TDF archives are built into
273 
<CODE>tcc</CODE>, and are not implemented by a separate compilation
274 
tool (in particular, TDF archives are not <CODE>ar</CODE> archives).
275 
Really TDF archives are a <CODE>tcc</CODE>-specific construction;
276 
they are not part of TDF proper.<P>
277 
<A NAME=S11>
278 
<H3>3.5.3.  TDF Notation</H3>
279 
TDF has the form of an abstract syntax tree which is encoded as a
280 
series of bits. In order to examine the contents of a TDF capsule
281 
it is necessary to translate it into an equivalent human readable
282 
form. Two tools are provided which do this. The TDF pretty printer,
283 
<CODE>disp</CODE>, translates TDF into text, whereas the TDF notation
284 
compiler, <CODE>tnc</CODE>, both translates TDF to text and text to
285 
TDF. The two textual forms of TDF are incompatible - <CODE>disp</CODE>
286 
output cannot be used as <CODE>tnc</CODE> input. <CODE>disp</CODE>
287 
is in many ways the more sophisticated decoder - it understands the
288 
TDF extensions used to handle diagnostics, for example - but it does
289 
not handle the text to TDF translation which <CODE>tnc</CODE> does.
290 
By default <CODE>tnc</CODE> is a text to TDF translator, it needs
291 
to be passed the <B>-p</B> flag in order to translate TDF into text.
292 
We refer to the textual form of TDF supported by <CODE>tnc</CODE>
293 
as TDF notation.<P>
294 
By default, <CODE>tcc</CODE> uses <CODE>disp</CODE>. If it is given
295 
the <B>-disp</B> command-line option then all target independent TDF
296 
capsules (<CODE>.j</CODE> files) are transformed into text using <CODE>disp
297 
</CODE>. The <B>-disp_t</B> option causes all target dependent TDF
298 
capsules (<CODE>.t</CODE> files) to be transformed into text. In both
299 
cases the output files have a <CODE>.p</CODE> suffix, and the compilation
300 
halts after they are produced.<P>
301 
In order for <CODE>tnc</CODE> to be used, the <B>-Ytnc</B> flag should
302 
be passed to <CODE>tcc</CODE>. In this case the <B>-disp</B> and the
303 
<B>-disp_t</B> option cause, not <CODE>disp</CODE>, but <CODE>tnc</CODE>
304 
<B>-p</B>, to be invoked. But this flag also causes <CODE>tcc</CODE>
305 
to recognise files with a <CODE>.p</CODE> suffix as TDF notation source
306 
files. These are translated by <CODE>tnc</CODE> into target independent
307 
TDF capsules, which join the main compilation path in the normal way.<P>
308 
Similarly if the <B>-Ypl_tdf</B> flag is passed to <CODE>tcc</CODE>
309 
then it recognises files with a <CODE>.pl</CODE> suffix as PL_TDF
310 
source files. These are translated by the PL_TDF compiler, <CODE>pl</CODE>,
311 
into target independent TDF capsules.<P>
312 
<CODE>disp</CODE> and <CODE>tnc</CODE> are further discussed in section
313 
5.7</A>.<P>
314 
<A NAME=S12>
315 
<H3>3.5.4.  Merging TDF Capsules</H3>
316 
The final unexplored path in Fig. 4 is the ability to combine all
317 
the target independent TDF capsules into a single capsule. This is
318 
specified by means of the <B>-M</B> command-line option to <CODE>tcc</CODE>.
319 
The combination of these capsules is performed by the TDF linker,
320 
<CODE>tld</CODE>. Whereas in the main compilation path <CODE>tld</CODE>
321 
is used to combine a single target independent TDF capsule with the
322 
TDF libraries to form a target dependent TDF capsule, in this case
323 
it is used to combine several target independent capsules into a single
324 
target independent capsule. By default the combined capsule is called
325 
<CODE>a.j</CODE>. The compilation will continue after the combination
326 
phase, with the resultant capsule rejoining the main compilation path.
327 
This merging operation is further discussed in section 5.2.2</A>.<P>
328 
The only unresolved issue in this case is, if the <B>-M</B> option
329 
is given, to what <CODE>.j</CODE> files do the <B>-Fj</B> and the
330 
<B>-Pj</B> options refer? In fact, <CODE>tcc</CODE> takes them to
331 
refer to the merged TDF capsule rather than the capsules which are
332 
merged to form it. The <B>-Pa</B> option, however, will cause both
333 
sets of capsules to be preserved.<P>
334 
To summarise, <CODE>tcc</CODE> has an extra three file types, and
335 
an extra three compilation tools (not including the TDF archive creating
336 
and splitting routines which are built into <CODE>tcc</CODE>). These
337 
are:<P>
338 
<UL>
339 
<LI>files ending in <CODE>.i</CODE> are understood to be preprocessed
340 
C source files,<P>
341 
<LI>files ending in <CODE>.ta</CODE> are understood to be TDF archives,<P>
342 
<LI>files ending in <CODE>.p</CODE> are understood to be TDF notation
343 
source files,<P>
344 
</UL>
345 
and:<P>
346 
<PRE>
347 
	<B>   TOOL					INPUT		OUTPUT</B>
348 
	6. C preprocessor (tdfcpp) 	c	C source	preproc. C source
349 
	7a. pretty printer (disp) 	d	TDF capsule	TDF notation
350 
	7b. reverse notation (tnc -p)	d	TDF capsule	TDF notation
351 
	8. notation compiler (tnc) 	d	TDF notation	TDF capsule
352 
</PRE>
353 
(see 7.1</A> and 7.2</A> for complete lists).<P>
354 
<A NAME=S13>
355 
<HR><H2>3.6.  Finding out what tcc is doing</H2>
356 
With so many different file types and alternative compilation paths,
357 
it is often useful to be able to keep track of what <CODE>tcc</CODE>
358 
is doing. There are several command-line options which do this. The
359 
simplest is <B>-v</B> which specifies that <CODE>tcc</CODE> should
360 
print each command in the compilation process on the standard output
361 
before it is executed. The <B>-vb</B> option is similar, but only
362 
causes the name of each input file to be printed as it is processed.
363 
Finally the <B>-dry</B> option specifies that the commands should
364 
be printed (as with <B>-v</B>) but not actually executed. This can
365 
be used to experiment with <CODE>tcc</CODE> to find out what it would
366 
do in various circumstances.<P>
367 
Occasionally an unclear error message may be printed by one of the
368 
compilation tools. In this case the <B>-show_errors</B> option to
369 
<CODE>tcc</CODE> might be useful. It causes <CODE>tcc</CODE> to print
370 
the command it was executing when the error occurred. By default,
371 
if an error occurs during the construction of an output file, the
372 
file is removed by <CODE>tcc</CODE>. It can however be preserved for
373 
examination using the <B>-keep_errors</B> option. This applies not
374 
only to normal errors, but also to exceptional errors such as the
375 
user interrupting <CODE>tcc</CODE> by pressing <CODE>^C</CODE>, or
376 
one of the compilation tools crashing. In the latter case, <CODE>tcc</CODE>
377 
will also remove any core file produced, unless the <B>-keep_errors</B>
378 
option is specified.<P>
379 
For purposes of configuration control, the <B>-version</B> flag will
380 
cause <CODE>tcc</CODE> to print its version number. This will typically
381 
be of the form:<P>
382 
<PRE>
383 
	tcc: Version: 4.0, Revision: 1.5, Machine: hp
384 
</PRE>
385 
giving the version and revision number, plus the target machine identifier.
386 
The <B>-V</B> flag will also cause each compilation tool to print
387 
its version number (if appropriate) as it is invoked.<P>
388 
<HR>
389 
<P><I>Part of the <A HREF="../index.html">TenDRA Web</A>.<BR>Crown
390 
Copyright &copy; 1998.</I></P>
391 
</BODY>
392 
</HTML>