home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cset21v1.zip / IBMCPP / CPPDLL.DOC < prev    next >
Text File  |  1993-05-17  |  6KB  |  168 lines
  1. C++ DLL Building
  2.  
  3. INTRODUCTION
  4.  
  5. Building Dynamic Link libraries is not a difficult task, but
  6. it does require the user to faithfully follow certain rules. The C/C++
  7. Tools Programming Guide describes this topic - Chapter 12. Building
  8. Dynamic Link Libraries - very well.
  9.  
  10. This document describes the steps for creating
  11. and using C++ dynamic link libraries through various simple
  12. examples.
  13.  
  14. You should already be familiar with the information
  15. presented in Chapter 12 of the IBM C/C++ Tools Programming Guide.
  16. If not, please take some time to review the chapter and
  17. have it handy for reference.
  18.  
  19. You can use two methods to build C++ DLL's:
  20.  
  21. Method 1: the use of features _Export  and #pragma export
  22.  
  23. Method 2: the use of .DEF building tool CPPFILT.EXE
  24.  
  25. We will show  how these two methods actually work.
  26.  
  27.  
  28. METHOD 1:  Using  _Export  and #pragma export
  29.  
  30.    This is the simplest method to create a C++ DLL.
  31.    It involves the use of the _Export keyword or the
  32.    #pragma export directive on the functions or classes you
  33.    wish to export. For example, to export the function
  34.    "int chris(int a)", simply insert the keyword as follow:
  35.    "int _Export chris(int a)".
  36.  
  37.    The files for a sample program that demonstrates this method are
  38.    located in the directory  IBMCPP\SAMPLES\COMPILER\SAMPLE07\METHOD1.
  39.  
  40.    The command file run.cmd, demonstrates each of the steps
  41.    given below:
  42.  
  43.        (1) Use _Export or #pragma export in your source files to
  44.            specify the items you want to export.
  45.  
  46.            The sample source file VF.H, shows how the
  47.            _Export keyword is used to export a class.
  48.  
  49.            For example, if you wish to export only a certain
  50.            member of a class, say getarea(), add the _Export
  51.            keyword to the declarator of the function:
  52.  
  53.                  class  triangle : public area    // deleted _Export
  54.                     {
  55.                     public:
  56.                        static int objectCount;
  57.                        double _Export getarea();  // added   _Export
  58.                        _Export triangle::triangle(void);
  59.                     }; // you must always export constructors and destructors
  60.  
  61.             You may also use #pragma export as follow:
  62.  
  63.                  #pragma export(triangle::getarea(),,1)
  64.  
  65.  
  66.        (2) Compile all files to objects (make sure you use the /Ge- option).
  67.  
  68.  
  69.        (3) Create a dummy .DEF file.
  70.  
  71.            BASIC.DEF is a sample dummy .def file.
  72.            Note that the internal name of the DLL
  73.            is specified after the LIBRARY keyword
  74.  
  75.        (4) Link the DLL with your objects, libraries, and DEF file.
  76.  
  77.            You should use ICC to link the DLL. The /Fe option
  78.            specifies the file name of your DLL.
  79.  
  80.        (5) Create the import library from the DLL.
  81.  
  82.  
  83.        (6) Link your application with the import library.
  84.  
  85.            Use ICC to compile/link your application to the
  86.            import library.
  87.  
  88.  
  89. Method 2: Using of .DEF file building tool CPPFILT.EXE
  90.  
  91.    This method requires the use of CPPFILT tool to create
  92.    the export names list to be used in the .DEF file.
  93.    The advantage of this method is that it offers you
  94.    a convenient way to build DLL's without having to modify
  95.    the source files.
  96.  
  97.    The files for a sample program that demonstrates this method are
  98.    located in the directory  IBMCPP\SAMPLES\COMPILER\SAMPLE07\METHOD2.
  99.  
  100.    Take a look at the command file run.cmd, which demonstrates
  101.    each of the steps given below:
  102.  
  103.  
  104.        (1) Compile all files to objects (make sure you use the /Ge- option).
  105.  
  106.  
  107.        (2) Compile all the tempinc files in the TEMPINC directory.
  108.  
  109.            The tempinc files contain the implementation of
  110.            all the templates we have instantiated and used
  111.            by the objects you will link to create a DLL.
  112.            It is necessary to include these tempinc object
  113.            files when linking the DLL. Otherwise, unresolved
  114.            externals (missing implementation) will result.
  115.  
  116.        (3) Copy the tempinc objects into your DLL building directory.
  117.  
  118.            Since you want to link your DLL with the tempinc object files,
  119.            it is convenient to have all the objects in the same
  120.            directory.
  121.  
  122.        (4) Run cppfilt.exe on all the object files using -b -p options,
  123.            directing the output to a temporary file. (In the example,
  124.            STK.TMP is the temporary file created).
  125.  
  126.            -b option tells CPPFILT that we are using objects and
  127.               libraries
  128.  
  129.            -p causes CPPFILT to dump out all public symbols that
  130.               can be exported
  131.  
  132.  
  133.        (5) Edit the temporary file (STK.TMP) created above
  134.            to exclude any symbols that you may not want to export and
  135.            add in the standard DEF file information.
  136.  
  137.            If there are functions or variables that you do not
  138.            want to export from the DLL, simply comment the
  139.            symbols out.
  140.  
  141.            You must add in the standard .DEF file header.
  142.            You should change the DLL name after the LIBRARY keyword
  143.            to the name you have given to the DLL you are building.
  144.  
  145.            In the example, STACK.DEF is created by adding in the
  146.            standard DEF file information to STK.TMP.
  147.  
  148.        (6) Link the DLL with your objects, libraries, and DEF file.
  149.  
  150.            You should use ICC to link the DLL. The /Fe option
  151.            is used to specify the file name of your DLL.
  152.  
  153.  
  154.        (7) Create the import library from the DLL.
  155.  
  156.            You can also use the .DEF file to create the import
  157.            library, for example, implib stack.lib stack.def
  158.  
  159.        (8) Link your application with the import library.
  160.  
  161.            In the sample program, the tempinc object
  162.            files included in the DLL have been deleted. If you forget
  163.            to delete those tempinc object files, you most likely
  164.            will get error messages from the linker saying
  165.            one or more symbols are multiply defined.
  166.  
  167. === End of document ===
  168.