Working with the IBM AIX XLC C++ Compiler

his section describes how to use clearmake effectively to build C++ programs using the IBM AIX XLC compiler.

XLC Compiler Template Instantiation: Interaction with clearmake

The XLC compiler instantiates a template when it encounters a #pragma directive in the source code. You can insert these directives into the source code manually, or you can direct the compiler to generate auxiliary source code that contains the necessary directives.

The XLC compiler’s automatic template instantiation works as follows:

1. • As the XLC compiler compiles a source module into an object module, it notes the templates that the module refers to.
   • When the compiler finishes the translation, it generates auxiliary source modules in a repository directory. By default, the repository directory is tempinc.
   • At link time, the compiler compiles the auxiliary sources and links the resulting object modules into the final executable. The template source and object modules remain in the repository, so that the compiler can reuse template code generated by earlier builds. The compiler verifies that cached template object modules are up to date with their sources.

If you use clearmake to build C++ programs that contain template code and are building in an MVFS directory, we recommend that you follow one of the procedures in this section to avoid any incorrect behavior that may result. For example:

• • clearmake executes unnecessary recompiles of program components.
  • clearmake fails to wink in available derived objects.
  • After a template source file changes, clearmake does not rebuild.
  • clearmake rebuilds the executable, but the compiler fails to reinstantiate template code for which the source has changed.
  • The output of cleartool commands such as catcr and diffcr that display configuration records is confusing.

This behavior occurs because the compiler manipulates files in the repository in a way that conflicts with clearmake build avoidance and configuration records. When a program uses templates, ClearCase often associates incorrect configuration information with the program file and the files in the repository.

Models for Working with IBM XLC

To help clearmake and the XLC C++ compiler work together effectively, we recommend that you set up your makefile and program sources according to one of the models described in this section. The model you choose depends on your needs:

• • The Simple model is easy to use and solves some of the problems mentioned earlier. It is the only model that makes use of automatic template instantiation to build template code efficiently. It works best for developers who work independently of others. It is not as effective for team projects in which sharing builds is important.
  • The Compile-Time Demand Instantiation model requires work to set up, but it is easy to use and avoids all the clearmake problems mentioned earlier. It also simplifies sharing builds in a team project. The penalty of using this model is that compile time can increase.
  • The Explicit Instantiation model is difficult to use, because it requires you to track template references. This model avoids all the clearmake problems mentioned earlier and simplifies sharing builds in a group project. It is also the best model to use for building archives and shared libraries that contain template code.

The remainder of this section describes each model in more detail.

The Simple Model

The Simple model relies on the automatic template instantiation of the XLC compiler. This model requires that you insert one line into your makefile.

The Simple model does not solve all the problems that result from conflicts between XLC automatic template instantiation and clearmake, but it allows you to make minimal changes to the project and to take advantage of the efficiency of automatic template instantiation. Configuration problems can result from version changes in the template sources. The Simple model is not appropriate for building libraries.

Modifying the Source Files

The XLC automatic template instantiation scheme requires that for every .h template header file, there is a corresponding .c source file with the same name that contains the implementation of the template. The .c extension is unusual in C++ source file names; you may want to set up your project source files so that each .c file refers to a corresponding source file with a more standard extension, such as .cxx or .C. You can set up a reference .c file in two ways:

• • Create a new element with the .c extension that includes the corresponding file of the standard extension.
  • Create a link with the .c extension that points to the corresponding file of the standard extension. For instructions about how to create a link in an MVFS directory, see the cleartool ln reference page.

Note: Do not set up template header files to include the corresponding source file. Doing so disables automatic template instantiation and defeats the Simple model.

Designing Your Makefile

To design your makefile:

1. • Insert the following line into your makefile, at any point in the file that does not break a rule or definition that spans multiple lines.

   .DEPENDENCY_IGNORED_FOR_REUSE: tempinc/%.C 

   This directive instructs clearmake not to rebuild program components that depend on a compiler-generated source file in the repository when that file changes or is deleted. Such rebuilds are unnecessary. This directive works if the leaf name of the repository directory is tempinc.

   • If you use the –qtempinc=tempinc compiler option to rename a repository directory, add to your makefile another directive of the form

   .DEPENDENCY_IGNORED_FOR_REUSE: my_repository/%.C 

   where my_repository is the leaf name of the repository.

Limitations of the Simple Model

Some problems remain when you use the Simple model. The following list describes the problems and how to work around them.

• • After you modify a template source file, clearmake sometimes fails to relink the executable.

  To work around this problem, delete the executable before you build with a new version of a template source file in your program.

  • When you revert to a version of a template source or header file that is older than the version the compiler used in a previous build, the compiler may reuse object modules in the repository that it should have recompiled. This can happen after you change a template, a checked-out source, or a header file from reserved to unreserved or after you modify your configuration specification. clearmake detects the change and recompiles the file. However, because the compiler relies on a file time-stamp comparison of cached template code with its source, it incorrectly reuses the code already in the repository.

  To work around the problem, remove all .o files from the repository when you revert to an older version of a template source or header file.

  • clearmake rebuilds program components rather than winking in available builds from another view. This problem makes the Simple model more difficult to use for team projects in which sharing builds is important.

  To manually wink in files produced by another build, use the cleartool winkin command. Use the –recurse option of the winkin command to wink in a hierarchy of files that produced a build. For more information, see the winkin reference page.

  • The configuration record for the final program contains confusing information about the dependency structure of the program. This problem becomes evident when you execute cleartool commands such as catcr and diffcr, which display configuration records.

The Compile-Time Demand Instantiation Model

The Compile-Time Demand Instantiation model does not use the XLC compiler’s automatic template instantiation. Instead, it forces the compiler to instantiate all the template code used by a given module. At link time, there may be multiple definitions of template symbols, but the linker drops the duplicate symbols.

To use this model, you may have to edit some source files. The advantage of using this model is that avoiding automatic template instantiation solves the conflicts between the compiler and clearmake. The disadvantage is that compiling duplicate template code takes extra time and disk space.

Modifying the Source Files

The Compile-Time Demand Instantiation model requires that every template header file include its corresponding source file. If you use this model, you must edit template header files that do not include their corresponding source file.

We recommend that you use conditional compilation directives as shown in the following pattern.

// Header file my_templ.h
 
//
 
#ifndef _my_templ_h__	 // header file exclusion -- use any
				// unique name
 
#define _my_templ_h__
 

... Place template declarations here ...

#ifdef TEMPLATE_CODE_IN_HEADERS
 
#include “my_templ.cxx”	 // source file name suffix may vary
 
#endif
 
#endif // _my_templ_h
 

Designing Your Makefile

If you set up your header files as recommended in the previous section, you must also define the macro that enables source file inclusion on the compiler command line. For the sample above, enable source file inclusion by specifying the compiler option –DTEMPLATE_CODE_IN_HEADERS. The conditional directive allows you to build under a different model or on other platforms without changing the source code.

To disable automatic template instantiation, specify the –qnotempinc compiler option.

Duplicate Symbol Warnings from the Linker

When you set up template header files to include their source files, the implementation of each template is available to the compiler at compile time. The compiler instantiates the template immediately and puts the compiled template code into the object module. As a result, every object module that refers to a certain template function or data contains the code for that template function or data, which leads to multiple definitions of template symbols at link time. The AIX linker drops the duplicate symbols without generating an error. As the linker drops each duplicate symbol, it issues a Duplicate symbol warning. You can ignore these warnings. To suppress them, specify the compiler option –LOOK_IT_UP in the final link step of the program.

The Explicit Instantiation Model

The Explicit Instantiation model is useful whenever it is necessary to assume full control over the placement of instantiated template code. For example, if you are building an archive or creating a shared library that contains template code, you probably want to use this model. To use the Explicit Instantiation model, you must disable automatic template instantiation and on-demand compile-time instantiation, and explicitly identify the templates that your program needs to instantiate.

The Explicit Instantiation model requires that you keep track of the set of templates the program requires and maintain source directives to instantiate the templates. This maintenance burden is worthwhile only when you are required to specify the module in which instantiated template code appears, for example, when building code for an archive or shared library. Otherwise, the Compile-Time Demand Instantiation model is more suitable.

Modifying the Source Files

For each template class or function that your program requires, add exactly one #pragma define directive to the source code. For example, if your program requires the class

Array<String>
 

then add this #pragma define directive:

#pragma define(Array<String>)
 

In each source file that contains a #pragma define directive, include the source files that contain the implementations of the templates used. For example, if the source for the Array template is contained in the file array.cxx, add the following #include directive to the file that contains the #pragma directive:

#include “array.cxx”
 

Do not set up header files to include corresponding source files. If you do, duplicate template instantiation may result (see The Compile-Time Demand Instantiation Model).

Remove function definitions from source files that contain #pragma define directives.

Designing Your Makefile

In your makefile, disable automatic template instantiation by specifying the –qnotempinc compiler option.