mirror of
https://github.com/TheLartians/ModernCppStarter.git
synced 2025-08-30 21:51:12 +02:00
121 lines
17 KiB
HTML
121 lines
17 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8" />
|
|
<title>Greeter</title>
|
|
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
|
|
<link rel="stylesheet" href="m-dark+documentation.compiled.css" />
|
|
<link rel="icon" href="favicon-dark.png" type="image/png" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
<meta name="theme-color" content="#22272e" />
|
|
</head>
|
|
<body>
|
|
<header><nav id="navigation">
|
|
<div class="m-container">
|
|
<div class="m-row">
|
|
<a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">Greeter</a>
|
|
<div class="m-col-t-4 m-hide-m m-text-right m-nopadr">
|
|
<a href="#search" class="m-doc-search-icon" title="Search" onclick="return showSearch()"><svg style="height: 0.9rem;" viewBox="0 0 16 16">
|
|
<path id="m-doc-search-icon-path" d="m6 0c-3.31 0-6 2.69-6 6 0 3.31 2.69 6 6 6 1.49 0 2.85-0.541 3.89-1.44-0.0164 0.338 0.147 0.759 0.5 1.15l3.22 3.79c0.552 0.614 1.45 0.665 2 0.115 0.55-0.55 0.499-1.45-0.115-2l-3.79-3.22c-0.392-0.353-0.812-0.515-1.15-0.5 0.895-1.05 1.44-2.41 1.44-3.89 0-3.31-2.69-6-6-6zm0 1.56a4.44 4.44 0 0 1 4.44 4.44 4.44 4.44 0 0 1-4.44 4.44 4.44 4.44 0 0 1-4.44-4.44 4.44 4.44 0 0 1 4.44-4.44z"/>
|
|
</svg></a>
|
|
<a id="m-navbar-show" href="#navigation" title="Show navigation"></a>
|
|
<a id="m-navbar-hide" href="#" title="Hide navigation"></a>
|
|
</div>
|
|
<div id="m-navbar-collapse" class="m-col-t-12 m-show-m m-col-m-none m-right-m">
|
|
<div class="m-row">
|
|
<ol class="m-col-t-6 m-col-m-none">
|
|
<li>
|
|
<a href="pages.html">Pages</a>
|
|
<ol>
|
|
<li><a href="about.html">About</a></li>
|
|
</ol>
|
|
</li>
|
|
<li><a href="namespaces.html">Namespaces</a></li>
|
|
</ol>
|
|
<ol class="m-col-t-6 m-col-m-none" start="3">
|
|
<li><a href="annotated.html">Classes</a></li>
|
|
<li><a href="files.html">Files</a></li>
|
|
<li class="m-show-m"><a href="#search" class="m-doc-search-icon" title="Search" onclick="return showSearch()"><svg style="height: 0.9rem;" viewBox="0 0 16 16">
|
|
<use href="#m-doc-search-icon-path" />
|
|
</svg></a></li>
|
|
</ol>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</nav></header>
|
|
<main><article>
|
|
<div class="m-container m-container-inflatable">
|
|
<div class="m-row">
|
|
<div class="m-col-l-10 m-push-l-1">
|
|
<h1>
|
|
Greeter
|
|
</h1>
|
|
<p><a name="md_README"></a><a href="https://github.com/TheLartians/ModernCppStarter/actions"><img class="m-image" src="https://github.com/TheLartians/ModernCppStarter/workflows/MacOS/badge.svg" alt="Image" /></a> <a href="https://github.com/TheLartians/ModernCppStarter/actions"><img class="m-image" src="https://github.com/TheLartians/ModernCppStarter/workflows/Windows/badge.svg" alt="Image" /></a> <a href="https://github.com/TheLartians/ModernCppStarter/actions"><img class="m-image" src="https://github.com/TheLartians/ModernCppStarter/workflows/Ubuntu/badge.svg" alt="Image" /></a> <a href="https://github.com/TheLartians/ModernCppStarter/actions"><img class="m-image" src="https://github.com/TheLartians/ModernCppStarter/workflows/Style/badge.svg" alt="Image" /></a> <a href="https://github.com/TheLartians/ModernCppStarter/actions"><img class="m-image" src="https://github.com/TheLartians/ModernCppStarter/workflows/Install/badge.svg" alt="Image" /></a> <a href="https://codecov.io/gh/TheLartians/ModernCppStarter"><img class="m-image" src="https://codecov.io/gh/TheLartians/ModernCppStarter/branch/master/graph/badge.svg" alt="Image" /></a></p><img class="m-image" src="https://repository-images.githubusercontent.com/254842585/4dfa7580-7ffb-11ea-99d0-46b8fe2f4170" alt="Image" /><section id="autotoc_md0"><h2><a href="#autotoc_md0">ModernCppStarter</a></h2><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><section id="autotoc_md1"><h3><a href="#autotoc_md1">Features</a></h3><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></section><section id="autotoc_md2"><h3><a href="#autotoc_md2">Usage</a></h3><section id="autotoc_md3"><h4><a href="#autotoc_md3">Adjust the template to your needs</a></h4><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></section><section id="autotoc_md4"><h4><a href="#autotoc_md4">Build and run the standalone target</a></h4><p>Use the following command to build and run the executable target.</p><pre class="m-code">cmake -Hstandalone -Bbuild/standalone
|
|
cmake --build build/standalone
|
|
./build/standalone/Greeter --help</pre></section><section id="autotoc_md5"><h4><a href="#autotoc_md5">Build and run test suite</a></h4><p>Use the following commands from the project's root directory to run the test suite.</p><pre class="m-code">cmake -Htest -Bbuild/test
|
|
cmake --build build/test
|
|
<span class="nv">CTEST_OUTPUT_ON_FAILURE</span><span class="o">=</span><span class="m">1</span> cmake --build build/test --target <span class="nb">test</span>
|
|
|
|
<span class="c1"># or simply call the executable: </span>
|
|
./build/test/GreeterTests</pre><p>To collect code coverage information, run CMake with the <code>-DENABLE_TEST_COVERAGE=1</code> option.</p></section><section id="autotoc_md6"><h4><a href="#autotoc_md6">Run clang-format</a></h4><p>Use the following commands from the project's root directory to run clang-format (must be installed on the host system).</p><pre class="m-code">cmake -Htest -Bbuild/test
|
|
|
|
<span class="c1"># view changes</span>
|
|
cmake --build build/test --target format
|
|
|
|
<span class="c1"># apply changes</span>
|
|
cmake --build build/test --target fix-format</pre><p>See <a href="https://github.com/TheLartians/Format.cmake">Format.cmake</a> for more options.</p></section><section id="autotoc_md7"><h4><a href="#autotoc_md7">Build the documentation</a></h4><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><pre class="m-code">cmake -Hdocumentation -Bbuild/doc
|
|
cmake --build build/doc --target GenerateDocs
|
|
<span class="c1"># view the docs</span>
|
|
open build/doc/doxygen/html/index.html</pre><p>To build the documentation locally, you will need Doxygen, jinja2 and Pygments on installed your system.</p></section><section id="autotoc_md8"><h4><a href="#autotoc_md8">Additional tools</a></h4><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><section id="autotoc_md9"><h5><a href="#autotoc_md9">Sanitizers</a></h5><p>Sanitizers can be enabled by configuring CMake with ‘-DUSE_SANITIZER=<Address | Memory | MemoryWithOrigins | Undefined | Thread | Leak | 'Address;Undefined’>`.</p></section><section id="autotoc_md10"><h5><a href="#autotoc_md10">Static Analyzers</a></h5><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></section><section id="autotoc_md11"><h5><a href="#autotoc_md11">Ccache</a></h5><p>Ccache can be enabled by configuring with <code>-DUSE_CCACHE=<ON | OFF></code>.</p></section></section></section><section id="autotoc_md12"><h3><a href="#autotoc_md12">FAQ</a></h3><blockquote><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><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><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><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><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><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><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><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><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></section><section id="autotoc_md13"><h3><a href="#autotoc_md13">Coming soon</a></h3><ul><li>Script to automatically adjust the template for new projects</li></ul></section></section>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</article></main>
|
|
<div class="m-doc-search" id="search">
|
|
<a href="#!" onclick="return hideSearch()"></a>
|
|
<div class="m-container">
|
|
<div class="m-row">
|
|
<div class="m-col-m-8 m-push-m-2">
|
|
<div class="m-doc-search-header m-text m-small">
|
|
<div><span class="m-label m-default">Tab</span> / <span class="m-label m-default">T</span> to search, <span class="m-label m-default">Esc</span> to close</div>
|
|
<div id="search-symbolcount">…</div>
|
|
</div>
|
|
<div class="m-doc-search-content">
|
|
<form>
|
|
<input type="search" name="q" id="search-input" placeholder="Loading …" disabled="disabled" autofocus="autofocus" autocomplete="off" spellcheck="false" />
|
|
</form>
|
|
<noscript class="m-text m-danger m-text-center">Unlike everything else in the docs, the search functionality <em>requires</em> JavaScript.</noscript>
|
|
<div id="search-help" class="m-text m-dim m-text-center">
|
|
<p class="m-noindent">Search for symbols, directories, files, pages or
|
|
modules. You can omit any prefix from the symbol or file path; adding a
|
|
<code>:</code> or <code>/</code> suffix lists all members of given symbol or
|
|
directory.</p>
|
|
<p class="m-noindent">Use <span class="m-label m-dim">↓</span>
|
|
/ <span class="m-label m-dim">↑</span> to navigate through the list,
|
|
<span class="m-label m-dim">Enter</span> to go.
|
|
<span class="m-label m-dim">Tab</span> autocompletes common prefix, you can
|
|
copy a link to the result using <span class="m-label m-dim">⌘</span>
|
|
<span class="m-label m-dim">L</span> while <span class="m-label m-dim">⌘</span>
|
|
<span class="m-label m-dim">M</span> produces a Markdown link.</p>
|
|
</div>
|
|
<div id="search-notfound" class="m-text m-warning m-text-center">Sorry, nothing was found.</div>
|
|
<ul id="search-results"></ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<script src="search-v1.js"></script>
|
|
<script src="searchdata-v1.js" async="async"></script>
|
|
<footer><nav>
|
|
<div class="m-container">
|
|
<div class="m-row">
|
|
<div class="m-col-l-10 m-push-l-1">
|
|
<p>Greeter. Created with <a href="https://doxygen.org/">Doxygen</a> 1.8.18 and <a href="https://mcss.mosra.cz/">m.css</a>.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</nav></footer>
|
|
</body>
|
|
</html>
|