Using Shared Libraries

On some environments, most notably Windows, we need to do some extra work when we want to use shared libraries.

• When we want a symbol to be visible to consumers of a shared library, we need to explicitly export it
• When a symbol we're using is defined in a shared library, we need to explicitly import it

With MSVC, for example, we export a symbol by annotating it with __declspec(dllexport). This means that, in our library code, we'd want something like this:

1// This symbol should be visible to consumers
2__declspec(dllexport) void some_function() {
3  // ...
4}

And, when code elsewhere wants to use a symbol defined in that library, it would annotate the declaration with __declspec(dllimport). This means that, in our executable target, our declaration of that symbol might look something like this:

1// This symbol will come from a shared library
2__declspec(dllimport) void some_function();
3
4int main() {
5  some_function();
6  return 0;
7}

This can be annoying so, to make things easier, we tend to implement this annotation logic in a single place - our library's header file. The code in this header file naturally gets added to every translation unit it is needed via #include directives.

The symbols in the translation unit used to compile the library will need dllexport attributes, whilst the translation unit of any library consumer will need dllimport attributes. We can use the preprocessor to switch between them. For example:

1#pragma once
2#include <string>
3
4#ifdef _WIN32
5  #ifdef GREETER_EXPORTS
6    #define GREETER_API __declspec(dllexport)
7  #else
8    #define GREETER_API __declspec(dllimport)
9  #endif
10#else
11  #define GREETER_API
12#endif
13
14// Any symbol that is part of our public API
15// can now use the `GREETER_API` macro:
16GREETER_API std::string get_greeting();
17
18// More examples
19GREETER_API void another_function();
20GREETER_API bool yet_another(int x);
21extern GREETER_API bool some_variable;
22
23// Not exported
24void some_internal_function();

This header file now annotates get_greeting() based on GREETER_API, which has one of three possible values:

• If we are targeting Windows and GREETER_EXPORTS is defined, GREETER_API will be replaced with __declspec(dllexport), thereby flagging our symbol for export.
• If we are targeting Windows and GREETER_EXPORTS is not defined, our symbol is flagged as being imported, as GREETER_API will be replaced with __declspec(dllimport).
• If we're not compiling for Windows, GREETER_API will have no value, meaning the preprocessor will remove it and our forward declaration will simply be std::string get_greeting().

Now, to make everything work, we just need to define GREETER_EXPORTS, but only for our library target:

1cmake_minimum_required(VERSION 3.16)
2
3add_library(GreeterLib src/Greeter.cpp)
4
5target_compile_definitions(GreeterLib PRIVATE GREETER_EXPORTS)
6
7target_include_directories(GreeterLib PUBLIC
8  "${CMAKE_CURRENT_SOURCE_DIR}/include"
9)

This means that, if we're targetting Windows, the Greeter.h contents in our library's translation unit will have GREETER_API set to __declspec(dllexport), whilst our executable's translation unit will use __declspec(dllimport).

To help with managing the visibility of symbols in shared libraries, CMake comes bundled with a useful module called GenerateExportHeader, which provides a generate_export_headers() command.

This command automatically creates a header file containing the preprocessor logic we just walked through. Below, we use it to generate a greeter_export.h file containing our GREETER_API macro.

This header file will be placed in our library's build directory, so we'll also add CMAKE_CURRENT_BINARY_DIR to our search paths to ensure it can be found:

1cmake_minimum_required(VERSION 3.16)
2
3add_library(GreeterLib src/Greeter.cpp)
4
5include(GenerateExportHeader)
6
7generate_export_header(GreeterLib
8  EXPORT_MACRO_NAME GREETER_API
9  EXPORT_FILE_NAME greeter_export.h
10)
11
12target_include_directories(GreeterLib PUBLIC
13  "${CMAKE_CURRENT_SOURCE_DIR}/include"
14  
15  # For greeter_export.h (generated) 
16  "${CMAKE_CURRENT_BINARY_DIR}" 
17)
18
19# No longer needed - generate_export_header() sets the
20# required definition on the target we provided as its
21# first argument
22target_compile_definitions(GreeterLib PRIVATE GREETER_EXPORTS)

We can now #include this generated header file to replace our previous logic:

1#pragma once
2#include <string>
3#include "greeter_export.h"
4
5#ifdef _WIN32
6  #ifdef GREETER_EXPORTS
7    #define GREETER_API __declspec(dllexport)
8  #else
9    #define GREETER_API __declspec(dllimport)
10  #endif
11#else
12  #define GREETER_API
13#endif
14
15GREETER_API std::string get_greeting();

This generate_export_header() approach is more robust than our basic manual implementation, as it contains logic to handle import/export requirements beyond just Windows.

It also defines further macros that we can optionally use if we want to explicitly declare some symbols as being internal (that is, not exported), or to flag some symbols as deprecated.

Official documentation for the GenerateExportHeader module is available here.

Let's walk through the entire process to see the effect of this change.

Configure with BUILD_SHARED_LIBS ON

From our build directory, we'll re-configure the project, this time setting our new option to ON:

1cmake -DBUILD_SHARED_LIBS=ON ..

Build the Project

Now, we run the build command as usual.

1cmake --build .

If you inspect your build/greeter directory, you'll see that instead of a static library (.a or .lib), CMake has produced a shared library (.so on Linux, .dll on Windows).

The Runtime Linking Problem

Now, let's try to run our GreeterApp (or GreeterApp.exe) application from the build/app directory:

1./app/GreeterApp

As you may have guessed, our GreeterApp now depends on a shared library that it probably can't find. As such, our program will likely error, or just appear to do nothing at all.

1./app/GreeterApp: error while loading shared libraries: libGreeterLib.so: cannot open shared object file: No such file or directory

The operating system's loader saw that GreeterApp needs libGreeterLib.so, but it didn't know where to find it.

The loader only checks a few specific places for any shared library that our executable needs. The /build/greeter directory where our shared library is placed after compilation is not one of them.

This is a classic deployment problem. Our build directory is a messy, intermediate workspace. It's not a clean, reliable environment for running our application. To solve this, we need a proper installation step.

The install() command is CMake's mechanism for taking the outputs from a messy build directory and arranging them into a clean, distributable layout. This "install" directory is what you would package into a .zip file or an installer to give to other people.

Installation, packaging and distribution is an important topic that we'll cover in a dedicated chapter later in the course. But for now, let's walk through a quick example, as the installation process sets some useful context of how CMake can also prepare our project for distribution to users.

The install() command tells CMake what to do when we run the --install build step. We'll cover how to run that soon, but lets first set up what should happen when we do.

Installing the Executable

In app/CMakeLists.txt, we'll add an install rule for our executable:

1cmake_minimum_required(VERSION 3.16)
2
3add_executable(GreeterApp src/main.cpp)
4target_link_libraries(GreeterApp GreeterLib)
5
6# Install the final executable to a 'bin' directory
7install(TARGETS GreeterApp DESTINATION "${CMAKE_SOURCE_DIR}/bin")

Our arguments are the following:

1. The TARGETS keyword, informing CMake that the installation rule we are setting applies to targets, and that the next argument(s) will specify those targets.
2. The targets that these rules apply to. We're applying this rule only to the GreeterApp target, so only a single argument follows TARGETS in this case. We could add more if needed.
3. The DESTINATION keyword informs CMake that the next argument will specify where we want our files installed to.
4. The "${CMAKE_SOURCE_DIR}/bin" argument will cause our files to be installed in a directory called bin (binary), which is a common convention. The use of the CMAKE_SOURCE_DIR prefix specifies that this bin directory will always be in the root of our project.

Eventually, users should be able to specifiy where on their system the program should be installed, but we'll keep things simple for now. We'll learn much more about installation later in the course.

Installing the Library

Let's set the same install() rules for our library:

1cmake_minimum_required(VERSION 3.16)
2
3add_library(GreeterLib src/Greeter.cpp)
4
5include(GenerateExportHeader)
6
7generate_export_header(GreeterLib
8  EXPORT_MACRO_NAME GREETER_API
9  EXPORT_FILE_NAME greeter_export.h
10)
11
12target_include_directories(GreeterLib PUBLIC
13  "${CMAKE_CURRENT_SOURCE_DIR}/include"
14  "${CMAKE_CURRENT_BINARY_DIR}"
15)
16
17install(TARGETS GreeterLib 
18  DESTINATION "${CMAKE_SOURCE_DIR}/bin"
19)

Combined, these rules will place our executable file and shared library in the same location - within /bin in our project root.

Setting the Runtime Library Search Path (rpath)

Placing our shared library in the same location as our executable is enough to let Windows find it. When an .exe file asks for a .dll file, Windows will automatically search the same directory.

However, on Unix-like systems (including macOS and Linux), we need one more step. We'll set the INSTALL_RPATH property on our GreeterApp target. This property gets embedded into the executable, and gives Unix-like systems some additional hints about where that executable's dependencies might be.

The special "$ORIGIN" path will be resolved to the directory the executable is in. This means the platform will look in that same location for any libraries we need, replicating Windows' behavior:

1cmake_minimum_required(VERSION 3.16)
2
3add_executable(GreeterApp src/main.cpp)
4target_link_libraries(GreeterApp GreeterLib)
5
6install(TARGETS GreeterApp DESTINATION "${CMAKE_SOURCE_DIR}/bin")
7
8set_target_properties(GreeterApp PROPERTIES 
9  INSTALL_RPATH "$ORIGIN" 
10)

Now let's see our new installation rules in action.

Configuring and Building

First, we configure and build our project as usual. Let's build the shared library version again.

1cmake -DBUILD_SHARED_LIBS=ON ..

1cmake --build .

Installing

Now, we execute the --install step. As with the previous step, we'll run this from our ./build directory, and use the . command to tell CMake the output of our build is in this same directory:

1cmake --install .

This command runs the install() rules we defined. It finds the built artifacts in the current directory and its subdirectories, and copies them to the locations we requested in our DESTINATION arguments.

Inspecting the Result

If you now look in the bin directory, you should both our library and our executable. And, if we run the executable from that location, everything should work.

The following command assumes we're currently in the build directory, so .. navigates up to our project root, and /bin navigates to the bin directory in that location. Remember to add .exe on Windows:

1../bin/GreeterApp

1Hello from the modular greeter library!

This was only a brief introduction to a very large topic, and our basic implementation isn't flexible or robust. For example:

• Users cannot control the installation directory. We've hardcoded the destination to the /bin directory in the project root. The cmake --install command even has a --prefix option to let users set their location, and this flexibility is required to package and ship our project, but our CMakeLists.txt files doesn't support it.
• If we revert back to a static library (such as by setting -DBUILD_SHARED_LIBS=OFF) then the library will still be copied over to our /bin directory, even though it's no longer needed.
• Installation isn't just for end-users wanting to run our executable. For example, it is also how we would prepare our libraries to be used by other developers. The implementation for that use case looks totally different to what we set up here.

We'll revisit installation and packaging later in the course, addressing all these limitations and much more.

This lesson covered some of the most important practical aspects of authoring and using libraries in a modern CMake project.

• Configurable Library Types: Use the BUILD_SHARED_LIBS option to allow users to easily switch between STATIC and SHARED builds of your libraries.
• Installation for Distribution: Use the install() command to gather your project's artifacts into a clean, distributable directory structure. This separates it from the temporary build tree and prepares it for packaging and shipping (which we'll cover later).