tcc User's Guide

The first paths to be considered involve preprocessed C source files. These form a distinct file type which tcc recognises by means of the .i file suffix. Input .i files are treated in exactly the same way as .c files; that is, they are fed into the producer.

tcc can be made to preprocess the C source files it is given by means of the -P and -E options. If the -P option is given then each .c file is transformed into a corresponding .i file by the TDF C preprocessor, tdfcpp . If the -E option is given then the output of tdfcpp is sent instead to the standard output. In both cases the compilation halts after the preprocessor has been applied. Preprocessing is discussed further in section 5.6.

The second new file type introduced in Fig. 4 is the TDF archive. This is recognised by tcc by means of the .ta file suffix. Basically a TDF archive is a set of target independent TDF capsules (this is slightly simplified, see section 5.2.3 for more details). Any input TDF archives are automatically split into their constituent target independent capsules. These then join the main compilation path in the normal way.

In order to create a TDF archive, tcc must be given the -prod command-line option. It will combine all the target independent TDF capsules it has into an archive, and the compilation will then halt. By default this archive is called a.ta, but another name may be specified using the -o option.

The routines for splitting and building TDF archives are built into tcc, and are not implemented by a separate compilation tool (in particular, TDF archives are not ar archives). Really TDF archives are a tcc-specific construction; they are not part of TDF proper.

TDF has the form of an abstract syntax tree which is encoded as a series of bits. In order to examine the contents of a TDF capsule it is necessary to translate it into an equivalent human readable form. Two tools are provided which do this. The TDF pretty printer, disp, translates TDF into text, whereas the TDF notation compiler, tnc, both translates TDF to text and text to TDF. The two textual forms of TDF are incompatible - disp output cannot be used as tnc input. disp is in many ways the more sophisticated decoder - it understands the TDF extensions used to handle diagnostics, for example - but it does not handle the text to TDF translation which tnc does. By default tnc is a text to TDF translator, it needs to be passed the -p flag in order to translate TDF into text. We refer to the textual form of TDF supported by tnc as TDF notation.

By default, tcc uses disp. If it is given the -disp command-line option then all target independent TDF capsules (.j files) are transformed into text using disp . The -disp_t option causes all target dependent TDF capsules (.t files) to be transformed into text. In both cases the output files have a .p suffix, and the compilation halts after they are produced.

In order for tnc to be used, the -Ytnc flag should be passed to tcc. In this case the -disp and the -disp_t option cause, not disp, but tnc -p, to be invoked. But this flag also causes tcc to recognise files with a .p suffix as TDF notation source files. These are translated by tnc into target independent TDF capsules, which join the main compilation path in the normal way.

Similarly if the -Ypl_tdf flag is passed to tcc then it recognises files with a .pl suffix as PL_TDF source files. These are translated by the PL_TDF compiler, pl, into target independent TDF capsules.

disp and tnc are further discussed in section 5.7.

The final unexplored path in Fig. 4 is the ability to combine all the target independent TDF capsules into a single capsule. This is specified by means of the -M command-line option to tcc. The combination of these capsules is performed by the TDF linker, tld. Whereas in the main compilation path tld is used to combine a single target independent TDF capsule with the TDF libraries to form a target dependent TDF capsule, in this case it is used to combine several target independent capsules into a single target independent capsule. By default the combined capsule is called a.j. The compilation will continue after the combination phase, with the resultant capsule rejoining the main compilation path. This merging operation is further discussed in section 5.2.2.

The only unresolved issue in this case is, if the -M option is given, to what .j files do the -Fj and the -Pj options refer? In fact, tcc takes them to refer to the merged TDF capsule rather than the capsules which are merged to form it. The -Pa option, however, will cause both sets of capsules to be preserved.

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

The most important producer options are those which tell it where to search for files included using a #include preprocessing directive. As with cc, the user can specify a directory, dir, to search for these files using the -Idir command-line option. However, unlike cc, the producer does not search /usr/include as default. Instead, the default search directories are those containing the target independent headers for the API selected, as given by the INCL identifier in the environment describing the API. In addition, the directories to search for the default start-up files (see below), as given by the STARTUP_DIR environmental identifier, are also passed to the producer.

If the -H option is passed to tcc then it will cause the producer to print the name of each file it opens. This is often helpful if a multiplicity of -I options leads to confusion.

The producer has a useful feature of start-up and end-up files. The tcc command-line option -ffile is equivalent to inserting the line:

            #include "file"
           

at the start of each input C source file. Similarly -efile is equivalent to inserting this line at the end of each such file. These included files are searched for along the directories specified by the -I options in the normal manner.

tcc generates a producer start-up file, called tcc_startup.h , in order to implement certain command-line options. The cc-compatible options:

            -Dname
            -Dname=value
            -Uname
            -Astr
           

are translated into the lines:

            #define name 1
            #define name value
            #undef name
            #assert str
           

respectively. tcc does not check that these lines are valid C preprocessing directives since this will be done by the producer. So any producer error message referring to tcc_startup.h is likely actually to refer to the -D, -U and -A command-line options. In case of difficulties, tcc_startup.h can be preserved for closer examination using the -Ph option to tcc.

There may be default start-up options specified by the STARTUP environmental identifier. The purpose of these is discussed below. The order the start-up options are passed to the producer is: firstly, the default start-up options; secondly, the start-up option for the tcc built-in start-up file, tcc_startup.h; thirdly, any command-line start-up options. (For technical reasons, a -no_startup_options command-line option is provided which causes no start-up or end-up options to be passed to tdfc. This is not likely to prove useful in normal use.

We have already described how one aspect of the compilation environment, the API, is specified to the producer by means of the default -I options. But another aspect, the control of the syntax and portability checks applied by the producer, can also be specified in a fairly precise manner.

The producer accepts a number of #pragma statements which tell it which portability checks to apply and which syntactic extensions to ISO/ANSI C to allow (see [3] and [2]). These can be inserted into the main C source, but the ideal place for them is in a start-up file. This is the purpose of the STARTUP environmental identifier, to give a list of default start-up files containing #pragma statements which specify the default behaviour of the producer.

In fact not all the information the producer requires is obtained through start-up files. The basic information on the minimum sizes which can be assumed for the basic integer types is passed to the producer by means of another type of file, the portability table. This is specified by means of the PORTABILITY environmental identifier. There are in fact only two portability tables provided, Ansi_Max.pf, which specifies the minimum sizes permitted by the ISO/ANSI standard, and Common.pf, which specifies the minimum sizes found on most 32-bits machines. The main difference between the two is that in ISO/ANSI it is stated that int is only guaranteed to have 16 bits, whereas on 32-bits machines it has at least 32 bits.

A number of tcc command-line options are concerned with specifying the compilation environment to the producer. The main option for setting the compilation mode is -Xmode. A number of different modes are available:

The default is -Xc. For a precise description of each of these modes, see [3] (tchk is just tcc in disguise). In addition the command-line options -not_ansi and -nepc can be used to modify the basic compilation modes. -not_ansi specifies that certain non-ANSI syntactic constructions should be allowed. -nepc switches off the producer's extra portability checks (it also suppresses certain constant overflow checks in the TDF translators). All these options are implemented by start-up files.

The portability table to be used is specified separately by means of an environment. The default is the ISO/ANSI portability table, but -Y32bit or -Ycommon can be used to specify 32-bit checking. -Y16bit will restore the portability table to the default. Note that all checks involving the portability table are switched off by the -nepc command-line option, so in this case no portability table is specified to the producer.

Let us briefly describe the compilation modes introduced in the previous section. The following tables describe some of the main features of each mode. The list of pre-defined macros is complete (other than the built-in macros, __FILE__, __LINE__, __DATE__ and __TIME__; because the producer is designed to be target independent it does not define any of the machine name macros which are built into cc. The cc-compatible option, -A-, which is meant to cause all pre-defined macros (other than those beginning with __) to be undefined, and all pre-assertions to be unasserted, is ignored by tcc. In the standard compilation modes there are no such macros and no such assertions. The integer promotion rules are either the arithmetic rules specified by ISO/ANSI or the "traditional" signed promotion rules. The precise set of syntactic relaxations to the ISO/ANSI standard allowed by each mode varies. For a complete list see [3]. The -not_ansi command-line option can be used to allow further relaxations. The extra prototype checks cause the producer to construct a prototype for procedures which are actually traditionally defined. This is very useful for getting prototype-like checking without having to use prototypes in function definitions. This, and other portability checks, are switched off by the -nepc option. Finally, the additional checks are lint-like checks which are useful in detecting possible portability problems.

            compilation mode: -Xs
            description: strict ISO/ANSI with additional checks
            pre-defined macros: __STDC__ = 1, __ANDF__ = 1, __TenDRA__ = 1
            integer promotions: ISO/ANSI
            syntactic relaxations: no
            extra prototype checks: yes
            additional checks: yes
       
            compilation mode: -Xp
            description: strict ISO/ANSI with minimal extra checks
            pre-defined macros: __STDC__ = 1, __ANDF__ = 1, __TenDRA__ = 1
            integer promotions: ISO/ANSI
            syntactic relaxations: no
            extra prototype checks: yes
            additional checks: some
       
            compilation mode: -Xc
            description: strict ISO/ANSI with no extra checks
            pre-defined macros: __STDC__ = 1, __ANDF__ = 1, __TenDRA__ = 1
            integer promotions: ISO/ANSI
            syntactic relaxations: no
            extra prototype checks: no
            additional checks: no
       
            compilation mode: -Xa (default)
            description: lenient ISO/ANSI with no extra checks
            pre-defined macros: __STDC__ = 1, __ANDF__ = 1, __TenDRA__ = 1
            integer promotions: ISO/ANSI
            syntactic relaxations: yes
            extra prototype checks: no
            additional checks: no
       
            compilation mode: -Xt
            description: traditional C
            pre-defined macros: __STDC__ = 0, __ANDF__ = 1, __TenDRA__ = 1
            integer promotions: signed
            syntactic relaxations: yes
            extra prototype checks: no
            additional checks: no
         

The choice of compilation mode very much depends on the level of checking required. -Xa is suitable for general compilation, and -Xc. -Xp and -Xs for serious program checking (although some may find the latter Xs-ive). -Xt is provided for cc compatibility only; its use is discouraged.

The recommended method of proceeding is to define your own compilation mode. In this way any choices about syntax and portability checking are made into conscious decisions. One still needs to select a basic mode to form the basis for this user-defined mode. -Xc is probably best; it is a well-defined mode (the definition being the ISO/ANSI standard) and so forms a suitable baseline. Suppose that, on examining the program to be compiled, we decide that we need to do the following:

The first two of these are syntactic in nature. The third is more interesting. ISO/ANSI says that any undeclared procedures are assumed to return int. However for strict API checking we really need to know about these undeclared procedures, because they may be library routines which are not part of the declared API. The fourth condition is a simple lint-like check that no procedure which is declared to return a value contains a simple return statement (without a return value).

To tell the producer about these options, it is necessary to have them included in every source file. The easiest way of doing this is by using a start-up file, check.h say, containing the lines:

            #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
         

The second, third, fourth and fifth lines correspond to the statements above (see [3]). The first line indicates that this file is defining a new checking scope.

Once the compilation mode has been described in this way, it needs to be specified to tcc in the form of the command-line options -Xc -fcheck.h.

In the main TDF linking phase, combining target independent capsules with TDF libraries to form target dependent capsules, two pieces of information need to be specified to tld. Firstly, the TDF libraries to be linked with, and, secondly, the directories to search for these libraries. For standard APIs, the location of the TDF libraries describing the API implementation is given in the environment corresponding to the API. The LIB identifier gives the names of the TDF libraries, and the LINK identifier the directories to be searched for these libraries. The user can also specify libraries and library directories by means of command-line options to tcc. The option -jstr indicates that the TDF library str.tl should be used for linking (.tl is the standard suffix for TDF libraries). The option -Jdir indicates that the directory dir should be added to the TDF library search path. Libraries and directories specified by command-line options are searched before those given in the API environment.

There is a potential source of confusion in that the tld options specifying the TDF library str.tl and the library directory dir are respectively -lstr and -Ldir. tcc automatically translates command-line -j options into tld -l options, and command-line -J options into tld -L options. However the LIB and LINK identifiers are actually lists of tld options, so they should use the -l and -L forms.

The second use of tld is to combine all the .j files in the producer half of the compilation into a single capsule. This is specified by means of the -M ("merge") command-line option to tcc described in section 3.5.4. By default, the resultant capsule is called a.j. If the -M option is used to merge all the .j files from a very large program, the resultant TDF capsule can in turn be very large. It may in fact become too large for the installer to handle. Interesting it is often the system assembler rather than TDF translator which has problems.

The -MA ("merge all") option is similar to -M, but will in addition "hide" all the external tag and token names in the resultant capsule, except for the token names required for linking with the TDF libraries and the tag names required for linking with the system libraries (plus main). In effect, all the names which are internal to the program are removed. This means that the -MA option should only be used to merge complete programs. For details on how to use tld for more selective name hiding, see below.

There is a final use of the TDF linker supported by tcc which has not so far been mentioned, namely the construction of TDF libraries. As has been mentioned, TDF libraries are an indexed set of TDF capsules. tld, in addition to its linking mode, also has routines for constructing and manipulating TDF libraries. The library construction mode is supported by tcc by means of the makelib environment. This tells tcc to merge all the .j files and then to stop. But it also passes an option to tld which causes the merged file to be, not a TDF capsule, but a TDF library. Thus the command-line options:

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

cause the TDF capsules a.j, b.j and c.j to be combined into a TDF library, a.tl.

tld has a number of options which may be useful to the general user. The -w option, which causes warnings to be printed about undefined tags and tokens, can often provide interesting information; other options are concerned with the hiding of tag and token names. These options can be passed directly to tld by means of the -WL, opt, ... command-line option to tcc . The tld options are fully documented on the appropriate manual page.

A number of tcc command-line options are aimed at controlling the behaviour of the TDF translator. The cc-compatible option -Kitem, ... specifies the behaviour indicated by the argument item. Possible values for item, together with the behaviour they specify, include:

            PIC     causes position independent code to be produced,
            ieee        causes strict conformance to the IEEE floating point standard,
            noieee      allows non-strict conformance to the IEEE standard,
            frame       specifies that a frame pointer should always be used,
            no_frame        specifies that frame pointers need not always be used,
            i386        causes code generation to be tuned for the i386 processor,
            i486        causes code generation to be tuned for the i486 processor,
            P5      causes code generation to be tuned for the P5 processor.
         

Obviously not all of these options are appropriate for all versions of trans. Therefore all -K options are implemented by means of environments which translate item into the appropriate trans options. If a certain item is not applicable on a particular target machine then the corresponding environment will not exist, and tcc will print a warning to this effect.

The cc-compatible -Zstr option is similarly implemented by means of environments. On those machines which support this option it can be used to specify the packing of structures. If str is p1 then they are tightly packed, with no padding. Values of p2 and p4 specify padding to 2 or 4 byte boundaries when appropriate.

Finally, the tcc command-line option -wsl causes the translator to make all string literals writable. Again, this is implemented by an environment. For many machines this behaviour is default; for others it requires an option to be passed to the translator.

For further specifying the behaviour of trans it may be necessary to pass options to it directly. The command-line options implemented by trans vary from machine to machine. The following options are however common to all translators and may prove useful:

            -E      switches off certain constant overflow checks,
            -X      switches off most optimisations,
            -Z      prints the version number(s) of the input capsule.
         

These options may be passed directly to trans by means of the -Wt, opt, ... command-line option to tcc . The -E option is also automatically invoked when the -nepc command-line option to tcc is used. The manual page for the appropriate version of trans should be consulted for more details on these and other, machine dependent, options.

As has been mentioned, the TDF translator is the main optimising phase of the TDF compilation scheme. All optimisations are believed to be correct and are switched on by default. Thus the standard cc -O option, which is intended to switch optimisations on, has no effect in tcc except to cancel any previous -g option. If, due to a translator bug, a certain piece of code is being optimised incorrectly, then the optimisations can be switched off by means of the -Wt, -X option mentioned above. However this should not normally be necessary.

As has been mentioned, the TDF --> MIPS® translator, mipstrans is genuinely exceptional in that it outputs a pair of files for each input TDF capsule, rather than a single assembly source file. The general scheme is shown in Fig. 5.

mipstrans translates each input target dependent TDF capsule, a.t, into a binasm source file, a.G, and an assembler symbol table file, a.T. It may optionally output an assembly source file, a.s, which combines all the information from a.G with part of the information from a.T (it is the remainder of the information in a.T which is the reason why this scheme has to be adopted). The .s file is only produced if tcc is explicit told to preserve .s files by means of one of the command-line options, -Ps, -Pa, -Fs or -S. The two main mipstrans output files, a.G and a.T, are then transformed by the auxiliary MIPS® assembler, as1, into a binary object file, a.o.

Although they can be preserved for examination, the .G and .T files output by mipstrans cannot subsequently be processed using tcc. If a break in compilation is required at this stage, a .s file should be produced, and then entered as a tcc input file in the normal way. The information lost from the symbol table in this process is only important when symbolic debugging information is required. Input .s files are translated into binary object files by the main MIPS® assembler, as, in the normal way.

So, in addition to the main assembler, which is given by the AS environmental identifier, the location of the auxiliary assembler also needs to be specified to tcc. This is done using the AS1 environmental identifier, which is normally defined in the default environment. There is a further piece of information required for the compilation scheme to operate correctly: mipstrans needs to know the as1 version number. This number can be specified by means of the VERSION environmental identifier.

The general form of tcc's calls to ld are as follows:

            ld (linker options) -o (output file)
                (initial .o files) (binary object files)
                (final .o files) (default system library directories)
                (default system libraries) (default standard libraries)
         

The linker may require certain default binary object files to be linked into every executable created. These are divided between the initial .o files, which come before the main list of binary object files, and the final .o files, which come after. For technical reasons, the list of initial .o files is split into two; the first list is given by the CRT0 environmental identifier, and the second by CRT1. The list of final .o files is given by the CRTN environmental identifier.

The information on the default system libraries the linker requires is given by three environmental identifiers. SYS_LINK gives a list of directories to be searched for system libraries. This will exclude /lib and /usr/lib which are usually built into ld. These directories will be given as a list of options of the form -Ldir. The default system libraries are divided into two lists. The environmental identifier SYS_LIBC gives the "standard" library options (usually just -lc), and SYS_LIB gives any other default library options. Both of these are given by lists of options of the form -lstr. This option specifies that the linker should search for the library libstr.a if linking statically, or libstr.so if linking dynamically.

So the main target dependencies affecting the system linker are described in these six environmental variables: CRT0, CRT1, CRTN, SYS_LINK, SYS_LIB and SYS_LIBC. For a given machine these will be given once and for all in the default environment. Standard API environments may modify SYS_LINK and SYS_LIB to specify the location of the system libraries containing the API implementation, although at present this has not been done.

The most important tcc command-line options affecting the system linker are those which specify the use of certain system libraries. The option -lstr indicates that the system libraries libstr.a (or libstr .so) should be searched for. The option -Ldir indicates that the directory dir should be added to the list of directories searched for system libraries. Both these options are position dependent. They are passed to the system linker in exactly the same position relative to the input files as they were given on the command-line. Thus normally -l (and to a lesser extent -L) options should be the final command-line options given.

The following tcc command-line options are passed directly to ld. A brief description is given of the purpose of each option, however whether or not ld supports this option depends on the target machine. The local ld manual page should be consulted for details.

            -Bstr       sets library type: str can be dynamic or static,
            -G      causes a shared object rather than an executable to be produced,
            -dn     causes dynamic linking to be switched off,
            -dy     causes dynamic linking to be switched on,
            -hstr       causes str to be marked as dynamic in a shared object,
            -s      causes the resultant executable to be stripped,
            -ustr       causes str to be marked as undefined,
            -zstr       specifies error behaviour, depending on str.
         

The position of any -Bstr options on the command-line is significant. These positions are therefore preserved. The position of the other options is not significant. In addition to these options, the -b command-line option causes the default standard system libraries (i.e. those given by the SYS_LIBC environmental identifier) not to be passed to ld.

Other command-line options may affect the system linker indirectly. For example, the -g option may require different default .o files and system libraries, the precise details of which are target dependent. Such options will be implemented by means of environments which will change the values of the environmental identifiers controlling the linker.