Creating a C++ library with CMake
All of the sudden I found myself in a situation that I have been successfully avoiding so far — I needed to make a C++ library with CMake.
To clarify, this will be about so-called normal kind of library.
The library
Folder structure and sources
For the sake of focusing on CMake side of things, the library itself is very trivial:
This particular folder structure is not enforced, but I’ve seen it being used around and I think it serves nicely for the purpose of keeping library files organized. Following this structure, you put internal library sources and headers to src folder, and public headers go to include folder. This article, however, lists a few disadvantages of such approach.
Public headers is something other projects will use to interface with your library. That is how they will know what functions are available in it and what is their signature (parameters names and types). So, include/some.h is a public header, and here are its contents:
So our library has just one function. Its definition is in src/some.cpp :
As you can see, this function just prints a message to standard output. The someString variable comes from internal header src/things.h :
CMakeLists
Making a library with CMake is not that different from making an application — instead of add_executable you call add_library. But doing just that would be too easy, wouldn’t it.
Here are some of the things you need to take care of:
- what artifacts should the library produce at install step
- where install artifacts should be placed
- how other applications can find the library
- when they are using it pre-built as an external dependency
- when its sources are nested in their source tree
- will you need to have it as DLL on Windows
Everything from this list is handled by CMake. So let’s gradually create a CMakeLists.txt for the library project.
Top-level and nested projects
In CMake projects there is a variable called CMAKE_PROJECT_NAME. It stores the top-level project name that you set with project command. This variable persists across all the nested projects, and so calling project command from nested projects will not change CMAKE_PROJECT_NAME , but will set another variable called PROJECT_NAME.
Knowing that, here’s how you can check if you are in the top-level project or not:
Later CMake versions added a PROJECT_IS_TOP_LEVEL variable, which might be more convenient.
Why even bother with this? Because later we will be setting certain properties for the target (our library). And I saw in lots of places how people copy-paste project name value to every command, which I believe is just a bad idea — it is much better to use already defined PROJECT_NAME variable instead, innit.
Target
Here go the library target and its sources:
Here the library is defined as STATIC , but actually it’s not a good idea to hardcode libraries type like that in their project files, because CMake has a global flag for this exact purpose — BUILD_SHARED_LIBS — and in general it’s better to rely on that flag instead of setting libraries type inline. There will be also a section about shared libraries later.
Include directories
Setting include directories correctly with target_include_directories is very important:
Paths in PRIVATE section are used by the library to find its own internal headers. So if you would place things.h to ./src/hdrs/things.h , then you will need to set this path to $
/src/hdrs . Paths in PUBLIC section are used by projects that link to this library. That’s where they will look for its public headers:
- BUILD_INTERFACE path is meant for projects that will build the library from their source tree, and here you need to add include , because that’s where public headers are in the library’s source folder
- INSTALL_INTERFACE is meant for external projects, and here you don’t need to add include , because CMake config will do that for you
Install instructions
We need to declare what artifacts should be put to installation directory after building the library. You also need to specify the path of installation directory (where you would like it to be).
Certainly, just building the library is already enough to be able to link to it, but we want to do it in the most comfortable way: not by providing paths to its binaries and headers from both build and sources directories, but by installing just the artifacts we need and using find_package command.
With find_package you let CMake to worry about finding the library, its public headers and configuring all that. Here’s a more detailed documentation about how find_package works, and here’s how you can create a CMake config of your own.
Installation path
First thing to think about it is the installation path. If you will not set it during configuration step via CMAKE_INSTALL_PREFIX ( -DCMAKE_INSTALL_PREFIX="/some/path" ), then CMake will set it to some system libraries path, which you might not want to use, especially if you are building your library for distribution.
Here’s how you can overwrite default installation path to install the artifacts into install folder in your source tree:
Public headers
Next thing you need to do is to declare PUBLIC_HEADER property:
Note, however, that this doesn’t preserve the folder structure, and so for more complex projects that won’t give the desired result. For instance, here are the public headers of the glad library:
Trying to install it, you’ll get the following result in the installation path:
which won’t work for khrplatform.h header, as it is expected to be included like this:
In order to preserve the folder structure, you can use the following trickery:
Debug suffix
It might be a good idea to add d suffix to debug binaries — that way you’ll get libSomeLibraryd.a with Debug configuration and libSomeLibrary.a with Release. To do that you need to set the DEBUG_POSTFIX property:
Or you can set it globally for the entire project on configuration with -DCMAKE_DEBUG_POSTFIX="d" .
Destinations
Here come the actual installation instructions:
Important to note here that INCLUDES is not part of the RUNTIME / LIBRARY / ARCHIVE / PUBLIC_HEADER group. See for yourself in the install() signature:
If you won’t have INCLUDES in the install() , then SomeLibraryTargets.cmake won’t have these lines:
and when you’ll try to use this (installed) library in an external project, it will configure fine, but it will fail to build:
Configs
Create Config.cmake.in file:
CMake documentation doesn’t mention it in a clear way, but you can still use the PROJECT_NAME variable here too — just wrap it in @@ .
And then in CMakeLists.txt :
The write_basic_package_version_file() function from above will create SomeLibraryConfigVersion.cmake file in the install folder. Having it, if you now try to find your package in external project ( cmake-library-example/external-project/CMakeLists.txt ) like this:
then you will get the following error on configuration:
Finally, the NAMESPACE property is exactly what is looks like — a namespace of your library. I reckon, that will help to avoid names collision and also allow to group related stuff in one namespace, similar to how Qt does it:
Building and installing
Go to library source tree root and run the usual:
Note that SomeLibraryConfig-noconfig.cmake has this weird noconfig suffix. This is because we ran configuration without specifying the build type — better to explicitly set it then, both Debug and Release:
So there you have it! The library has been successfully built and nicely installed, so now you can just zip the install folder contents and distribute it to your users.
Linking to the library
Now let’s see how your users or yourself can link to the library.
From external project
Let’s take a simple project:
The project file:
The PRIVATE keyword means that the library will be used by this project, but it will not be available to other projects via this project’s interface. For example, if this project is in turn a library itself, then yet another external/parent project linking to it won’t be able to use printSomething() function from the underlying library.
Let’s now try to build and run the application:
No need to set include_directories and use magic variables
You might have seen in other projects that they also set include_directories for external libraries, and probably you are now wondering why I didn’t do it here, and how then it all works.
Indeed, if we take a look at one of such projects, for example SDL2 installed via Homebrew on Mac OS:
Thanks to Homebrew, it is discoverable even without setting CMAKE_PREFIX_PATH :
But trying to build your application you’ll get this error:
To fix that you’ll also need to add the following to the project file:
That is because SDL2 CMake package was created in a rather obsolete manner, so you have to manually set include_directories and also to use these magic variables such as _INCLUDE_DIRS and _LIBRARIES .
Our library package is written in a more modern way, so including directories is already taken care of, and also there is no need to use any magic variables, just the package name. Nice, innit.
From internal top-level project
But what if we have our library as a part of some other top-level project, so the library lives in its source tree? Do we still need to build it first and add it to the main project via find_package ? Not exactly — now there is no need to “find” it: the library will be built together with the parent project and then linked to.
Adding nested library to the main project
Here’s the full project structure:
The main CMakeLists.txt :
Yes, it is all the same as with external project — we just need to link to the library. No crazy relative paths, just the very same target_link_libraries .
But this time we don’t need find_package and also we don’t need to provide the namespace. That last part I don’t entirely understand, but perhaps that is because everything in the project is supposed to be within the same namespace already?
Following add_subdirectory statement, we get to libraries folder, which also has a CMakeLists.txt :
And there we get to our library project.
About include paths
Let’s start with main.cpp :
While the code here is the same as the one from external project, there is one notable difference — some.h is not prepended with SomeLibrary/ in the #include statement.
Why is that, why is it different from the way in was included in external project? Well, it is because that is how this header is placed in the library’s source include folder — there is no SomeLibrary folder nested there. But when you install the library, then there is SomeLibrary folder inside include in the installation folder, so in that case you need to add SomeLibrary/ to #include statement.
I wasn’t sure if that is really how things are, so I went and asked about this on StackOverflow, hoping that there is perhaps some way to handle this in a unified way, but the answer was:
So if you would like to unify the way you include the library’s public headers both in external and internal projects, then you’ll need to create SomeLibrary folder inside library’s source include folder (yeah, to get the ugly SomeLibrary/include/SomeLibrary path) and adjust the library’s CMakeLists.txt accordingly.
Building
Main project
Do the usual in the project source tree root:
Library as a target
We can also build and install just the library, without building the entire project. Aside from just going to the library folder and running CMake from there, you can actually do it from the project root — by setting —target option on build:
Here you can also see how you can install a single target with —install option — by pointing it to the target folder inside build folder. Also note that install folder is now on the project’s source tree root level, not in the library’s nested source folder.
STATIC vs SHARED
Hopefully, you already know the difference between static and shared libraries. If not, then, to put it simple, static libraries are “bundled” into your binaries, and shared libraries are separate files which need to be discoverable by your binaries in order for the latter to work.
A little practical example: let’s build our library as static, link to it from external project, then build it as shared and link to that one.
To make our library shared, we need to replace STATIC with SHARED in add_library statement in the library’s CMakeLists.txt . And once again, like I already said, the library type should not be hardcoded like that, as it would be better to have add_library() without type and instead set -DBUILD_SHARED_LIBS=1 on project configuration.
Anyway, first thing that will be different about resulting executable ( another-application ) is its size:
- statically linked with SomeLibrary: 51 920 bytes
- dynamically linked with SomeLibrary: 51 616 bytes
Not a very noticeable difference (remember that our library just prints a line of text), but it is there: statically linked executable is bigger, because the library is “bundled” into it.
Secondly, if you now rename or delete libSomeLibrary.dylib ( libSomeLibrary.so , SomeLibrary.dll ), then trying to run this dynamically linked application you’ll get an error like this on Mac OS:
or like this on Linux:
So in case of a shared library on Mac OS or Linux it has to either stay available in its installation path, or be placed into the one of the system libraries paths. Be aware that simply copying it to the same folder with executable won’t work, unless you set the LD_LIBRARY_PATH variable on Linux (or DYLD_FALLBACK_LIBRARY_PATH / DYLD_LIBRARY_PATH on Mac OS) before running the application:
And on Windows it will fail even if you haven’t touched the library in its install folder, however you can just copy it to the same folder where executable is, but more on that below.
SHARED DLL on Windows
Shared libraries on Windows are a special thing. There it is not enough just to replace STATIC with SHARED in add_library statement (or set -DBUILD_SHARED_LIBS=1 ).
If you build and install it having done nothing else, then you will get this error trying to configure a project that needs to link to it:
And indeed, there is no SomeLibrary.lib in install/lib/ , only SomeLibrary.dll in install/bin/ . That is because a DLL on Windows needs an explicit listing of all the symbols that it will export, and apparently this is what SomeLibrary.lib is supposed to be.
As I understood, in order to produce it, in past it was required to add __declspec compiler directives to every public single class or function declaration in your library sources, which is quite a bummer, especially if you have a lot of those. Here’s one example of how this is done.
Fortunately, starting with CMake 3.4, this is no longer required. Instead you can just set the CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS option when configuring the library:
However, I saw somewhere that it is not recommended to export all the symbols like that. I didn’t quite get why, but probably there is a reason, so just keep that in mind.
Either way, now you can build and install the library as usual. Note that if you are using Visual Studio CMake generator, then -DCMAKE_BUILD_TYPE won’t work, because there configuration is specified on build step:
After that configuring and building the external application will also succeed, because now it will get that missing SomeLibrary.lib .
However, unlike Mac OS and Linux, trying to run the resulting application will fail even if you haven’t touched the SomeLibrary.dll in the install folder:
or, if running from Git BASH:
That is because on Windows you need to explicitly put the DLL either to the same folder where the executable is or somewhere in PATH.
Final words and repository
Later I will probably update the article, because, like I said, here I touched only “normal” libraries, but there are also other kinds. Plus, one can go further than just making a CMake config and create a proper package. So there are quite a few things left to talk about.
You might have noticed that most of the stuff I was doing on Mac OS, but actually everything (library and sample applications) builds and works just fine also on Linux and Windows.
Full source code of the library, its parent project and external project are available in this repository.
Updates
2022-07-05 | Updated repository
Be aware that I’ve been updating the referenced repository as I was discovering new things, but not everything has been synced-up back to the article, and so by now the article contains a somewhat simpler CMake code, while repository has a bit more advanced things (such as installation instructions being a separate CMake module).
You might also want to take a look at the article about using CPack and its example project (you can ignore the packing parts), as in particular it has a better organized installation and demonstrates re-using “shared” CMake modules.
2022-09-17 | Dynamic libraries and paths
2023-07-22 | About target_link_libraries() scopes
At some point later I also wrote about target_link_libraries() scopes in particular. There you will find yet another repository, which I now consider to be my best example of creating C++ libraries with CMake (until I learn some more CMake and make an even better one). Among other improvements, it includes exporting symbols for making a .lib file for DLLs on Windows.
How do I create a library?
Let’s say I have 10 *.hpp and *.cpp files that I need to compile a code. I know that I will need those same files for many different codes. Can I create a «package» with those files that would allow me to simply write:
I wouldn’t then need to write a makefile every time I need this «package».
To be more precise, I use Linux.
6 Answers 6
A collection of CPP sources (H files and CPP files) can be compiled together in to a "library," which can then be used in other programs and libraries. The specifics of how to do this are platform- and toolchain-specific, so I leave it to you to discover the details. However, I’ll provide a couple links that you can have a read of:
Libraries can be seperated in to two types: source code libraries, and binary libraries. There can also be hybrids of these two types — a library can be both a source and binary library. Source code libraries are simply that: a collection of code distributed as just source code; typically header files. Most of the Boost libraries are of this type. Binary libraries are compiled in to a package that is runtime-loadable by a client program.
Even in the case of binary libraries (and obviously in the case of source libraries), a header file (or multiple header files) must be provided to the user of the library. This tells the compiler of the client program what functions etc to look for in the library. What is often done by library writers is a single, master header file is composed with declarations of everything that is exported by the library, and the client will #include that header. Later, in the case of binary libraries, the client program will "link" to the library, and this resolves all the names mentioned in the header to executable addresses.
When composing the client-side header file, keep complexity in mind. There may be many cases where some of your clients only want to use some few parts of your library. If you compose one master header file that includes everything from your library, your clients compilation times will be needlessly increased.
A common way of dealing with this problem is to provide individual header files for correlated parts of your library. If you think of all of Boost a single library, then Boost is an example of this. Boost is an enormous library, but if all you want is the regex functionality, you can only #include the regex-related header(s) to get that functionality. You don’t have to include all of Boost if all you want is the regex stuff.
Under both Windows and Linux, binary libraries can be further subdivided in to two types: dynamic and static. In the case of static libraries, the code of the library is actually "imported" (for lack of a better term) in to the executable of the client program. A static library is distributed by you, but this is only needed by the client during the compilation step. This is handy when you do not want to force your client to have to distribute additional files with their program. It also helps to avoid Dependancy Hell. A Dynamic library, on the other hand, is not "imported" in to the client program directly, it is dynamically loaded by the client program when it executes. This both reduces the size of the client program and potentially the disc footprint in cases where multiple programs use the same dynamic library, but the library binary must be distributed & installed with the client program.
Руководство по CMake для разработчиков C++ библиотек
В этой статье я расскажу о том, как правильно писать современные CMakeLists.txt файлы для C++ библиотек. Идеи, используемые в ней, основаны на докладе Крейга Скотта (разработчик CMake) и докладе Роберта Шумахера (разработчик vcpkg) c CppCon 2019. Поскольку мне достаточно часто приходится разрабатывать С++ библиотеки, я создал для себя небольшой шаблон cpp-lib-template, который будет использоваться в этой статье в качестве примера.
Замечу, что я предполагаю, что читатель этой статьи имеет опыт работы с CMake, однако, как и я, часто задается вопросом, как правильно ему сделать сборку своей библиотеки.
Введение
Разработчик C++ библиотеки, очевидно, должен дать своим пользователям возможность легко ее использовать. И раз уж мы пишем на компилируемом языке, то к этому относится и то, насколько быстро пользователь сможет пройти путь от клонирования ваших исходников до получения бинарного файла библиотеки под свою платформу.
Когда мы говорим о пользователях библиотеки, то в первую очередь думаем о других разработчиках, которые захотят использовать функциональность библиотеки в своих проектах. Существует два способа, которыми библиотека может интегрироваться в проект:
С помощью find_package — в этом случае библиотека должна предоставить package configuration file, который импортирует в CMakeLists.txt приложения таргет библиотеки. Этот файл, вместе с собранной библиотекой, ее публичными заголовочными файлами и некоторой другой информацией устанавливается в директорию, которая потом указывается в переменной CMAKE_PREFIX_PATH при сборке проекта.
Как подпроект, добавленный в качестве git submodule или с помощью CMake модуля FetchContent — в этом случае приложение использует обычный (не импортированный) таргет библиотеки ( find_package не вызывается), и сборка библиотеки становится этапом сборки самого проекта.
Еще одна категория пользователей библиотеки — мейнтейнеры различных пакетных менеджеров (например, vcpkg, conan и другие), которым нужно собирать библиотеку под десятки различных платформ и конфигураций. Для них важно, чтобы сборкой библиотеки можно было управлять извне, без необходимости внесения патчей в ее CMakeLists.txt.
Исходя из вышесказанного, хорошо сделанная библиотека должна удовлетворять следующим требованиям:
Единообразно интегрироваться и через find_package , и через add_subdirectory / FetchContent , т.е. импортированный таргет и обычный должны быть эквивалентны. В англоязычных источниках это требование часто формулируют как «build interface should match install interface».
В ее CMakeLists.txt не должны хардкодиться опции и флаги компиляции/компоновки кроме тех, которые абсолютно необходимы для сборки библиотеки. В противном случае мейнтейнерам менеджеров пакетов будет проблематично упаковывать библиотеку, так как с вероятностью, стремящейся к 1, на какой-то из платформ некоторые захардкоденные значения окажутся невалидны и придется делать патч для CMakeLists.txt .
Структура директорий
В своих библиотеках я придерживаюсь структуры директорий, представленной ниже. На мой взгляд, она является наиболее распространенной, кроме того, интуитивно разделяет файлы библиотеки на основные компоненты: публичные заголовки ( include/<libname> ), исходники ( src ), утилиты для сборки ( cmake ), примеры ( examples ) и тесты ( tests ).
Пример библиотеки
В дальнейшем в этой статье мы будем рассматривать простую библиотеку mylib, предоставляющую всего одну функцию add , которая возвращает результат сложения двух чисел:
Соответствующий заголовочный файл:
Наконец, файл mylib/export.h :
Файлы export_shared.h и export_static.h генерируются CMake и будут рассмотрены ниже.
Определение проекта
Первое, что нужно сделать в CMakeLists.txt — это создать проект для библиотеки:
Я предпочитаю заранее определить таргет для библиотеки, а инициализировать его ниже в коде, когда определены все необходимые параметры. Здесь же мы определим алиас для библиотеки, который должен иметь то же имя, что и импортируемый таргет. Это позволит пользователям библиотеки легко переключаться между ее подключением через find_package , в результате которого создается импортированный таргет с именем mylib::mylib , и подключением через add_subdirectory / FetchContent , который делает доступным алиас mylib::mylib в их проекте. Таким образом, приложение, использующее нашу библиотеку, в обоих случаях может линковаться к библиотеке с помощью команды:
Переменная is_top_level используется в дальнейшем в нескольких местах для определения, собирается ли библиотека как stand-alone проект или как подпроект. Версии CMake, начиная с 3.21, предоставляют переменную PROJECT_IS_TOP_LEVEL для этой же цели. Можно использовать и ее, но тогда в cmake_minimum_required придется указать версию не ниже 3.21.
Опции сборки
Сразу после определения проекта для библиотеки я рекомендую указать все опции, которые вы предоставляете для управления ее сборкой. Эта информация важна для пользователей библиотеки и поэтому лучше размещать ее в самом начале в одном месте. Типичными опциями являются:
Опции MYLIB_BUILD_* определяют, собирать или нет соответствующий компонент библиотеки. По умолчанию они выключены, потому что пользователи библиотеки, как правило, заинтересованы только в сборке самой библиотеки.
Если библиотека может быть собрана как статически, так и динамически, крайне не рекомендуется использовать кастомную переменную для определения типа сборки, потому что общепринятым стандартом является использование переменной BUILD_SHARED_LIBS , которая обрабатывается самим CMake. Следующий код является примером того, как делать не стоит:
BUILD_SHARED_LIBS , однако, влияет на все библиотеки, попадающие в сборку, а пользователям в редких случаях может понадобиться собрать несколько библиотек иначе, чем указано в BUILD_SHARED_LIBS . Поэтому среди опций библиотеки mylib есть MYLIB_SHARED_LIBS , которая может использоваться для переопределения значения BUILD_SHARED_LIBS .
Переменная MYLIB_INSTALL определяет, нужно ли генерировать таргет для установки mylib. Ее значение по умолчанию определяется тем, собирается ли mylib как отдельный проект, или как подпроект другого проекта.
Наконец, переменная MYLIB_INSTALL_CMAKEDIR позволяет указать, куда устанавливать файл конфигурации пакета (package configuration file), и предназначена в основном для мейнтейнеров менеджеров пакетов. Функция set_if_undefined определена в файле cmake/utils.cmake и аналогична set , но устанавливает значение только если переменная еще не определена (напомню, что мы не хотим переопределять любые переменные, которые установлены через командную строку CMake или в проектах верхнего уровня).
Экспорт символов
В бинарном файле любой динамической библиотеки есть раздел, в котором хранится информация о том, какие функции экспортируются данной библиотекой. Эта информация используется динамическим загрузчиком — компонентом ОС, который занимается тем, что загружает в память динамические библиотеки, нужные приложению. Помимо этого, задача динамического загрузчика заключается в том, чтобы выполнить релокации — заменить заглушки в исполняемом файле приложения на реальные адреса в памяти, куда была загружена динамическая библиотека.
В деталях описание этого процесса можно найти в статьях, ссылки на которые даны в конце поста. Сейчас же для нас важно знать, что от количества экспортируемых функций напрямую зависит, как быстро будут стартовать приложения, использующие вашу библиотеку (чем меньше экспортируемых функций, тем быстрее).
GCC и Clang по умолчанию экспортируют все символы, которые есть в библиотеке (в том числе те, что не являются частью API), что, как мы только что выяснили, негативно сказывается на скорости загрузки. CMake позволяет легко отключить это поведение, установив следующие переменные (замечу, что здесь я тоже использую функцию set_if_undefined , чтобы дать возможность пользователю при необходимости переопределить эти значения):
MSVC по умолчанию ничего не экспортирует, однако CMake предоставляет переменную CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS , которая позволяет получить поведение, аналогичное GCC и Clang. Очевидно, что использовать ее не стоит.
Для экспорта конкретного символа из библиотеки разные компиляторы предоставляют разные директивы. Чтобы не углубляться в особенности компиляторов, можно воспользоваться функцией CMake generate_export_header . Эта функция создает файл, содержащий определение макроса MYLIB_EXPORT , который нужно указывать для экспортируемых символов. Процесс генерации файла элементарен:
В результате в зависимости от типа сборки библиотеки CMake создаст в билд-директории один из двух файлов: export_shared.h или export_static.h .
Объясню, почему используются разные имена в зависимости от типа сборки. Это нужно, чтобы статическую и динамическую версию библиотеки при желании можно было установить в одну директорию. Для этого файлы должны иметь разные имена, чтобы не быть перезаписанными файлом для другого типа сборки. При этом выбор нужного можно сделать в отдельном файле ( mylib/export.h , см. выше) с помощью идентификатора MYLIB_STATIC_DEFINE , который будет определяться только для статического таргета mylib.
Исходники библиотеки
Исходники библиотеки инициализируются с помощью следующих команд:
Я предпочитаю использовать отдельную переменную для хранения публичных заголовков, потому что это лучше отражает разницу между этими файлами и может использоваться потом при создании install-таргета (см. ниже). Функция source_group заставляет CMake сгенерировать такую же структуру директорий в IDE, как и в самом репозитории библиотеки.
Таргет библиотеки
Теперь все готово для того, чтобы проинициализировать таргет библиотеки, который мы создали в самом начале. Делается это с помощью следующих команд:
Пояснения здесь требует, пожалуй, только момент связанный определением MYLIB_STATIC_DEFINE для статического таргета. Это нужно, чтобы файл mylib/export.h включал файл mylib/export_static.h , если используется статическая версия библиотеки, и файл mylib/export_shared.h в противном случае.
Обратите также внимание, что мы не пытаемся установить какие-то флаги компиляции или свойства таргета здесь. Как уже говорилось, это в дальнейшем создаст проблемы сторонним разработчикам, которые будут упаковывать вашу библиотеку под свою платформу. Например, во многих библиотеках, которые могут собираться под Windows, в свойствах таргета библиотеки часто указываются <CONFIG>_POSTFIX , чтобы бинарные файлы библиотеки, собранные под разные конфигурации (static/shared, debug/release), получали разные имена и могли устанавливаться в одну директорию. Если это сделать в CMakeLists.txt библиотеки, отказаться от выбранной разработчиком схемы будет проблематично. Вместо этого, постфиксы можно задать на этапе конфигурирования проекта с помощью переменных CMAKE_<CONFIG>_POSTFIX , указанных явно в командной строке или в пресете (preset), о которых мы поговорим позже.
Install-таргет библиотеки
Поскольку мы держим в уме тот факт, что библиотека может собираться как подпроект, мы предоставляем специальную переменную MYLIB_INSTALL , с помощью которой можно отключить генерацию install-таргета. Кроме того, самому CMake также можно указать, чтобы он не генерировал таргет для install команд с помощью переменной CMAKE_SKIP_INSTALL_RULES . По этой причине, код для создания install-таргета помещен внутрь условия:
Сам код для создания install-таргета имеет такой вид:
В этом коде все достаточно традиционно, отмечу лишь, что в команде install(TARGETS) пути, куда нужно устанавливать основные файлы, можно опустить. В этом случае CMake по умолчанию использует те, которые предоставляются модулем GnuInstallDirs (что правильно, так как их легко переопределить на этапе конфигурации при необходимости).
Кроме того, я рекомендую явно указывать компоненты библиотеки с помощью параметра COMPONENT . В любой библиотеке можно выделить как минимум два компонента:
runtime — то, что нужно, чтобы приложение, использующее библиотеку, в принципе могло запуститься ( so или dll файл); в своих библиотеках я как правило называю этот компонент также, как и саму библиотеку, т.е. <libname>
development — то, что нужно пользователю библиотеки (заголовочные файлы, библиотека импорта, файл конфигурации пакета и т.д.); для этого компонента я использую имя <libname>-dev
Разделение на компоненты позволяет в дальнейшем выполнять установку только необходимых файлов. Например, следующая инструкция установит только runtime-компонент библиотеки mylib:
Замечу, что файлы с определением импортируемых таргетов имеют разные имена в зависимости от типа сборки библиотеки. Это нужно для того, чтобы иметь возможность устанавливать статическую и динамическую версию библиотеки в одну директорию.
При создании install-таргета под Windows дополнительно указывается, как будут устанавливаться pdb-файлы, нужные для отладки библиотеки:
Здесь нужно учесть один момент. Дело в том, что msvc при компиляции генерирует pdb-файл для каждого объектного файла .obj (compiler pdb-файл), а потом компоновщик объединяет их в один pdb-файл (linker pdb-файл) для итогового исполняемого файла (например, .dll ). Когда вы собираете статическую библиотеку (которая по сути своей является таким же объектным файлом), компоновщик не вызывается вообще, только компилятор, который создает compiler pdb-файл.
CMake предоставляет простой способ получить linker pdb-файл: выражение-генератор TARGET_PDB_FILE . К сожалению, с помощью него вы не сможете получить compiler pdb-файл, когда собираете статическую версию библиотеки. В качестве хоть какого-то варианта решения этой проблемы, я предполагаю, что compiler pdb-файл лежит по тому же пути, что и статическая библиотека и имеет то же имя. Тем не менее, это не обязательно должно быть так, поэтому команда для установки pdb-файлов отмечена как OPTIONAL . Если вы можете предложить лучший вариант для обработки compiler pdb-файлов, поделитесь им в комментариях.
Файл конфигурации пакета
Файл конфигурации пакета предоставляется разработчиком библиотеки (я обычно помещаю его в директорию cmake ) и устанавливается в одну директорию с файлами, сгенерированными командой install(EXPORT) и содержащими определения импортированных таргетов библиотеки ( mylib-shared-targets.cmake и mylib-static-targets.cmake ). В этом файле как правило делаются две вещи:
включается mylib-shared-targets.cmake или mylib-static-targets.cmake
с помощью find_dependency находятся все зависимости импортированного таргета
Наша тривиальная библиотека ни от чего не зависит, поэтому ее файл конфигурации имеет такой вид:
Единственное, что заслуживает в нем внимания, это простой алгоритм, по которому определяется, какой таргет (для статической или динамической версии библиотеки) импортировать. Вкратце алгоритм можно описать так: MYLIB_SHARED_LIBS > BUILD_SHARED_LIBS > static > shared.
Другие таргеты
Большинство проектов C++ библиотек содержат примеры использования и тесты. Как правило эти компоненты размещаются в отдельных директориях (обычно /examples и /tests ), в которые я рекомендую поместить CMakeLists.txt для их сборки, чтобы не засорять основной CMakeLists.txt в корне библиотеки. В основной CMakeLists.txt остается добавить лишь вызов add_subdirectory для нужных директорий:
Таргет для тестов
Я считаю полезным, когда с тестами библиотеки можно работать не только как с частью библиотеки, но и как с самостоятельным проектом. Например, это позволяет легко собрать тесты для экземпляра библиотеки, установленного где-то в системе. Поэтому файл tests/CMakeLists.txt начинается с определения проекта для тестов, а также содержит опциональный вызов enable_testing и find_package(mylib) , если тесты собираются как stand-alone проект:
Я использую googletest, который предпочитаю подключать с помощью CMake модуля FetchContent. Документация googletest содержит подробные инструкции как это сделать, поэтому я не буду останавливаться на этом в своем руководстве (тем более, что вы возможно используете другой фреймворк).
Само определение таргета для тестов тривиально и следует тем же принципам, что и определение таргета библиотеки (замечу, что gtest_main это библиотека фреймворка googletest):
В Unix-подобных ОС в бинарном файле есть специальная запись rpath, в которой можно прописать путь к используемым динамическим библиотекам. Когда вы собираете библиотеку и тесты где-то в своей билд-директории, CMake в исполняемый файл mylib-tests добавляет rpath, указывающий на файл библиотеки. Таким образом при запуске mylib-tests динамический компоновщик сумеет найти библиотеку mylib , несмотря на то, что она не установлена по системному пути и не прописана в переменной среды PATH .
К сожалению, в Windows нет аналогичного rpath механизма. Поэтому при сборке тестов для динамической библиотеки возникает проблема с тем, что тесты не запускаются из IDE или с помощью CTest, поскольку DLL-файл библиотеки находится в билд-директории, о которой динамический загрузчик как правило ничего не знает. Чтобы обойти это ограничение, в файле cmake/utils.cmake определена функция win_copy_deps_to_target_dir , которая копирует dll-файл (а также pdb, если мы собираем дебаг-версию) в директорию с исполняемым файлом mylib-tests . В tests/CMakeLists.txt эта функция вызывается после определения таргета следующим образом:
Замечу, что когда mylib-tests собирается как stand-alone проект, я предпочитаю не копировать зависимости в его билд-директорию, поскольку dll-файл может находится в директории, куда не будет доступа на копирование.
Рассмотрим функцию win_copy_deps_to_target_dir поподробнее:
Эта функция создает кастомную команду для указанного таргета, которая будет запускаться после его сборки. Собственно копирование выполняется CMake скриптом cmake/silent_copy.cmake , который после парсинга своих аргументов вызывает:
Возможно у вас возникнет вопрос, почему потребовалось вынести конструкцию $
-E copy_if_different <files> <dest> в отдельный скрипт вместо того, чтобы просто указать ее при определении кастомной команды. Дело в том, что в режиме -E CMake выдаст ошибку, если список содержит несуществующие файлы. А это может произойти если, например, библиотека собиралась без отладочной информации (т.е. pdb-файл не был сгенерирован). Можно правильно обработать такие ситуации, но мне показалось проще написать скрипт, который просто игнорирует ошибки, связанные с отсутствующими файлами. Также обратите внимание, что начиная с версии 3.21 CMake предоставляет выражение генератора TARGET_RUNTIME_DLLS , которое возвращает абсолютные пути ко всем динамическим библиотекам, от которых зависит таргет (напрямую или транзитивно). Это выражение позволяет значительно упростить использование функции win_copy_deps_to_target_dir , поскольку можно не передавать в нее явным образом зависимости таргета — функция сумеет определить их самостоятельно.
В заключение нам остается только сообщить CTest, какие тесты есть в нашем проекте. Для фреймворка googletest это можно выполнить следующим образом:
Функция gtest_discover_tests определенным образом запускает исполняемый файл mylib-tests , чтобы узнать имена всех тестов, которые в нем содержатся (при этом сами тесты на этом этапе не выполняются), а затем интегрировать их в CTest.
Таргеты для примеров
Таргеты для примеров библиотеки (в директории /examples ) как правило отличаются только именами, поэтому достаточно рассмотреть один:
Как и в случае с тестами, я предпочитаю дать пользователям возможность собирать примеры как отдельные проекты. Кроме того, для удобной отладки примеров под Windows используется знакомая нам по предыдущему разделу функция win_copy_deps_to_target_dir .
Пресеты (presets)
Пресеты (извините, не подобрал хорошего перевода) являются относительно новой возможностью CMake (появились в CMake 3.19), позволяющей вынести параметры сборки из CMakeLists.txt . Как уже говорилось в начале статьи, делать это нужно для того, чтобы ваши проекты без проблем собирались под разные платформы и тулчейны.
Пресет представляет из себя простой json-файл, в котором задаются различные параметры, влияющие на сборку проекта (опции конфигурации, флаги компилятора и т.д.). Существует два типа пресетов:
CMakePresets.json для хранения глобальных настроек — этот файл обычно хранится в репозитории проекта
CMakeUserPresets.json для локальных настроек разработчика — этот файл не нужно хранить в репозитории (у каждого разработчика он как правило свой), и поэтому он указывается в .gitignore
Многие IDE (например, CLion) поддерживают пресеты, позволяя выбирать нужный в своем GUI. Подробнее о пресетах можно почитать в официальной документации, здесь я лишь приведу простой пример для библиотеки mylib:
Ссылки
В заключение приведу некоторые полезные ссылки:
cpp-lib-template — шаблон для C++/CMake библиотеки, который использовался в качестве примера в этой статье
Библиотеки
Библиотеки позволяют использовать разработанный ранее программный код в различных программах. Таким образом, программист может не разрабатывать часть кода для своей программы, а воспользоваться тем, что входит в состав библиотек.
В языке программирования C код библиотек представляет собой функции, размещенные в файлах, которые скомпилированы в объектные файлы, а те, в свою очередь, объединены в библиотеки. В одной библиотеке объединяются функции, решающие определенный тип задач. Например, существует библиотека математических функций.
У каждой библиотеки должен быть свой заголовочный файл, в котором должны быть описаны прототипы (объявления) всех функций, содержащихся в этой библиотеке. С помощью заголовочных файлов вы «сообщаете» вашему программному коду, какие библиотечные функции есть и как их использовать.
При компиляции программы библиотеки подключаются линковщиком, который вызывается gcc. Если программе требуются только стандартные библиотеки, то дополнительных параметров линковщику передавать не надо (есть исключения). Он «знает», где стандартные библиотеки находятся, и подключит их автоматически. Во всех остальных случаях при компиляции программы требуется указать имя библиотеки и ее местоположение.
Библиотеки бывают двух видов — статические и динамические. Код первых при компиляции полностью входит в состав исполняемого файла, что делает программу легко переносимой. Код динамических библиотек не входит в исполняемый файл, последний содержит лишь ссылку на библиотеку. Если динамическая библиотека будет удалена или перемещена в другое место, то программа работать не будет. С другой стороны, использование динамических библиотек позволяет сократить размер исполняемого файла. Также если в памяти находится две программы, использующие одну и туже динамическую библиотеку, то последняя будет загружена в память лишь единожды.
Далее будет описан пример, в котором создается библиотека, после чего используется при создании программы.
Пример создания библиотеки
Допустим, мы хотим создать код, который в дальнейшем планируем использовать в нескольких проектах. Следовательно, нам требуется создать библиотеку. Исходный код для библиотеки было решено разместить в двух файлах исходного кода.
Также на данный момент у нас есть план первого проекта, использующего эту библиотеку. Сам проект также будет включать два файла.В итоге, когда все будет сделано, схема каталогов и файлов будет выглядеть так:
Пусть каталоги library и project находятся в одном общем каталоге, например, домашнем каталоге пользователя. Каталог library содержит каталог source с файлами исходных кодов библиотеки. Также в library будут находиться заголовочный файл (содержащий описания функций библиотеки), статическая (libmy1.a) и динамическая (libmy2.so) библиотеки. Каталог project будет содержать файлы исходных кодов проекта и заголовочный файл с описанием функций проекта. Также после компиляции с подключением библиотеки здесь будет располагаться исполняемый файл проекта.
В операционных системах GNU/Linux имена файлов библиотек должны иметь префикс «lib», статические библиотеки — расширение *.a, динамические — *.so.Для компиляции проекта достаточно иметь только одну библиотеку: статическую или динамическую. В образовательных целях мы получим обе и сначала скомпилируем проект со статической библиотекой, потом — с динамической. Статическая и динамическая «разновидности» одной библиотеки по-идее должны называться одинаково (различаются только расширения). Поскольку у нас обе библиотеки будут находиться в одном каталоге, то чтобы быть уверенными, что при компиляции проекта мы используем ту, которую хотим, их названия различны (libmy1 и libmy2).
Исходный код библиотеки
В файле figure.c содержатся две функции — rect() и diagonals() . Первая принимает в качестве аргументов символ и два числа и «рисует» на экране с помощью указанного символа прямоугольник заданной ширины и высоты. Вторая функция выводит на экране две диагонали квадрата («рисует» крестик).
В файле text.c определена единственная функция, принимающая указатель на символ строки. Функция выводит на экране звездочки в количестве, соответствующем длине указанной строки.
Заголовочный файл можно создать в каталоге source, но мы лучше сохраним его там, где будут библиотеки. В данном случае это на уровень выше (каталог library). Тем самым как бы подчеркивается, что файлы исходных кодов после создания из них библиотеки вообще не нужны пользователям библиотек, они нужны лишь разработчику библиотеки. А вот заголовочный файл библиотеки требуется для ее правильного использования.
Создание статической библиотеки
Статическую библиотеку создать проще, поэтому начнем с нее. Она создается из обычных объектных файлов путем их архивации с помощью утилиты ar.
Все действия, которые описаны ниже выполняются в каталоге library (т.е. туда надо перейти командой cd). Просмотр содержимого каталога выполняется с помощью команды ls или ls -l.
Получаем объектные файлы:
В итоге в каталоге library должно наблюдаться следующее:
Далее используем утилиту ar для создания статической библиотеки:
Параметр r позволяет вставить файлы в архив, если архива нет, то он создается. Далее указывается имя архива, после чего перечисляются файлы, из которых архив создается.
Объектные файлы нам не нужны, поэтому их можно удалить:
В итоге содержимое каталога library должно выглядеть так:
, где libmy1.a — это статическая библиотека.
Создание динамической библиотеки
Объектные файлы для динамической библиотеки компилируются особым образом. Они должны содержать так называемый позиционно-независимый код (position independent code). Наличие такого кода позволяет библиотеке подключаться к программе, когда последняя загружается в память. Это связано с тем, что библиотека и программа не являются единой программой, а значит как угодно могут располагаться в памяти относительно друг друга. Компиляция объектных файлов для динамической библиотеки должна выполняться с опцией -fPIC компилятора gcc:
В отличие от статической библиотеки динамическую создают при помощи gcc указав опцию -shared:
Использованные объектные файлы можно удалить:
В итоге содержимое каталога library:
Использование библиотеки в программе
Исходный код программы
Теперь в каталоге project (который у нас находится на одном уровне файловой иерархии с library) создадим файлы проекта, который будет использовать созданную библиотеку. Поскольку сама программа будет состоять не из одного файла, то придется здесь также создать заголовочный файл.
Функция data() запрашивает у пользователя данные, помещая их в массив strs. Далее вызывает библиотечную функцию diagonals() , которая выводит на экране «крестик». После этого на каждой итерации цикла вызывается библиотечная функция text() , которой передается очередной элемент массива; функция text() выводит на экране звездочки в количестве равному длине переданной через указатель строки.
Обратите внимание на то, как подключается заголовочный файл библиотеки: через относительный адрес. Две точки обозначают переход в каталог на уровень выше, т.е. родительский по отношению к project, после чего путь продолжается во вложенный в родительский каталог library. Можно было бы указать абсолютный путь, например, «/home/pl/c/les22/library/mylib.h». Однако при перемещении каталогов библиотеки и программы на другой компьютер или в другой каталог адрес был бы уже не верным. В случае с относительным адресом требуется лишь сохранять расположение каталогов project и library относительно друг друга.
Здесь два раза вызывается библиотечная функция rect() и один раз функция data() из другого файла проекта. Чтобы сообщить функции main() прототип data() также подключается заголовочный файл проекта.
Файл project.h содержит всего одну строчку:
Из обоих файлов проекта с исходным кодом надо получить объектные файлы для объединения их потом с файлом библиотеки. Сначала мы получим исполняемый файл, содержащий статическую библиотеку, потом — связанный с динамической библиотекой. Однако с какой бы библиотекой мы не компоновали объектные файлы проекта, компилируются они как для статической, так и динамической библиотеки одинаково:
При этом не забудьте сделать каталог project текущим!
Компиляция проекта со статической библиотекой
Теперь в каталоге project есть два объектных файла: main.o и data.o. Их надо скомпилировать в исполняемый файл project, объединив со статической библиотекой libmy1.a. Делается это с помощью такой команды:
Начало команды должно быть понятно: опция -o указывает на то, что компилируется исполняемый файл project из объектных файлов.
Помимо объектных файлов проекта в компиляции участвует и библиотека. Об этом свидетельствует вторая часть команды: -L../library -lmy1. Здесь опция -L указывает на адрес каталога, где находится библиотека, он и следует сразу за ней. После опции -l записывается имя библиотеки, при этом префикс lib и суффикс (неважно .a или .so) усекаются. Обратите внимание, что после данных опций пробел не ставится.
Опцию -L можно не указывать, если библиотека располагается в стандартных для данной системы каталогах для библиотек. Например, в GNU/Linux это /lib/, /urs/lib/ и др.
Запустив исполняемый файл project и выполнив программу, мы увидим на экране примерно следующее:
Посмотрим размер файла project:
Его размер равен 8698 байт.
Компиляция проекта с динамической библиотекой
Теперь удалим исполняемый файл и получим его уже связанным с динамической библиотекой. Команда компиляции с динамической библиотекой выглядит так (одна команда разбита на две строки с помощью обратного слэша и перехода на новую строку):
Здесь в отличии от команды компиляции со статической библиотеки добавлены опции для линковщика: -Wl,-rpath. /library/. -Wl — это обращение к линковщику, -rpath — опция линковщика, ../library/ — значение опции. Получается, что в команде мы два раза указываем местоположение библиотеки: один раз с опцией -L, а второй раз с опцией -rpath. Видимо для того, чтобы понять, почему так следует делать, потребуется более основательно изучить процесс компиляции и компоновки программ на языке C.
Следует заметить, что если вы скомпилируете программу, используя приведенную команду, то исполняемый файл будет запускаться из командной строки только в том случае, если текущий каталог project. Стоит сменить каталог, будет возникать ошибка из-за того, что динамическая библиотека не будет найдена. Но если скомпилировать программу так:
, т.е. указать для линковщика абсолютный адрес, то программа в данной системе будет запускаться из любого каталога.
Размер исполняемого файла проекта, связанного с динамической библиотекой, получился равным 8544 байта. Это немного меньше, чем при компиляции проекта со статической библиотекой. Если посмотреть на размеры библиотек:
, то видно, что динамическая больше статической, хотя исполняемый файл проекта со статической библиотекой больше. Это доказывает, что в исполняемом файле, связанном с динамической библиотекой, присутствует лишь ссылка на нее.