mirror of
https://github.com/TheLartians/ModernCppStarter.git
synced 2025-10-31 02:01:33 +01:00
223 lines
16 KiB
HTML
223 lines
16 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
|
<meta name="generator" content="Doxygen 1.8.18"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>Greeter: Main Page</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="jquery.js"></script>
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
|
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="resize.js"></script>
|
|
<script type="text/javascript" src="navtreedata.js"></script>
|
|
<script type="text/javascript" src="navtree.js"></script>
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
|
<script type="text/javascript" src="search/search.js"></script>
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr style="height: 56px;">
|
|
<td id="projectalign" style="padding-left: 0.5em;">
|
|
<div id="projectname">Greeter
|
|
 <span id="projectnumber">1.0</span>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.8.18 -->
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
|
/* @license-end */
|
|
</script>
|
|
<script type="text/javascript" src="menudata.js"></script>
|
|
<script type="text/javascript" src="menu.js"></script>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
|
$(function() {
|
|
initMenu('',true,false,'search.php','Search');
|
|
$(document).ready(function() { init_search(); });
|
|
});
|
|
/* @license-end */</script>
|
|
<div id="main-nav"></div>
|
|
</div><!-- top -->
|
|
<div id="side-nav" class="ui-resizable side-nav-resizable">
|
|
<div id="nav-tree">
|
|
<div id="nav-tree-contents">
|
|
<div id="nav-sync" class="sync"></div>
|
|
</div>
|
|
</div>
|
|
<div id="splitbar" style="-moz-user-select:none;"
|
|
class="ui-resizable-handle">
|
|
</div>
|
|
</div>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
|
$(document).ready(function(){initNavTree('index.html',''); initResizable(); });
|
|
/* @license-end */
|
|
</script>
|
|
<div id="doc-content">
|
|
<!-- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
</div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<iframe src="javascript:void(0)" frameborder="0"
|
|
name="MSearchResults" id="MSearchResults">
|
|
</iframe>
|
|
</div>
|
|
|
|
<div class="PageDoc"><div class="header">
|
|
<div class="headertitle">
|
|
<div class="title">Greeter Documentation</div> </div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><p><a class="anchor" id="md__Users_runner_runners_2"></a>.263.0_work_ModernCppStarter_ModernCppStarter_README <a href="https://github.com/TheLartians/ModernCppStarter/actions"><img src="https://github.com/TheLartians/ModernCppStarter/workflows/MacOS/badge.svg" alt="Actions Status" style="pointer-events: none;" class="inline"/></a> <a href="https://github.com/TheLartians/ModernCppStarter/actions"><img src="https://github.com/TheLartians/ModernCppStarter/workflows/Windows/badge.svg" alt="Actions Status" style="pointer-events: none;" class="inline"/></a> <a href="https://github.com/TheLartians/ModernCppStarter/actions"><img src="https://github.com/TheLartians/ModernCppStarter/workflows/Ubuntu/badge.svg" alt="Actions Status" style="pointer-events: none;" class="inline"/></a> <a href="https://github.com/TheLartians/ModernCppStarter/actions"><img src="https://github.com/TheLartians/ModernCppStarter/workflows/Style/badge.svg" alt="Actions Status" style="pointer-events: none;" class="inline"/></a> <a href="https://github.com/TheLartians/ModernCppStarter/actions"><img src="https://github.com/TheLartians/ModernCppStarter/workflows/Install/badge.svg" alt="Actions Status" style="pointer-events: none;" class="inline"/></a> <a href="https://codecov.io/gh/TheLartians/ModernCppStarter"><img src="https://codecov.io/gh/TheLartians/ModernCppStarter/branch/master/graph/badge.svg" alt="codecov" style="pointer-events: none;" class="inline"/></a></p>
|
|
<p align="center"></p>
|
|
<p><img src="https://repository-images.githubusercontent.com/254842585/4dfa7580-7ffb-11ea-99d0-46b8fe2f4170" alt="" height="175" width="auto" class="inline"/> </p>
|
|
<h1><a class="anchor" id="autotoc_md0"></a>
|
|
ModernCppStarter</h1>
|
|
<p>Setting up a new C++ project usually requires a significant amount of preparation and boilerplate code, even more so for modern C++ projects with tests, executables and continuous integration. This template is the result of learnings from many previous projects and should help reduce the work required to setup up a modern C++ project.</p>
|
|
<h2><a class="anchor" id="autotoc_md1"></a>
|
|
Features</h2>
|
|
<ul>
|
|
<li><a href="https://pabloariasal.github.io/2018/02/19/its-time-to-do-cmake-right/">Modern CMake practices</a></li>
|
|
<li>Suited for single header libraries and projects of any scale</li>
|
|
<li>Clean separation of library and executable code</li>
|
|
<li>Integrated test suite</li>
|
|
<li>Continuous integration via <a href="https://help.github.com/en/actions/">GitHub Actions</a></li>
|
|
<li>Code coverage via <a href="https://codecov.io">codecov</a></li>
|
|
<li>Code formatting enforced by <a href="https://clang.llvm.org/docs/ClangFormat.html">clang-format</a> via <a href="https://github.com/TheLartians/Format.cmake">Format.cmake</a></li>
|
|
<li>Reproducible dependency management via <a href="https://github.com/TheLartians/CPM.cmake">CPM.cmake</a></li>
|
|
<li>Installable target with automatic versioning information and header generation via <a href="https://github.com/TheLartians/PackageProject.cmake">PackageProject.cmake</a></li>
|
|
<li>Automatic <a href="https://thelartians.github.io/ModernCppStarter">documentation</a> and deployment with <a href="https://www.doxygen.nl">Doxygen</a> and <a href="https://pages.github.com">GitHub Pages</a></li>
|
|
<li>Support for <a href="#additional-tools">sanitizer tools, and more</a></li>
|
|
</ul>
|
|
<h2><a class="anchor" id="autotoc_md2"></a>
|
|
Usage</h2>
|
|
<h3><a class="anchor" id="autotoc_md3"></a>
|
|
Adjust the template to your needs</h3>
|
|
<ul>
|
|
<li>Use this repo <a href="https://help.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template">as a template</a> and replace all occurrences of "Greeter" in the relevant CMakeLists.txt with the name of your project</li>
|
|
<li>Replace the source files with your own</li>
|
|
<li>For header-only libraries: see the comments in <a href="CMakeLists.txt">CMakeLists.txt</a></li>
|
|
<li>Add <a href="https://docs.codecov.io/docs/quick-start">your project's codecov token</a> to your project's github secrets under <code>CODECOV_TOKEN</code></li>
|
|
<li>Happy coding!</li>
|
|
</ul>
|
|
<p>Eventually, you can remove any unused files, such as the standalone directory or irrelevant github workflows for your project. Feel free to replace the License with one suited for your project.</p>
|
|
<h3><a class="anchor" id="autotoc_md4"></a>
|
|
Build and run the standalone target</h3>
|
|
<p>Use the following command to build and run the executable target.</p>
|
|
<div class="fragment"><div class="line">cmake -Hstandalone -Bbuild/standalone</div>
|
|
<div class="line">cmake --build build/standalone</div>
|
|
<div class="line">./build/standalone/Greeter --help</div>
|
|
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md5"></a>
|
|
Build and run test suite</h3>
|
|
<p>Use the following commands from the project's root directory to run the test suite.</p>
|
|
<div class="fragment"><div class="line">cmake -Htest -Bbuild/test</div>
|
|
<div class="line">cmake --build build/test</div>
|
|
<div class="line">CTEST_OUTPUT_ON_FAILURE=1 cmake --build build/test --target test</div>
|
|
<div class="line"> </div>
|
|
<div class="line"># or simply call the executable: </div>
|
|
<div class="line">./build/test/GreeterTests</div>
|
|
</div><!-- fragment --><p>To collect code coverage information, run CMake with the <code>-DENABLE_TEST_COVERAGE=1</code> option.</p>
|
|
<h3><a class="anchor" id="autotoc_md6"></a>
|
|
Run clang-format</h3>
|
|
<p>Use the following commands from the project's root directory to run clang-format (must be installed on the host system).</p>
|
|
<div class="fragment"><div class="line">cmake -Htest -Bbuild/test</div>
|
|
<div class="line"> </div>
|
|
<div class="line"># view changes</div>
|
|
<div class="line">cmake --build build/test --target format</div>
|
|
<div class="line"> </div>
|
|
<div class="line"># apply changes</div>
|
|
<div class="line">cmake --build build/test --target fix-format</div>
|
|
</div><!-- fragment --><p>See <a href="https://github.com/TheLartians/Format.cmake">Format.cmake</a> for more options.</p>
|
|
<h3><a class="anchor" id="autotoc_md7"></a>
|
|
Build the documentation</h3>
|
|
<p>The documentation is automatically built and <a href="https://thelartians.github.io/ModernCppStarter">published</a> whenever a <a href="https://help.github.com/en/github/administering-a-repository/managing-releases-in-a-repository">GitHub Release</a> is created. To manually build documentation, call the following command.</p>
|
|
<div class="fragment"><div class="line">cmake -Hdocumentation -Bbuild/doc</div>
|
|
<div class="line">cmake --build build/doc --target GenerateDocs</div>
|
|
<div class="line"># view the docs</div>
|
|
<div class="line">open build/doc/doxygen/html/index.html</div>
|
|
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md8"></a>
|
|
Additional tools</h3>
|
|
<p>The test and standalone subprojects include the <a href="cmake/tools.cmake">tools.cmake</a> file which is used to import additional tools on-demand through CMake configuration arguments. The following are currently supported.</p>
|
|
<h4><a class="anchor" id="autotoc_md9"></a>
|
|
Sanitizers</h4>
|
|
<p>Sanitizers can be enabled by configuring CMake with ‘-DUSE_SANITIZER=<Address | Memory | MemoryWithOrigins | Undefined | Thread | Leak | 'Address;Undefined’>`.</p>
|
|
<h4><a class="anchor" id="autotoc_md10"></a>
|
|
Static Analyzers</h4>
|
|
<p>Static Analyzers can be enabled by setting <code>-DUSE_STATIC_ANALYZER=<clang-tidy | iwyu | cppcheck></code>, or a combination of those in quotation marks, separated by semicolons. By default, analyzers will automatically find configuration files such as <code>.clang-format</code>. Additional arguments can be passed to the analyzers by setting the <code>CLANG_TIDY_ARGS</code>, <code>IWYU_ARGS</code> or <code>CPPCHECK_ARGS</code> variables.</p>
|
|
<h4><a class="anchor" id="autotoc_md11"></a>
|
|
Ccache</h4>
|
|
<p>Ccache can be enabled by configuring with <code>-DUSE_CCACHE=<ON | OFF></code>.</p>
|
|
<h2><a class="anchor" id="autotoc_md12"></a>
|
|
FAQ</h2>
|
|
<blockquote class="doxtable">
|
|
<p>Can I use this for header-only libraries? </p>
|
|
</blockquote>
|
|
<p>Yes, however you will need to change the library type to an <code>INTERFACE</code> library as documented in the <a href="CMakeLists.txt">CMakeLists.txt</a>. See <a href="https://github.com/TheLartians/StaticTypeInfo">here</a> for an example header-only library based on the template.</p>
|
|
<blockquote class="doxtable">
|
|
<p>I don't need a standalone target / documentation. How can I get rid of it? </p>
|
|
</blockquote>
|
|
<p>Simply remove the standalone / documentation directory and according github workflow file.</p>
|
|
<blockquote class="doxtable">
|
|
<p>Can I build the standalone and tests at the same time? </p>
|
|
</blockquote>
|
|
<p>To keep the template modular, projects have been separated into their own CMake modules. However it's easy to create a new directory, say <code>all</code>, that uses <code>CPMAddProject</code> to add both the standalone and the tests as well as any other subprojects to a single build. Note, that it's not recommended to include the standalone or tests from the main CMakeLists, as it will make the project more difficult for others to use as a library.</p>
|
|
<blockquote class="doxtable">
|
|
<p>I see you are using <code>GLOB</code> to add source files in CMakeLists.txt. Isn't that evil? </p>
|
|
</blockquote>
|
|
<p>Glob is considered bad because any changes to the source file structure <a href="https://cmake.org/cmake/help/latest/command/file.html#filesystem">might not be automatically caught</a> by CMake's builders and you will need to manually invoke CMake on changes. I personally prefer the <code>GLOB</code> solution for its simplicity, but feel free to change it to explicitly listing sources.</p>
|
|
<blockquote class="doxtable">
|
|
<p>I want create additional targets that depend on my library. Should I modify the main CMakeLists to include them? </p>
|
|
</blockquote>
|
|
<p>Avoid including derived projects from the libraries CMakeLists (even though it is a common sight in the C++ world), as this effectively inverts the dependency tree and makes the build system hard to reason about. Instead, create a new directory or project with a CMakeLists that adds the library as a dependency (e.g. like the <a href="standalone/CMakeLists.txt">standalone</a> directory). Depending type it might make sense move these components into a separate repositories and reference a specific commit or version of the library. This has the advantage that individual libraries and components can be improved and updated independently.</p>
|
|
<blockquote class="doxtable">
|
|
<p>You recommend to add external dependencies using CPM.cmake. Will this force users of my library to use CPM as well? </p>
|
|
</blockquote>
|
|
<p><a href="https://github.com/TheLartians/CPM.cmake">CPM.cmake</a> should be invisible to library users as it's a self-contained CMake Script. If problems do arise, users can always opt-out by defining <code>CPM_USE_LOCAL_PACKAGES</code>, which will override all calls to <code>CPMAddPackage</code> with <code>find_package</code>. Alternatively, you could use <code>CPMFindPackage</code> instead of <code>CPMAddPackage</code>, which will try to use <code>find_package</code> before calling <code>CPMAddPackage</code> as a fallback. Both approaches should be compatible with common C++ package managers without modifications, however come with the cost of reproducible builds.</p>
|
|
<blockquote class="doxtable">
|
|
<p>Can I configure and build my project offline? </p>
|
|
</blockquote>
|
|
<p>Using CPM, all missing dependencies are downloaded at configure time. To avoid redundant downloads, it's recommended to set a CPM cache directory, e.g.: <code>export CPM_SOURCE_CACHE=$HOME/.cache/CPM</code>. This will also allow offline configurations if all dependencies are present. No internet connection is required for building.</p>
|
|
<blockquote class="doxtable">
|
|
<p>Can I use CPack to create a package installer for my project? </p>
|
|
</blockquote>
|
|
<p>As there are a lot of possible options and configurations, this is not (yet) in the scope of this template. See the <a href="https://cmake.org/cmake/help/latest/module/CPack.html">CPack documentation</a> for more information on setting up CPack installers.</p>
|
|
<blockquote class="doxtable">
|
|
<p>This is too much, I just want to play with C++ code and test some libraries. </p>
|
|
</blockquote>
|
|
<p>Perhaps the <a href="https://github.com/TheLartians/MiniCppStarter">MiniCppStarter</a> is something for you!</p>
|
|
<h2><a class="anchor" id="autotoc_md13"></a>
|
|
Coming soon</h2>
|
|
<ul>
|
|
<li>Script to automatically adjust the template for new projects </li>
|
|
</ul>
|
|
</div></div><!-- PageDoc -->
|
|
</div><!-- contents -->
|
|
</div><!-- doc-content -->
|
|
<!-- start footer part -->
|
|
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
|
<ul>
|
|
<li class="footer">Generated by
|
|
<a href="http://www.doxygen.org/index.html">
|
|
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.18 </li>
|
|
</ul>
|
|
</div>
|
|
</body>
|
|
</html>
|