Adding several more chapters, and placeholders.
This commit is contained in:
Henry Fredrick Schreiner
parent
6fda3e2328
commit
ebc704f4c9
12
SUMMARY.md
12
SUMMARY.md
|
|
@ -6,26 +6,28 @@
|
|||
* [What's new in CMake](chapters/intro/newcmake.md)
|
||||
* [Introduction to the Basics](chapters/basics.md)
|
||||
* [Variables and the Cache](chapters/basics/variables.md)
|
||||
* [Programming in CMake (X)](chapters/basics/functions.md)
|
||||
* [Communicating with your code (X)](chapters/basics/comms.md)
|
||||
* [How to Structure Your Project](chapters/basics/structure.md)
|
||||
* [Running Other Programs (X)](chapters/basics/programs.md)
|
||||
* [Adding Features](chapters/features.md)
|
||||
* [C++11 and Beyond](chapters/features/cpp11.md)
|
||||
* [Small but common needs](chapters/features/small.md)
|
||||
* [Tidy and Format (X)](chapters/features/tidy.md)
|
||||
* [IDEs (X)](chapters/features/IDEs.md)
|
||||
* [Utilities](chapters/features/utilities.md)
|
||||
* [IDEs](chapters/features/ides.md)
|
||||
* [Debugging (X)](chapters/features/debug.md)
|
||||
* [Including Projects](chapters/projects.md)
|
||||
* [Submodule](chapters/projects/submodule.md)
|
||||
* [DownloadProject](chapters/projects/download.md)
|
||||
* [Fetch (3.11)](chapters/projects/fetch.md)
|
||||
* [Fetch (CMake 3.11)](chapters/projects/fetch.md)
|
||||
* [Testing](chapters/testing.md)
|
||||
* [GoogleTest](chapters/testing/googletest.md)
|
||||
* [Catch](chapters/testing/catch.md)
|
||||
* [Catch (X)](chapters/testing/catch.md)
|
||||
* [Exporting and Installing](chapters/exporting.md)
|
||||
* [Looking for libraries](chapters/packages.md)
|
||||
* [CUDA](chapters/packages/CUDA.md)
|
||||
* [OpenMP](chapters/packages/OpenMP.md)
|
||||
* [Boost (X)](chapters/packages/Boost.md)
|
||||
* [Boost](chapters/packages/Boost.md)
|
||||
* [MPI](chapters/packages/MPI.md)
|
||||
* [ROOT](chapters/packages/ROOT.md)
|
||||
* [Simple Example](examples/root-simple/README.md)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,9 @@
|
|||
# Communication with your code
|
||||
|
||||
## TODO: Configure File
|
||||
|
||||
## TODO: Reading files
|
||||
|
||||
{% hint style='working' %}
|
||||
This document is a work in progress. You can raise an issue or put in a merge request on [GitLab](https://gitlab.com/CLIUtils/modern-cmake).
|
||||
{% endhint %}
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
# Programming in CMake
|
||||
|
||||
## TODO: Control flow
|
||||
|
||||
## TODO: Generator expressions
|
||||
|
||||
## TODO: Macros
|
||||
|
||||
## TODO: Functions
|
||||
|
||||
## TODO: Arguments
|
||||
|
||||
|
||||
{% hint style='working' %}
|
||||
This document is a work in progress. You can raise an issue or put in a merge request on [GitLab](https://gitlab.com/CLIUtils/modern-cmake).
|
||||
{% endhint %}
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
# Running other programs
|
||||
|
||||
## TODO: Running a command at configure time
|
||||
|
||||
## TODO: Running a command at build time
|
||||
|
||||
## TODO: Included common utilities
|
||||
|
||||
(Like `cmake -E`)
|
||||
|
||||
{% hint style='working' %}
|
||||
This document is a work in progress. You can raise an issue or put in a merge request on [GitLab](https://gitlab.com/CLIUtils/modern-cmake).
|
||||
{% endhint %}
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
# Debugger support
|
||||
|
||||
|
||||
{% hint style='working' %}
|
||||
This document is a work in progress. You can raise an issue or put in a merge request on [GitLab](https://gitlab.com/CLIUtils/modern-cmake).
|
||||
{% endhint %}
|
||||
|
|
@ -0,0 +1,27 @@
|
|||
# Supporting IDEs
|
||||
|
||||
In general, IDEs are already supported by a standard CMake project. There are just a few extra things that can help IDEs perform even better.
|
||||
|
||||
## Folders
|
||||
|
||||
Some IDEs, like Xcode, support folders. You have to manually enable the `USE_FOLDERS` global property to allow CMake to organize your files by folders:
|
||||
|
||||
```cmake
|
||||
set_property(GLOBAL PROPERTY USE_FOLDERS ON)
|
||||
```
|
||||
|
||||
Then, you can add targets to folders when after you create them:
|
||||
|
||||
```cmake
|
||||
set_property(TARGET MyFile PROPERTY FOLDER "Scripts")
|
||||
```
|
||||
|
||||
Folders can be nested with `/`. You can control how files show up in each folder with regular expressions or explicit listings in [`source_group`](https://cmake.org/cmake/help/latest/command/source_group.html):
|
||||
|
||||
```
|
||||
source_group("Source Files" REGULAR_EXPRESSION ".*\\.c[ucp]p?")
|
||||
```
|
||||
|
||||
## Running with an IDE
|
||||
|
||||
To use an IDE, either pass `-G"name of IDE" if CMake can produce that IDE's files (like Xcode, Visual Studio), or open the CMakeLists.txt file from your IDE if that IDE has built in support for CMake (CLion, QtCreator, many others).
|
||||
|
|
@ -0,0 +1,69 @@
|
|||
# CCache and Utilities
|
||||
|
||||
Over the versions, common utilities that help you write good code have had support added to CMake. This is usually in the form of a property and matching `CMAKE_*` initialization variable. The feature is not meant to be tied to one special program, but rather any program that is somewhat similar in behavior.
|
||||
|
||||
All of these take `;` separated values (a standard list in CMake) that describe the program and options that you should run on the source files of this target.
|
||||
|
||||
## CCache
|
||||
|
||||
Set the `CMAKE_<LANG>_COMPILER_LAUNCHER` variable or the `<LANG>_COMPILER_LAUNCHER` property on a target to use something like CCache to "wrap" the compilation of the target. Support for CCache has been expanding in the latest versions of CMake. In practice, this tends to look like this:
|
||||
|
||||
|
||||
```cmake
|
||||
find_program(CCACHE_PROGRAM ccache)
|
||||
if(CCACHE_PROGRAM)
|
||||
set(CMAKE_CXX_COMPILER_LAUNCHER "${CCACHE_PROGRAM}")
|
||||
set(CMAKE_CUDA_COMPILER_LAUNCHER "${CCACHE_PROGRAM}") # CMake 3.9+
|
||||
endif()
|
||||
```
|
||||
|
||||
|
||||
## Utilities
|
||||
|
||||
Set the following properties or `CMAKE_*` initializer variables to the command line for the tools. Most of them are limited to C or CXX with make or ninja generators.
|
||||
|
||||
* `<LANG>_CLANG_TIDY`: CMake 3.6+
|
||||
* `<LANG>_CPPCHECK`
|
||||
* `<LANG>_CPPLINT`
|
||||
* `<LANG>_INCLUDE_WHAT_YOU_USE`
|
||||
|
||||
Here is a simple example of using Clang-Tidy:
|
||||
|
||||
```cmake
|
||||
if(CMAKE_VERSION VERSION_GREATER 3.6)
|
||||
# Add clang-tidy if available
|
||||
option(CLANG_TIDY_FIX "Perform fixes for Clang-Tidy" OFF)
|
||||
find_program(
|
||||
CLANG_TIDY_EXE
|
||||
NAMES "clang-tidy"
|
||||
DOC "Path to clang-tidy executable"
|
||||
)
|
||||
|
||||
if(CLANG_TIDY_EXE)
|
||||
if(CLANG_TIDY_FIX)
|
||||
set(CMAKE_CXX_CLANG_TIDY "${CLANG_TIDY_EXE}" "-fix")
|
||||
else()
|
||||
set(CMAKE_CXX_CLANG_TIDY "${CLANG_TIDY_EXE}")
|
||||
endif()
|
||||
endif()
|
||||
endif()
|
||||
```
|
||||
|
||||
The `-fix` part is optional, and will modify your source files to try to fix the tidy warning issued. If you are working in a git repository, this is fairly safe as you can see what has changed. However, make sure you **do not run your makefile/ninja build in parallel**! This will not work very well at all if it tries to fix the same header twice.
|
||||
|
||||
If you want to explicitly use the target form to ensure you only call this on your local targets, you can set a variable (I usually chose `DO_CLANG_TIDY`) instead of the `CMAKE_CXX_CLANG_TIDY` variable, then add it to your target properties as you create them.
|
||||
|
||||
## Link what you use
|
||||
|
||||
There is a boolean target property, `LINK_WHAT_YOU_USE`, that will check for extraneous files when linking.
|
||||
|
||||
## Clang-format
|
||||
|
||||
Clang-format doesn't really have an integration with CMake, unfortunately. You could make a custom target (See [this post](https://arcanis.me/en/2015/10/17/cppcheck-and-clang-format), or you can run it manually. An interesting project that I have not really tried is [here](https://github.com/kbenzie/git-cmake-format); it adds a format target and even makes sure that you can't commit unformatted files.
|
||||
|
||||
The following two line would do that in a git repository in bash (assuming you have a `.clang-format` file):
|
||||
|
||||
```bash
|
||||
git ls-files -- '*.cpp' '*.h' | xargs clang-format -i -style=file
|
||||
git diff --exit-code --color
|
||||
```
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
# Boost library
|
||||
|
||||
The Boost library is included in the find packages that CMake provides, but it has a couple of oddities in how it works. See [FindBoost] for a full description; this will just give a quick overview and provide a recipe. Be sure to check the page for the minimum required version of CMake you are using and see what options you have.
|
||||
|
||||
First, you can customize the behavior of the Boost libraries selected using a set of variables that you set before searching for Boost. There are a growing number of settings, but here are the three most common ones:
|
||||
|
||||
```cmake
|
||||
set(Boost_USE_STATIC_LIBS OFF)
|
||||
set(Boost_USE_MULTITHREADED ON)
|
||||
set(Boost_USE_STATIC_RUNTIME OFF)
|
||||
```
|
||||
|
||||
In CMake 3.5, imported targets were added. These targets handle dependencies for you as well, so they are a very nice way to add Boost libraries. However, CMake has the dependency information baked into it for all known versions of Boost, so CMake must be newer than Boost for these to work. In a recent [merge request][MROldBoost], CMake started assuming that the dependencies hold from the last version it knows about, and will use that (along with giving a warning). This
|
||||
functionality was backported into CMake 3.9.
|
||||
|
||||
The import targets are in the `Boost::` namespace. `Boost::boost` is the header only part. The other compiled libraries are available, and include dependencies as needed.
|
||||
|
||||
Here is an example for using the `Boost::filesystem` library:
|
||||
|
||||
```cmake
|
||||
set(Boost_USE_STATIC_LIBS OFF)
|
||||
set(Boost_USE_MULTITHREADED ON)
|
||||
set(Boost_USE_STATIC_RUNTIME OFF)
|
||||
find_package(Boost 1.50 REQUIRED COMPONENTS filesystem)
|
||||
message(STATUS "Boost version: ${Boost_VERSION}")
|
||||
|
||||
# This is needed if your Boost version is newer than your CMake version
|
||||
# or if you have an old version of CMake (<3.5)
|
||||
if(NOT TARGET Boost::filesystem)
|
||||
add_library(Boost::filesystem IMPORTED INTERFACE)
|
||||
set_property(TARGET Boost::filesystem PROPERTY
|
||||
INTERFACE_INCLUDE_DIRECTORIES ${Boost_INCLUDE_DIR})
|
||||
set_property(TARGET Boost::filesystem PROPERTY
|
||||
INTERFACE_LINK_LIBRARIES ${Boost_LIBRARIES})
|
||||
endif()
|
||||
|
||||
target_link_libraries(MyExeOrLibrary PUBLIC Boost::filesystem)
|
||||
```
|
||||
|
||||
|
||||
|
||||
[FindBoost]: https://cmake.org/cmake/help/v3.11/module/FindBoost.html
|
||||
[MROldBoost]: https://gitlab.kitware.com/cmake/cmake/merge_requests/1172
|
||||
Loading…
Reference in New Issue