2. TCC Environments
- 2.1. The Environment Search Path
- 2.2. The Default Environment: Configuring tcc
- 2.3. Using Environments to Specify APIs
- 2.4. Using Environments to Implement tcc Options
- 2.5. User-Defined Environments
In addition to command-line options, there is a second method of specifying TCC's behaviour, namely TCC environments.
An environment is just a file consisting of lines of the form:
*IDENTIFIER "text"
where * stands for one of the environment prefixes, +, < and > (in fact ? is also a valid environment prefix. It is used to query the values represented by environmental identifiers. If TCC is invoked with the -Ystatus 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. IDENTIFIER will be one of the environmental identifiers recognised by TCC, the environment prefix will tell TCC how to modify the value given by this identifier, and text what to modify it by.
The simplest environmental identifiers are those which are used to pass flags to TCC and the various components of the compilation system. The line:
+FLAG "text"
causes text to be interpreted by TCC as if it was a command-line option. Similarly:
+FLAG_TDFC "text"
causes text to be passed as an option to TDFC. There are similar environmental identifiers for each of the components of the compilation system (see 7.6 for a complete list).
The second class of environmental identifiers are those corresponding to simple string variables. Only the form:
+IDENTIFIER "text"
is allowed. This will set the corresponding variable to text. The permitted environmental identifiers and the corresponding variables are:
| Variable | Content |
|---|---|
ENVDIR | The default environments directory (see section 4.1) |
PORTABILITY | The producer portability table (see section 5.1.3) |
TEMP | The default temporary directory (see section 6.4) |
The final class of environmental identifiers are those corresponding to lists of strings. Firstly text 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:
| Prefix | Behaviour |
|---|---|
+ | a = b |
> | a = a + b |
< | a = b + a |
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 TDFC, TLD, 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):
| Variable | Content |
|---|---|
INCL | list of default producer include file directories (as -I options) |
STARTUP | list of default producer start-up files (as -f options) |
STARTUP_DIR | list of default producer start-up directories (as -I options) |
LIB | list of default TDF libraries (as -l options) |
LINK | list of default TDF library directories (as -L 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 -l options) |
SYS_LIBC | list of default standard system libraries (as -l options) |
SYS_LINK | list of default system library directories (as -L options) |
2.1. The Environment Search Path
The command-line option -Yenv tells TCC to read the environment env. If env 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 TCCENV (we use the term system variable
to describe TCCENV rather than the more normal environmental variable
to avoid confusion with TCC environments) if this is defined, and the final segment of which consists of the default environments directory, which is built into TCC at compile-time, and the current working directory. The option -vd causes TCC to print this environment search path. If the environment cannot be found, then a warning is issued.
2.2. The Default Environment: Configuring tcc
The most important environment is the default environment, which is built into TCC at compile-time. This does not mean that the default environment is read every time that TCC is invoked, but rather that it is read once (at compile-time) to determine the default configuration of TCC.
The information included in the default 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).
TCC 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 default environment. The interaction with the system assembler and, more importantly, the system linker is also expressed using environments.
2.3. Using Environments to Specify APIs
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 INCL environmental identifier can be used to specify the location of the target independent headers, LIB and LINK the location of the TDF libraries, and SYS_LIB and SYS_LINK the location of the system libraries. Moreover, all this information can be canned into a single command-line option.
By default, programs are checked against the standard ISO C API as specified in the ISO C standard Chapter 7. Other APIs are specified by passing the -Yapi-name flag to TCC, where api-name is one of the API designators listed below. APIs fall into two categories: base APIs and extension APIs. If more than one base API is specified to TCC, only the last one is used for checking; the others are ignored. Additional extension APIs, however, may be used in addition to any suitable base API.
A number of standard APIs have been described as target independent headers and are provided with the TDF system. A TCC environment is provided for each of these APIs (for example, ansi, posix, xpg3 - see 7.5 for a complete list, also see section 6.3). 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 -Yposix sets the API to be precisely POSIX, whereas the option -Yx5_lib sets it to the existing API plus the X11 Release 5 basic X library. This is done by using +INCL etc. in the posix environment to set the various variables corresponding to these environmental identifiers to precisely the values for POSIX, but <INCL etc. in the x5_lib 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 -Yposix -Yx5_lib are required (in that order).
All the standard API environments provided also contain lines which set, or modify, the INFO environmental identifier. This contains textual information on the API, including API names and version numbers. This information can be printed by invoking TCC with the -info command-line option. For example, the command-line options:
% tcc -info -Yposix -Yx5_lib
cause the message:
tcc: API is X11 Release 5 Xlib plus POSIX (1003.1).
to be printed.
As was mentioned above, the default API is C89. Thus invoking TCC without specifying an API environment is equivalent to giving the -Yc89 command-line option. On the basis that, when it comes to portability, explicit decisions are better than implicit ones, the use of -Yc89 is recommended.
2.4. Using Environments to Implement tcc Options
Another use to which environments are put is to implement certain TCC 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 TCC.
An important example is the -g 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 -g is specified, or the default .o files and libraries used by the linker may need to be changed. For this reason TCC uses a standard environment, tcc_diag, to implement the -g option.
For a complete list of those options which are implemented by means of environments, see 7.7. If the given option is not supported on a particular target machine, then the corresponding environment will not exist, and TCC will issue a warning to that effect.
2.5. User-Defined Environments
The TCC user can also set up and use environments. It is anticipated that this facility will be used mainly to group a number of TCC command-line options into an environment using the FLAG environmental identifier and to set up environments corresponding to user-defined APIs.