|
DataReel DLL Kit |
Overview
DLL Kit Files
Building A DLL
Building A Project
Exporting Templates
The DataReel DLL kit is supplied as an additional component to the open-source library. The DLL kit includes all the necessary source code and makefiles to build WIN32 dynamic link libraries for all the currently supported WIN32 platforms. Dynamic linking is a mechanism where executables link to the library at run-time. Static linking is a process that links the library and executable together forming a standalone executable. Dynamic linking results in smaller executables and allows you to modify the library without re-compiling the executables. The primary disadvantages of dynamic linking are the complexities of developing the DLL itself and executable dependency issues that complicate binary distributions. Static and dynamic libraries speed up compile times considerably and allow you organize and manage large projects more efficiently.
Pre-compiled DLLs are available from glNET Software. Additionally glNET Software provides custom-built static libraries, WIN32 dynamic link libraries, and UNIX shared libraries. For more information about obtaining the DataReel DLL kit or pre-compiled libraries please contact:
glNET Software
P.O. Box 820314
South Florida, FL. 33082-0314
FAX: 413-622-7705
glnet@glnetsoftware.com
http://www.glnetsoftware.com
The DataReel DLL kit is distributed as a zip archive and should be installed in the "dll" subdirectory of the source code distribution. The dll directory is composed of four subdirectories and includes WIN32 makefiles used to build DLLs. The "dll\include" and "dll\src" subdirectories contain a mirror copy of the source code distribution with DLL imports/exports for all library components that require external linkage. The DLL entry point, import/export macro, and dependencies are defined in the following files supplied with the DLL kit:
gxdlincs.h - Required include files referenced in the stdafx.h file. stdafx.h - Standard system include files, and project specific include files. gxdlcode.h - Defines the "GXDLCODE_API" DLL import/export macro. stdafx.cpp - Source code file used to generate pre-compiled headers. gxdlcode.cpp - Defines the entry point for the DLL application.
The "dll\release" and "dll\debug" subdirectories are used by the WIN32 DLL makefile to store release and debug versions of the DLL and all other compiled files.
The MSVC dynamic link libraries have been built using the following compilers and tested on the subsequent WIN32 platforms:
Microsoft Visual C/C++ 4.2 Microsoft Visual C/C++ 6.0 SP3 Windows 95A Windows 95C Windows 98 Windows 98SE Windows NT 4.0 SP4 Server Windows NT 4.0 SP4 Workstation
The WIN32 DLL kit includes two makefiles used to compile the DLL and a VC template file used to generate application makefiles. The DLL makefiles included with the DLL kit do not require any modifications to build a WIN32 DLL. The following makefiles are required to build the DLL:
msvc.env - Common environment settings for the DLL and project makefiles. msvc.mak - Makefile used to build the dynamic link library
All configurable parameters are contained in the msvc.env include file. When building DLLs within the MSVC IDE please refer to the msvc.env $(DEFMACS) variable for the required and optional preprocessor directives. To set the preprocessor directives for your active configuration press Alt-F7 and select the C++ tab. If you encounter any run-time errors after building a DLL within the MSVC IDE always check the compiler and linker set in the msvc.env and msvc.mak files against the MSVC IDE active configuration. NOTE: Using the C++ "new" and "delete" operators may not always be safe with the debug version of LIBCMT. By default the MSVC IDE will use LIBCMTD.LIB specified by the /MTd compiler flag. To avoid possible run-time errors be sure to use MSVCRTD.LIB by specifying the /MDd compiler flag.
To build the 32-bit debug and release libraries outside of the MSVC IDE execute the following commands:
C:\>CD C:\dreel410\dll nmake -f msvc.mak FINAL=0 nmake -f msvc.mak clean nmake -f msvc.mak FINAL=1 nmake -f msvc.mak clean
This will generate the "debug\gxcode32d.dll" debug DLL and the "release\gxcode32.dll" release DLL. The debug and release subdirectories will also contain a .lib file that must be linked to the project at compile time, a .exp file containing the DLL exports, a .pch file containing precompiled headers, and a .pdb program database file.
To build the 64-bit debug and release libraries outside of the MSVC IDE execute the following commands:
C:\>CD C:\dreel410\dll nmake -f msvc.mak FINAL=0 64BITCFG=1 nmake -f msvc.mak clean nmake -f msvc.mak FINAL=1 64BITCFG=1 nmake -f msvc.mak clean
This will generate the "debug\gxcode64d.lib" debug DLL and the "release\gxcode64.lib" release DLL. The debug and release subdirectories will also contain a .lib file that must be linked to the project at compile time, a .exp file containing the DLL exports, a .pch file containing precompiled headers, and a .pdb program database file.
A makefile template is supplied in the dll directory and is used to build applications using the dynamic library with compiler and linker options set in the compiler's ".env" file. Before using the template file you must set the absolute path to the DataReel library in the template file's $(GCODE_LIB_DIR) variable:
# Setup my path to the gxcode library GCODE_LIB_DIR = #--> Set the absolute path here
To use the makefile template copy the template to the project directory and set the absolute path:
copy C:\dreel410\dll\template.vc C:\dreel410\examples.db\simple\Makefile edit C:\dreel410\examples.db\simple\Makefile # Setup my path to the gxcode library GCODE_LIB_DIR = C:\dreel410
To build the project executable execute one of the following commands depending on your configuration:
C:\>CD C:\dreel410\examples.db\simple nmake FINAL=0 nmake FINAL=1 nmake FINAL=0 64BITCFG=1 nmake FINAL=1 64BITCFG=1
The template file will link the project's object file to the .lib file in the dreel410\dll\debug directory if FINAL=0 or the dreel410\dll\release directory if FINAL=1.
NOTE: Before the executable can be launched you must install the DLL or set a path to the DLL. The DLL can be installed in the directory with the executable, in the Windows system directory, or be visible in any set path.
None of the core database or communication components use templates but a few non-essential general support classes use the generic binary search tree and linked-list, which generate warnings when the DLL is compiled. This is a known, non-fatal incompatibly with MSVC 6 noted in DataReel version 4. The long-term solution will be to re-code individual versions of the parameterized data structures directly for the data type being used.
The following technical note was found this note in the MSVC 6 documentation in reference to exporting template class and functions.
DLLs for Beginners, Debabrata Sarma, Microsoft Developer Support, November 1996
Exporting Template Class and Functions
Visual C++ does not support export of template class or functions. One
reason for this arises from the notion of a template itself. A class
template is an abstract representation of similar, but distinct,
types. There is no code or data that exists to be exported until an
instance of a class template is generated. One workaround (not
recommended) is to declare the template class or functions with the
declspec attribute in the DLL and instantiate all possible types in
the DLL source. As you can see, this defeats the very purpose of using
templates.
For the same reason, you cannot export the Standard Template Library (STL) classes or functions.