Creating a Useable Library for Other Developers

If you are creating a third-party library that will be used by other developers, then those developers will be your users, and you want to give them a product that is highly useable. Many times I have been given a library by other developers (often within the same company I worked for at the time), and these libraries were practically unuseable. Therefore, here are some rules to help you create a highly useable library for other developers:

RULE

Allow for both static and dynamic linking.

Include two versions of your library: One is a dynamic library, and one is a static library. That way the other developer can choose whether to static-link your code right into an application or to ship your dynamic library with the application; let it be the developer’s choice!

RULE

Include the proper files with your library.

This should go without saying. Always remember to ship all the necessary files with your library, including:

• The correct import libraries

• A prebuilt dynamic library

• A prebuilt static library

• The correct header files

• Possibly the source code

Of course, you might not want to ship the source code. But even if you do, please include prebuilt libraries so that the developers don’t have to rebuild the libraries from scratch. (Besides, would you really want them rebuilding the dynamic library and then shipping their own custom-built version of your dynamic library?)

RULE

Remember to use that strange declspec stuff in your header files.

A declspec line is a line in a Windows code file that specifies whether the function is exported by the library or imported into the application. Why include that line? Because you will typically use the same header file for both building the library and building the application using the library. But when building a dynamic library, you need to denote each function as being exported by the library. When building an application using the library, you need to denote each function as being imported from a dynamic library, if you’re using a dynamic library. And if you’re using static libraries, you neither import nor export the functions. And you specify this information all within a single header file.

The standard way to do this is by using some preprocessor definitions. People have different ways of defining the symbols, but here is one way I use that works:

• One symbol is set in the case of building the dynamic library.

• Another symbol is set in the case of building the application using the dynamic library.

• No symbols are set in the case of building the static library and the application using the static library.

Here’s an example; this goes inside the header file:

 #ifdef MYDLL_EXPORT  #define MYDLL_API __declspec(dllexport)  #elif defined(MYDLL_IMPORT)  #define MYDLL_API __declspec(dllimport)  #else  #define MYDLL_API  #endif  MYDLL_API int foo(void); 

The preprocessor lines check whether the symbol MYDLL_EXPORT is defined, in which case the symbol MYDLL_API gets set to __declspec(dllexport). Or, if the symbol MYDLL_IMPORT is defined, the symbol MYDLL_API gets set to __declspec(dllimport). Or, if neither is defined, the symbol MYDLL_API gets set to nothing.

Now look at the function prototype; it begins with MYDLL_API. Thus, in the case of a dynamic library where MYDLL_EXPORT was defined, this function is preceded by the directive __declspec(dllexport), telling the compiler to export the function.

In the case of an application using the dynamic library (where MYDLL_IMPORT was defined), the function will be preceded by the directive __declspec(dllimport), which tells the compiler to import the function during link time.

And finally, in the case of either a static library being built or an application using the static library being built, the MYDLL_API symbol will be defined as nothing, putting no directive in front of the function, making the function neither imported nor exported.

This means that for your dynamic library project, you need to define the symbol MYDLL_ EXPORT in your project settings. For an application using the dynamic library, you need to define the symbol MYDLL_IMPORT in your project settings. For a static library project, you do not define either symbol. And similarly, with a project for an application using the static library, again you do not define either symbol.

SUGGESTION

Don’t require a gazillion other libraries in order to link.

Nothing is more frustrating than receiving a library, attempting to link the library into an application, and then receiving a bunch of undefined symbol errors. Don’t require all sorts of other libraries, and if you do require these libraries, make it very clear when distributing your library that the other libraries are necessary.

RULE

Don’t require “dummy functions.”

I’m serious. I’ve seen this happen: A developer creates a static library without realizing that the library requires certain functions that existed in the main test application and not the library itself. When another developer receives the library, she is distraught to learn that several functions are needed to make the library work, and the only way to get past this roadblock is to create dummy functions that do nothing but satisfy the linker. (Yes, I really have seen this happen!)

SUGGESTION

Document your library.

I shouldn’t have to tell you the importance of documenting your library, but again, I’ve seen developers ship libraries without any documentation. Come on, folks, it doesn’t take that long to write up a short synopsis of the functions and to include a sample or two. In fact, here are documentation items you should include with your library:

• Good documentation explaining what each function and class does. (In other words, this is a reference guide.)

• A general write-up explaining how to use the library. (Don’t expect the developers to just read the entire reference guide and piece together the necessary functions!)

• Some samples that make use of the majority of the functions. (Yes, some of us prefer samples to abstract help documents.)

• Solid installation procedures for deploying the library with the application. Remember these developers will probably be shipping your library to end users’ computers, and the developers will need solid instructions on how to install your library. This is especially true if you have implemented your own versioning system as I describe in “Implementing Your Own Versioning System on Windows,” earlier in this chapter.