| 2 |
7u83 |
1 |
<!-- Crown Copyright (c) 1998 -->
|
|
|
2 |
<HTML>
|
|
|
3 |
<HEAD>
|
|
|
4 |
<TITLE>tcc User's Guide: tcc Environments</TITLE>
|
|
|
5 |
</HEAD>
|
|
|
6 |
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000FF" VLINK="#400080" ALINK="#FF0000">
|
|
|
7 |
<A NAME=S14>
|
|
|
8 |
<H1>tcc User's Guide</H1>
|
|
|
9 |
<H3>January 1998</H3>
|
|
|
10 |
<A HREF="tcc6.html"><IMG SRC="../images/next.gif" ALT="next section"></A>
|
|
|
11 |
<A HREF="tcc4.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="#S15"><B>4.1</B> - The Environment Search Path</A><DD>
|
|
|
19 |
<DT><A HREF="#S16"><B>4.2</B> - The Default Environment: Configuring
|
|
|
20 |
tcc</A><DD>
|
|
|
21 |
<DT><A HREF="#S17"><B>4.3</B> - Using Environments to Specify APIs</A><DD>
|
|
|
22 |
<DT><A HREF="#S18"><B>4.4</B> - Using Environments to Implement tcc
|
|
|
23 |
Options</A><DD>
|
|
|
24 |
<DT><A HREF="#S19"><B>4.5</B> - User-Defined Environments</A><DD>
|
|
|
25 |
</DL>
|
|
|
26 |
|
|
|
27 |
<HR>
|
|
|
28 |
<H1>4. tcc Environments</H1>
|
|
|
29 |
In addition to command-line options, there is a second method of specifying
|
|
|
30 |
<CODE>tcc</CODE>'s behaviour, namely <CODE>tcc</CODE> environments.
|
|
|
31 |
An environment is just a file consisting of lines of the form:<P>
|
|
|
32 |
<PRE>
|
|
|
33 |
*IDENTIFIER "text"
|
|
|
34 |
</PRE>
|
|
|
35 |
where <CODE>*</CODE> stands for one of the environment prefixes, <CODE>+</CODE>,
|
|
|
36 |
<CODE><</CODE> and <CODE>></CODE>
|
|
|
37 |
(in fact <CODE>?</CODE> is also a valid environment prefix. It is
|
|
|
38 |
used to query the values represented by environmental identifiers.
|
|
|
39 |
If <CODE>tcc
|
|
|
40 |
</CODE> is invoked with the <B>-Ystatus</B> command-line option it
|
|
|
41 |
will print the values of all the environmental identifiers it recognises).
|
|
|
42 |
Any line in the environment not beginning with one of these characters
|
|
|
43 |
is ignored. <CODE>IDENTIFIER</CODE> will be one of the environmental
|
|
|
44 |
identifiers recognised by <CODE>tcc</CODE>, the environment prefix
|
|
|
45 |
will tell <CODE>tcc</CODE> how to modify the value given by this identifier,
|
|
|
46 |
and <CODE>text</CODE> what to modify it by.<P>
|
|
|
47 |
The simplest environmental identifiers are those which are used to
|
|
|
48 |
pass flags to <CODE>tcc</CODE> and the various components of the compilation
|
|
|
49 |
system. The line:<P>
|
|
|
50 |
<PRE>
|
|
|
51 |
+FLAG "text"
|
|
|
52 |
</PRE>
|
|
|
53 |
causes <CODE>text</CODE> to be interpreted by <CODE>tcc</CODE> as
|
|
|
54 |
if it was a command-line option. Similarly:<P>
|
|
|
55 |
<PRE>
|
|
|
56 |
+FLAG_TDFC "text"
|
|
|
57 |
</PRE>
|
|
|
58 |
causes <CODE>text</CODE> to be passed as an option to <CODE>tdfc</CODE>.
|
|
|
59 |
There are similar environmental identifiers for each of the components
|
|
|
60 |
of the compilation system (see 7.6</A> for a complete list).<P>
|
|
|
61 |
The second class of environmental identifiers are those corresponding
|
|
|
62 |
to simple string variables. Only the form:<P>
|
|
|
63 |
<PRE>
|
|
|
64 |
+IDENTIFIER "text"
|
|
|
65 |
</PRE>
|
|
|
66 |
is allowed. This will set the corresponding variable to <CODE>text</CODE>.
|
|
|
67 |
The permitted environmental identifiers and the corresponding variables
|
|
|
68 |
are:<BR>
|
|
|
69 |
<CODE>ENVDIR</CODE> the default environments directory (see section
|
|
|
70 |
4.1),<P>
|
|
|
71 |
<PRE>
|
|
|
72 |
MACHINE the target machine type (see section 4.2),
|
|
|
73 |
PORTABILITY the producer portability table (see section 5.1.3),
|
|
|
74 |
TEMP the default temporary directory (see section 6.4),
|
|
|
75 |
VERSION the target machine version (Mips only, see section 5.3.4).
|
|
|
76 |
</PRE>
|
|
|
77 |
The final class of environmental identifiers are those corresponding
|
|
|
78 |
to lists of strings. Firstly <CODE>text</CODE> is transformed into
|
|
|
79 |
a list of strings, b say, by splitting at any spaces, then the list
|
|
|
80 |
corresponding to the identifier, a say, is modified by this value.
|
|
|
81 |
How this modification is done depends on the environment prefix:<P>
|
|
|
82 |
<UL>
|
|
|
83 |
<LI>if the prefix is <CODE>+</CODE> then a = b,<P>
|
|
|
84 |
<LI>if the prefix is <CODE>></CODE> then a = a + b,<P>
|
|
|
85 |
<LI>if the prefix is <CODE><</CODE> then a = b + a,<P>
|
|
|
86 |
</UL>
|
|
|
87 |
where + denotes concatenation of lists. The lists represented in this
|
|
|
88 |
way include those giving the pathnames of the executables of the various
|
|
|
89 |
compilation components (plus default flags). These are given by the
|
|
|
90 |
identifiers <CODE>TDFC</CODE>, <CODE>TLD</CODE>, etc. (see 7.6 for
|
|
|
91 |
a complete list). The other lists can be divided between those affecting
|
|
|
92 |
the producer, the TDF linker, and the system linker respectively (see
|
|
|
93 |
sections 5.1, 5.2 and 5.5 for more details):<P>
|
|
|
94 |
<PRE>
|
|
|
95 |
INCL list of default producer include file directories (as <B>-I</B> options),
|
|
|
96 |
STARTUP list of default producer start-up files (as <B>-f</B> options),
|
|
|
97 |
STARTUP_DIR list of default producer start-up directories (as <B>-I</B> options),
|
|
|
98 |
|
|
|
99 |
LIB list of default TDF libraries (as <B>-l</B> options),
|
|
|
100 |
LINK list of default TDF library directories (as <B>-L</B> options),
|
|
|
101 |
|
|
|
102 |
CRT0 list of default initial .o files,
|
|
|
103 |
CRT1 second list of default initial .o files,
|
|
|
104 |
CRTN list of default final .o files,
|
|
|
105 |
SYS_LIB list of default system libraries (as <B>-l</B> options),
|
|
|
106 |
SYS_LIBC list of default standard system libraries (as <B>-l</B> options),
|
|
|
107 |
SYS_LINK list of default system library directories (as <B>-L</B> options).
|
|
|
108 |
</PRE>
|
|
|
109 |
<A NAME=S15>
|
|
|
110 |
<HR><H2>4.1. The Environment Search Path</H2>
|
|
|
111 |
The command-line option <B>-Y</B><I>env</I> tells <CODE>tcc</CODE>
|
|
|
112 |
to read the environment <I>env</I>. If <I>env</I> is not a full pathname
|
|
|
113 |
then it is searched for along the environment search path. This consists
|
|
|
114 |
of a colon-separated list of directories, the initial segment of which
|
|
|
115 |
is given by the system variable <CODE>TCCENV</CODE>
|
|
|
116 |
(we use the term "system variable" to describe <CODE>TCCENV</CODE>
|
|
|
117 |
rather than the more normal "environmental variable" to
|
|
|
118 |
avoid confusion with <CODE>tcc</CODE> environments) if this is defined,
|
|
|
119 |
and the final segment of which consists of the default environments
|
|
|
120 |
directory, which is built into <CODE>tcc</CODE>
|
|
|
121 |
at compile-time, and the current working directory. The option <B>-show_env</B>
|
|
|
122 |
causes <CODE>tcc</CODE> to print this environment search path. If
|
|
|
123 |
the environment cannot be found, then a warning is issued.<P>
|
|
|
124 |
<A NAME=S16>
|
|
|
125 |
<HR><H2>4.2. The Default Environment: Configuring tcc</H2>
|
|
|
126 |
The most important environment is the <CODE>default</CODE> environment,
|
|
|
127 |
which is built into <CODE>tcc</CODE> at compile-time. This does not
|
|
|
128 |
mean that the <CODE>default</CODE> environment is read every time
|
|
|
129 |
that <CODE>tcc</CODE> is invoked, but rather that it is read once
|
|
|
130 |
(at compile-time) to determine the default configuration of <CODE>tcc</CODE>.<P>
|
|
|
131 |
The information included in the <CODE>default</CODE> environment includes:
|
|
|
132 |
the pathnames and default flags of the various components of the compilation
|
|
|
133 |
system; the target machine type; the default temporary directory;
|
|
|
134 |
the specification of the target independent headers, TDF libraries
|
|
|
135 |
and system libraries comprising the default API (which is always ANSI);
|
|
|
136 |
the variables specifying the default compilation mode; the default
|
|
|
137 |
environments directory (mentioned above).<P>
|
|
|
138 |
The target machine type, defined by the <CODE>MACHINE</CODE> environmental
|
|
|
139 |
identifier, actually plays a very minor role in dealing with the very
|
|
|
140 |
real target dependency problems in <CODE>tcc</CODE>. These problems
|
|
|
141 |
are caused by the fact that <CODE>tcc</CODE> is designed to work on
|
|
|
142 |
many different target machines. All the information on where the executables,
|
|
|
143 |
include files, TDF libraries etc. are located on a particular machine
|
|
|
144 |
is stored in the standard environments, and in particular, the <CODE>default
|
|
|
145 |
</CODE> environment. The interaction with the system assembler and,
|
|
|
146 |
more importantly, the system linker is also expressed using environments.
|
|
|
147 |
The only target dependencies for which the machine type needs to be
|
|
|
148 |
known are genuine aberrations. For example, the TDF to Mips translator
|
|
|
149 |
and the Mips assembler are completely different from most other translator-assembler
|
|
|
150 |
pairs in that they pass two files, a <CODE>.G</CODE> and a <CODE>.T</CODE>
|
|
|
151 |
file, between them, rather than the more normal single <CODE>.s</CODE>
|
|
|
152 |
file. Thus it is important for <CODE>tcc</CODE> to know that the machine
|
|
|
153 |
type is Mips in this case (see section 5.3.4</A> for more details).<P>
|
|
|
154 |
<A NAME=S17>
|
|
|
155 |
<HR><H2>4.3. Using Environments to Specify APIs</H2>
|
|
|
156 |
Another important use of environments concerns their use in specifying
|
|
|
157 |
APIs. As was mentioned above, an API may be considered to have three
|
|
|
158 |
components: the target independent headers, giving an abstract description
|
|
|
159 |
of the API to the producer, and the TDF libraries and system libraries,
|
|
|
160 |
giving the details of the API implementation to the installer. Environments
|
|
|
161 |
are an ideal medium for expressing this information. The <CODE>INCL</CODE>
|
|
|
162 |
environmental identifier can be used to specify the location of the
|
|
|
163 |
target independent headers, <CODE>LIB</CODE> and <CODE>LINK</CODE>
|
|
|
164 |
the location of the TDF libraries, and <CODE>SYS_LIB</CODE> and <CODE>SYS_LINK
|
|
|
165 |
</CODE> the location of the system libraries. Moreover, all this information
|
|
|
166 |
can be canned into a single command-line option.<P>
|
|
|
167 |
A number of standard APIs have been described as target independent
|
|
|
168 |
headers and are provided with the TDF system. A <CODE>tcc</CODE> environment
|
|
|
169 |
is provided for each of these APIs (for example, <CODE>ansi</CODE>,
|
|
|
170 |
<CODE>posix</CODE>, <CODE>xpg3</CODE> - see 7.5</A> for a complete
|
|
|
171 |
list, also see section 6.3</A>). There is an important distinction
|
|
|
172 |
to be made between base APIs (for example, POSIX) and extension APIs
|
|
|
173 |
(for example, X11 Release 5). The command-line option <B>-Yposix</B>
|
|
|
174 |
sets the API to be precisely POSIX, whereas the option <B>-Yx5_lib</B>
|
|
|
175 |
sets it to the existing API plus the X11 Release 5 basic X library.
|
|
|
176 |
This is done by using <CODE>+INCL</CODE> etc. in the <CODE>posix</CODE>
|
|
|
177 |
environment to set the various variables corresponding to these environmental
|
|
|
178 |
identifiers to precisely the values for POSIX, but <CODE><INCL</CODE>
|
|
|
179 |
etc. in the <CODE>x5_lib</CODE> environment to extend these variables
|
|
|
180 |
by the values for X11 Release 5. Thus, to specify the API POSIX plus
|
|
|
181 |
X11 Release 5, the command-line options <B>-Yposix -Yx5_lib</B> are
|
|
|
182 |
required (in that order).<P>
|
|
|
183 |
All the standard API environments provided also contain lines which
|
|
|
184 |
set, or modify, the <CODE>INFO</CODE> environmental identifier. This
|
|
|
185 |
contains textual information on the API, including API names and version
|
|
|
186 |
numbers. This information can be printed by invoking <CODE>tcc</CODE>
|
|
|
187 |
with the <B>-info</B> command-line option. For example, the command-line
|
|
|
188 |
options:<P>
|
|
|
189 |
<PRE>
|
|
|
190 |
> tcc -info -Yposix -Yx5_lib
|
|
|
191 |
</PRE>
|
|
|
192 |
cause the message:<P>
|
|
|
193 |
<PRE>
|
|
|
194 |
tcc: API is X11 Release 5 Xlib plus POSIX (1003.1).
|
|
|
195 |
</PRE>
|
|
|
196 |
to be printed.<P>
|
|
|
197 |
As was mentioned above, the default API is ANSI. Thus invoking <CODE>tcc</CODE>
|
|
|
198 |
without specifying an API environment is equivalent to giving the
|
|
|
199 |
<B>-Yansi</B> command-line option. On the basis that, when it comes
|
|
|
200 |
to portability, explicit decisions are better than implicit ones,
|
|
|
201 |
the use of <B>-Yansi</B> is recommended.<P>
|
|
|
202 |
<A NAME=S18>
|
|
|
203 |
<HR><H2>4.4. Using Environments to Implement tcc Options</H2>
|
|
|
204 |
Another use to which environments are put is to implement certain
|
|
|
205 |
<CODE>tcc</CODE> command-line options. In particular, some options
|
|
|
206 |
require different actions depending on the target machine. It is far
|
|
|
207 |
easier to implement these by means of an environment, which can be
|
|
|
208 |
defined differently on each target machine, rather than by trying
|
|
|
209 |
to build all the alternative definitions into <CODE>tcc</CODE>.<P>
|
|
|
210 |
An important example is the <B>-g</B> flag, which causes the generation
|
|
|
211 |
of information for symbolic debugging. Depending on the target machine,
|
|
|
212 |
different flags may need to be passed to the assembler and system
|
|
|
213 |
linker when <B>-g</B> is specified, or the default <CODE>.o</CODE>
|
|
|
214 |
files and libraries used by the linker may need to be changed. For
|
|
|
215 |
this reason <CODE>tcc</CODE> uses a standard environment, <CODE>tcc_diag</CODE>,
|
|
|
216 |
to implement the <B>-g</B> option.<P>
|
|
|
217 |
For a complete list of those options which are implemented by means
|
|
|
218 |
of environments, see 7.7</A>. If the given option is not supported
|
|
|
219 |
on a particular target machine, then the corresponding environment
|
|
|
220 |
will not exist, and <CODE>tcc</CODE> will issue a warning to that
|
|
|
221 |
effect.<P>
|
|
|
222 |
<A NAME=S19>
|
|
|
223 |
<HR><H2>4.5. User-Defined Environments</H2>
|
|
|
224 |
The <CODE>tcc</CODE> user can also set up and use environments. It
|
|
|
225 |
is anticipated that this facility will be used mainly to group a number
|
|
|
226 |
of <CODE>tcc</CODE> command-line options into an environment using
|
|
|
227 |
the <CODE>FLAG</CODE> environmental identifier and to set up environments
|
|
|
228 |
corresponding to user-defined APIs.<P>
|
|
|
229 |
<HR>
|
|
|
230 |
<P><I>Part of the <A HREF="../index.html">TenDRA Web</A>.<BR>Crown
|
|
|
231 |
Copyright © 1998.</I></P>
|
|
|
232 |
</BODY>
|
|
|
233 |
</HTML>
|