docs/modern-cmake
docs/modern-cmake
1
0
Fork 0
mirror of synced 2024-12-22 04:30:01 +01:00
Code Issues Releases Wiki Activity

chore: use 3.15 as min everywhere

Browse Source
This commit is contained in:
Henry Schreiner 2024-08-16 06:30:35 +00:00
parent b44ee71361
commit 0335f5e5d3
13 changed files with 52 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
README.md
View File

@ -7,9 +7,8 @@ Certainly there are no shortage of problems when building.
But I think that, in 2023, we have a very good solution to quite a few of those problems.
It's CMake. Not CMake 2.8 though; that was released before C++11 even existed!
Nor the horrible examples out there for CMake (even those posted on KitWare's own tutorials list).
I'm talking about Modern CMake. CMake 3.5+, maybe even CMake 3.30+!
I'm talking about Modern CMake. CMake 3.15+, maybe even CMake 3.30+!
It's clean, powerful, and elegant, so you can spend most of your time coding, not adding lines to an unreadable, unmaintainable Make (Or CMake 2) file.
And CMake 3.11+ is supposed to be significantly faster, as well!
:::{note}

45
chapters/basics.md
View File

@ -6,7 +6,7 @@ Here's the first line of every `CMakeLists.txt`, which is the required name of
the file CMake looks for:
```cmake
cmake_minimum_required(VERSION 3.1)
cmake_minimum_required(VERSION 3.15)
```
Let's mention a bit of CMake syntax. The command name
@ -22,50 +22,27 @@ newest CMake versions. If you set it to 3.3 or less, you'll get the wrong
hidden symbols behaviour, etc. A list of policies and versions is available at
{{ cmake.format('policies') }}.
Starting in CMake 3.12, this supports a range, such as `VERSION 3.1...3.15`;
this means you support as low as 3.1 but have also tested it with the new
policy settings up to 3.15. This is much nicer on users that need the better
Starting in CMake 3.12, this supports a range, such as `VERSION 3.15...3.30`;
this means you support as low as 3.15 but have also tested it with the new
policy settings up to 3.30. This is much nicer on users that need the better
settings, and due to a trick in the syntax, it's backward compatible with older
versions of CMake (though actually running CMake 3.1-3.11 will only set the 3.1
version of the policies in this example, since those versions didn't treat this
specially). New versions of policies tend to be most important for macOS and
Windows users, who also usually have a very recent version of CMake.
versions of CMake (though actually running CMake 3.1-3.11 will only set the old
version of the policies, since those versions didn't treat this specially). New
versions of policies tend to be most important for macOS and Windows users, who
also usually have a very recent version of CMake.
This is what new projects should do:
```cmake
cmake_minimum_required(VERSION 3.7...3.30)
if(${CMAKE_VERSION} VERSION_LESS 3.12)
cmake_policy(VERSION ${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION})
endif()
cmake_minimum_required(VERSION 3.15...3.30)
```
If CMake version is less than 3.12, the if block will be true, and the policy
will be set to the current CMake version. If CMake is 3.12 or higher, the if
block will be false, but the new syntax in `cmake_minimum_required` will be
respected and this will continue to work properly!
WARNING: MSVC's CMake server mode [originally had a
bug](https://github.com/fmtlib/fmt/issues/809) in reading this format, so if
you need to support non-command line Windows builds for older MSVC versions,
you will want to do this instead:
```cmake
cmake_minimum_required(VERSION 3.7)
if(${CMAKE_VERSION} VERSION_LESS 3.30)
cmake_policy(VERSION ${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION})
else()
cmake_policy(VERSION 3.30)
endif()
```
:::{tip}
If you really need to set to a low value here, you can use
{{ command.format('cmake_policy') }} to conditionally increase the policy level or set a
specific policy. Please at least do this for your macOS users!
specific policy.
:::
@ -152,7 +129,7 @@ Targets can have include directories, linked libraries (or linked targets), comp
See if you can follow the following file. It makes a simple C++11 library and a program using it. No dependencies. I'll discuss more C++ standard options later, using the CMake 3.8 system for now.
```cmake
cmake_minimum_required(VERSION 3.8)
cmake_minimum_required(VERSION 3.15...3.30)
project(Calculator LANGUAGES CXX)

23
chapters/intro/dodonot.md
View File

@ -21,7 +21,7 @@ The next two lists are heavily based on the excellent gist [Effective Modern CMa
- **Use lowercase function names**: CMake functions and macros can be called lower or upper case. Always use lower case. Upper case is for variables.
- **Use `cmake_policy` and/or range of versions**: Policies change for a reason. Only piecemeal set OLD policies if you have to.
## Selecting a minimum in 2022:
## Selecting a minimum in 2024:
What minimum CMake should you _run_ locally, and what minimum should you _support_ for people using your
code? Since you are reading this, you should be able to get a release in the last few versions of CMake;
@ -34,22 +34,29 @@ at least as new as your compiler.
### What minimum to choose - OS support:
- 3.4: The bare minimum. Never set less.
- 3.7: Debian old-stable.
- 3.10: Ubuntu 18.04.
- 3.11: CentOS 8 (use EPEL or AppSteams, though)
- 3.13: Debian stable.
- 3.16: Ubuntu 20.04.
- 3.17: Amazon Linux
- 3.19: First to support Apple Silicon.
- 3.20: CentOS 8.
- 3.22: Ubuntu 22.04.
- 3.25: Debian 12 (11 backports)
- 3.28: Ubuntu 24.04.
- 3.29: Debian 13 (12 backports)
- latest: pip/conda-forge/homebew/chocolaty, etc.
### What minimum to choose - Features:
- 3.8: C++ meta features, CUDA, lots more
- 3.11: `IMPORTED INTERFACE` setting, faster, FetchContent, `COMPILE_LANGUAGE` in IDEs
- 3.12: C++20, `cmake --build build -j N`, `SHELL:`, FindPython
- 3.14/3.15: CLI, FindPython updates
- 3.16: Unity builds / precompiled headers, CUDA meta features
- 3.17/3.18: Lots more CUDA, metaprogramming
- 3.17/3.18: Lots more CUDA, metaprogramming, FindPython updates
- 3.19: Presets
- 3.20: C++23, `cmake_path`
- 3.24: Package finder
- 3.25: Blocks for scoping
- 3.28: C++20 modules
- 3.29: Build before test target
- 3.30: Full C++26 support
[effective modern cmake]: https://gist.github.com/mbinna/c61dbb39bca0e4fb7d1f73b0d66a4fd1

33
chapters/intro/installing.md
View File

@ -2,11 +2,11 @@
:::{tip}
Your CMake version should be newer than your compiler. It should be newer than the libraries you are using (especially Boost). New versions work better for everyone.
Your CMake version should be newer than your compiler. It should be newer than the libraries you are using. New versions work better for everyone.
:::
If you have a built in copy of CMake, it isn't special or customized for your system. You can easily install a new one instead, either on the system level or the user level. Feel free to instruct your users here if they complain about a CMake requirement being set too high. Especially if they want 3.1+ support. Maybe even if they want 3.30+ support...
If you have a built in copy of CMake, it isn't special or customized for your system. You can easily install a new one instead, either on the system level or the user level. Feel free to instruct your users here if they complain about a CMake requirement being set too high. Especially if they want 3.15+ support. Maybe even if they want 3.30+ support...
## Quick list (more info on each method below)
@ -85,21 +85,18 @@ Homebrew is quite a bit more popular nowadays on macOS, at least according to Go
#### RHEL/CentOS
[![CentOS 7 package](https://repology.org/badge/version-for-repo/centos_7/cmake.svg?minversion=3.10.0)][centos]
[![CentOS 8 package](https://repology.org/badge/version-for-repo/centos_8/cmake.svg?minversion=3.10.0)][centos]
[![EPEL 7 package](https://repology.org/badge/version-for-repo/epel_7/cmake.svg?minversion=3.10.0)][centos]
[![CentOS 7 package](https://repology.org/badge/version-for-repo/centos_7/cmake.svg?minversion=3.15.0)][centos]
[![CentOS 8 package](https://repology.org/badge/version-for-repo/centos_8/cmake.svg?minversion=3.15.0)][centos]
[![EPEL 7 package](https://repology.org/badge/version-for-repo/epel_7/cmake.svg?minversion=3.15.0)][centos]
The default on 8 is not too bad, but you should not use the default on 7. Use the EPEL package instead.
The default on 8 is not too bad, but you should not use the default on the end-of-life CentOS 7. Use the EPEL package instead.
#### Ubuntu
[![Ubuntu 14.04 package](https://repology.org/badge/version-for-repo/ubuntu_14_04/cmake.svg?minversion=3.10.0)](https://launchpad.net/ubuntu/trusty/+source/cmake)
[![Ubuntu 16.04 package](https://repology.org/badge/version-for-repo/ubuntu_16_04/cmake.svg?minversion=3.10.0)](https://launchpad.net/ubuntu/xenial/+source/cmake)
[![Ubuntu 18.04 package](https://repology.org/badge/version-for-repo/ubuntu_18_04/cmake.svg?minversion=3.10.0)](https://launchpad.net/ubuntu/bionic/+source/cmake)
[![Ubuntu 20.04 package](https://repology.org/badge/version-for-repo/ubuntu_20_04/cmake.svg?minversion=3.10.0)](https://launchpad.net/ubuntu/focal/+source/cmake)
[![Ubuntu 22.04 package](https://repology.org/badge/version-for-repo/ubuntu_22_04/cmake.svg?minversion=3.10.0)](https://launchpad.net/ubuntu/jammy/+source/cmake)
You should only use the default CMake on 18.04+; it's an LTS release with a pretty decent minimum version!
[![Ubuntu 18.04 package](https://repology.org/badge/version-for-repo/ubuntu_18_04/cmake.svg?minversion=3.15.0)](https://launchpad.net/ubuntu/bionic/+source/cmake)
[![Ubuntu 20.04 package](https://repology.org/badge/version-for-repo/ubuntu_20_04/cmake.svg?minversion=3.15.0)](https://launchpad.net/ubuntu/focal/+source/cmake)
[![Ubuntu 22.04 package](https://repology.org/badge/version-for-repo/ubuntu_22_04/cmake.svg?minversion=3.15.0)](https://launchpad.net/ubuntu/jammy/+source/cmake)
[![Ubuntu 24.04 package](https://repology.org/badge/version-for-repo/ubuntu_24_04/cmake.svg?minversion=3.15.0)](https://launchpad.net/ubuntu/noble/+source/cmake)
#### Debian
@ -111,9 +108,9 @@ You should only use the default CMake on 18.04+; it's an LTS release with a pret
#### Other
[![Alpine Linux 3.15 package](https://repology.org/badge/version-for-repo/alpine_3_15/cmake.svg)](https://pkgs.alpinelinux.org/packages?name=cmake&branch=v3.15)
[![Alpine Linux 3.20 package](https://repology.org/badge/version-for-repo/alpine_3_20/cmake.svg)](https://pkgs.alpinelinux.org/packages?name=cmake&branch=v3.20)
[![Arch package](https://repology.org/badge/version-for-repo/arch/cmake.svg)][repology]
[![Fedora 35 package](https://repology.org/badge/version-for-repo/fedora_35/cmake.svg)][repology]
[![Fedora 40 package](https://repology.org/badge/version-for-repo/fedora_40/cmake.svg)][repology]
[![FreeBSD port](https://repology.org/badge/version-for-repo/freebsd/cmake.svg)][repology]
[![OpenBSD port](https://repology.org/badge/version-for-repo/openbsd/cmake.svg)][repology]
[![Gentoo package](https://repology.org/badge/version-for-repo/gentoo/cmake.svg)][repology]
@ -133,8 +130,6 @@ Just `pip install cmake` on many systems. Add `--user` if you have to (modern pi
| Distribution | CMake version | Notes |
| ------------------------------------------------------------------------------------------------------------------------------------ | ------------- | ------------------------------------------------------------ |
| [TravisCI Xenial](https://docs.travis-ci.com/user/reference/xenial/#compilers-and-build-toolchain) | 3.12.4 | Mid November 2018 this image became ready for widescale use. |
| [TravisCI Bionic](https://docs.travis-ci.com/user/reference/bionic/#compilers-and-build-toolchain) | 3.12.4 | Same as Xenial at the moment. |
| [Azure DevOps](https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/hosted?view=azure-devops#use-a-microsoft-hosted-agent) | 3.30.0 | kept up to date |
| [GitHub Actions 20.04](https://github.com/actions/virtual-environments/blob/main/images/linux/Ubuntu2004-Readme.md) | 3.30.0 | Same runners as Azure DevOps |
@ -142,9 +137,9 @@ If you are using GitHub Actions, also see the [jwlawson/actions-setup-cmake](htt
### Full list
Versions less than 3.10 are marked by a deeper color of red.
Versions less than 3.15 are marked by a deeper color of red.
[![Full listing](https://repology.org/badge/vertical-allrepos/cmake.svg?columns=3&minversion=3.10.0)][repology]
[![Full listing](https://repology.org/badge/vertical-allrepos/cmake.svg?columns=3&minversion=3.15.0)][repology]
Also see [pkgs.org/download/cmake](https://pkgs.org/download/cmake).

4
chapters/intro/newcmake.md
View File

@ -108,7 +108,7 @@ of CMake introduced a few releases ago are now usable in `find_` commands with
- C++26 support
- LTO for CUDA with nvcc
- Workflow presets added, package presets too.
- `SYSTEM` added to `add_subdirectory`, `FetchContent`, and as a directory property
- `SYSTEM` added to `add_subdirectory`, `FetchContent`, and as a directory property.
- `block()`/`endblock()` for policy/variable scopes, also `PROPOGATE` in `return()`
- `BSD` & `LINUX` variables added
- `VALIDATOR` function for `find_*` commands.
@ -153,7 +153,7 @@ couple of compilers were added.
- A couple of new supported compilers, and better C# support.
- `FILE_SET` for `install` and `target_sources` header-only source files.
- `<INTERFACE_>HEADER_SETS`, `<INTERFACE_>HEADER_DIRS` for target headers.
- `CUDA_ARCHITECTURES` support for all and all-major.a
- `CUDA_ARCHITECTURES` support for all and all-major.
- DEBUG messages from can be enabled for `find_*` or find modules.
- `define_property()` has a handy `INITIALIZE_FROM_VARIABLE` option.
- `CMAKE_<SYSTEM_>IGNORE_PREFIX_PATH` to control `find_*` commands.

2
chapters/testing/googletest.md
View File

@ -97,7 +97,7 @@ You can use the downloader in my [CMake helper repository][cliutils/cmake], usin
This is a downloader for [GoogleTest], based on the excellent [DownloadProject] tool. Downloading a copy for each project is the recommended way to use GoogleTest (so much so, in fact, that they have disabled the automatic CMake install target), so this respects that design decision. This method downloads the project at configure time, so that IDEs correctly find the libraries. Using it is simple:
```cmake
cmake_minimum_required(VERSION 3.10)
cmake_minimum_required(VERSION 3.15)
project(MyProject CXX)
list(APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake)

2
examples/CMakeLists.txt
View File

@ -1,4 +1,4 @@
cmake_minimum_required(VERSION 3.11...3.30)
cmake_minimum_required(VERSION 3.15...3.30)
project(ModernCMakeExamples)
set(MODERN_CMAKE_BUILD_TESTING ON)

4
examples/extended-project/CMakeLists.txt
View File

@ -1,5 +1,5 @@
# Works with 3.14 and tested through 3.30
cmake_minimum_required(VERSION 3.14...3.30)
# Works with 3.15 and tested through 3.30
cmake_minimum_required(VERSION 3.15...3.30)
# Project name and a few useful settings. Other commands can pick up the results
project(

2
examples/fetch/CMakeLists.txt
View File

@ -1,4 +1,4 @@
cmake_minimum_required(VERSION 3.14...3.30)
cmake_minimum_required(VERSION 3.15...3.30)
project(FetchExample LANGUAGES CXX)

2
examples/root-dict/CMakeLists.txt
View File

@ -2,7 +2,7 @@
## [main]
cmake_minimum_required(VERSION 3.4...3.30)
cmake_minimum_required(VERSION 3.15...3.30)
project(RootDictExample LANGUAGES CXX)

2
examples/root-simple/CMakeLists.txt
View File

@ -1,7 +1,7 @@
# CMake ROOT simple example
## [main]
cmake_minimum_required(VERSION 3.1...3.30)
cmake_minimum_required(VERSION 3.15...3.30)
project(RootSimpleExample LANGUAGES CXX)

2
examples/root-usefile/CMakeLists.txt
View File

@ -1,7 +1,7 @@
# CMake ROOT usefile example
## [main]
cmake_minimum_required(VERSION 3.1...3.30)
cmake_minimum_required(VERSION 3.15...3.30)
project(RootUseFileExample LANGUAGES CXX)

2
examples/simple-project/CMakeLists.txt
View File

@ -6,7 +6,7 @@
# You should always specify a range with the newest
# and oldest tested versions of CMake. This will ensure
# you pick up the best policies.
cmake_minimum_required(VERSION 3.1...3.30)
cmake_minimum_required(VERSION 3.15...3.30)
# This is your project statement. You should always list languages;
# Listing the version is nice here since it sets lots of useful variables