📚 How to export C++ library

This repository provides an OS-agnostic C++ library template with plain CMake files with the following features:

• distribution of the library
• automatic exposition of symbols for Windows dlls using CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS
• test support with ctest
• GitHub Actions script configured
• dedicated Doxygen target for generating documentation

Overview

• 💢 Complexities around C++ library
• 🏅 CI and badges
• 🎛 Dependencies
• 🔨 Build the libraries
• ✂️ Copy and customize this template
• 🔬 Add a test
• 🐛 Run the tests
• 📝 Generate documentation
• 📑 Licensing your library
• 💼 Other template and examples

💢 Complexities around C++ library

This project simplifies the process of taking a bunch of C++ classes/functions and exposing them as a CMake package so that third-party code can use it. However, the risk is that new users underestimate the actual complexity of maintaining a C++ library used by many external users!

A complete and proper training on the art and craft of C++ library maintenance is out of the scope of this project, but we feel that we should at least report some useful link to drive the curiosity and the attention of new users to topics relevant to a proper maintenence of a C++ library.

Problems typically overlooked by new C++ library developers:

• The basics of C/C++ compilation pipeline
• API/ABI backward compatibility
• Dynamic loading
• So you want to know even more about shared/dynamic libraries? There you go!
• Continuous Delivery
• Good practices using Git branching
• Version handling
• How to properly handle RPATH

🏅 CI and badges

Awesomness	Github Actions

Go to the top

🎛 Dependencies

There are no dependencies for this template. However, we make use of the following three files from the YCM project.

1. AddInstallRPATHSupport
2. AddUninstallTarget
3. InstallBasicPackageFiles

These files can be found under ./cmake subdirectory and they are plain CMake code. Check them out, they make your life easier!

If you like the YCM project and it is not a problem to have it as a dependency, updating the template is as simple as follows.

1. Install YCM
2. Add find(YCM REQUIRED) in the main CMakeLists.txt, after the project() command.
3. Delete/Empty the ./cmake folder.

You are now 100% good to go! 🎉

Go to the top

🔨 Build the libraries

If your shell environment supports mkdir, you can just execute the following commands:

git clone https://github.com/robotology/how-to-export-cpp-library.git
cd how-to-export-cpp-library
mkdir build && cd build
cmake ..
cmake --build .

You can also create platform specific input files for a native build system using CMake Generator.

For more detailed example, check the CGold section on Generate native tool files.

Go to the top

✂️ Copy and customize this template

For customizing the CMake/C++ code, check the comments in the main CMakeLists.txt.

To enable Continuous Integration (CI) using Travis (Linux and macOS) and AppVeyor (Windows) follow the documentation of these services to create an account and connect them to your repository.

Once you're done with that, you can easily modify the appveyor.yml and travis.yml to account changes for your project, such as the project name from how-to-export-cpp-library (the name of the git repository) and LibTemplateCMake (the name of the CMake Project/Package) to the one of your repository/project.

Go to the top

🔬 Add a test

This snippet from test/CMakeLists.txt shows the fundamental commands to add a test:

add_executable(test_name_exec test_name_exec_source.cpp)
target_link_libraries(test_name_exec lib-template-cmake)
add_test(NAME test_name COMMAND test_name_exec)

A single test is just a simple C++ executable with an int main() function that returns 0 on success and any value different from 0 upon failure.

For more info on this topic and related CMake commands, check add_test documentation and references therein.

Go to the top

🐛 Run the tests

If you want to run tests, compile the library enabling the BUILD_TESTING CMake option. Once you do that, test will be compiled along with the library and any other executable in the project.

To list the compiled/available tests, run ctest -N in the build directory. To run the tests, use ctest command in the build directory, while to run a single test, us ctest -R test_name. You can add -VV to get a full verbose output during tests.

For more info and options with ctest, check the ctest documentation.

Go to the top

📝 Generate documentation

If the Doxygen tool is installed on your machine, the Doxygen documentation for the project can be generated using the dox target, see doc/CMakeLists.txt for details on the process of documents generation. Once generated, the doxygen documentation can be browsed at build/doc/html/index.html. If the documentation is generated, it will be installed in ${CMAKE_INSTALL_PREFIX}/share/doc/${PROJECT_NAME}/html/. The build and installation directories for the doxygen documentation can be changed using the DOXYGEN_BUILD_DIR and DOXYGEN_INSTALL_DIR CMake variables.

If you are interested on how to host your documentation using gh-pages, robotology/how-to-document-modules contains a detailed (and maintained) example on how to produce and host Doxygen documentation using GitHub gh-pages.

Go to the top

📑 Licensing your library

The project as-is comes with two files:

1. LICENSE
2. LICENSE-template

The first file, LICENSE, is the one covering this very template. You have to modify/delete it. ⚠️ Don't use it straightforwardly as it includes our name, not yours!

The second file, LICENSE-template, is an MIT License template that you can use adding the year and copyright holder names in the heading. We provide template of the MIT License as it is the one used for this template, but you can choose one of the many available.

Should you not be sure what to do about it (licensing produces severe headhaces) you can use one of the following website to clear your mind:

• Choose a license
• tl;drLegal

Go to the top

💼 Other template and examples

The Awesome CMake repository contains an interesting list of template and examples similar to this one.

Go to the top

If you feel this CMake project template was useful, consider starring the project!
We also created the following shield to provide a nice-looking link to this project (feel free to modify its look-and-feel as you please).
Otherwise, not a big deal! 👍