7.5 Template Definition Searching

When you use the definitions-separate template organization, template definitions are not available in the current compilation unit, and the compiler must search for the definition. This section describes how the compiler locates the definition.

Definition searching is somewhat complex and prone to error. Therefore, you should use the definitions-included template file organization if possible. Doing so helps you avoid definition searching altogether. See 5.2.1 Template Definitions Included.

7.5.1 Source File Location Conventions

Without the specific directions provided with an options file, the compiler uses a Cfront-style method to locate template definition files. This method requires that the template definition file contain the same base name as the template declaration file. This method also requires the template definition file to be on the current include path. For example, if the template function foo() is located in foo.h, the matching template definition file should be named foo.cc or some other recognizable source-file extension (.C, .c, .cc, .cpp, .cxx, or .c++). The template definition file must be located in one of the normal include directories or in the same directory as its matching header file.

7.5.2 Definitions Search Path

As an alternative to the normal search path set with –I, you can specify a search directory for template definition files with the option –ptidirectory. Multiple -pti flags define multiple search directories, that is, a search path. If you use -ptidirectory, the compiler looks for template definition files on this path and ignores the –I flag. Because the -ptidirectory flag complicates the search rules for source files, use the -I option instead of the -ptidirectory option.

7.5.3 Troubleshooting a Problematic Search

Sometimes the compiler generates confusing warnings or error messages because it is looking for a file that you don’t intend to compile. Usually, the problem is that a file, for example foo.h, contains template declarations and another file, such as foo.cc, gets implicitly included.

If a header file, foo.h, has template declarations, the compiler searches for a file called foo with a C++ file extension (.C, .c, .cc, .cpp, .cxx, or .c++) by default. If the compiler finds such a file, it includes the file automatically. See 7.5 Template Definition Searching for more information on such searches.

If you have a file foo.cc that you don’t intend to be treated this way, you have two options:

• Change the name of the .h or the .cc file to eliminate the name match.

• Disable the automatic search for template definition files by specifying the -template=no%extdef option. You must then include all template definitions explicitly in your code and will not be able to use the “definitions separate” model.