@@ -2,6 +2,13 @@

 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++

@@ -14,11 +21,281 @@ 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`](LICENSE) file.

+[`LICENSE`][] file.

 [BSD 0-Clause License]: https://choosealicense.com/licenses/0bsd/

+[`LICENSE`]: LICENSE

@@ -5,3 +5,20 @@ A [CMake][]\>=3.14 [C++][] common project helper.

 [`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][].

+

+[License]: #license

+

+## License

+

+Licensed under the [BSD 0-Clause License][] unless otherwise noted, see the

+[`LICENSE`](LICENSE) file.

+

+[BSD 0-Clause License]: https://choosealicense.com/licenses/0bsd/

new file mode 100644

@@ -0,0 +1,7 @@

+# [`cmake-common`][]

+

+A [CMake][]\>=3.14 [C++][] common project helper.

+

+[`cmake-common`]: https://git.rcrnstn.net/rcrnstn/cmake-common

+[CMake]: https://cmake.org

+[C++]: https://en.wikipedia.org/wiki/C++