diff --git a/SUMMARY.md b/SUMMARY.md index ad549fe..3bc5989 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,18 +1,19 @@ # Summary * [An Introduction to Modern CMake](README.md) - * [Installing CMake](chapters/installing.md) - * [Running CMake](chapters/running.md) - * [What's new in CMake](chapters/newcmake.md) + * [Installing CMake](chapters/intro/installing.md) + * [Running CMake](chapters/intro/running.md) + * [What's new in CMake](chapters/intro/newcmake.md) * [Introduction to the Basics](chapters/basics.md) * [Variables and the Cache](chapters/basics/variables.md) - * [How to Structure Your Project](chapters/structure.md) - * [Running Other Programs (X)](chapters/programs.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/cpp11.md) - * [Tidy and Format (X)](chapters/tidy.md) - * [IDEs (X)](chapters/IDEs.md) - * [Debugging (X)](chapters/debug.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) + * [Debugging (X)](chapters/features/debug.md) * [Including Projects](chapters/projects.md) * [Submodule](chapters/projects/submodule.md) * [DownloadProject](chapters/projects/download.md) @@ -21,13 +22,12 @@ * [GoogleTest](chapters/testing/googletest.md) * [Catch](chapters/testing/catch.md) * [Exporting and Installing](chapters/exporting.md) -* [Built-in package discovery](chapters/builtin.md) - * [CUDA](specifics/CUDA.md) - * [OpenMP](specifics/OpenMP.md) - * [Boost (X)](specifics/Boost.md) - * [MPI](specifics/MPI.md) -* [Other common packages](chapters/external.md) - * [ROOT](specifics/ROOT.md) +* [Looking for libraries](chapters/packages.md) + * [CUDA](chapters/packages/CUDA.md) + * [OpenMP](chapters/packages/OpenMP.md) + * [Boost (X)](chapters/packages/Boost.md) + * [MPI](chapters/packages/MPI.md) + * [ROOT](chapters/packages/ROOT.md) * [Simple Example](examples/root-simple/README.md) * [Simple Example CMake 3.11+](examples/root-simple-3.11/README.md) * [Dictionary Example](examples/root-dict/README.md) diff --git a/chapters/structure.md b/chapters/basics/structure.md similarity index 100% rename from chapters/structure.md rename to chapters/basics/structure.md diff --git a/chapters/external.md b/chapters/external.md deleted file mode 100644 index 91ebb05..0000000 --- a/chapters/external.md +++ /dev/null @@ -1,3 +0,0 @@ -# Finding Package - -There are two ways to find packages in CMake. diff --git a/chapters/features.md b/chapters/features.md index 084cf06..4390f51 100644 --- a/chapters/features.md +++ b/chapters/features.md @@ -1,50 +1,3 @@ -# Adding Features +# Adding features -There are lots of compiler and linker settings. When you need to add something special, you could check first to see if CMake supports it; if it does, you can avoid explicitly tying yourself to a compiler version. And, better yet, you explain what you mean in your CMakeLists, rather than spewing flags. - -The first and most common feature was C++ standards support, which got it's own chapter. - -## Platform independent code - -[This](https://cmake.org/cmake/help/v3.9/variable/CMAKE_POSITION_INDEPENDENT_CODE.html) is best known as the `-fPIC` flag. Much of the time, you don't need to do anything. CMake will include the flag for `SHARED` or `MODULE` libraries. If you do explicitly need it: - -```cmake -set(CMAKE_POSITION_INDEPENDENT_CODE ON) -``` - -will do it globally, or: - -```cmake -set_target_properties(lib1 PROPERTIES POSITION_INDEPENDENT_CODE ON) -``` - -to explicitly turn it `ON` (or `OFF`) for a target. - -## Little libraries - -If you need to link to the `dl` library, with `-ldl` on Linux, just use the built-in CMake variable [`${CMAKE_DL_LIBS}`](https://cmake.org/cmake/help/v3.9/variable/CMAKE_DL_LIBS.html) in a `target_link_libraries` command. No module or `find_package` needed. (This adds whatever is needed to get `dlopen` and `dlclose`) - -Unfortunately, the math library is not so lucky. If you need to explicitly link to it, you can always do `target_link_libraries(MyTarget PUBLIC m)`, but it might be better to use CMake's generic [`find_library`](https://cmake.org/cmake/help/v3.9/command/find_library.html): - -```cmake -find_library(MATH_LIBRARY m) -if(MATH_LIBRARY) - target_link_libraries(MyTarget PUBLIC ${MATH_LIBRARY}) -endif() -``` - -You can pretty easily find `Find*.cmake`'s for this and other libraries that you need with a quick search; most major packages have a helper library of CMake modules. See the chapter on existing package inclusion for more. - - - -## Interprocedural optimization - -[This](https://cmake.org/cmake/help/v3.9/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.html) is available on very recent versions of CMake. You can turn this on with `CMAKE_INTERPROCEDURAL_OPTIMIZATION` (CMake 3.9 only) or the `INTERPROCEDURAL_OPTIMIZATION` property on targets. Support for GCC and Clang was added in CMake 3.8. In `cmake_minimum_required(VERSION 3.9)`, setting this to `ON` on a target is an error if the compiler doesn't support it. You can use [`check_ipo_supported()`](https://cmake.org/cmake/help/v3.9/module/CheckIPOSupported.html), from the built-in `CheckIPOSupported` module, to see if support is available before hand. An example of 3.9 style usage: - -```cmake -include(CheckIPOSupported) -check_ipo_supported(RESULT result) -if(result) - set_target_properties(foo PROPERTIES INTERPROCEDURAL_OPTIMIZATION TRUE) -endif() -``` +This section covers adding common features to your CMake project. You'll learn how to add a variety of options commonly needed in C++ projects, like C++11 support, as well as how to support IDEs and more. diff --git a/chapters/cpp11.md b/chapters/features/cpp11.md similarity index 100% rename from chapters/cpp11.md rename to chapters/features/cpp11.md diff --git a/chapters/features/small.md b/chapters/features/small.md new file mode 100644 index 0000000..084cf06 --- /dev/null +++ b/chapters/features/small.md @@ -0,0 +1,50 @@ +# Adding Features + +There are lots of compiler and linker settings. When you need to add something special, you could check first to see if CMake supports it; if it does, you can avoid explicitly tying yourself to a compiler version. And, better yet, you explain what you mean in your CMakeLists, rather than spewing flags. + +The first and most common feature was C++ standards support, which got it's own chapter. + +## Platform independent code + +[This](https://cmake.org/cmake/help/v3.9/variable/CMAKE_POSITION_INDEPENDENT_CODE.html) is best known as the `-fPIC` flag. Much of the time, you don't need to do anything. CMake will include the flag for `SHARED` or `MODULE` libraries. If you do explicitly need it: + +```cmake +set(CMAKE_POSITION_INDEPENDENT_CODE ON) +``` + +will do it globally, or: + +```cmake +set_target_properties(lib1 PROPERTIES POSITION_INDEPENDENT_CODE ON) +``` + +to explicitly turn it `ON` (or `OFF`) for a target. + +## Little libraries + +If you need to link to the `dl` library, with `-ldl` on Linux, just use the built-in CMake variable [`${CMAKE_DL_LIBS}`](https://cmake.org/cmake/help/v3.9/variable/CMAKE_DL_LIBS.html) in a `target_link_libraries` command. No module or `find_package` needed. (This adds whatever is needed to get `dlopen` and `dlclose`) + +Unfortunately, the math library is not so lucky. If you need to explicitly link to it, you can always do `target_link_libraries(MyTarget PUBLIC m)`, but it might be better to use CMake's generic [`find_library`](https://cmake.org/cmake/help/v3.9/command/find_library.html): + +```cmake +find_library(MATH_LIBRARY m) +if(MATH_LIBRARY) + target_link_libraries(MyTarget PUBLIC ${MATH_LIBRARY}) +endif() +``` + +You can pretty easily find `Find*.cmake`'s for this and other libraries that you need with a quick search; most major packages have a helper library of CMake modules. See the chapter on existing package inclusion for more. + + + +## Interprocedural optimization + +[This](https://cmake.org/cmake/help/v3.9/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.html) is available on very recent versions of CMake. You can turn this on with `CMAKE_INTERPROCEDURAL_OPTIMIZATION` (CMake 3.9 only) or the `INTERPROCEDURAL_OPTIMIZATION` property on targets. Support for GCC and Clang was added in CMake 3.8. In `cmake_minimum_required(VERSION 3.9)`, setting this to `ON` on a target is an error if the compiler doesn't support it. You can use [`check_ipo_supported()`](https://cmake.org/cmake/help/v3.9/module/CheckIPOSupported.html), from the built-in `CheckIPOSupported` module, to see if support is available before hand. An example of 3.9 style usage: + +```cmake +include(CheckIPOSupported) +check_ipo_supported(RESULT result) +if(result) + set_target_properties(foo PROPERTIES INTERPROCEDURAL_OPTIMIZATION TRUE) +endif() +``` diff --git a/chapters/installing.md b/chapters/intro/installing.md similarity index 100% rename from chapters/installing.md rename to chapters/intro/installing.md diff --git a/chapters/newcmake.md b/chapters/intro/newcmake.md similarity index 100% rename from chapters/newcmake.md rename to chapters/intro/newcmake.md diff --git a/chapters/running.md b/chapters/intro/running.md similarity index 100% rename from chapters/running.md rename to chapters/intro/running.md diff --git a/chapters/builtin.md b/chapters/packages.md similarity index 100% rename from chapters/builtin.md rename to chapters/packages.md diff --git a/specifics/CUDA.md b/chapters/packages/CUDA.md similarity index 100% rename from specifics/CUDA.md rename to chapters/packages/CUDA.md diff --git a/specifics/MPI.md b/chapters/packages/MPI.md similarity index 100% rename from specifics/MPI.md rename to chapters/packages/MPI.md diff --git a/specifics/OpenMP.md b/chapters/packages/OpenMP.md similarity index 100% rename from specifics/OpenMP.md rename to chapters/packages/OpenMP.md diff --git a/specifics/ROOT.md b/chapters/packages/ROOT.md similarity index 91% rename from specifics/ROOT.md rename to chapters/packages/ROOT.md index 2773830..16febcf 100644 --- a/specifics/ROOT.md +++ b/chapters/packages/ROOT.md @@ -7,7 +7,7 @@ ROOT is a C++ Toolkit for High Energy Physics. It is huge. There are really a lo ROOT supports config file discovery, so you can just do: -[import:'find_package', lang:'cmake'](../examples/root-simple/CMakeLists.txt) +[import:'find_package', lang:'cmake'](../../examples/root-simple/CMakeLists.txt) to attempt to find ROOT. If you don't have your paths set up, you can pass `-DROOT_DIR=$ROOTSYS/cmake` to find ROOT. (But, really, you should source `thisroot.sh`) @@ -19,18 +19,18 @@ ROOT provides a utility to set up a ROOT project, which you can activate using ` ROOT does not correctly set up it's imported targets. To fix this error, you'll need something like: -[import:'setup_properties', lang:'cmake'](../examples/root-simple/CMakeLists.txt) +[import:'setup_properties', lang:'cmake'](../../examples/root-simple/CMakeLists.txt) In CMake 3.11, you can replace that last function call with: -[import:'modern_fix', lang:'cmake'](../examples/root-simple-3.11/CMakeLists.txt) +[import:'modern_fix', lang:'cmake'](../../examples/root-simple-3.11/CMakeLists.txt) All the ROOT targets will require `ROOT::Core`, so this will be enough regardless of which ROOT targets you need. To link, just pick the libraries you want to use: -[import:'add_and_link', lang:'cmake'](../examples/root-simple/CMakeLists.txt) +[import:'add_and_link', lang:'cmake'](../../examples/root-simple/CMakeLists.txt) ## Dictionary generation