How to Create and Managed Shared Libraries that contain C++ Templates

   AIX V3, CSet++ version 2 for AIX compiler
   AIX V4, CSet++ version 3 for AIX compiler
    How do you create and manage C++ libraries that instantiate 
    template classes?

    The way that C++ template classes and archived or shared
    libraries work together on AIX is not seemless.  In order 
    to minimize the compile/link time, the size of libraries and 
    programs, and the number of duplicate symbols requires some 
    understanding of how the C++ templates are generated and 
    compiled on AIX.  There are basically two ways C++ template 
    classes are generated - compile time and link time. 
    AIX refers to link time generation as automatic template 
    generation. Automatic template generation is typically the 
    best approach for most programming projects that build 
    intermediate libraries and then build programs that link 
    with these libraries.

    1. Organize source code to use automatic (link time) 
       template instantiation.
    2. Compile library source files with -c option.
    3. Compile ./tempinc/*.C files or create dummy main.
    4. Archive *.o and ./tempinc/*.o into library
    5. Link main program with library. 

STEP 1. Organize source code to use automatic (link time) template
      The primary way that the compiler selects the template generation
      method is by the way the template class source code is organized.
      To use link time template class instantiation organize the template
      class source code as follows.

    - Place template class DECLARATIONS in a header file (.h file)
    - Place template class DEFINITIONS into a .c file with the same
           name (prefix) as the corresponding .h file.
    - Place the .h and .c files in the same include directory.
    - Only include the .h files in the source files (i.e. main program)
      using the template classes.  Do not include the .c files.
    - If you compile and link with different steps make sure
      that all the compiler options are included in the link

Step II. Compile library source files with -c option.
    - cd to the directory where your source files for the 
      library are located.
    - Compile the source files with the -c compiler option.
      In addition to .o files being produced there should
      be a sub-directory called tempinc that is created.  The tempinc 
      directory should also contain one or more .C files. These
      .C files normally are compiled in a prelink step and are not
      compiled when using the the -c option.

STEP III. Compile ./tempinc/*.C files or create dummy main.
      Compile the ./tempinc/*.C files.  This can be accomplished
      in one of two ways. 
      Compile and link a "dummy" main
      program or compile ./tempinc/*.C files from the library directory
      and not the ./tempinc subdirectory.  

      Method 1. When compiling the ./tempinc/*.C files directly 
      do NOT change directories into the tempinc directory but
      rather include the "./tempinc/*.C" and "-o ./tempinc/*.o" in
      the compile line.  If the ./tempinc/*.C files are compiled from
      within the ./tempinc directory as the current working directory
      another ./tempinc subdirectory will be created that will have the 
      additional .C files in it.

      Method 2. Compile and link the library source code into a dummy 
      main program except do not link the main function. In other words,
      perform a link step but it is not important if the dummy program 
      is built successfully or not.  The reason the link step is executed
      is to compile the ./tempinc/*.C files.  There is actually a prelink
      step that takes place when working with template classes. Before,
      the link begins if a ./tempinc directory is detected and if there are
      any .C files in the tempinc directory detected those files 
      are compiled.   
STEP IV. Archive *.o and ./tempinc/*.o into library
    - The .o files from the library directory and the ./tempinc/.o files
      must all be archived.  Assuming that the code was organized 
      as in step I.  Then all the template class functions will be in the 
      ./tempinc/*.o files and not in the library directory.  

      NOTE: It is possible to have both a tempinc directory and also
      have template classes in the .o files of the library directory.
      The template classes will be generated in a .o file any time
      the template class declarations and definitions are present in 
      the compilation unit (.C file in this case).  This is typically
      should be avoided as it will result in duplicate symbols and 
      unnecessarily longer compile/link times due to the extra code
      present in the .o files.
      Note: These .o files may also be used to created a shared module
      using the /usr/lpp/xlC/bin/makeC++SharedLib.

STEP V. Link main program with library. 
       Link the main program with the library.  There are a couple
      of issues here related to automatic template generation.
      If the main program uses the same template classes with the 
      same data types as the library does then there will be 
      duplicate symbol warnings for these template classes.
      The reason is that compiling the main program source files 
      will produce another ./tempinc subdirectory where the .C
      files will be created and compiled and then ./tempinc/*.o files
      added to the link step.  Since the symbols are in the library
      and also in the ./tempinc/*.o files then duplicate symbols 
      warnings will be generated.  However, this is probably the best
      that can be achieved. 

      If the main program only instantiates template classes
      that are already in the libraries that will be linked then the
      -qnotempinc option can be specified on the compile and link commands.
      This will suppress the tempinc directory from being created.  
      Of course, if the main program does instantiate a template class
      not in the library then if the -qnotempinc option is used the
      template class with the new data type will be undefined. 


Closing with Customer Approval

Support Line: How to Create and Managed Shared Libraries that contain C++ Templates ITEM: BU1715L
Dated: February 1997 Category: N/A
This HTML file was generated 99/06/24~13:30:19
Comments or suggestions? Contact us