The TCC Users' Guide

1.1. Specifying the API

As we have seen, the API plays a far more concrete role in the TDF compilation strategy than in the traditional scheme. Therefore the API needs to be explicitly specified to TCC before any compilation takes place. As can be seen from Fig. 3, the API has three components. Firstly, in the target independent (or production) half of the compilation, there are the target independent headers which describe the API. Secondly in the target dependent (or installation) half, there is the API implementation for the particular target machine. This is divided between the TDF libraries, derived from the system headers, and the system libraries. Specifying the API to TCC essentially consists of telling it what target independent headers, TDF libraries and system libraries to use. The precise way in which this is done is discussed below (in section 4.3).

1.2. The Main Compilation Path

Once the API has been specified, the actual compilation can begin. The default action of TCC is to perform production and installation consecutively on the same machine; any other action needs to be explicitly specified. So let us describe the entire compilation path from C source to executable shown in Fig. 3.

1. The first stage is production. The C → TDF producer transforms each input C source file into a target independent TDF capsule, using the target independent headers to describe the API in abstract terms. These target independent capsules will contain tokens to represent the uses of objects from the API, but these tokens will be left undefined.

2. The second stage, which is also the first stage of the installation, is TDF linking. Each target independent capsule is combined with the TDF library describing the API implementation to form a target dependent TDF capsule. Recall that the TDF libraries contain the local definitions of the tokens left undefined by the producer, so the resultant target dependent capsule will contain both the uses of these tokens and the corresponding token definitions.

3. The third stage of the compilation is for the TDF translator to transform each target dependent TDF capsule into an assembly source file for the appropriate target machine. Some TDF translators output not an assembly source file, but a binary object file. In this case the following assembler stage is redundant and the compilation skips to the system linking.

4. The next stage of the compilation is for each assembly source file to be translated into a binary object file by the system assembler.

5. The final compilation phase is for the system linker to combine all the binary object files with the system libraries to form a single, final executable. Recall that the system libraries are the final constituent of the API implementation, so this stage completes the combination of the program with the API implementation started in stage 2).

Let us, for convenience, tabulate these stages, giving the name of each compilation tool (plus the corresponding executable name), a code letter which TCC uses to refer to this stage, and the input and output file types for the stage (also see 7.2).

The executable name of the TDF translator varies, depending on the target machine. It will normally start, or end, however, in trans. These stages are documented in more detail in sections 5.1 to 5.5.

The code letters for the various compilation stages can be used in the -Wtool, opt, ... command-line option to TCC. This passes the option(s) opt directly to the executable in the compilation stage identified by the letter tool. For example, -Wl, -x will cause the system linker to be invoked with the -x option. Similarly the -Etool: file allows the executable to be invoked at the compilation stage tool to be specified as file. This allows the TCC user access to the compilation tools in a very direct manner.

1.3. Input File Types

This compilation path may be joined at any point, and terminated at any point. The latter possibility is discussed below. For the former, TCC determines, for each input file it is given, to which of the file types it knows (C source, target independent TDF, etc.) this file belongs. This determines where in the compilation path described this file will start. The method used to determine the type of a file is the normal filename suffix convention:

Files whose type cannot otherwise be determined are assumed to be binary object files (for a complete list see 7.1).

Thus, for example, we speak of .j files as a shorthand for target independent TDF capsules. Each file type recognised by TCC is assigned an identifying letter. For convenience, this corresponds to the suffix identifying the file type (c for C source files, j for target independent TDF capsules etc.).

There is an alternative method of specifying input files, by means of the -Stype, file, ... command-line option. This specifies that the file file should be treated as an input file of the type corresponding to the letter type, regardless of its actual suffix. Thus, for example, -Sc, file specifies that file should be regarded as a C source (or .c) file.

1.4. Intermediate and Output Files

During the compilation, TCC makes up names for the output files of each of the compilation phases. These names are based on the input file name, but with the input file suffix replaced by the output file suffix (unless the -make_up_names command-line option is given, in which case the intermediate files are given names of the form _tccnnnn.x, where nnnn is a number which is incremented for each intermediate file produced, and x is the suffix corresponding to the output file type). Thus if the input file file.c is given, this will be transformed into file.j by the producer, which in turn will be transformed into file.t by the TDF linker, and so on. The system linker output file name can not be deduced in the same way since it is the result of linking a number of .o files. By default, as with CC, this file is called a.out.

For most purposes these intermediate files are not required to be preserved; if we are compiling a single C source file to an executable, then the only output file we are interested in is the executable, not the intermediate files created during the compilation process. For this reason TCC creates a temporary directory in which to put these intermediate files, and removes this directory when the compilation is complete. All intermediate files are put into this temporary directory except:

• those which are an end product of the compilation (such as the executable),

• those which are explicitly ordered to be preserved by means of command-line options,

• binary object files, when more than one such file is produced (this is for compatibility with CC).

TCC can be made to preserve intermediate files of various types by means of the -Ptype... command-line option, which specifies a list of letters corresponding to the file types to be preserved. Thus for example -Pjt specifies that all TDF capsules produced, whether target independent or target dependent, (i.e. all .j and .t files) should be preserved. The special form -Pa specifies that all intermediate files should be preserved. It is also possible to specify that a certain file type should not be preserved by preceding the corresponding letter by - in the -P option. The only really useful application of this is to use -P-o to cancel the CC convention on preserving binary object files mentioned above.

By default, all preserved files are stored in the current working directory. However the -work dir command-line option specifies that they should be stored in the directory dir.

The compilation can also be halted at any stage. The -Ftype option to TCC tells it to stop the compilation after creating the files of the type corresponding to the letter type. Because any files of this type which are produced will be an end product of the compilation, they will automatically be preserved. For example, -Fo halts the compilation after the creation of the binary object, or .o, files (i.e. just before the system linking), and preserves all such files produced. A number of other TCC options are equivalent to options of the form -Ftype:

If more than one -F option (including the equivalent options just listed) is given, then TCC issues a warning. The stage coming first in the compilation path takes priority.

If the compilation has precisely one end product output file, then the name of this file can be specified to be file by means of the -o file command-line option. If a -o file option is given when there is more than one end product, then the first such file produced will be called file, and all such files produced subsequently will cause TCC to issue a warning.

1.5. Other Compilation Paths

So far we have been discussing the main TCC compilation path from C source to executable. This is however only part of the picture. The full complexity (almost) of all the possible compilation paths supported by TCC is shown in Fig. 4. This differs from Fig. 3 in that it only shows the left hand, or program, half of the main compilation diagram. The solid arrows show the default compilation paths; the dashed arrows are only followed if TCC is so instructed by means of command-line options. Let us consider those paths in this diagram which have not so far been mentioned.

To summarise, TCC has an extra three file types, and an extra three compilation tools (not including the TDF archive creating and splitting routines which are built into TCC). These are:

and:

(see 7.1 and 7.2 for complete lists).

1.6. Finding out what tcc is doing

With so many different file types and alternative compilation paths, it is often useful to be able to keep track of what TCC is doing. There are several command-line options which do this. The simplest is -v which specifies that TCC should print each command in the compilation process on the standard output before it is executed. The -vb option is similar, but only causes the name of each input file to be printed as it is processed. Finally the -dry option specifies that the commands should be printed (as with -v) but not actually executed. This can be used to experiment with TCC to find out what it would do in various circumstances.

Occasionally an unclear error message may be printed by one of the compilation tools. In this case the -show_errors option to TCC might be useful. It causes TCC to print the command it was executing when the error occurred. By default, if an error occurs during the construction of an output file, the file is removed by TCC. It can however be preserved for examination using the -keep_errors option. This applies not only to normal errors, but also to exceptional errors such as the user interrupting TCC by pressing ^C, or one of the compilation tools crashing. In the latter case, TCC will also remove any core file produced, unless the -keep_errors option is specified.

For purposes of configuration control, the -version flag will cause TCC to print its version number. This will typically be of the form:

tcc: Version: 4.0, Revision: 1.5, Machine: hp

giving the version and revision number, plus the target machine identifier. The -V flag will also cause each compilation tool to print its version number (if appropriate) as it is invoked.

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.

3.1. The C to TDF Producer

We now turn to the individual components of the TDF system. Most of the command-line options to TCC so far discussed have been concerned with controlling the behaviour of TCC itself. Another, even more important, class of options concern the ways in which the behaviour of the components can be specified. The -Wtool, opt, ... command-line option for communicating directly with the components has already been mentioned. This however is not recommended for normal purposes; the other TCC command-line options give a more controlled access to the components.

The first component to be considered is the C → TDF producer, TDFC. This translates an input C source file (a .c file or a .i file) into a output target independent TDF capsule (a .j file).

#include "file"

#pragma TenDRA begin
#pragma TenDRA directive ident allow
#pragma TenDRA unknown escape warning
#pragma TenDRA implicit function declaration warning
#pragma TenDRA incompatible void return warning

3.2. The TDF Linker

The next component of the system to be considered is the TDF linker, TLD. This is used to combine several TDF capsules or TDF libraries into a single TDF capsule. It is put to two distinct purposes in the TCC compilation scheme. Firstly, in the main compilation path, it is used in the installer half to combine a target independent TDF capsule (a .j file) with the TDF libraries representing the API implementation on the target machine, to form a target dependent TDF capsule (a .t file). Secondly, if the -M option is given to TCC, it is used in the producer half to combine all the target independent TDF capsules (.j files) into a single target independent capsule. Let us consider these two cases separately.

% tcc -Ymakelib -o a.tl a.j b.j c.j

3.3. The TDF to Target Translator

The next compilation tool to be considered is the TDF translator. This translates an input target dependent TDF capsule (.t file) into an assembly source file (.s) file for the appropriate target machine. This is the main code generation phase of the compilation process; most of the optimisation of code which occurs happens in the translator (some machines also have optimising assemblers).

Although referred to by the generic name of trans, the TDF translators for different target machines in fact have different names. The main division between translators is in the supported processor. However, operating system dependent features such as the precise form of the assembler input, and the symbolic debugger to be supported, may also cause different versions of the basic translator to be required for different machines of the same processor group. The current generation of translators includes the following:

• The TDF → i386/i486 translator is called trans386. This exists in two versions, one running on SVR4.2 and one on SCO. The two versions differ primarily in the symbolic debugger they support. trans386 has also been ported to several other i386-based machines, including MS-DOS.

• The TDF → Sparc (Version 7) translator is called sparctrans. This again exists in two versions, one running on SVR4.2 and one on SunOS and Solaris 1. These versions again differ primarily in the symbolic debugger supported.

• The TDF → Mips (R2000/R3000, little-endian) translator is called mipstrans. This differs from the other translators in that instead of outputting a single .s file, it outputs two files, a binasm file (with a .G suffix) and a symbol table file (with a .T suffix). This is discussed in more detail below. mipstrans runs on Ultrix, but again has two versions. One runs on Ultrix 4.1 and earlier, the other on 4.2 and later. This necessary because of a change in the format of the binasm file between these two releases.

• The TDF → 68030/68040 translator also exists in two versions. One runs on HP-UX and is called hptrans; the other runs on NeXTStep and is called nexttrans (however the NeXT is not a supported platform because of its lack of standard API coverage). These differ, not only in the symbolic debugger supported, but also in the format of the assembly source output.

This list is not intended to be definitive. Development work is proceeding on new translators all the time. Existing translators are also updated to support new operating systems releases when this is necessary.

3.4. The System Assembler

The system assembler is the stage in the TCC compilation path which is likely to be of least interest to normal users. The assembler translates an assembly source (or .s) file into a binary object (or .o) file. (The exception to this is the Mips auxiliary assembler discussed above.) Most assemblers are straight translation phases, although some also offer peephole optimisation and scheduling facilities. No TCC command-line options are directly concerned with the assembler, however options can be passed to it directly by means of the -Wa, opt, ... command-line option.

3.5. The System Linker

The final stage in the main TCC compilation path is the system linking. The system linker, ld, combines all the binary object files with the system libraries to form a final executable image. By default this executable is called a.out, although this can be changed using the -o command-line option to TCC. In terms of the differences between target machines, the system linker is the most complex of the tools which are controlled by TCC. Our discussion can be divided between those aspects of the linker's behaviour which are controlled by TCC environments, and those which are controlled by command-line options.

3.6. The C Preprocessor

The TDF C preprocessor, TDFCPP, is invoked only when TCC is passed the -E or -P command-line option, as described in section 3.5.1. These both cause all input .c files to be preprocessed, but in the former case the output is send to the standard output, whereas in the latter it is send to the corresponding .i files.

The TDF system differs from most C compilation systems in that preprocessing is an integral part of the producer, TDFC, rather than a preliminary textual substitution phase. This is because of difficulties involved with trying to perform the preprocessing in a target independent manner. Therefore TDFCPP is merely a modified version of TDFC which halts after the preprocessing phase and prints what it has read. This means that the TDFCPP output, while being equivalent to its input, will not correspond at the textual level to the degree which is normal in C preprocessors.

3.7. The TDF Pretty Printer

The TDF pretty printer, disp, and the TDF notation compiler, TNC, have already been discussed in some detail in section 3.5.3. The TDF decoding command-line options, -disp and -disp_t, cause respectively all .j files and all .t files to be decoded into .p files. This decoding is done using disp by default, and with TNC -p if the -Ytnc command-line option is specified. The -Ytnc option also causes any input .p files to be encoded into .j files by TNC.

The pretty printer, disp, can be used as a useful check that a given .j or .t file is a legal TDF capsule. The TDF decoding routines in the TDF linker and the TDF translator assume that their input is a legal capsule. The pretty printer performs more checks and has better diagnostics for illegal capsules. By default disp only decodes capsule units which belong to "core" TDF. Options to decode other unit types can be passed directly to disp by means of the -Wd, opt, ... command-line option to TCC. The potentially useful disp options include:

The manual page for disp should be consulted for more details.

The TDF notation compiler, TNC, is fully documented in [4].

3.8. The TDF Archiver

A TDF archive is a TCC-specific form intended for software distribution. It consists of a set of target independent TDF capsules (.j files) and a set of TCC command-line options. It is intended that a TDF archive can be produced on one machine, and distributed to, and installed on, a number of target machines.

If a TDF archive is given as an input file to TCC (it will be recognised by its .ta suffix), then it is split into its constituent capsules and options. The options are interpreted as if they had been given on the command-line (unless the -WJ, -no_options flag is specified), and the capsules are treated as input files in the normal way. The archive splitting and archive building routines are both built into TCC; there is no separate TDF archiver tool. Options passed to the archiver using -WJ, opt are interpreted by TCC.

In order to specify that a TDF archive should be created, the -prod flag should be used. This specifies that all target independent capsules (.j files) and all options opt given by a TCC option of the form -WI, opt, ... should be combined into a TDF archive. The compilation process halts after producing this archive. By default the TDF archive created is called a.ta, but this can be changed using the -o option. Normally the names of the capsules comprising the archive are inserted into the archive, but this may be suppressed by the use of the -WJ, -no_names option.

As an example of the kind of option that might be included in an archive, suppose that the production has been done using the POSIX API. Then the installation should also be done using this same API. Alternatively expressed, if a TDF archive has been constructed using the posix environment, then the -Yposix flag should be included in the archive to ensure that the installation also takes place in this same environment. In fact the environments describing the standard APIs have been set up so that this happens automatically. For example, the posix environment contains the line:

+FLAG "-WI,-Yposix"

Another kind of option that it might be useful to include in an archive is a -lstr option. In this way all the information on the install-time options can be specified at produce-time.

A final example of an option which might be included in an archive is the -message option. The command-line option -message str causes TCC to print the message str with any @ characters in str replaced by spaces (there are problems with escaping spaces). So, by using the command-line option:

-WI,-message"Installing@TDF@archive@..."

one can produce an archive which prints a message as it is installed. This option is also useful in environments. By inserting the line:

+FLAG "-message Reading@tcc@environment@..."

one can produce an environment which prints a message whenever it is read.

4.1. Intermodular Checks

All of the extra compiler checks described in section 5.1.3 refer to a single C source file, however TCC also has support for a number of intermodular checks. These checks are enabled by means of the -im command-line option. This causes the producer to create for each C source file, in addition to its TDF capsule output file, a second output file, called a C spec file, containing a description of the C objects declared in that file. This C spec file is kept associated with the target independent TDF as it is transformed to a target dependent capsule, an assembly source file, and a binary object file. When these binary object files are linked then the associated C spec files are also linked using the C spec linker, spec_linker, into a single C spec file. This file is named a.k by default. It is this linking process which constitutes the intermodular checking (in fact spec_linker may also be invoked at the TDF merging level when the -M option is used).

When intermodular checks are specified, TCC will also recognise input files with a .k suffix as C spec files and pass them to the C spec linker.

The nature of the association between a C spec file and its binary object file needs discussion. While these files are internal to a single call of TCC it can keep track of the association, however if the compilation is halted before linking it needs to preserve this association. For example in:

% tcc -im -c a.c

the binary object file a.o and the C spec file a.k need to be kept together. This is done by forming them into a single archive file named a.o. When a.o is subsequently linked, TCC recognises that it is an archive and splits it into its two components, one of which it passes to the system linker, and one to the C spec linker.

Intermodular checking is described in more detail in [3]. In tcc -ch intermodular checking is on by default, but may be switched off using -im0.

4.2. Debugging and Profiling

TCC supports options for both symbolic debugging using the target machine's default debugger, and profiling using prof on those machines which have it.

The -g command-line option causes the producer to output extra debugging information in its output TDF capsule, and the TDF translator to translate this information into the appropriate assembler directives for its supported debugger (for details of which debuggers are supported by which translators, consult the appropriate manual pages).

For the translator to have all the diagnostic information it requires, not only the TDF capsules output by the producer, but also those linked in by the TDF linker from the TDF libraries, need to contain this debugging information. This is ensured for the standard TDF libraries by having two versions of each library, one containing diagnostics and one not.

By default the environmental identifier LINK, which gives the directories which the TDF linker should search, is set so that the non-diagnostic versions are found. However the -g option modifies LINK so that the diagnostic versions are found first.

Depending on the target machine, the -g option may also need to modify the behaviour of the system assembler and the system linker. Like all potentially target dependent options, -g is implemented by means of a standard environment, in this case tcc_diag.

The -p option is likewise implemented by means of a standard environment, tcc_prof. It causes the producer to output extra information on the names of statically declared objects, and the TDF translator to output assembler directives which enable prof to profile the number of calls to each procedure (including static procedures). The behaviour of the system assembler and system linker may also be modified by -p, depending on the target machine.

4.3. The System Environment

In section 4.3 we discussed how TCC environments can be used to specify APIs. There is one API environment however which is so exceptional that it needs to be treated separately. This is the system environment, which specifies that TCC should emulate CC on the machine on which it is being run.

The system environment specifies that TCC should use the system headers directory, /usr/include, as its default include file directory, and should define all the machine dependent macros which are built into CC. It will also specify the 32-bit portability table on 32-bit machines.

Despite the differences from the normal API environments, the system environment is indeed specifying an API, namely the system headers and libraries on the host machine. This means that the .j files produced when using this environment are only target independent in the sense that they can be ported successfully to machines which have the exactly the same system headers and predefined macros.

Using the system headers is fraught with difficulties. In particular, they tend to be very CC-specific. It is often necessary to use the -not_ansi and -nepc options together with -Ysystem merely to negotiate the system headers. Even then, TCC may still reject some constructs. Of course, the number of problems encountered will vary considerably between different machines.

To conclude, the system environment is at best only suitable for experimental compilation. There are also potential problems involved with its use. It should therefore be used with care.

4.4. The Temporary Directory

As we have said, TCC creates a temporary directory in which to put all the intermediate files which are created, but are not to be preserved. By default, these intermediate files are left in the temporary directory until the end of the compilation, when the temporary directory is removed. However, if disk space is short, or a particularly large compilation is taking place, the -tidy command-line option may be appropriate. This causes TCC to remove each unwanted intermediate file immediately when it is no longer required.

The name of the temporary directory created by TCC to store the intermediate files is generated by the system library routine tempnam. It takes the form TEMP/tcc????, where TEMP is the main TCC temporary directory, and ???? is an automatically generated unique suffix. There are three methods of specifying TEMP, listed in order of increasing precedence:

1. by the TEMP environmental identifier (usually in the default environment),

2. by the -temp dir command-line option,

3. by the TMPDIR system variable.

Normally TEMP will be a normal temporary directory, /tmp or /usr/tmp for example, but any directory to which the user has write permission may be used. In general, the more spare disk space which is available in TEMP, the better.