docs/modern-cmake
docs
/
modern-cmake
mirror of
1
0
Fork 0
Code Issues Releases Wiki Activity

Adding CMake 3.12

This commit is contained in:
Henry Fredrick Schreiner 2018-07-19 11:54:08 +02:00
parent 3d3b8f257a
commit 8fb00b0c8b
6 changed files with 34 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitlab-ci.yml
View File

@ -4,7 +4,7 @@ test_code:
stage: test
before_script:
- mkdir -p $HOME/.local
- curl -s "https://cmake.org/files/v3.11/cmake-3.11.0-Linux-x86_64.tar.gz" | tar --strip-components=1 -xz -C $HOME/.local
- curl -s "https://cmake.org/files/v3.12/cmake-3.12.0-Linux-x86_64.tar.gz" | tar --strip-components=1 -xz -C $HOME/.local
- export PATH=$HOME/.local/bin:$PATH
script:
- mkdir -p build

4
README.md
View File

@ -7,9 +7,9 @@ Certainly there are no shortage of problems when building.
But I think that, in 2018, 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.1+, maybe even CMake 3.11+!
I'm talking about Modern CMake. CMake 3.1+, maybe even CMake 3.12+!
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 significantly faster, as well!
And CMake 3.11+ is supposed to be significantly faster, as well!
{% hint style='working' %}

10
chapters/basics.md
View File

@ -13,13 +13,13 @@ Let's mention a bit of CMake syntax. The command name «command:`cmake_minimum_r
This line is special! [^2] The version of CMake will also dictate the policies, which define behavior changes. So, if you set `minimum_required` to `VERSION 2.8`, you'll get the wrong linking behavior on macOS, for example, even in the 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:policies».
In the upcoming CMake 3.12, this will support a range, such as `VERSION 3.1...3.12`; this means you support as low as 3.1 but have also tested it with the new policy settings up to 3.12. 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.2-3.11 will only set the 3.1 version of the policies in this example). New versions of policies tend to be most important for macOS and Windows users, who also
In CMake 3.12, this will support a range, such as `VERSION 3.1...3.12`; this means you support as low as 3.1 but have also tested it with the new policy settings up to 3.12. 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.2-3.11 will only set the 3.1 version of the policies in this example). 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.1...3.11)
cmake_minimum_required(VERSION 3.1...3.12)
if(${CMAKE_VERSION} VERSION_LESS 3.12)
cmake_policy(VERSION ${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION})
@ -28,15 +28,15 @@ endif()
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 [seems to have a bug](https://github.com/fmtlib/fmt/issues/809) in reading this format, so if you need to support non-command line Windows builds, you will want to do this instead:
WARNING: MSVC's CMake server mode [seems to have a bug](https://github.com/fmtlib/fmt/issues/809) in reading this format, so if you need to support non-command line Windows builds, you will want to do this instead:
```cmake
cmake_minimum_required(VERSION 3.1)
if(${CMAKE_VERSION} VERSION_LESS 3.11)
if(${CMAKE_VERSION} VERSION_LESS 3.12)
cmake_policy(VERSION ${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION})
else()
cmake_policy(VERSION 3.11)
cmake_policy(VERSION 3.12)
endif()
```

8
chapters/intro/dodonot.md
View File

@ -11,10 +11,10 @@ You'll need to pick a minimum required version of CMake. This will affect the CM
| Ubuntu 14.04 LTS | 2.8.12 | Don't use the default on this system. |
| Ubuntu 16.04 LTS | 3.5.1 | |
| Ubuntu 17.10 | 3.9.1 | |
| Ubuntu 18.04 LTS | 3.10.2 | |
| Ubuntu 18.04 LTS | 3.10.2 | An LTS with a pretty decent minimum version! |
| Python PyPI | 3.10 | Just `pip install cmake` on many systems. Add `--user` for local installs. |
| Homebrew on macOS | 3.11 | On macOS with Homebrew, this is only a few minutes behind cmake.org. |
| Chocolaty on Windows | 3.11 | Also up to date. The normal cmake.org installers are common on Windows, as well. |
| Homebrew on macOS | latest | On macOS with Homebrew, this is only a few minutes behind cmake.org. |
| Chocolaty on Windows | latest | Also up to date. The normal cmake.org installers are common on Windows, as well. |
| TravisCI | 3.9 | The December 2017 update added a recent version of clang and CMake! Finally! |
## CMake Antipatterns
@ -23,7 +23,7 @@ The next two lists are heavily based on the excellent gist [Effective Modern CMa
* **Do not use global functions**: This includes `link_directories`, `include_libraries`, and similar.
* **Don't add unneeded PUBLIC requirements**: You should avoid forcing something on users that is not required (`-Wall`). Make these PRIVATE instead.
* **Don't GLOB files**: Make or another tool will not know if you add files without rerunning CMake.
* **Don't GLOB files**: Make or another tool will not know if you add files without rerunning CMake. Note that CMake 3.12 adds a `CONFIGURE_DEPENDS` flag that makes this far better if you need to use it.
* **Link to built files directly**: Always link to targets if available.
* **Never skip PUBLIC/PRIVATE when linking**: This causes all future linking to be keyword-less.

12
chapters/intro/installing.md
View File

@ -4,7 +4,7 @@
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.
{% endhint %}
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 CMake < 3.11 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.1 support. Maybe even if they want CMake < 3.12 support...
## Official package
@ -13,14 +13,14 @@ You can [download CMake from KitWare][cmake-download]. This is how you'll probab
On Linux, there are binaries provided, but you'll need to pick an install location. If you already use `~/.local` for user-space packages, the following single line command[^1] will get CMake for you [^2]:
{% term %}
~ $ wget -qO- "https://cmake.org/files/v3.11/cmake-3.11.1-Linux-x86_64.tar.gz" | tar --strip-components=1 -xz -C ~/.local
~ $ wget -qO- "https://cmake.org/files/v3.12/cmake-3.12.0-Linux-x86_64.tar.gz" | tar --strip-components=1 -xz -C ~/.local
{% endterm %}
If you just want a local folder with CMake only:
{% term %}
~ $ mkdir -p cmake-3.11 && wget -qO- "https://cmake.org/files/v3.11/cmake-3.11.1-Linux-x86_64.tar.gz" | tar --strip-components=1 -xz -C cmake-3.11
~ $ export PATH=`pwd`/cmake-3.11/bin:$PATH
~ $ mkdir -p cmake-3.12 && wget -qO- "https://cmake.org/files/v3.12/cmake-3.12.0-Linux-x86_64.tar.gz" | tar --strip-components=1 -xz -C cmake-3.12
~ $ export PATH=`pwd`/cmake-3.12/bin:$PATH
{% endterm %}
You'll obviously want to append to the PATH every time you start a new terminal, or add it to your `.bashrc` or to an [LMod] system.
@ -28,7 +28,7 @@ You'll obviously want to append to the PATH every time you start a new terminal,
And, if you want a system install, install to `/usr/local`; this is an excellent choice in a Docker container, for example on GitLab CI. Do not try it on a non-containerized system.
{% term %}
docker $ wget -qO- "https://cmake.org/files/v3.11/cmake-3.11.1-Linux-x86_64.tar.gz" | tar --strip-components=1 -xz -C /usr/local
docker $ wget -qO- "https://cmake.org/files/v3.12/cmake-3.12.0-Linux-x86_64.tar.gz" | tar --strip-components=1 -xz -C /usr/local
{% endterm %}
@ -49,7 +49,7 @@ And as long as a binary exists for your system, you'll be up-and-running almost
This has the benefit of respecting your current virtual environment, as well.
{% hint style='info' %}
Personally, on Linux, I put versions of CMake in folders, like `/opt/cmake311` or `~/opt/cmake311`, and then add them to [LMod]. See [`envmodule_setup`][envmodule_setup] for help setting up an LMod system on macOS or Linux. It takes a bit to learn, but is a great way to manage package and compiler versions.
Personally, on Linux, I put versions of CMake in folders, like `/opt/cmake312` or `~/opt/cmake312`, and then add them to [LMod]. See [`envmodule_setup`][envmodule_setup] for help setting up an LMod system on macOS or Linux. It takes a bit to learn, but is a great way to manage package and compiler versions.
[envmodule_setup]: https://github.com/CLIUtils/envmodule_setup
{% endhint %}

22
chapters/intro/newcmake.md
View File

@ -138,18 +138,27 @@ to IMPORTED libraries (the internal `Find*.cmake` scripts should become much cle
* Source file properties have been expanded
* `FetchContent` module now allows downloads to happen at configure time (Wow)
## CMake 3.12 : In progress
## [CMake 3.12] : Version ranges and CONFIGURE_DEPENDS
Potential, possible new features:
Very powerful release, containing lots of smaller long-requested features. One of the smaller
but immediately noticeable changes is the addition of version ranges;
you can now set both the minimum and maximum known CMake version easily. You can also set
`CONFIGURE_DEPENDS` on a `GLOB`ed set of files, and the build system will check those files and
rerun if needed! You can use the general `PackageName_ROOT`
for all `find_package` searches. Lots of additions to strings and lists, module updates,
shiny new Python find module (2 and 3 versions too), and many more.
* Support for OpenMP on macOS
* C++20 support
* Support for `cmake_minimum_required` ranges (backward compatible)
* Support for `-j,--parallel` in `--build` mode (passed on to build tool)
* Support for `$<SHELL:` shell strings (not deduplicated)
* New FindPython module
* `string(JOIN`
* `file(TOUCH`
* `string(JOIN` and `list(JOIN`, and `list(TRANSFORM`
* `file(TOUCH` and `file(GLOB CONFIGURE_DEPENDS`
* C++20 support
* CUDA as a language improvements: CUDA < 7.5 supported
* Support for OpenMP on macOS (command line only)
* Several new properties and property initializers
* CPack finally reads `CMAKE_PROJECT_VERSION` variables
[Releases]: https://cmake.org/cmake/help/latest/release/index.html
@ -165,4 +174,5 @@ Potential, possible new features:
[CMake 3.9]: https://cmake.org/cmake/help/latest/release/3.9.html
[CMake 3.10]: https://cmake.org/cmake/help/latest/release/3.10.html
[CMake 3.11]: https://cmake.org/cmake/help/latest/release/3.11.html
[CMake 3.12]: https://cmake.org/cmake/help/latest/release/3.12.html
[fastercmake]: https://blog.kitware.com/improving-cmakes-runtime-performance/