{"id":22253418,"url":"https://github.com/tblauwe/cpp_lib_starter","last_synced_at":"2025-03-25T12:25:03.412Z","repository":{"id":184784319,"uuid":"668652453","full_name":"TBlauwe/cpp_lib_starter","owner":"TBlauwe","description":"Template repo for c++ libraries (as a learning process)","archived":false,"fork":false,"pushed_at":"2025-01-06T09:35:37.000Z","size":1341,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-30T11:25:42.722Z","etag":null,"topics":["cpp","template-repository"],"latest_commit_sha":null,"homepage":"https://tblauwe.github.io/cpp_lib_starter/","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/TBlauwe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-20T09:51:21.000Z","updated_at":"2025-01-06T09:35:41.000Z","dependencies_parsed_at":"2023-12-13T20:14:20.162Z","dependency_job_id":"ff96a6c7-e969-47c2-a6c3-5c5c9f37578a","html_url":"https://github.com/TBlauwe/cpp_lib_starter","commit_stats":null,"previous_names":["tblauwe/cpp_lib_starter"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TBlauwe%2Fcpp_lib_starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TBlauwe%2Fcpp_lib_starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TBlauwe%2Fcpp_lib_starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TBlauwe%2Fcpp_lib_starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TBlauwe","download_url":"https://codeload.github.com/TBlauwe/cpp_lib_starter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245460149,"owners_count":20619015,"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":["cpp","template-repository"],"created_at":"2024-12-03T07:18:18.280Z","updated_at":"2025-03-25T12:25:03.366Z","avatar_url":"https://github.com/TBlauwe.png","language":"CMake","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cpp Library Starter\n\n![C++](https://img.shields.io/badge/c++-%2300599C.svg?style=for-the-badge\u0026logo=c%2B%2B\u0026logoColor=white) ![CMake](https://img.shields.io/badge/CMake-%23008FBA.svg?style=for-the-badge\u0026logo=cmake\u0026logoColor=white) [![Static Badge](https://img.shields.io/badge/See%20example%20here-blue?style=for-the-badge\u0026logo=readthedocs\u0026logoColor=white)](https://github.com/TBlauwe/CLS_Example/)\n\n\nAn opinionated template repository for C++ library using **[TCM](https://github.com/TBlauwe/tcm)**.\n\n\n\u003e [!NOTE]\n\u003e\n\u003e I'm using it as a continuous learning process. Suggestions are always welcome ! \n\n\n## Main Features\n\n* __Quick setup__ :\n  * Click `Use this template`, fill a few fields and a project/repository will be generated based on available information.\n  * Thanks to **[Tmplr](https://github.com/loreanvictor/tmplr)**, there are no leftover, no replacement needed. For example, a barebone `README.md` is generated, with working links, instructions, etc.\n \n* CI ready:\n  * Documentation is published to GitHub pages.\n  * Build is tested against several configurations.\n\t\u003cdetails\u003e\n\t\u003csummary\u003eCI Executions\u003c/summary\u003e\n\n\t|Platform | Toolchains |\n\t\t| --- | --- |\n\t| Windows | msvc \u0026 clang-cl |\n\t| Ubuntu | gcc \u0026 clang |\n\t| MacOS | gcc \u0026 clang |\n\t\u003c/details\u003e\n\n* __Use TCM__ :\n  * __[TCM](https://github.com/TBlauwe/tcm)__ is a CMake module to reduce boilerplate :\n    * __Documentation__ generated with **[Doxygen](https://www.doxygen.nl/)** and **[Doxygen Awesome CSS](https://jothepro.github.io/doxygen-awesome-css/)**.\n\t* Setup tools like **[CPM](https://github.com/cpm-cmake/)** to manage dependencies.\n\t  \u003cdetails\u003e\n\t  \u003csummary\u003eProject generated from this template are also CPM-ready\u003c/summary\u003e\n\n\t  ```cmake\n\t  CPMAddPackage(\n\t\t  NAME my_lib \n\t\t  GITHUB_REPOSITORY my_lib_repo/my_lib\n\t  )\n\n\t  target_link_libraries(some_target PUBLIC my_lib)\n\t  ```\n\t  \u003c/details\u003e\n    * __Tests__ written with **[Catch2](https://github.com/catchorg/Catch2)** and executed during CI.\n    * __Benchmarks__ written with **[Google Benchmark](https://github.com/google/benchmark)**.\n\n* A __Cross-platform__ and __modular__ _CMakePreset.json_  provided.\n\n\n## Getting started\n\nOn the [GitHub repository](https://github.com/TBlauwe/cpp_lib_starter), click on `Use this template` and fill the fields\n\nThere are two steps left :\n1. Allow deployment of GitHub Pages through GitHub actions\n2. [OPTIONAL] - Clean workflow files\n\n\n### Set up GitHub Pages\nGo to your repository and follow these steps : \n\n1. Click on `Settings`\n2. Click on `Pages` in the section `Code and automation`\n3. In 'Build and deployment', change `Source` to `GitHub Actions`, instead of `Deploy from a branch`.\n\nOtherwise, GitHub Pages' deployment will always failed.\n\n\u003cdetails\u003e\n\n\u003csummary\u003eDeploy GitHub Pages without commiting\u003c/summary\u003e\n\nIf you wish to deploy the documentation now, you can trigger the workflow from GitHub by following these steps :\n\n1. Click on `Actions`\n2. In the left pane, Click on `Documentation build \u0026 deploy`\n3. To the right, click on `Run workflow`\n\n\u003c/details\u003e\n\n\n### [OPTIONAL] - Clean workflow files\n\n\u003e [!NOTE]\n\u003e\n\u003e I need to improve the template so this is not necessary. It is a workaround so that the user do not need to create a personal account token.\n\u003e They are maybe another way but I haven't found it. Any help is appreciated !\n\nModifications of workflows file needs additional permissions. Without them, we can't add them during generation. \nBut, it seems to require additional steps from the user.\nTo circumvent that, all workflows files are initially present. \nBut we add to alter them slightly, so they can run only when relevant :\n\n1. All workflows should not run in the template repository\n```yaml\n    if: github.repository != 'TBlauwe/cpp_lib_starter'\n```\n\n2. Delete `.github/workflows/init.yaml` (after the project is generated.)\n\n3. Other workflows should run only when the project is generated, meaning when there is a root `CMakeLists.txt`. \n```yaml\n        - name: Check file existence\n          id: check_files\n          uses: andstor/file-existence-action@v2\n          with:\n            files: 'CMakeLists.txt'\n```\n\n\n## Build\n\nUse following command in the root directory :\n\n```console\ncmake -S . -B build\ncmake --build build --target \u003ca-target\u003e\n```\n\nTargets available :\n\n|                                  Targets | Type | Description |\n|-----------------------------------------:| :---: | :--- |\n|                    `\u003cyour_project_name\u003e` | Library | Build main library |\n|              `\u003cyour_project_name\u003e_Tests` | Executable | Build executable to run tests |\n|         `\u003cyour_project_name\u003e_Benchmarks` | Executable | Build executable to run benchmarks |\n|      `\u003cyour_project_name\u003e_Documentation` | Utility | Build documentation |\n| `\u003cyour_project_name\u003e_Documentation_Open` | Utility | Open documentation in default browser |\n\nYou can also use `CMakePresets.json` instead, [see below](#cmakepresets.json)\n\n\n## CMakePresets.json\n\n```console\ncmake --preset \u003cpreset-name\u003e\ncmake --build \u003cpreset-build-directory\u003e --target \u003ca-target\u003e\n```\n\n* `\u003cpreset-name\u003e` : name of a configuration preset, [see below](#configuration-presets) for a list.\n* `\u003cpreset-build-directory\u003e` : build folder. By default, it is set to `out/build/\u003cpreset-name\u003e`.\n* `\u003ca-target\u003e` : name of a target, [see above](#targets).\n\nAvailable presets : \n\n|                Targets | Inherits | Note | \n|-----------------------:| :--- | :--- |\n|       `x64-msvc-debug` | `Base`, `Ninja`, `x64`, `MSVC`, `Debug`| Windows specific (Visual studio)|\n|     `x64-msvc-release` | `Base`, `Ninja`, `x64`, `MSVC`, `Release`| Windows specific (Visual studio) |\n|   `x64-clang-cl-debug` | `Base`, `Ninja`, `x64`, `Clang-cl`, `Debug`| Windows specific (Visual studio) |\n| `x64-clang-cl-release` | `Base`, `Ninja`, `x64`, `Clang-cl`, `Release`| Windows specific (Visual studio) |\n|        `x64-gcc-debug` | `Base`, `Ninja`, `x64`, `GCC`, `Debug`| Windows specific (CLion) |\n|      `x64-gcc-release` | `Base`, `Ninja`, `x64`, `GCC`, `Release`| Windows specific (Clion) |\n|      `x64-clang-debug` | `Base`, `Ninja`, `x64`, `Clang`, `Debug`| Unix, MacOs, WSL |\n|    `x64-clang-release` | `Base`, `Ninja`, `x64`, `Clang`, `Release`| Unix, MacOs, WSL|\n|        `x64-gnu-debug` | `Base`, `Ninja`, `x64`, `GCC`, `Debug`, `wsl`| Unix, MacOs, WSL |\n|      `x64-gnu-release` | `Base`, `Ninja`, `x64`, `GCC`, `Release`, `wsl`| Unix, MacOs, WSL|\n\n\u003e [!NOTE]\n\u003e\n\u003e `Clang-cl` refers to the clang toolchain provided by [Visual Studio 2022](https://learn.microsoft.com/en-us/cpp/build/clang-support-msbuild?view=msvc-170)\n\nThanks to the structure of the file (credits to [DirectXTK](https://github.com/microsoft/DirectXTK/blob/main/CMakePresets.json)), you can easily add other configurations, by inheriting relevant configurations.\n\n```json\n{\"name\": \"x86-msvc-release\", \"inherits\": [\"Base\", \"Ninja\", \"x86\", \"MSVC\", \"Release\"]},\n```\n\nIf you need to specify some cache variables for CMake, you can add them to the `base` configuration :\n\n```json\n    {\n      \"name\": \"Base\",\n      \"hidden\": true,\n      \"displayName\": \"Default config\",\n      \"description\": \"Default build\",\n      \"binaryDir\": \"${sourceDir}/out/build/${presetName}\",\n      \"installDir\": \"${sourceDir}/out/install/${presetName}\",\n      \"cacheVariables\": \n\t  {\n\t\t// HERE !\n\t  }\n    },\n```\n\n\u003e [!WARNING]\n\u003e\n\u003e Some configurations may not work if some binaries and libraries are not in your `PATH`. \n\u003e For example, by default with Visual Studio 2022, all windows specific configurations works but `GCC`.\n\u003e Vice versa, only `GCC` works in CLion but not the others (unless you tweak your path). \n\n\n## Additional functionality\n\nIf you wish, they are some additional functionality that requires a bit more work from you.\n\n\n### CPM Download location\n\nBy default, **[CPM](https://github.com/cpm-cmake/)** download source files in the output directory.\nIf you have several projects that use the same libraries, it may be favorable to download them in one place.\n\n**[CPM](https://github.com/cpm-cmake/)** documentation is far more comprehensive, but you can set the cmake variable `CPM_SOURCE_CACHE` to an adequate location.\nPersonally, I recommend to set it in your path, rather than in your .cmake files or in your preset.\n\n\n### CCache\n\nBy default and when configured as the main project, if **[CCache](https://ccache.dev/)** is installed, it will be activated.\nOtherwise it will be ignored.\n\nTo install **[CCache](https://ccache.dev/)** on windows, you can use chocolatey (need elevated privileges) like so :\n\n```bash\nchoco install ccache\n```\n\n\n### Documentation\n\n__Documentation__ is built with **[Doxygen](https://www.doxygen.nl/)** and **[Doxygen Awesome CSS](https://jothepro.github.io/doxygen-awesome-css/)**\n\n\u003e Documentation is only built when the project is the main project !\n\nDocumentation is built through GitHub actions and deploy it through GitHub pages when commiting on master. \nIf you wish to built it locally, the following tools are needed :\n* **[Doxygen](https://www.doxygen.nl/)**, 1.9.6+ recommended.\n\n\n#### Instructions\n\nOn Ubuntu :\n\n```sh\nsudo apt-get install doxygen\nsudo apt-get install graphviz\n```\n\nOn MacOs :\n\n```sh\nbrew install doxygen\nbrew install graphviz\n```\n\nOn windows using chocolatey (need elevated privileges) :\n\n```sh\nchoco install doxygen.install\nchoco install graphviz\n```\n\n\u003e [!WARNING]\n\u003e\n\u003e Make sure doxygen is in your path !\n\n#### Writing docs\n\nTo help you write docs, [this page](https://tblauwe.github.io/cpp_lib_starter/pages/reference.html) is a reference of some commands.\n\n### Tests\n\nThe library used for testing is [Catch2](https://github.com/catchorg/Catch2).\n\n\u003e Tests are only configured when the project is the main project !\n\n\n### Benchmarks\n\nThe library used for benchmarking is [Google benchmark](https://github.com/google/benchmark).\n\n\u003e Benchmarks are only configured when the project is the main project !\n\nIf you want to pass more options to tune the benchmarking, see [Google benchmark usage guide](https://github.com/google/benchmark/blob/main/docs/user_guide.md).\n\n\n#### Comparing benchmarks\n\nTo compare two benchmarks, you can use the following command :\n\n```console\npy benchmarks_tools/compare.py benchmarks \u003cbaseline\u003e \u003ccomparison\u003e\n```\n\nReplace `\u003cbaseline\u003e` and `\u003ccomparison\u003e` with `.json` files obtained when running your benchmarks.\n\nTo use this tools, requirement must be installed :\n\n```console\ncd benchmarks_tools\npip3 install -r requirements.txt\n```\n\n## Credits\n\n_CMake_:\n* **[cmake-init](https://github.com/friendlyanon/cmake-init)**\n* **[CCache](https://ccache.dev/)**\n\n_Benchmarks_:\n* **[Google Benchmark](https://github.com/google/benchmark)**\n\n_Tests_:\n* **[Catch2](https://github.com/catchorg/Catch2)**\n\n_Documentation_:\n* **[Doxygen](https://www.doxygen.nl/index.html)**\n* **[Doxygen Awesome CSS](https://jothepro.github.io/doxygen-awesome-css/)**\n\n_Utility_:\n* **[Tmplr](https://github.com/loreanvictor/tmplr)**\n\n\n## TODOs\n\n* [x] Support shared library\n* [ ] Semantic versionning from Github\n* [ ] Release/publish action\n* [ ] Add interactive charts for continuous benchmarking\n* [ ] Add section for continuous benchmarking\n* [ ] Install rules needs testing\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftblauwe%2Fcpp_lib_starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftblauwe%2Fcpp_lib_starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftblauwe%2Fcpp_lib_starter/lists"}