The Basics of Creating a Static Library Using Visual C++

This article shows creation of a static library and how to use a static library using Visual Studio. The sample projects in this article were created using Visual Studio 2010.

A static library consists of object files that are linked together with an exe file. Object files are the output of compilers of unmanaged code and consists of functions that can only be used by unmanaged code. A static library is linked with the code that uses (calls) it by the link editor. If you are not familiar with link editors then the concept and purposes of link editors probably seems strange to you. The important thing is that a static library is combined with the other code such that everything is put into one executable file. A static library can be used by multiple programs and when it is, it is copied into every executable file it is used in. A static library cannot be used by managed (.Net) code directly therefore they are useless for most C# programmers.

One practical use of a static library is to split a very large unmanaged project into two or more smaller projects. If that is done then the static library is likely used in just the one project and the static library project would probably be created after the project that uses it. The static libray might be tested using the project that uses it or another project could be created just for testing purposes.

Another practical use of a static library is as a general-purpose library used by multiple unmanaged applications. It would then likely exist in a project created for it and a test application would be created for it. In this article, I am creating a static library as if it will be a general-purpose library used by multiple applications. Therefore we will begin by creating the project for the static library, then we will create a console application to test it. The console application will show the details of how to use a static library. It is possible to create a static library that can be called by non-managed languages other than C++ but if that is to be done then the functions must be linked with "C" linkage as described in this article.

Static libraries are not defined by the C++ language; they are a Windows thing. Each operating system implements static libraries differently, or might not implement them at all. Therefore, to create  a static library project, we must create a Win32 project.

To create the static library project, start by creating a "Win32 Project". When you do, the first Wizard page will be the "Welcome to the Win32 Application Wizard" as in the following:

WizardWelcome.jpg

In the next wizard page, change the "Application type" radio button to "Static library". Leave the others with default values. You can leave the "Precompiled header" option on. The Win32 Application Wizard will look something as in:

WizardSettings2.jpg

When the project was created, there will be source code files that were generated for the project named stdafx.h, stdafx.cpp and targetver.h. We will not change them. We do however need to add a header (StaticLibrarySample.h) and implementation (StaticLibrarySample.cpp) file. In the Solution Explorer, right-click on the project and select "Add" | "New Item...". Then select "Header File (.h)" as in:

AddHeader.jpg

Be sure to give the file a name. Then do the same to create a cpp file (C++ File (.cpp)), as in:

AddImplementation.jpg

For most programs, you would add #includes to the stdafx.h file but the details of that are outside the scope of this article.

Now modify the header to be as:

#pragma once
extern "C" {
int Test(int a, int b);
}

Note that the extern "C" makes the function callable by C and by other languages as well. The disadvantage of extern "C" is that it prevents use of classes and other C++ features with any functions exposed for use by callers of the static library. Modify the implementation file to be:

#include "stdafx.h"
#include "StaticLibrarySample.h"
extern "C" {
int Test(int a, int b) {
return a + b;
}
}

You can now build the project. The build will look something as:

1>------ Build started: Project: StaticLibrarySample, Configuration: Debug Win32 ------
1>  stdafx.cpp
1>  StaticLibrarySample.cpp
1>  StaticLibrarySample.vcxproj -> C:\Users\Sam\Documents\Visual Studio 2010\Projects\
C-SharpCorner Articles\StaticLibrarySample\Debug\StaticLibrarySample.lib ========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

Using the Static Library

To create a program that uses the library, go to the Solution Explorer and right-click on the Solution. Select "Add" | "New Project...". Create a Visual C++ Win32 Console Application. In the Application Settings window, keep the defaults; we do not want an empty project and we do want pre-compiled headers. The "Add New Project" window will look something as:

NewProject.jpg

When the project has been generated, set it as the Startup project.

We need to add the include directory to the project. Go to the Solution Explorer and right-click on the test project, then select "Properties". In the left side, under "Configuration properties" expand the "C/C++" node, then select "General". In the top-right is "Configuration"; change it to "All Configurations". Then in "Additional Include Directories" add the directory of the static library project where the static library's header (StaticLibrarySample.h) is at. The window will look something like:

IncludeDirectory.jpg

Next we need to specify the library to be used. In the project properties, and with the configuration set for All Configurations, go to the "Input" node of the "Linker" properties. In the "Additional Dependencies" add the name of the static library; just the filename and extension, but not the directory. The properties window will look something like:

Library.jpg

If you click in the box for entering the Additional Dependencies then you will see an arrow at the right of that. Click the arrow and select "<Edit...>". You will then get a dialog for editing the dependencies that looks like:

LibraryDependency.jpg

Next we need to specify the directory of the library. That is done in the project properties, but this time we will specify different directories for each configuration. So with the configuration set for "Active(Debug)", go to the "General" node of the "Linker" properties. Specify the directory where the Debug configuraton of the library is at. The property page will look something like:

LibraryDirectory.jpg

Do the same for the Release configuration.

Then in the test program's cpp file, after the include for "stdafx.h", add an #include for "StaticLibrarySample.h". Then in the main function, add the line:

_tprintf(_T("%d"), Test(1, 9));

One more thing worth doing is to ensure that the solution knows that the test project depends on the static library. Go to the Solution Explorer again but right-click on the Solution then choose Properties. Then in the left side click on "Project Dependencies" under the "Common Properties" node. Ensure that the test project has the checkbox checked for the static library. That property page looks like:

ProjectDependency.jpg

Build and test the program.