{"id":28851867,"url":"https://github.com/robotology/how-to-export-cpp-library","last_synced_at":"2025-10-26T23:10:16.624Z","repository":{"id":21518605,"uuid":"24837748","full_name":"robotology/how-to-export-cpp-library","owner":"robotology","description":"An OS-agnostic C++ library template in plain CMake.","archived":false,"fork":false,"pushed_at":"2021-01-13T16:07:10.000Z","size":5985,"stargazers_count":364,"open_issues_count":12,"forks_count":54,"subscribers_count":25,"default_branch":"master","last_synced_at":"2024-12-06T19:47:57.181Z","etag":null,"topics":["cmake","cmake-examples","cmake-template"],"latest_commit_sha":null,"homepage":"","language":"CMake","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robotology.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-template.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-10-06T07:49:35.000Z","updated_at":"2024-11-10T21:16:04.000Z","dependencies_parsed_at":"2022-08-21T17:40:57.062Z","dependency_job_id":null,"html_url":"https://github.com/robotology/how-to-export-cpp-library","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/robotology/how-to-export-cpp-library","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robotology%2Fhow-to-export-cpp-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robotology%2Fhow-to-export-cpp-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robotology%2Fhow-to-export-cpp-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robotology%2Fhow-to-export-cpp-library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robotology","download_url":"https://codeload.github.com/robotology/how-to-export-cpp-library/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robotology%2Fhow-to-export-cpp-library/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260837734,"owners_count":23070558,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cmake","cmake-examples","cmake-template"],"created_at":"2025-06-19T21:38:56.947Z","updated_at":"2025-10-26T23:10:16.613Z","avatar_url":"https://github.com/robotology.png","language":"CMake","readme":"# 📚 How to export C++ library\n\nThis repository provides an OS-agnostic C++ library template with plain [CMake](https://cmake.org/) files with the following features:\n  * distribution of the library\n  * automatic exposition of symbols for Windows dlls using [`CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS`](https://blog.kitware.com/create-dlls-on-windows-without-declspec-using-new-cmake-export-all-feature/)\n  * test support with `ctest`\n  * [GitHub Actions](https://github.com/features/actions) script configured\n  * dedicated [Doxygen](https://www.stack.nl/~dimitri/doxygen/) target for generating documentation\n\n# Overview\n- [💢 Complexities around C++ library](#-complexities-around-c++-library)\n- [🏅 CI and badges](#️-ci-and-badges)\n- [🎛 Dependencies](#-dependencies)\n- [🔨 Build the libraries](#-build-the-libraries)\n- [✂️ Copy and customize this template](#-copy-and-customize-this-template)\n- [🔬 Add a test](#-add-a-test)\n- [🐛 Run the tests](#-run-the-tests)\n- [📝 Generate documentation](#-generate-documentation)\n- [📑 Licensing your library](#-licensing-your-library)\n- [💼 Other template and examples](#-other-template-and-examples)\n\n# 💢 Complexities around C++ library\nThis 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!\n\nA 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.\n\nProblems typically overlooked by new C++ library developers:\n - [The basics of C/C++ compilation pipeline](https://github.com/green7ea/cpp-compilation/blob/master/README.md)\n - [API/ABI backward compatibility](https://abi-laboratory.pro/index.php?view=binary-compatibility)\n - [Dynamic loading](https://amir.rachum.com/blog/2016/09/17/shared-libraries/)\n - [So you want to know even more about shared/dynamic libraries? There you go!](https://www.akkadia.org/drepper/dsohowto.pdf)\n - [Continuous Delivery](https://www.atlassian.com/continuous-delivery)\n - [Good practices using Git branching](https://nvie.com/posts/a-successful-git-branching-model/)\n - [Version handling](https://semver.org/)\n - [How to properly handle RPATH](https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/RPATH-handling)\n\n# 🏅 CI and badges\nAwesomness | Github Actions\n-----------| ------------\n[![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/onqtam/awesome-cmake) | [![GitHub Actions status](https://github.com/robotology/how-to-export-cpp-library/workflows/C++%20CI%20Workflow/badge.svg)](https://github.com/robotology/how-to-export-cpp-library/actions) \n\n[`Go to the top`](#overview)\n\n# 🎛 Dependencies\nThere are no dependencies for this template.\nHowever, we make use of the following three files from the [YCM](https://github.com/robotology/ycm) project.\n 1. [`AddInstallRPATHSupport`](https://github.com/robotology/ycm/blob/master/modules/AddInstallRPATHSupport.cmake)\n 2. [`AddUninstallTarget`](https://github.com/robotology/ycm/blob/master/modules/AddUninstallTarget.cmake)\n 3. [`InstallBasicPackageFiles`](https://github.com/robotology/ycm/blob/master/modules/InstallBasicPackageFiles.cmake)\n\nThese files can be found under `./cmake` subdirectory and they are **_plain CMake code_**.\nCheck them out, they make your life easier!\n\nIf 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.\n 1. [Install YCM](http://robotology.github.io/ycm/gh-pages/git-master/manual/ycm-installing.7.html)\n 2. Add `find(YCM REQUIRED)` in the main [CMakeLists.txt](https://github.com/robotology/how-to-export-cpp-library/blob/master/CMakeLists.txt), after the `project()` command.\n 3. Delete/Empty the `./cmake` folder.\n\nYou are now 100% good to go! 🎉\n\n[`Go to the top`](#overview)\n\n# 🔨 Build the libraries\nIf your shell environment supports `mkdir`, you can just execute the following commands:\n\n```shell\ngit clone https://github.com/robotology/how-to-export-cpp-library.git\ncd how-to-export-cpp-library\nmkdir build \u0026\u0026 cd build\ncmake ..\ncmake --build .\n```\n\nYou can also create platform specific input files for a native build system using [CMake Generator](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html).\n\nFor more detailed example, check the [CGold section on Generate native tool files](https://cgold.readthedocs.io/en/latest/first-step/generate-native-tool.html).\n\n[`Go to the top`](#overview)\n\n# ✂️ Copy and customize this template\nFor customizing the CMake/C++ code, check the [comments in the main CMakeLists.txt](https://github.com/robotology/how-to-export-cpp-library/blob/master/CMakeLists.txt#L3).\n\nTo enable **Continuous Integration** (CI) using [Travis](https://travis-ci.org/) (Linux and macOS) and [AppVeyor](https://www.appveyor.com/) (Windows) follow the documentation of these services to create an account and connect them to your repository.\n\nOnce 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.\n\n[`Go to the top`](#overview)\n\n# 🔬 Add a test\nThis snippet from [`test/CMakeLists.txt`](test/CMakeLists.txt) shows the fundamental commands to add a test:\n```cmake\nadd_executable(test_name_exec test_name_exec_source.cpp)\ntarget_link_libraries(test_name_exec lib-template-cmake)\nadd_test(NAME test_name COMMAND test_name_exec)\n```\nA _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.\n\nFor more info on this topic and related CMake commands, check [`add_test`](https://cmake.org/cmake/help/v3.7/command/add_test.html) documentation and references therein.\n\n[`Go to the top`](#overview)\n\n# 🐛 Run the tests\nIf 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.\n\nTo list the compiled/available tests, run `ctest -N` in the build directory.\nTo run the tests, use `ctest` command in the build directory, while to run a single test, us `ctest -R test_name`.\nYou can add `-VV` to get a full verbose output during tests.\n\nFor more info and options with `ctest`, check the [ctest documentation](https://cmake.org/cmake/help/latest/manual/ctest.1.html).\n\n[`Go to the top`](#overview)\n\n# 📝 Generate documentation\nIf the Doxygen tool is installed on your machine, the Doxygen documentation for the project can\nbe generated using the `dox` target, see [`doc/CMakeLists.txt`](https://github.com/robotology/how-to-export-cpp-library/blob/master/doc/CMakeLists.txt) for details on the process of documents\ngeneration. Once generated, the doxygen documentation can be browsed at `build/doc/html/index.html`.\nIf the documentation is generated, it will be installed in `${CMAKE_INSTALL_PREFIX}/share/doc/${PROJECT_NAME}/html/`.\nThe build and installation directories for the doxygen documentation can be changed using the `DOXYGEN_BUILD_DIR` and `DOXYGEN_INSTALL_DIR`\nCMake variables.\n\nIf you are interested on how to host your documentation using `gh-pages`, [robotology/how-to-document-modules](https://github.com/robotology/how-to-document-modules) contains a detailed (and maintained) example on how to produce and host `Doxygen` documentation using GitHub `gh-pages`.\n\n[`Go to the top`](#overview)\n\n# 📑 Licensing your library\nThe project as-is comes with two files:\n 1. `LICENSE`\n 2. `LICENSE-template`\n\n**The first file**, `LICENSE`, is the one covering this very template. You **have to** modify/delete it.\n⚠️ Don't use it straightforwardly as it includes our name, not yours!\n\n**The second file**, `LICENSE-template`, is an [MIT License](https://en.wikipedia.org/wiki/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.\n\nShould 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:\n - [Choose a license](http://choosealicense.com/)\n - [tl;drLegal](https://tldrlegal.com/)\n\n[`Go to the top`](#overview)\n\n# 💼 Other template and examples\nThe [Awesome CMake](https://github.com/onqtam/awesome-cmake) repository contains an interesting [list of template and examples](https://github.com/onqtam/awesome-cmake#examples--templates) similar to this one.\n\n[`Go to the top`](#overview)\n\n\n---\nIf you feel this CMake project template was useful, consider starring the project!  \nWe 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).  \nOtherwise, not a big deal! 👍\n\n[![how-to-export-cpp-library](https://img.shields.io/badge/-Project%20Template-brightgreen.svg?style=flat-square\u0026logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAEAAAAA9CAYAAAAd1W%2FBAAAABmJLR0QA%2FwD%2FAP%2BgvaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4QEFECsmoylg4QAABRdJREFUaN7tmmuIVVUUx%2F%2F7OmpaaGP6oedkGJWNIWoFVqRZGkIPSrAQgqhEqSYxszeFUB%2FCAqcXUaSRZmZP6IFm42QEUWAjqT1EQ0dLHTMfaWajv76sM%2BxO59znuY%2Bcs2CYmXv33mud31577bX3WU5lEEDOueDvfpLGSBolaaiksyUNknRyqNs%2BSR2SfrKf1ZJaJG11zv1rzJoX4ETgYWAtpcuvwCvABQHcJMUlPevAi5KmxTTbKalN0hZJ2yRlvO%2BOlzTYvOScmP5fSrreOber1mZcQF9gU2j2dgDNwLgixmwE7ge%2BC415FDi%2FFt1%2BuWfkRuBqH1CJYw8B3vfG7wR61NLDn%2BoZt6IcHma%2F7%2FX0zEo6HpRi4KWeYWOTNswfz9OzoKpr3ov2s4HNnmHtwMAy6Vvk6VkPjKkWgInA5zm2r0eBulJn3P6%2FEdgZo2c%2F8BDQu9wP3Qg8DRyIMGJPFhCfAjOAUcAgwOXQ08%2BC3hSb8SMF5AyfANcG4Iteip7L9QMejNjeAlkEjLZ1n490Ah023g%2FAZ0AL8DWwAdgO%2FBnT9y%2Fgdm8CllggbI9ouxeYD4wsNtBcBXwcY8hGYGqo7xjKJyuAyZ6uQ%2Fb5fO%2BzEcCbMf23ANNzeZ6AYcA8oxeWbcDcIAGJWKOlANgCfGNesBR4Cpjqz15ocgIAr0Z4bE%2FgDhsvSt71kzJAAm7O4uJvABfnSmhKBNBY4PL8D4CYdqcBc4CDETp%2Fs3g2SDFGNRVoVCkARhQYlwJ5vgD7JgDLInTvzsT0mQd8BFyTTzrrnGstd84hqR5Y5321LJtNHrABks6V1FfSkVCzeuUxQweAl4Ah2WAAd5XDA4AzgOdCfVbmAe4G22GI2SXATnGFyBrg1rikw05vhcpwIGMBrI%2Bt3UnAMxYgw7Lc7I7Sf7oF0ajcYZ%2BdTBuA24oF4O%2FnS4ErI4w4E3irgLF22f5%2FMEe7r4AJ3vG7y8WBO4Fvs0T%2B8SEb7y4VgC%2B%2FW0QdGFLSC5hmsaRYWWNp7ikRoK%2FL4uLrbZZ7xnhqFwBHske3lZKelfSBc%2B5o6G6wQdJIuxMcIKnBu5FykrZL2iVpq6TVzrm2CMMHS5ouaYak8MPtlfS6pGbn3Ibw3WQYgKTm8LaSpOwHFgCXJHAC7A80AW0xupb4SzGf%2BUx6CeSzxmcBmQLT8Yl2VoiSDZbx9SgSbkUB%2BPKeHZwyMSn1YOBJ4HBM9tYMnFfqNVs1AQTSYQ8zDOgN3AOsi2n7jn%2FxkUTIqgUAuWSTbW3lyi67ANSpdmS3pIWSXnbOra2U0loB8IikJ4JXYJWUTI0AaA%2F260q%2F%2F8uom0sKIAWQAkgBpABSACmAFEAKIAWQAkgBpABSACmAFEB3kc5uBSD0wuUySVN8AB3dgEF%2FK7PdLWmVpOCV3dGMpCGSZkr6%2FliabeA44CagVdIeSXMl1XtNV0kaH%2B58VkQ1RiXklgQBjAYWW11hVLXbfVY2k3OgKfZ%2BvuYB2Bvk2THltIetYOOiYl2pAXgM%2BLkWAHh21dkktcaM2WolgD3DgbCUCDoceK3KAC7MUkO8A5gJ1Fci2DQBP1YCAHCSFWD9EtH3b3Pxy6sVdYdaZVZHEgA8Fw%2Fi0BcxfVqAyUCvklw84STjCuDDEgEMBxbGtPsDeAA4odb34D5WZt%2BeJ4AmK6PZHPHdQeBtYOz%2FNTEZCbwQU%2FaSq0x%2BEtCnqi6eMIxJWUrZAxd%2FPHjoY%2FZQYrnFHIvqh2zNj6uGTf8ARTOPo64fR94AAAAASUVORK5CYII%3D)](https://github.com/robotology/how-to-export-cpp-library)\n","funding_links":[],"categories":["Examples / Templates"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobotology%2Fhow-to-export-cpp-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobotology%2Fhow-to-export-cpp-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobotology%2Fhow-to-export-cpp-library/lists"}