schtobia/ModernCppStarter
1
0
Fork 0
mirror of https://github.com/TheLartians/ModernCppStarter.git synced 2025-08-30 13:41:13 +02:00
Code Issues Activity

Doxygen support (#43)

Browse source 
* init doxygen

* fix format

* use readme as main file

* don't generate LaTeX

* automatically use correct project version and update html settings

* minify Doxyfile

* add documentation

* add workflow to publish documentation

* remove mac comment

* formatting

* fix typo

* grammar
This commit is contained in:
Lars Melchior 2020-06-03 14:31:53 +02:00 • committed by GitHub
parent fa77b5371f
commit 032e506c12
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 144 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

43
README.md
View file

@ -25,7 +25,8 @@ This template is the result of learnings from many previous projects and should
- Code formatting enforced by [clang-format](https://clang.llvm.org/docs/ClangFormat.html) via [Format.cmake](https://github.com/TheLartians/Format.cmake)
- Reproducible dependency management via [CPM.cmake](https://github.com/TheLartians/CPM.cmake)
- Installable target with versioning information via [PackageProject.cmake](https://github.com/TheLartians/PackageProject.cmake)
- Support for [sanitizer tools and more](#additional-tools)
- Automatic documentation generation with [Doxygen](https://www.doxygen.nl)
- Support for [sanitizer tools, and more](#additional-tools)
## Usage
@ -81,14 +82,36 @@ cmake --build build/test --target fix-format
See [Format.cmake](https://github.com/TheLartians/Format.cmake) for more options.
### Build the documentation
The documentation is automatically built and updated after every [release](https://help.github.com/en/github/administering-a-repository/managing-releases-in-a-repository).
To manually build documentation, call the following command.
```bash
cmake -Hdocumentation -Bbuild/doc
cmake --build build/doc --target GenerateDocs
# view the docs
open build/doc/doxygen/html/index.html
```
### Additional tools
The test and standalone subprojects include the [tools.cmake](cmake/tools.cmake) file which is used to import additional tools on-demand through CMake configuration arguments.
The following are currently supported.
- **Sanitizers**, by setting `-DUSE_SANITIZER=<Address | Memory | MemoryWithOrigins | Undefined | Thread | Leak | 'Address;Undefined'>`.
- **Static Analyzers**, by setting `-DUSE_STATIC_ANALYZER=<clang-tidy | iwyu | cppcheck>`, or a combination of those in quotation marks, separated by semicolons. Arguments can be passed to the analyzers by setting the `CLANG_TIDY_ARGS`, `IWYU_ARGS` or `CPPCHECK_ARGS` variables.
- **Ccache**, by setting `-DUSE_CCACHE=<ON | OFF>`.
#### Sanitizers
Sanitizers can be enabled by configuring CMake with `-DUSE_SANITIZER=<Address | Memory | MemoryWithOrigins | Undefined | Thread | Leak | 'Address;Undefined'>`.
#### Static Analyzers
Static Analyzers can be enabled by setting `-DUSE_STATIC_ANALYZER=<clang-tidy | iwyu | cppcheck>`, or a combination of those in quotation marks, separated by semicolons.
By default, analyzers will automatically find configuration files such as `.clang-format`.
Additional arguments can be passed to the analyzers by setting the `CLANG_TIDY_ARGS`, `IWYU_ARGS` or `CPPCHECK_ARGS` variables.
#### Ccache
Ccache can be enabled by configuring with `-DUSE_CCACHE=<ON | OFF>`.
## FAQ
@ -97,9 +120,15 @@ The following are currently supported.
Yes, however you will need to change the library type to an `INTERFACE` library as documented in the [CMakeLists.txt](CMakeLists.txt).
See [here](https://github.com/TheLartians/StaticTypeInfo) for an example header-only library based on the template.
> I don't need a standalone target. How can I get rid of it?
> I don't need a standalone target / documentation. How can I get rid of it?
Simply remove the standalone directory and github workflow file.
Simply remove the standalone / documentation directory and according github workflow file.
> Can I build the standalone and tests at the same time?
To keep the template modular, projects have been separated into their own CMake modules.
However it's easy to create a new directory, say `all`, that uses `CPMAddProject` 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.
> I see you are using `GLOB` to add source files in CMakeLists.txt. Isn't that evil?
@ -108,7 +137,7 @@ Glob is considered bad because any changes to the source file structure [might n
> I want create additional targets that depend on my library. Should I modify the main CMakeLists to include them?
Always 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.
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 [standalone](standalone/CMakeLists.txt) 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.