When the C++ compiler finds a template declaration in a header (.h) file, the compiler needs the definition of the template to allow compilations to proceed faster (on average), because template definitions that are not used don't need to be processed. Hence the compiler automatically searches for a .cc or .C or .cpp etc file with the same name. If such a file exists, it is automatically included in the current compilation. Note that it is not separately compiled. This compiler behavior means that some source code organizations won't work with our compiler.

For example, the compilation of the following driver program fails with Multiple declaration of a variable. The driver program calls a function template multiply, which in turn calls another function template
Array. The definitions of multiply and Array are in different source (.cpp) files. Since there is a dependency between Array and multiply function templates, the compiler tries to include both source files into the compilation unit and hence the failure.

%cat array.h
#ifndef _ARRAY_H_
#define _ARRAY_H_

const int ArraySize = 20;
template <class Type> class Array {

private:
        Type* data;
        int size;
public:
        Array(int sz=ArraySize);
        int GetSize();
};

#endif // _ARRAY_H_

% cat array.cpp
static const char file_id [ ] = "$Header: array.cpp 1 04/05/05 1:35p Giri $";

#include "array.h"

template <class Type> Array<Type>::Array(int sz) {
        size = sz;
        data = new Type[size];
}

template <class Type> int Array<Type>::GetSize() {
        return size;
}

% cat multiply.h
#include "array.h"
int AnyNumber;

template <class Number>

Number multiply(Number original);

% cat multiply.cpp
static const char file_id [ ] = "$Header: multiply.cpp 1 04/05/05 1:35p Giri $" ;

template <class Number>

Number multiply( Number original ) {
        Array<int> IntArray;
        int size = IntArray.GetSize();

        return (size * original);
}

% cat driver.cpp
#include "multiply.h"
#include <stdio.h>

int main( ) {
        printf("\n ** %d **\n", multiply(50));
}

% CC -o driver driver.cpp
"array.cpp", line 1: Error: file_id is initialized twice.
"array.cpp", line 1: Error: Multiple declaration for file_id.
2 Error(s) detected.

% truss -f -o truss.log CC -o driver driver.cpp
% cat truss.log | egrep "multiply|array"
24813:  open("multiply.h", O_RDONLY)                    = 6
24813:  open("multiply.cpp", O_RDONLY)                  = 5
24813:  open("array.h", O_RDONLY)                       = 6
24813:  open("array.cpp", O_RDONLY)                     = 5

Note that both multiply.cpp and array.cpp are syntactically correct; but the problem can be seen only during the compilation of multiply routine. The above mentioned behavior of the compiler has been documented in Sun C++ User's Guide, Compiling Templates chapter.

Sun C++ User's Guide suggests employing a definitions separate template compilation model. This model can better be described as follows: If file x.h has any template declarations, a file called x.cc or x.C or x.cpp, etc must contain definitions of those templates, and nothing else; no #include directives, no definitions of anything other than the templates declared in x.h.

To comply with the definitions separate template compilation model, array.cpp and multiply.cpp files can be modified as follows:

% cat array.cpp
template <class Type> Array<Type>::Array(int sz) {
        size = sz;
        data = new Type[size];
}

template <class Type> int Array<Type>::GetSize() {
        return size;
}

% cat multiply.cpp

template <class Number>

Number multiply( Number original ) {
        Array<int> IntArray;
        int size = IntArray.GetSize();

        return (size * original);
}

Now the compilation of driver.cpp should succeed, due to the implementation of definitions separate template compilation model.

% CC -o driver driver.cpp
%./driver

 ** 1000 **

As we can see, the compilation succeeds and the driver program prints the expected result on console.

If the source code organization does not follow this model, you can use the compiler option -template=no%extdef. This option tells the compiler not to look for template definitions in associated files. With this compiler option, the
compilation succeeds, but the linking may fail. For example, compiling the original source files with -template=no%extdef compiler option, fails during linking phase with the following error:

% CC -o driver -template=no%extdef driver.cpp
Undefined                       first referenced
 symbol                             in file
__type_0 multiply(__type_0)            driver.o
ld: fatal: Symbol referencing errors. No output written to driver

Moral of the story: rely on "definitions separate template compilation" model as suggested by the documentation, but not on temporary workarounds.

If source code changes are not feasible, carefully guarding the common interfaces, variable names etc., with #ifdef directives will do the trick and the compilation and eventually linking succeds.

Acknowledgements:
Steve Clamage of Sun Microsystems