Blame | Last modification | View Log | RSS feed
<!-- Crown Copyright (c) 1998 -->
<HTML>
<HEAD>
<TITLE>tcc User's Guide: tcc Environments</TITLE>
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000FF" VLINK="#400080" ALINK="#FF0000">
<A NAME=S14>
<H1>tcc User's Guide</H1>
<H3>January 1998</H3>
<A HREF="tcc6.html"><IMG SRC="../images/next.gif" ALT="next section"></A>
<A HREF="tcc4.html"><IMG SRC="../images/prev.gif" ALT="previous section"></A>
<A HREF="tcc1.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="#S15"><B>4.1</B> - The Environment Search Path</A><DD>
<DT><A HREF="#S16"><B>4.2</B> - The Default Environment: Configuring
tcc</A><DD>
<DT><A HREF="#S17"><B>4.3</B> - Using Environments to Specify APIs</A><DD>
<DT><A HREF="#S18"><B>4.4</B> - Using Environments to Implement tcc
Options</A><DD>
<DT><A HREF="#S19"><B>4.5</B> - User-Defined Environments</A><DD>
</DL>
<HR>
<H1>4. tcc Environments</H1>
In addition to command-line options, there is a second method of specifying
<CODE>tcc</CODE>'s behaviour, namely <CODE>tcc</CODE> environments.
An environment is just a file consisting of lines of the form:<P>
<PRE>
*IDENTIFIER "text"
</PRE>
where <CODE>*</CODE> stands for one of the environment prefixes, <CODE>+</CODE>,
<CODE><</CODE> and <CODE>></CODE>
(in fact <CODE>?</CODE> is also a valid environment prefix. It is
used to query the values represented by environmental identifiers.
If <CODE>tcc
</CODE> is invoked with the <B>-Ystatus</B> command-line option it
will print the values of all the environmental identifiers it recognises).
Any line in the environment not beginning with one of these characters
is ignored. <CODE>IDENTIFIER</CODE> will be one of the environmental
identifiers recognised by <CODE>tcc</CODE>, the environment prefix
will tell <CODE>tcc</CODE> how to modify the value given by this identifier,
and <CODE>text</CODE> what to modify it by.<P>
The simplest environmental identifiers are those which are used to
pass flags to <CODE>tcc</CODE> and the various components of the compilation
system. The line:<P>
<PRE>
+FLAG "text"
</PRE>
causes <CODE>text</CODE> to be interpreted by <CODE>tcc</CODE> as
if it was a command-line option. Similarly:<P>
<PRE>
+FLAG_TDFC "text"
</PRE>
causes <CODE>text</CODE> to be passed as an option to <CODE>tdfc</CODE>.
There are similar environmental identifiers for each of the components
of the compilation system (see 7.6</A> for a complete list).<P>
The second class of environmental identifiers are those corresponding
to simple string variables. Only the form:<P>
<PRE>
+IDENTIFIER "text"
</PRE>
is allowed. This will set the corresponding variable to <CODE>text</CODE>.
The permitted environmental identifiers and the corresponding variables
are:<BR>
<CODE>ENVDIR</CODE> the default environments directory (see section
4.1),<P>
<PRE>
MACHINE the target machine type (see section 4.2),
PORTABILITY the producer portability table (see section 5.1.3),
TEMP the default temporary directory (see section 6.4),
VERSION the target machine version (Mips only, see section 5.3.4).
</PRE>
The final class of environmental identifiers are those corresponding
to lists of strings. Firstly <CODE>text</CODE> is transformed into
a list of strings, b say, by splitting at any spaces, then the list
corresponding to the identifier, a say, is modified by this value.
How this modification is done depends on the environment prefix:<P>
<UL>
<LI>if the prefix is <CODE>+</CODE> then a = b,<P>
<LI>if the prefix is <CODE>></CODE> then a = a + b,<P>
<LI>if the prefix is <CODE><</CODE> then a = b + a,<P>
</UL>
where + denotes concatenation of lists. The lists represented in this
way include those giving the pathnames of the executables of the various
compilation components (plus default flags). These are given by the
identifiers <CODE>TDFC</CODE>, <CODE>TLD</CODE>, etc. (see 7.6 for
a complete list). The other lists can be divided between those affecting
the producer, the TDF linker, and the system linker respectively (see
sections 5.1, 5.2 and 5.5 for more details):<P>
<PRE>
INCL list of default producer include file directories (as <B>-I</B> options),
STARTUP list of default producer start-up files (as <B>-f</B> options),
STARTUP_DIR list of default producer start-up directories (as <B>-I</B> options),
LIB list of default TDF libraries (as <B>-l</B> options),
LINK list of default TDF library directories (as <B>-L</B> options),
CRT0 list of default initial .o files,
CRT1 second list of default initial .o files,
CRTN list of default final .o files,
SYS_LIB list of default system libraries (as <B>-l</B> options),
SYS_LIBC list of default standard system libraries (as <B>-l</B> options),
SYS_LINK list of default system library directories (as <B>-L</B> options).
</PRE>
<A NAME=S15>
<HR><H2>4.1. The Environment Search Path</H2>
The command-line option <B>-Y</B><I>env</I> tells <CODE>tcc</CODE>
to read the environment <I>env</I>. If <I>env</I> is not a full pathname
then it is searched for along the environment search path. This consists
of a colon-separated list of directories, the initial segment of which
is given by the system variable <CODE>TCCENV</CODE>
(we use the term "system variable" to describe <CODE>TCCENV</CODE>
rather than the more normal "environmental variable" to
avoid confusion with <CODE>tcc</CODE> environments) if this is defined,
and the final segment of which consists of the default environments
directory, which is built into <CODE>tcc</CODE>
at compile-time, and the current working directory. The option <B>-show_env</B>
causes <CODE>tcc</CODE> to print this environment search path. If
the environment cannot be found, then a warning is issued.<P>
<A NAME=S16>
<HR><H2>4.2. The Default Environment: Configuring tcc</H2>
The most important environment is the <CODE>default</CODE> environment,
which is built into <CODE>tcc</CODE> at compile-time. This does not
mean that the <CODE>default</CODE> environment is read every time
that <CODE>tcc</CODE> is invoked, but rather that it is read once
(at compile-time) to determine the default configuration of <CODE>tcc</CODE>.<P>
The information included in the <CODE>default</CODE> environment includes:
the pathnames and default flags of the various components of the compilation
system; the target machine type; the default temporary directory;
the specification of the target independent headers, TDF libraries
and system libraries comprising the default API (which is always ANSI);
the variables specifying the default compilation mode; the default
environments directory (mentioned above).<P>
The target machine type, defined by the <CODE>MACHINE</CODE> environmental
identifier, actually plays a very minor role in dealing with the very
real target dependency problems in <CODE>tcc</CODE>. These problems
are caused by the fact that <CODE>tcc</CODE> is designed to work on
many different target machines. All the information on where the executables,
include files, TDF libraries etc. are located on a particular machine
is stored in the standard environments, and in particular, the <CODE>default
</CODE> environment. The interaction with the system assembler and,
more importantly, the system linker is also expressed using environments.
The only target dependencies for which the machine type needs to be
known are genuine aberrations. For example, the TDF to Mips translator
and the Mips assembler are completely different from most other translator-assembler
pairs in that they pass two files, a <CODE>.G</CODE> and a <CODE>.T</CODE>
file, between them, rather than the more normal single <CODE>.s</CODE>
file. Thus it is important for <CODE>tcc</CODE> to know that the machine
type is Mips in this case (see section 5.3.4</A> for more details).<P>
<A NAME=S17>
<HR><H2>4.3. Using Environments to Specify APIs</H2>
Another important use of environments concerns their use in specifying
APIs. As was mentioned above, an API may be considered to have three
components: the target independent headers, giving an abstract description
of the API to the producer, and the TDF libraries and system libraries,
giving the details of the API implementation to the installer. Environments
are an ideal medium for expressing this information. The <CODE>INCL</CODE>
environmental identifier can be used to specify the location of the
target independent headers, <CODE>LIB</CODE> and <CODE>LINK</CODE>
the location of the TDF libraries, and <CODE>SYS_LIB</CODE> and <CODE>SYS_LINK
</CODE> the location of the system libraries. Moreover, all this information
can be canned into a single command-line option.<P>
A number of standard APIs have been described as target independent
headers and are provided with the TDF system. A <CODE>tcc</CODE> environment
is provided for each of these APIs (for example, <CODE>ansi</CODE>,
<CODE>posix</CODE>, <CODE>xpg3</CODE> - see 7.5</A> for a complete
list, also see section 6.3</A>). There is an important distinction
to be made between base APIs (for example, POSIX) and extension APIs
(for example, X11 Release 5). The command-line option <B>-Yposix</B>
sets the API to be precisely POSIX, whereas the option <B>-Yx5_lib</B>
sets it to the existing API plus the X11 Release 5 basic X library.
This is done by using <CODE>+INCL</CODE> etc. in the <CODE>posix</CODE>
environment to set the various variables corresponding to these environmental
identifiers to precisely the values for POSIX, but <CODE><INCL</CODE>
etc. in the <CODE>x5_lib</CODE> environment to extend these variables
by the values for X11 Release 5. Thus, to specify the API POSIX plus
X11 Release 5, the command-line options <B>-Yposix -Yx5_lib</B> are
required (in that order).<P>
All the standard API environments provided also contain lines which
set, or modify, the <CODE>INFO</CODE> environmental identifier. This
contains textual information on the API, including API names and version
numbers. This information can be printed by invoking <CODE>tcc</CODE>
with the <B>-info</B> command-line option. For example, the command-line
options:<P>
<PRE>
> tcc -info -Yposix -Yx5_lib
</PRE>
cause the message:<P>
<PRE>
tcc: API is X11 Release 5 Xlib plus POSIX (1003.1).
</PRE>
to be printed.<P>
As was mentioned above, the default API is ANSI. Thus invoking <CODE>tcc</CODE>
without specifying an API environment is equivalent to giving the
<B>-Yansi</B> command-line option. On the basis that, when it comes
to portability, explicit decisions are better than implicit ones,
the use of <B>-Yansi</B> is recommended.<P>
<A NAME=S18>
<HR><H2>4.4. Using Environments to Implement tcc Options</H2>
Another use to which environments are put is to implement certain
<CODE>tcc</CODE> command-line options. In particular, some options
require different actions depending on the target machine. It is far
easier to implement these by means of an environment, which can be
defined differently on each target machine, rather than by trying
to build all the alternative definitions into <CODE>tcc</CODE>.<P>
An important example is the <B>-g</B> flag, which causes the generation
of information for symbolic debugging. Depending on the target machine,
different flags may need to be passed to the assembler and system
linker when <B>-g</B> is specified, or the default <CODE>.o</CODE>
files and libraries used by the linker may need to be changed. For
this reason <CODE>tcc</CODE> uses a standard environment, <CODE>tcc_diag</CODE>,
to implement the <B>-g</B> option.<P>
For a complete list of those options which are implemented by means
of environments, see 7.7</A>. If the given option is not supported
on a particular target machine, then the corresponding environment
will not exist, and <CODE>tcc</CODE> will issue a warning to that
effect.<P>
<A NAME=S19>
<HR><H2>4.5. User-Defined Environments</H2>
The <CODE>tcc</CODE> user can also set up and use environments. It
is anticipated that this facility will be used mainly to group a number
of <CODE>tcc</CODE> command-line options into an environment using
the <CODE>FLAG</CODE> environmental identifier and to set up environments
corresponding to user-defined APIs.<P>
<HR>
<P><I>Part of the <A HREF="../index.html">TenDRA Web</A>.<BR>Crown
Copyright © 1998.</I></P>
</BODY>
</HTML>