In this article I will describe how to use Dynamic Link Libraries (DLL) in your own projects. I will show an example of how to define a DLL that is statically linked at compile-time to support implicit loading of the DLL at runtime. I will also show how to to use explicit DLL loading to allow your project to support plug-ins that can be dynamically loaded into your main executable at run-time. For this example, I will use Microsoft’s Visual Studio 2008 as the programming IDE.

Introduction

Dynamic Link Library (DLL) is Microsoft’s implementation of the Shared Library Library concept in the Windows operating system. Under the Unix-like operating system the Dynamic Shared Object (DSO) or just Shared Object (SO) concept applies. The practices shown here should be similar in both implementations.

DLL’s can be used primarily in two ways. Either the DLL can be implicitly linked linked to your application in which case the DLL will be loaded automatically when the application is executed, or the DLL can be loaded dynamically at run-time.

Implicit Linking

When you compile a DLL two files are generated. A library object file (.lib) is created and the DLL file itself is generated. To enable implicit linking, your main application can directly link against the generated .lib file which will ensure that the DLL is loaded automatically when your application starts. This is similar to the way you link against any static lib except any class, free function, or shared data must be exported when the DLL is compiled and imported when the main application that uses that library is compiled. I will discuss importing and exporting symbols later in the article.

Explicit Linking

Explicit linking occurs when you load the DLL into your application at run-time using the LoadLibrary (or LoadLibraryEx) methods in a Windows application or dlopen on Unix-like systems. Explicit linking is required when you want to support additional functionality to your application using the Plug-In concept. In this case, your application does not have access to the classes, methods, and data at compile time and must be exposed by the DLL at run-time. In this article, I will demonstrate how to implement a Plug-In system using explicit linking of DLL files.

Creating A Common Library

Before you can support a Plug-In system, you probably want to define a common interface that will be used by both the main application, as well as all the dynamic link libraries that your application can load at run-time. To facilitate this, we will create a common DLL that will be implicitly linked to both the main application and any DLL that needs to support your plug-in system.

The Common DLL Project

Open Visual Studio 2008 and create a new project (File -> New -> Project…). You should be presented with the “New Project” dialog box shown below.

In the “Project types:” frame, select “Visual C++ -> Win32” and in the “Templates:” frame, select “Win32 Project” as shown in the image above.

Give your project a name, a location, and a solution. I called it “CommonDLL” because it is the common DLL that will define the interface types that are needed by both the main application and the plug-in types that will be loaded explicitly.

When ready, click the “OK” button to proceed to the next step. You should be presented with the “Win32 Application Wizard” dialog box.

When the Wizard opens, you’ll see the “Welcome to the Win32 Application Wizard” page. Either click “Next” or click the “Application Settings” text on the left-side of the window to go to “Application Settings” page.

Select “DLL” radio-button under the “Application type:” header and also check the “Export symbols” check-box under the “Additional options:” header. Checking the “Export symbols” check-box will generate some macros in your source files that will allow the symbols defined in this library to be exported when generating the library itself, and the same symbols will be imported when you are linking against this library.

Click “Finish” and you should have a new project in your solution explorer with several header files and source files.

If you open the “CommonDLL.h” header file that is automatically generated together with your project, you should see something similar to what is shown below.

If you open the CommonDLL project properties you will also notice that the preprocessor macro “COMMONDLL_EXPORTS” is defined in the “Preprocessor Definitions” as shown in the image below.

Defining the “COMMONDLL_EXPORTS” macro in the project settings will allow the symbols that have the “COMMONDLL_API” macro definition to be exported when the DLL is compiled and linked.

In this particular example, the CCommonDLL class and all of it’s operations and data will be exported and accessible outside the DLL. In addition to the class, the global int variable called nCommonDLL will also be exported and finally the fnCommonDLL method will also be exported.

If we examine the source code for the CCommonDLL source file, you will notice that the nCOmmonDLL integer and the fnCommonDLL method are defined with the storage-class specifier as a syntactic reminder that these symbols are exported and accessible outside the DLL.

Now let’s add something interesting. The interface for our Plugin type!

The Plugin Interface

Create a new class in the CommonDLL project called “Plugin”

The Plugin class will be the base class for all of our plugin types that our application will support. For this example, I will only implement a very simple do-nothing interface. I simply want to give you an idea of how you might implement the plugin base type.

We will export the class by appending the COMMONDLL_API macro to the class declaration to ensure the class’s data and methods are usable outside the DLL.

If you recall from the “CommonDLL.h” header file, the “COMMONDLL_API” macro will resolve to “__declspec(dllexport)” if the “COMMONDLL_EXPORTS” preprocessor macro is defined or “__declspec(dllimport)” if it is not defined.

The Plugin Manager

We probably also want a class that can keep track of the Plugin-Ins and manage their lifetime. For this purpose, we will add the Plug-In manager class.

Add a new class to the CommonDLL project called “PluginManager” and open the header file for the new PluginManager class.

The PluginManager needs to provide at least two methods:

1. LoadPlugin: This method will load a plugin from a DLL and return a pointer to the plugin object.
2. UnloadPlugin: This method will unload a particular plugin from the plugin manager. The DLL associated with the Plugin will also be unloaded.

Let’s see what the interface for the Plugin manager might look like.

The m_Plugins map will store the pointers to the Plugin‘s that are loaded from the DLL and the m_Libs will store the handles to the DLL’s that are dynamically loaded.

The PluginManager::LoadPlugin Method

Now let’s first take a look at the LoadPlugin method. The basic idea is that we want to load a DLL and get the address of a method that has been exported from the DLL that will be used to create and return a pointer to the plugin type that has been defined in the DLL. Let’s see how we might do that.

First, let’s define the signatures for the methods we expect to find in the DLL.

The “CreatePlugin” function will create an instance of the plugin object and return a pointer to the plugin. The “DestroyPlugin” function will simply destroy the plugin that was created with the CreatePlugin function.

Let’s look at the definition of the PluginManager::LoadPlugin method.

First, we check the map to see if the plugin has been loaded before. If the plugin is found in the plugin map, we don’t try to load it again but instead just return the plugin that was already loaded.

On line 25, we use the LoadLibrary method to get a handle to the DLL with the name pluginName. If the LoadLibrary returns a valid handle, we then use the GetProcAddress method to get the address of the symbol that is exported from the DLL with the name “CreatePlugin“. Every plugin that your application will load will need to define a method called CreatePlugin which returns a pointer to the Plugin object defined in the DLL. In the next section, I will show how we define and export this function from the DLL.

If the function pointer is valid and the “CreatePlugin” method generates a valid plugin, then we register both the plugin and the library it came from in the m_Plugins and m_Libs maps so we can unload the plugin later.

The remainder of the method is just error checking to make sure that everything is as it should be. If anything goes wrong, an error message is reported and a NULL plugin is returned.

The PluginManager::UnloadPlugin Method

When a plugin needs to be unloaded, we need to release all of the resources that were allocated in the DLL and free the DLL library itself. When we no longer need a plugin (or want to load a different plugin that does the same thing but in a different way) we will use the PluginManager::UnloadPlugin method to remove the plugin and library from memory.

On line 75, the address of the “DestroyPlugin” is found using the “GetProcAddress” method. If the address to the method is valid, it is invoked to destroy the plugin instance that was created in the “CreatePlugin” method. All resource that were allocated by the plugin should also be freed.

The DLL library itself is free’d using the FreeLibrary method on line 89.

Creating a Plugin DLL

Now that we know how to load, and unload DLL’s, let’s see how we could implement the Plugin in a DLL that is dynamically loaded at run-time.

Create a new DLL project in your current solution called “PluginDLL” for example. The steps to create this plugin project are identical to the CommonDLL we created earlier (that is, create a “Win32 Project” and set the application type to “DLL” and make sure “Export symbols” is checked).

The “New Project” wizard will create a new project in our solution with the name “PluginDLL” and it will also define a preprocessor macro with the name PLUGINDLL_EXPORTS that will export our DLL interface types when the macro is defined, or import the DLL interface types when it is not defined (this is no different from the COMMONDLL_EXPORTS preprocessor macro defined in the CommonDLL project).

Before we can start defining classes that are derived from the Plugin base type, we must setup implicit linking for the CommonDLL library by telling our PluginDLL project to link against the “CommonDLL.lib” file.

There are multiple ways to tell the Visual Studio linker to link one project against another. The easiest way is to create a dependency between the two projects. This may be easier than explicitly setting up the paths and explicitly defining the libraries to link against in the project settings, but it is less obvious to anyone who may be using your project outside this of this solution. Generally, for my own test solutions, I will use this method to link projects together only when I am creating a small test case that generally won’t be shared with anyone, but for shared projects, I do not recommend using this method.

To setup (or check) a dependency between two projects, right-click the project in the Solution Explorer and select the “Project Depencies…” item from the pop-up menu as shown in the image below.

In the “Project Dependencies” dialog that appears, make sure that “PluginDLL” is selected in the “Projects” drop-down list and check the box next to “CommonDLL” in the “Depends on” frame.

Using this method, you must ensure the “Link Library Dependencies” setting in the linker options in the project properties is set to “Yes“.

Another way to link against the CommonDLL library is to explicitly tell the linker to link against the CommonDLL.lib file in the “Additional Dependencies” setting in the linker options in the project properties. Make sure you also include the output directory of the CommonDLL project to the “Additional Library Directories” setting in the linker options for the PluginDLL project properties otherwise the linker won’t know where to find the library file.

If you want to be really explicit, you may want to add the “#pragma comment” preprocessor directive directly in one of the source files for the project. The “#pragma comment” preprocessor directive can be used to instruct the linker to include a specific library when the DLL is linked. Such a pragma directive for the CommonDLL.lib file might look like this:

Using this method, you still need to add the directory paths to the “Additional Library Directories” setting in the linker options for the PluginDLL project properties.

Linking against the CommonDLL library will allow the PluginDLL library to use the classes, methods, and data that are exported from the CommonDLL library. When using the CommonDLL library, we don’t define the COMMONDLL_EXPORTS preprocessor macro which will ensure that the COMMONDLL_API macro resolves to “__declspec(dllimport)” when the classes are declared in the PluginDLL project.

In addition to linking the CommonDLL.lib file, we also add the include paths for the CommonDLL project to the PluginDLL project include file search paths. This is done by adding the path to the CommonDLL header files in the “Additional Include Directories” setting in the “C/C++” options for the PluginDLL project properties.

The ConcretePlugin Class

Now let’s create a new class in our PluginDLL project called “ConcretePlugin“.

The ConcretePlugin type is derived from the Plugin base type that was defined in the CommonDLL library.

Now let’s define the functions that will be exported from the PluginDLL library and used by the PluginManager to get access to the ConcretePlugin type.

The CreatePlugin and DestroyPlugin methods

In the “PluginDLL.h” file that is automatically generated by the project wizard, we’ll declare a few methods that will be exported from the DLL and used by the PluginManager to create an instance of the ConcretePlugin we just declared.

Besides exporting the function prototypes using the PLUGINDLL_API macro, we need to also tell the compiler to use “C” linkage when compiling these methods. Doing this will prevent the compiler from mangling the names of these methods and make it possible to get the address of the method using the GetProcAddress method in the PluginManager class.

Let’s take a look at the definition of these functions.

We define a pointer to a ConcretePlugin type in the global scope of the PluginDLL compilation unit called “g_ConcretePlugin“.

In the CreatePlugin method, we create the ConcretePlugin and return a pointer to it.

In the DestroyPlugin method, we simply delete the plugin and set the g_ConcretePlugin pointer to NULL.

The ApplicationTest Project

Now we need an application to test our dynamic plugin loading.

Create a new Win32 project in the current solution but this time select “Win32 Console Application” or create a “Win32 Project” and set the “Application type” to “Windows application” instead of “DLL”. Give the new project a name like “ApplicationTest” or something similar.

Before we can use the plug-in system defined in the CommonDLL project, we must setup implicit linking with the CommonDLL.dll file. Since I’ve already explained how to setup implicit linking when we created the PluginDLL project, I won’t explain it here again. Just make sure the ApplicationTest adds the CommonDLL.lib file as a library dependency.

The Main Source

For our test application, we only need a single file that will use the PluginManager defined in the CommonDLL project to load a plugin from the PluginDLL library that is explicitly linked from the “PluginDLL.dll” file at run-time.

You’ll see that it is now very easy to dynamically load a plugin using the PluginManager class. We only need to use the PluginManager::LoadPlugin method to load the DLL and get a pointer to the plugin defined in the DLL.

Special Considerations

There are a few things you have to consider when making DLL’s. The largest concern is with sharing memory across DLL boundaries. Another issue I would like to address is the annoying warnings given by Visual Studio when exporting a class that defines templated type member variables.

Sharing Memory Across DLL Boundaries

Usually it isn’t safe to allocate memory in a DLL and pass that memory across the DLL boundary into the main application. The problem is that if the DLL is explicitly linked, then it can be explicitly un-linked which may leave that dynamic memory allocated inside the DLL in no-man’s-land. Which could be bad for the end-user who may not understand this restriction. A possible solution to this problem is using handles. Handles can refer to an object that is created in, and owned by an interface that is only accessible using functions exposed by the DLL itself. This is a pretty common solution to this problem, but it has it’s drawbacks. The most obvious drawback is that you don’t have direct access to the methods and data members that are associated with the created object. A lot of extra code has to be written that strictly hides access to the object types using methods.

A more natural way of sharing this type of data across DLL boundaries is using weak pointers. Weak pointers are pointer objects that don’t give ownership of the pointed-to (pointee) object but only keep track of the pointee’s existence. Before you can use the pointee that the weak pointer refers to, you must first check if the weak pointer points to a valid object by “locking” the referenced object so that it won’t suddenly be deleted while your trying to use it.

The Boost library provides the boost::smart_ptr and boost::weak_ptr pointer objects that can be used to safely share memory across shared libraries.

How to Avoid the C4251 Warning

The other consideration I wanted to bring up is the annoying warnings that Visual Studio generates when you try to declare templated data members in an exported class.

This was demonstrated in the PluginManager class with the m_Plugins and m_Libs member variables which will generate the following warnings:

The warning occurs because you are trying to export the PluginManager class including all of the methods and members that are declared in the class but the instantiated template type is not exported so it can’t be used directly outside the DLL without being defined.

Usually this error can be safely ignored if it is reported on private member variables that can’t be accessed outside the class anyways. These particular data members are only used internally so why would I care if these members are exported when they shouldn’t be.

One solution to this problem is not to export the entire class, but only the public and protected members of the class.

We could change our PluginManager class declaration to this:

You’ll notice that I removed the COMMONDLL_API specifier on the class definition and added the specifier to the public methods. Using this approach, no member functions or data will be exported unless explicitly stated using the COMMONDLL_API macro.

Another solution to the problem is to hide the data members from the interface using the Pimpl (pointer to (private) implementation) idiom.

If we convert the PluginManager class to using the Pimpl idiom, we may get something similar to what is shown below:

On line 6 a class called PluginManagerPimpl is forward-declared and on line 21, we’ve replaced the data members with a pointer to the PluginManagerPimpl type. The PluginManagerPimpl class is defined in the same compilation unit as the PluginManager class.

The PluginManagerPimpl class only stores the two data members that have been removed from the PluginManager class. Then we have to update the PluginManager‘s constructor and destructor to create and delete the instance of the PluginManagerPimpl.

As well, we also need to update all of the occurances of m_Plugins and m_Libs with m_Implementation->m_Plugins and m_Implementation->m_Libs throughout the PluginManager functions.

Personally, I would prefer to use the first approach to explicitly export the necessary methods from the class instead of exporting the entire class because it communicates the intentions of the class to the user more clearly than the Pimpl approach does.

Conclusion

In this article I have shown how you can create a Common DLL that is implicitly linked in both the main application as well as the dynamic Plugin DLL. I’ve shown how you can explicitly link a DLL at run-time using the LoadLibrary method. I’ve also shown how you can define some methods that can be exposed outside of an explicitly loaded DLL using the extern “C” linkage specification. And finally, I’ve discussed a few additional points that you should be aware of when working with DLL’s and how to circumvent the annoying C4251 warning.

If you have any questions, concerns or comments, please leave a message at the end of this post and I will try to answer your questions as best as I can.

Download the Source

You can download the source code from this article including solution and project files for Visual Studio 2008 from here:

[CreatingDLLs.zip]

(Select “File -> Download Original” from the file menu or use the Ctrl-S shortcut key to save the .zip file from Google Docs).