tcc User's Guide

January 1998

4.1 - The Environment Search Path
4.2 - The Default Environment: Configuring tcc
4.3 - Using Environments to Specify APIs
4.4 - Using Environments to Implement tcc Options
4.5 - User-Defined Environments

4. tcc 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:
ENVDIR the default environments directory (see section 4.1),

	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).

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:

if the prefix is + then a = b,
if the prefix is > then a = a + b,
if the prefix is < then 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):

	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).

4.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 -show_env causes tcc to print this environment search path. If the environment cannot be found, then a warning is issued.

4.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).

The target machine type, defined by the MACHINE environmental identifier, actually plays a very minor role in dealing with the very real target dependency problems in tcc. These problems are caused by the fact that 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. 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 .G and a .T file, between them, rather than the more normal single .s file. Thus it is important for tcc to know that the machine type is Mips in this case (see section 5.3.4 for more details).

4.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.

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 ANSI. Thus invoking tcc without specifying an API environment is equivalent to giving the -Yansi command-line option. On the basis that, when it comes to portability, explicit decisions are better than implicit ones, the use of -Yansi is recommended.

4.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.

4.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.