📚 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 |
|---|---|
 |
 |
🎛 Dependencies
There are no dependencies for this template. However, we make use of the following three files from the YCM project.
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.
- Install YCM
- Add
find(YCM REQUIRED)in the main CMakeLists.txt, after theproject()command. - Delete/Empty the
./cmakefolder.
You are now 100% good to go!
🔨 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.
✂️ 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.
🔬 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.
🐛 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.
📝 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.
📑 Licensing your library
The project as-is comes with two files:
LICENSELICENSE-template
The first file, LICENSE, is the one covering this very template. You have to modify/delete it.
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:
💼 Other template and examples
The Awesome CMake repository contains an interesting list of template and examples similar to this one.
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!
