tcc User's Guide

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

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.

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.

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:

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

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:

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.

Figure 2.2. Full tcc Compilation Path

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

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.

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.

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

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.

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.

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.

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"
           

            -Dname
            -Dname=value
            -Uname
            -Astr
           

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

            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
         

            #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 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
         

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:

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.

            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.
         

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

4.3.4. The MIPS® Translator and Assembler

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.

Figure 4.1. MIPS® Compilation Path

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

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.

            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)
         

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

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:

        -A      causes all known unit types to be decoded,
        -g      causes diagnostic information units to be decoded,
        -D      causes a binary dump of the capsule to be printed,
        -U      causes link information units to be decoded,
        -V      causes the input not to be rationalised,
        -W      causes a warning to be printed if a token is used before it is declared.
     

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

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

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.

All of the extra compiler checks described in Section 4.1.3, “Compilation Modes and Portability Tables” 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 tchk intermodular checking is on by default, but may be switched off using -im0.

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.

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.

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:

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.

All tcc command-line options and environmental directives are actually processed by the same method, namely the tcc option interpreter. A simple pattern matching algorithm is applied to the input and, if a match is found, the corresponding instructions are sent to the low-level option interpreter. The command-line option --str, ... causes str to be passed directly to the option interpreter. This is intended primarily to help in debugging tcc and not for use by the general user. However, if you are interested, --1DB is a good place to start.

            [1] TDF and Portability, DRA, 1994.
            [2] The C to TDF Producer, DRA, 1993.
            [3] The TenDRA Static Checker, DRA, 1994.
            [4] The TDF Notation Compiler, DRA, 1994.
       

tcc identifies the file type of the input files it is passed by means of their file suffix. The recognised file suffixes are as follows:

Each file type is assigned an identifying letter, usually corresponding to its file suffix, which may be used in various command-line options. For example, -Fs instructs tcc to halt the compilation after creating the assembly source files, and is therefore equivalent to -S. Similarly -Po instructs it to preserve any binary object files it creates. There are a couple of special file type codes which may be used with the -P option. The option -Pa causes all intermediate files to be created, whereas -Ph causes the start-up file, tcc_startup.h, used by tcc to be preserved. The -P option can also be used to specify that intermediate files of various forms should not be preserved. For example, the option -P-o indicates that binary object files should not be preserved.

Most output file names are derived from the input file names with a simple substitution of file suffix, however certain output files (and other files) have default names. These are as follows:

If there is a single output file, its name may be specified using the -o option. The default output filenames can also be overridden. For example, -doj b.j sets the default merged TDF capsule name to b.j.

The various compilation phases under the control of tcc may be summarised as follows:

Each compilation phase is assigned a code letter which is used to identify that phase in various command-line options. For example, in order to pass the -x option to tdfc the -Wc, -x command-line option may be used. Similarly, to set the tld executable an option of the form -EL: /usr/local/bin/tld may be used.

The following options are accepted by tcc. They can be given by command-line options or the TCCOPTS system variable. The spaces in the option descriptions are optional, they show where two-part or multi-part options can be split over more than one command-line argument.

Please see the manpage for a complete list of command-line options.

The following two tables list the producer and archiver options which can be passed using the -Wc, opt and -WJ, opt options, respectively.

The built-in compilation modes are as follows:

The mode Xs is specified by passing the -Xs command-line option to tcc, and so on.

The following standard APIs are supported in the form of TenDRA headers:

Each API is specified to tcc by means of an environment with the same name as the API. Thus, for example, -Yposix specifies POSIX 1003.1. APIs are divided into two types, base APIs, such as POSIX 1003.1, and extension APIs, such as the X11 (Release 5) Toolkit. A program API consists of a base API plus an number of extension APIs, for example, POSIX plus the X11 Toolkit. This example would be specified by means of the options -Yposix -Yx5_t, in that order (base APIs override the previous API, extension APIs add to it).

Information on the current API may be printed by passing the -info option to tcc.

The following tcc environment identifiers are recognised:

* stands for any of the allowed environment modifiers +, < or >.

In addition to the environments implementing the supported APIs (see section 7.5. on page 31), the following environments are standard: