Static Libraries
From a Game Programming Perspective
by Stefan Hajnoczi
intertainment@mad.scientist.com
http://www.intertainmentsoftware.com

What are static libraries?

A static library is a library that is linked into your code at compile-time. The file extension for a static library is ".LIB". They are called Win32 Static Library in Microsoft Visual C++. Many standard Windows libraries are provided to you as static libraries. If you look around in Visual C++’s "\Lib" directory, you will find all of the standard static libraries that come with Visual C++. If you have ever used DirectX, then you will know that you must include various libraries in your project in order to get it to work. So if we use DirectX as an example, with every static library, you also have an associated header file. The DirectDraw component is accessible from "ddraw.h" and "ddraw.lib". The library file contains all the code, while the header declares all the functions that are in the library. So if we visualize the process of creating a static library:

First we program our library, we have a header and a source file. After compiling it, we distribute the header and the library file. We will get more into the details of creating static libraries later, but first, let’s take a look at the pros and cons of static libraries.

Why use static libraries?

Static libraries don’t have any run-time speed penalties and are simpler to make the Dynamic Link Libraries. If you don’t want any terribly dynamic architecture similar to many plug-in systems, static libraries are a good choice. Of course, if the library changes and you want the program to use the newest version, the program will have to be re-compiled. In those cases, dynamic link libraries are better, since as long as the functions’ return values and parameter list haven’t changed, you can just "plug" it in and take advantage of the newest features. Here are the advantages of static libraries:

Who ever uses the libraries cannot see or change the source code.
The library code won’t get mixed up in the actual project source code.
There is no speed penalty for using static libraries.
Static libraries can be easily re-used across multiple projects.

So if you are developing a library, engine, or wrapper, static libraries are great. For example a scripting library can be neatly isolated from the rest of a program in a static library. Even more importantly, it can be re-used in future projects.

Creating static libraries

Start Visual C++ and click File | New. Select Win32 Static Library, enter a name for the project, and click OK.

Now you can choose if your header should be pre-compiled and if you want support for the MFC. Usually, you should say no to both. Click on Finish.

Confirm the next dialog box you get and you are ready to go. Create a header file and a source file, implement your library, and compile (Crtl + F5) it. Once you have compiled, you will have a ".LIB" instead of an ".EXE". A dialog box will appear asking for an executable that uses this library.

The library can’t be executed like a program, but it can be included in another project that is executable. So in order to test your library for bugs, you will have to code a test harness, which is good practice anyway. If you don’t have a test program yet, you can just click Cancel.

Using static libraries

Using static libraries is very easy, in fact, you probably already know how. Just in case you don’t know how, I’ll show you. Note that both a Win32 Console Application and a Win32 Application can use static libraries. Pretty much any type of project can use static libraries. You need to include the library’s header file in the source files of your project.

Now click Project | Add to Project | Files… and select the ".LIB" you want to use.

In the Open… dialog box, you will need to change the file type to Library Files (.lib) in order to see ".LIB" files. After selecting the appropriate file and clicking OK, the library will be included in your project.

Now you can compile (Ctrl + F5) and everything should work fine.

About the demo

I wrote a sample library and a program that uses it. I decided to write a math library, called MathLib. This math library has a constant (p), several functions (² and Ö, for both integers and floats), and a class (a 3d vector). The program that uses it performs a few calculations using MathLib and displays their results. MathLib is very basic and is only useful as an example. It is very low performance and considering the size of the functions, they can all be inlined for increased speed. But that has nothing to do with making static libraries, and so I decided to leave the code easy to understand. I have included the full workspace for both MathLib, the static library, and LibDemo, a program that uses MathLib.

Get the demo here.

Conclusion

Static libraries are an easy way of isolating code into libraries. Considering that making static libraries is almost no different from making a simple program, it is definitely a good thing to know how to do. The potential for code re-use makes static libraries a very good way to implement various wrappers or libraries. If you are planning on sharing, re-using, or even selling a library, then static libraries are definitely the way to go. If you have any comments, please send them to intertainment@mad.scientist.com.

Good Luck and happy coding,

Stefan Hajnoczi

Discuss this article in the forums

Date this article was posted to GameDev.net: 3/2/2001
(Note that this date does not necessarily correspond to the date the article was written)

See Also:
General
Sweet Snippets