Template options

The following options are only relevant in the modes C++ 2017, C++ 2020 and C++ V3 as templates are not supported in the Cfront C++ mode.

-T none
-T auto
-T local
-T all

These options control how templates with external linkage are instantiated. This includes function templates as well as (non-static and non-inline) functions and static variables that are members of class templates. These template types are combined under the generic term "template entity" below.

In all instantiation modes, the compiler generates all instances per compilation unit that are requested with the explicit instantiation directive template declaration or with the instantiation pragma #pragma instantiate template entity.

The remaining template entities are instantiated as follows:

-T none

No instances are generated unless explicitly requested.


-T auto (default)
Instantiation is carried out globally for all compilation units by a prelinker. The prelinker is activated when an executable file is generated with the CC command or if the -y option (see "Options for selecting compilation phases") is specified. No instantiations are performed by the prelinker when generating a prelinked object file ( -r option). The principle of automatic instantiation is described in detail in section “Automatic instantiation”.

-T local

Instantiation is carried out per compilation unit. All template entities used in a compilation unit are instantiated, with internal linkage for the functions generated in the process. This provides a very simple mechanism for starting template programming. The compiler instantiates the functions required in each compilation unit as local functions. The program links them and then terminates correctly. However, this method produces a large number of copies of the instantiated functions and is therefore not recommended for production. And for the same reasons this mode is not suitable if one of the templates contains static variables.

Warning:

The basic_string template contains a static variable which is used to represent an empty string. If you use the -T local option and select the string type from the library the empty string is no longer recognized. Try to avoid using this combination as it can lead to serious problems.

-T all

Instantiation is carried out per compilation unit. All template entities that are used or declared in a compilation unit are instantiated. All member functions and static variables of a class template are instantiated regardless of whether they are used or not. Function templates are also instantiated if they are just declared.

-T add_prelink_files, pl_file1[, pl_file2...]

This option can be used to specify objects and libraries that are taken into account as described below when the prelinker determines the instances to be generated:

pl_filei is the name of an object file (.o file) or a static library (.a file).

• If an object file or library pl_filei contains the definition of a function or static data member, no instance of a template entity that is a duplicate this is generated.

• If an object file or library pl_filei needs instances for template entities, these instances are not generated.

Problem

The libX.a and libY.a libraries contain references to the same template instances. Duplicates occur if the objects of the two libraries were each preinstantiated with the-y option.

In such cases, the prelinker must be informed that symbols are defined elsewhere and it should therefore not generate any instances. The -T add_prelink_files option is provided for this purpose.

Solution

The objects of the libX.a library are initially preinstantiated with the -y option. Then the objects of the libY.a library are preinstantiated, using the
-T add_prelink_files,libX.a option to inform the prelinker to consider libX.a and ensure that no duplicate of this is generated.

-T max_iterations, n

In automatic instantiation mode ( -T auto ), this option specifies the maximum number n of prelinker runs. The default is n = 30. The number of prelinker runs is unlimited if n is set to the value 0.

-T etr_file_none
-T etr_file_all
-T etr_file_assigned

These three options are used to control the creation of an ETR file file.etr (ETR=Explicit Template Request) for the application of explicit template instantiation (see section “Generating explicit template instantiation statements (ETR files)”).

Warning:

The etr_file_all and etr_file_assigned options are ignored if they are used in conjunction with the preprocessor options -P / -E / -M.

-T etr_file_none

This is the default setting and suppresses the output of instantiation information.

-T etr_file_all

This option outputs all the possible template information.

-T etr_file_assigned

This option ensures that only those instantiation templates assigned by the prelinker are output.

-T [no_]definition_list or -T [no_]dl

This options allows for internal communication between the front end and the prelinker during the recompilation phase of the automatic template instantiation. You will find more information in the section “Automatic instantiation”.

-K arg1 [, arg2 ...]

General input rules for the -K option can be found in section "Calling syntax and general rules". The following entries are possible as arg arguments to control template instantiation:

assign_local_only
no_assign_local_only

These arguments determine whether or not instantiation assignments are only supported locally. If -K assign_local_only is set, the following applies:

• Instantiations can only be assigned to object files that are located in the current directory (local files).

• Instantiations can only be assigned to an object file if the current directory at the time of the instantiation matches the current directory at compile time.

Example

cd dir1          # The current directory when
CC -c test1.c    # compiling test1.c is dir1
cd ../dir2       # The current directory when
CC -c test2.c    # compiling test2.c is dir2 
cd ../dir1       # The current directory for the
                 # prelinker is dir1
CC -K assign_local_only -o test test1.c ../dir2/test2.o

In this example, the assignment of instantiations is restricted to the local object file test1.o .

-K no_assign_local_only is the default setting.

implicit_include
no_implicit_include

These arguments determine whether the definition of a template is implicitly included (see section “Implicit inclusion”).

-K implicit_include is the default setting.

instantiation_flags
no_instantiation_flags

-K instantiation_flags is the default setting and causes special symbols to be generated for use by the prelinker during automatic instantiation.
If -K no_instantiation_flags is set, no such symbols are generated, so the object size is reduced. Consequently, no automatic instantiation with -T auto is possible in this case.