# [`cmake-common`][]
A [CMake][]\>=3.14 [C++][] common project helper.
[CMake][] has many useful features but requires verbose per-project
configuration to enable them. This helper allows you to just place your files
where everyone expects them to be anyway, install the tools you want to use,
and things like downloading dependencies, linting, building, testing,
sanitizing, packaging (build artifacts, assets, documentation), and installing
will automatically be enabled.
[`cmake-common`]: https://git.rcrnstn.net/rcrnstn/cmake-common
[CMake]: https://cmake.org
[C++]: https://en.wikipedia.org/wiki/C++
## Usage
This work is licensed in such a way that you may use it however you please,
including relicensing, without attribution. As such, the encouraged way to use
this work is to simply copy the required files or content into your project,
optionally(!) mentioning where it came from in the readme or other
documentation. See [License][].
Copy the file [`common.cmake`][] into your project and [`include`][] it from
(e.g.) the main [`CMakeLists.txt`][]. This will define a `common` function that
takes a number of arguments to configure the project.
[License]: #license
[`include`]: https://cmake.org/cmake/help/v3.14/command/include.html
[`common.cmake`]: common.cmake
[`CMakeLists.txt`]: https://cmake.org/cmake/help/v3.14/manual/cmake-language.7.html#directories
### Overview
```cmake
## CMake
cmake_minimum_required(VERSION 3.14)
if(NOT CMAKE_BUILD_TYPE)
set(CMAKE_BUILD_TYPE Debug)
endif()
## Project
project(project-name
VERSION 1.0.0
LANGUAGES CXX
)
## Main target
add_library(${PROJECT_NAME})
## Common
include(common.cmake)
common(
CXX_STANDARD 11
DISABLE_INCLUDE_WHAT_YOU_USE
PACKAGES
Package
EXTERNAL
external_project
FETCHCONTENT
"https://example.com/user/online_project GIT_TAG v1.2.3"
DEPENDENCIES_PUBLIC
Package::Package
DEPENDENCIES_PRIVATE
external_project
DEPENDENCIES_TESTS
online_project
DEFINITIONS
PROJECT_FEATURE
)
```
### Main target
If there are files in the `src` and/or `include` directories, they are added as
sources to a single "main" target, which is assumed to already be declared with
the name `${`[`PROJECT_NAME`][]`}` (which is automatically set by CMake when
calling [`project`][]). The "main" target may be of any type, such as [normal
executable][], [normal library][], [interface library][], or [custom target][]
(the latter probably with the `ALL` specifier, so that it is added to the
default build target so that it will be run every time).
[`PUBLIC`][] dependencies are taken from `DEPENDENCIES_PUBLIC` and
[`PRIVATE`][] dependencies are taken from `DEPENDENCIES_PRIVATE`, see
[Dependencies][].
For [top level project][]s, `*Config.cmake` and `*ConfigVersion.cmake` files
that can be used by [`find_package`][] to find this project are
[`install`][]ed, see [Packaging][].
[`PROJECT_NAME`]: https://cmake.org/cmake/help/v3.14/variable/PROJECT_NAME.html
[`project`]: https://cmake.org/cmake/help/v3.14/command/project.html
[normal executable]: https://cmake.org/cmake/help/v3.14/command/add_executable.html#normal-executables
[normal library]: https://cmake.org/cmake/help/v3.14/command/add_library.html#normal-libraries
[interface library]: https://cmake.org/cmake/help/v3.14/command/add_library.html#interface-libraries
[custom target]: https://cmake.org/cmake/help/v3.14/command/add_custom_target.html
[`PUBLIC`]: https://cmake.org/cmake/help/v3.14/manual/cmake-buildsystem.7.html#target-usage-requirements
[`PRIVATE`]: https://cmake.org/cmake/help/v3.14/manual/cmake-buildsystem.7.html#target-usage-requirements
[Dependencies]: #dependencies
[top level project]: https://cmake.org/cmake/help/v3.14/variable/CMAKE_PROJECT_NAME.html
[`find_package`]: https://cmake.org/cmake/help/v3.14/command/find_package.html
[`install`]: https://cmake.org/cmake/help/v3.14/command/install.html
[Packaging]: #packaging
### Test targets
For [top level project][]s, every file directly under the `tests` directory is
individually added as a source to a separate executable "test" target, which is
automatically declared with the name `${PROJECT_NAME}-test-${TEST_NAME}` and
passed to [`add_test`][]. All files in the `tests/common` directory are also
added as sources to all "test" targets.
A ([`PRIVATE`][]) dependency on the "main" target is declared and further
([`PRIVATE`][]) dependencies are taken from `DEPENDENCIES_TESTS`, see
[Dependencies][].
CMake can be run with the standard `-D`[`BUILD_TESTING`][]`=OFF` to disable
testing.
See [Testing][].
[`add_test`]: https://cmake.org/cmake/help/v3.14/command/add_test.html
[`BUILD_TESTING`]: https://cmake.org/cmake/help/v3.14/module/CTest.html
[Testing]: #testing
### Assets
If there are files in the `assets` directory, a target named
`${PROJECT_NAME}-assets` that runs by default and [symlink][]s them to
`${`[`CMAKE_BINARY_DIR`][]`}/assets` is automatically declared.
If the path does not include `/tests/`, the asset is [`install`][]ed into
`${`[`CMAKE_INSTALL_DATADIR`][]`}/${CMAKE_PROJECT_NAME}/assets` (note that
`CMAKE_PROJECT_NAME` is the name of the [top level project][]), see
[Packaging][].
[symlink]: https://en.wikipedia.org/wiki/Symbolic_link
[`CMAKE_BINARY_DIR`]: https://cmake.org/cmake/help/v3.14/variable/CMAKE_BINARY_DIR.html
[`CMAKE_INSTALL_DATADIR`]: https://cmake.org/cmake/help/v3.14/module/GNUInstallDirs.html
### Documentation
For [top level project][]s, documentation from the `doc` directory and
repository root is automatically [`install`][]ed, see [Packaging][].
### Man pages
For [top level project][]s, [man page][]s from the `man` directory is
automatically [`install`][]ed, see [Packaging][].
[man page]: https://en.wikipedia.org/wiki/Man_page
### Dependencies
Dependencies on other targets are declared with `DEPENDENCIES_PUBLIC`,
`DEPENDENCIES_PRIVATE`, and `DEPENDENCIES_TESTS`, see [Main target][] and [Test
targets][].
Three mechanisms to make these dependencies available are provided, given as
arguments to the `common` function:
- `PACKAGES`: Packages passed to [`find_package`][]`(...)` in order to find
system packages.
- `EXTERNAL`: Subdirectories of `external` that is passed to
[`add_subdirectory`][].
- `FETCHCONTENT`: [Git][] [URL][]s passed to [`FetchContent_Declare`][]'s
`GIT_REPOSITORY`. If a specific [Git tag][] is wanted, specify it in the
same (quoted) argument, delimited with `GIT_TAG`, see [Usage][].
(`GIT_SHALLOW` and `GIT_PROGRESS` are always set to `TRUE`).
[`FetchContent_MakeAvailable`][] is automatically called in order to
download and make targets available during the CMake configure step.
If more involved steps are required to make targets available, perform them
manually before calling the `common` function.
[Main target]: #main-target
[Test targets]: #test-targets
[`add_subdirectory`]: https://cmake.org/cmake/help/v3.14/command/add_subdirectory.html
[Git]: https://git-scm.com
[URL]: https://en.wikipedia.org/wiki/URL
[`FetchContent_Declare`]: https://cmake.org/cmake/help/v3.14/module/FetchContent.html#command:fetchcontent_declare
[`FetchContent_MakeAvailable`]: https://cmake.org/cmake/help/v3.14/module/FetchContent.html#command:fetchcontent_makeavailable
[Git tag]: https://git-scm.com/book/en/v2/Git-Basics-Tagging
[Usage]: #usage
### Preprocessor definitions
[Preprocessor definitions][] can be specified with the `DEFINITIONS` argument
to the `common` function. Both `NAME` and `NAME=EXPANSION` forms are supported.
[preprocessor definitions]: https://en.cppreference.com/w/cpp/preprocessor/replace#.23define_directives
### Language version
For [top level project][]s, the `CXX_STANDARD` argument to the `common`
function sets the [`CXX_STANDARD`][] property applied to configured targets
([`CXX_STANDARD_REQUIRED`][] is always set to `ON`, [`CXX_EXTENSIONS`][] is
always set to `OFF`).
[`CXX_STANDARD`]: https://cmake.org/cmake/help/v3.14/prop_tgt/CXX_STANDARD.html
[`CXX_STANDARD_REQUIRED`]: https://cmake.org/cmake/help/v3.14/prop_tgt/CXX_STANDARD_REQUIRED.html
[`CXX_EXTENSIONS`]: https://cmake.org/cmake/help/v3.14/prop_tgt/CXX_EXTENSIONS.html
### Build options
For [top level project][]s, aggressive warnings are enabled and treated as
errors.
For projects compiled with [GCC][] or [Clang][], [`-Wshadow`][] is enabled by
default, but can be disabled by passing `DISABLE_WSHADOW` to the `common`
function.
For projects compiled with [MSVC][], [`/Zc:__cplusplus`][] is enabled.
If supported, [interprocedural optimization][] (also known as link-time
optimization) is enabled.
For projects compiled with the `Debug` [build type][] with [GCC][] or
[Clang][], [address sanitizer][] ([wiki][address sanitizer wiki]), [leak
sanitizer][] ([wiki][leak sanitizer wiki]), and [undefined behavior
sanitizer][] are linked into all targets. The sanitizers can be disabled by
passing `DISABLE_SANITIZERS` to the `common` function. Suppression files that
match the [glob][]s `*.asan.supp`, `*.lsan.supp`, and `*.ubsan.supp`
respectively in the repository root are automatically used.
[GCC]: https://gcc.gnu.org
[Clang]: https://clang.llvm.org
[`-Wshadow=`]: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wshadow
[MSVC]: https://visualstudio.microsoft.com/vs/
[`/Zc:__cplusplus`]: https://learn.microsoft.com/en-us/cpp/build/reference/zc-cplusplus
[interprocedural optimization]: https://en.wikipedia.org/wiki/Interprocedural_optimization
[build type]: https://cmake.org/cmake/help/v3.14/variable/CMAKE_BUILD_TYPE.html
[address sanitizer]: https://clang.llvm.org/docs/AddressSanitizer.html
[address sanitizer wiki]: https://github.com/google/sanitizers/wiki/AddressSanitizer
[leak sanitizer]: https://clang.llvm.org/docs/LeakSanitizer.html
[leak sanitizer wiki]: https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer
[undefined behavior sanitizer]: https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html
[glob]: https://en.wikipedia.org/wiki/Glob_(programming)
### Tools
For [top level project][]s compiled with the `Debug` [build type][],
[Cppcheck][], [Clang-Tidy][], and [Include What You Use][] are automatically
configured if present on the system. The tools can be disabled by passing the
`DISABLE_CPPCHECK`, `DISABLE_CLANG_TIDY`, and/or `DISABLE_INCLUDE_WHAT_YOU_USE`
options, respectively, to the `common` function. CppCheck suppressions list
files that match the [glob][] `.cppcheck.supp`, a Clang-Tidy configuration file
named `.clang-tidy`, and Include What You Use [mapping files][] that match the
[glob][] `*.iwyu.imp`, in the repository root, are automatically used.
[Cppcheck]: https://cppcheck.sourceforge.io
[Clang-Tidy]: https://clang.llvm.org/extra/clang-tidy
[Include What You Use]: https://include-what-you-use.org
[mapping files]: https://github.com/include-what-you-use/include-what-you-use/blob/0.20/docs/IWYUMappings.md
### Testing
For [top level project][]s, [CTest][] is automatically configured and can be
run with [`ctest`][], see the [`BUILDING.md`][] auxiliary file.
[CTest]: https://cmake.org/cmake/help/v3.14/module/CTest.html
[`ctest`]: https://cmake.org/cmake/help/v3.14/manual/ctest.1.html
[`BUILDING.md`]: BUILDING.md
### Packaging
For [top level project][]s, [CPack][] is automatically configured and can be
run with [`cpack`][], see the [`BUILDING.md`][] auxiliary file.
[CPack]: https://cmake.org/cmake/help/v3.14/module/Pack.html
[`cpack`]: ttps://cmake.org/cmake/help/v3.14/manual/cpack.1.html
## Auxiliary files
This repository includes some files besides [`common.cmake`][] that may be of
use:
- [`BUILDING.md`][]: Instructions to build a project that uses
[`cmake-common`][].
- [`.gitignore`][]: A configuration file for [Git][] that makes it ignore the
created `_build` directory created when following the instructions in
[`BUILDING.md`][].
- [`.cppcheck.supp`][]: A suppressions list for [CppCheck][] with a set of
suppressed warnings.
- [`.clang-tidy`][]: A configuration file for [Clang-Tidy][] with a set of
enabled and disabled warnings.
[`.gitignore`]: .gitignore
[`.cppcheck.supp`]: .cppcheck.supp
[`.clang-tidy`]: .clang-tidy
## License
Licensed under the [BSD 0-Clause License][] unless otherwise noted, see the
[`LICENSE`][] file.
[BSD 0-Clause License]: https://choosealicense.com/licenses/0bsd/
[`LICENSE`]: LICENSE
git.rcrnstn.net