Help: Populate tutorial guide text

Migrate tutorial text from individual `directions.txt` files to the main
tutorial document.  Add some comments to source code to provide anchors
for inclusion.

Help/guide/tutorial/Complete/CMakeLists.txt

@@ -1,20 +1,20 @@
 cmake_minimum_required(VERSION 3.3)
 project(Tutorial)
 
+set(CMAKE_CXX_STANDARD 14)
+
+# set the version number
+set(Tutorial_VERSION_MAJOR 1)
+set(Tutorial_VERSION_MINOR 0)
+
 # control where the static and shared libraries are built so that on windows
 # we don't need to tinker with the path to run the executable
 set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 
-set(CMAKE_CXX_STANDARD 14)
-
 option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
 
-# the version number.
-set(Tutorial_VERSION_MAJOR 1)
-set(Tutorial_VERSION_MINOR 0)
-
 if(APPLE)
   set(CMAKE_INSTALL_RPATH "@executable_path/../lib")
 elseif(UNIX)

Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt

@@ -1,4 +1,3 @@
-
 # add the library that runs
 add_library(MathFunctions MathFunctions.cxx)
 
@@ -62,6 +61,7 @@ target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
 set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0")
 set_property(TARGET MathFunctions PROPERTY SOVERSION "1")
 
+# install rules
 install(TARGETS MathFunctions
         DESTINATION lib
         EXPORT MathFunctionsTargets)

Help/guide/tutorial/Consumer/directions.txt

@@ -1,6 +0,0 @@
-# Import a CMake Project#
-
-This examples shows how a project can find other CMake packages that
-generated Config.cmake files.
-
-It also shows how to state a projects external dependencies when generating a Config.cmake.

Help/guide/tutorial/MultiPackage/directions.txt

@@ -1,34 +0,0 @@
-# Packaging Debug and Release #
-
-By default CMake is model is that a build directory only contains a single
-configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo.
-
-But it is possible to setup CPack to bundle multiple build directories at the same
-time to build a package that contains multiple configurations of the same project.
-
-First we need to ahead and construct a directory called 'multi_config' this
-will contain all the builds that we want to package together.
-
-Second create a 'debug' and 'release' directory underneath 'multi_config'. At
-the end you should have a layout that looks like:
-
-─ multi_config
-    ├── debug
-    └── release
-
-Now we need to setup debug and release builds, which would roughly entail
-the following:
-
-  cd debug
-  cmake -DCMAKE_BUILD_TYPE=Debug ../../MultiPackage/
-  cmake --build .
-  cd ../release
-  cmake -DCMAKE_BUILD_TYPE=Release ../../MultiPackage/
-  cmake --build .
-  cd ..
-
-
-Now that both the debug and release builds are complete we can now use
-the custom MultiCPackConfig to package both builds into a single release.
-
-  cpack --config ../../MultiPackage/MultiCPackConfig.cmake

Help/guide/tutorial/Readme.txt

@@ -1,16 +0,0 @@
-
-Step 0: A Starting Point
-Step 1: Configure a File and C++11 Controls
-Step 2: Adding a Library
-Step 3: Usage Requirements for Library
-Step 4: Installing and Testing
-Step 5: System Introspection
-Step 6: Custom Command and Generated File
-Step 7: Building an Installer
-Step 8: CDash submission
-Step 9: Mixing Static and Shared
-Step 10: Generator Expressions
-Step 11: Adding Export Configuration
-Complete: End result of Step 11
-Consumer: Example of Import Packages
-MultiPackage: How to package Debug and Release versions

Help/guide/tutorial/Step1/directions.txt

@@ -1,95 +0,0 @@
-# Adding a Version Number and Configured Header File #
-
-The first feature we will add is to provide our executable and project with a
-version number. While we could do this exclusively in the source code, using
-CMakeLists provides more flexibility.
-
-To add a version number we modify the CMakeLists file as follows:
-
-  cmake_minimum_required(VERSION 3.3)
-  project(Tutorial)
-
-  # the version number.
-  set(Tutorial_VERSION_MAJOR 1)
-  set(Tutorial_VERSION_MINOR 0)
-
-  # configure a header file to pass some of the CMake settings
-  # to the source code
-  configure_file(
-    "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"
-    "${PROJECT_BINARY_DIR}/TutorialConfig.h"
-    )
-
-  # add the executable
-  add_executable(Tutorial tutorial.cxx)
-
-  # add the binary tree to the search path for include files
-  # so that we will find TutorialConfig.h
-  target_include_directories(Tutorial PUBLIC
-                             "${PROJECT_BINARY_DIR}"
-                             )
-
-
-We then create a TutorialConfig.h.in file in the source tree with the
-following contents:
-
-  // the configured options and settings for Tutorial
-  #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
-  #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
-
-When CMake configures this header file the values for @Tutorial_VERSION_MAJOR@
-and @Tutorial_VERSION_MINOR@ will be replaced by the values from the CMakeLists
-file. Next we modify tutorial.cxx to include the configured header file and to
-make use of the version numbers. The resulting source code is listed below.
-
-  // A simple program that computes the square root of a number
-  #include <cmath>
-  #include <iostream>
-  #include <string>
-  #include <sstream>
-
-  #include "TutorialConfig.h"
-
-  int main (int argc, char *argv[])
-  {
-    if (argc < 2) {
-      std::cout << argv[0] << " Version "
-                << Tutorial_VERSION_MAJOR << "." << Tutorial_VERSION_MINOR
-                << std::endl;
-      std::cout << "Usage: " << argv[0] << " number" << std::endl;
-      return 1;
-    }
-
-    double inputValue = atof(argv[1]);
-
-    double outputValue = sqrt(inputValue);
-    std::cout << "The square root of "
-              << inputValue << " is " << outputValue << std::endl;
-    return 0;
-  }
-
-# Adding C++11 support #
-
-Let's add some C++11 features to our project. We will need to explicitly state
-in the CMake code that it should use the correct flags. The easiest way to
-enable C++11 support for CMake is by using the CMAKE_CXX_STANDARD
-and CMAKE_CXX_STANDARD_REQUIRED variables.
-
-First, replace `atof` with `std::stod` in tutorial.cxx.
-
-Then, add the CMAKE_CXX_STANDARD and CMAKE_CXX_STANDARD_REQUIRED variables to
-the CMakeLists file. The STANADARD value should be set to 11, and REQUIRED
-should be set to True.
-
-
-# Build and Test #
-
-Run cmake or cmake-gui to configure the project and then build it with your
-chosen build tool
-
-cd to the directory where Tutorial was built (likely the make directory or
-a Debug or Release build configuration subdirectory) and run these commands:
-
-  Tutorial 4294967296
-  Tutorial 10
-  Tutorial

Help/guide/tutorial/Step10/CMakeLists.txt

@@ -1,20 +1,20 @@
 cmake_minimum_required(VERSION 3.3)
 project(Tutorial)
 
+set(CMAKE_CXX_STANDARD 14)
+
+# Set the version number
+set(Tutorial_VERSION_MAJOR 1)
+set(Tutorial_VERSION_MINOR 0)
+
 # control where the static and shared libraries are built so that on windows
 # we don't need to tinker with the path to run the executable
 set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 
-set(CMAKE_CXX_STANDARD 14)
-
 option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
 
-# the version number.
-set(Tutorial_VERSION_MAJOR 1)
-set(Tutorial_VERSION_MINOR 0)
-
 # configure a header file to pass the version number only
 configure_file(
   "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"

Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt

@@ -1,4 +1,3 @@
-
 # add the library that runs
 add_library(MathFunctions MathFunctions.cxx)
 
@@ -57,5 +56,6 @@ endif()
 # building on windows
 target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
 
+# install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

Help/guide/tutorial/Step10/directions.txt

@@ -1,38 +0,0 @@
-# Adding Generator Expressions #
-
-Generator expressions are evaluated during build system generation to produce
-information specific to each build configuration.
-
-Generator expressions are allowed in the context of many target properties, such
-as LINK_LIBRARIES, INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and others. They may
-also be used when using commands to populate those properties, such as
-target_link_libraries(), target_include_directories(),
-target_compile_definitions() and others.
-
-Generator expressions may to used to enable conditional linking, conditional
-definitions used when compiling, and conditional include directories and more.
-The conditions may be based on the build configuration, target properties,
-platform information or any other queryable information.
-
-There are different types of generator expressions including Logical,
-Informational, and Output expressions.
-
-Logical expressions are used to create conditional output. The basic expressions
-are the 0 and 1 expressions. A "$<0:...>" results in the empty string, and
-"$<1:...>" results in the content of "...".  They can also be nested.
-For example:
-
-  if(HAVE_LOG AND HAVE_EXP)
-    target_compile_definitions(SqrtLibrary
-                               PRIVATE "HAVE_LOG" "HAVE_EXP")
-  endif()
-
-Can be rewritten with generator expressions:
-
-  target_compile_definitions(SqrtLibrary PRIVATE
-                             "$<$<BOOL:${HAVE_LOG}>:HAVE_LOG>"
-                             "$<$<BOOL:${HAVE_EXP}>:HAVE_EXP>"
-                            )
-
-Note that "${HAVE_LOG}" is evaluated at CMake configure time while
-"$<$<BOOL:${HAVE_LOG}>:HAVE_LOG>" is evaluated at build system generation time.

Help/guide/tutorial/Step10/tutorial.cxx

@@ -9,6 +9,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;

Help/guide/tutorial/Step11/CMakeLists.txt

@@ -1,20 +1,20 @@
 cmake_minimum_required(VERSION 3.3)
 project(Tutorial)
 
+set(CMAKE_CXX_STANDARD 14)
+
+# set the version number
+set(Tutorial_VERSION_MAJOR 1)
+set(Tutorial_VERSION_MINOR 0)
+
 # control where the static and shared libraries are built so that on windows
 # we don't need to tinker with the path to run the executable
 set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 
-set(CMAKE_CXX_STANDARD 14)
-
 option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
 
-# the version number.
-set(Tutorial_VERSION_MAJOR 1)
-set(Tutorial_VERSION_MINOR 0)
-
 # configure a header file to pass the version number only
 configure_file(
   "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"

Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt

@@ -1,4 +1,3 @@
-
 # add the library that runs
 add_library(MathFunctions MathFunctions.cxx)
 
@@ -56,5 +55,6 @@ target_compile_definitions(MathFunctions PRIVATE "$<$<BOOL:${USE_MYMATH}>:USE_MY
 #building on windows
 target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
 
+# install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

Help/guide/tutorial/Step11/directions.txt

@@ -1,104 +0,0 @@
-# Adding Export Configuration #
-
-During Step 4 of the tutorial we added the ability for CMake to install the
-library and headers of the project. During Step 7 we added the ability
-to package up this information so it could be distributed to other people.
-
-The next step is to add the necessary information so that other CMake projects
-can use our project, be it from a build directory, a local install or when
-packaged.
-
-The first step is to update our install(TARGETS) commands to not only specify
-a DESTINATION but also an EXPORT. The EXPORT keyword generates and installs a
-CMake file containing code to import all targets listed in the install command
-from the installation tree. So let's go ahead and explicitly EXPORT the
-MathFunctions library by updating the install command in
-MathFunctions/CMakeLists.txt to look like:
-
-  install(TARGETS MathFunctions DESTINATION lib EXPORT MathFunctionsTargets)
-
-Now that we have MathFunctions being exported, we also need to explicitly install
-the generated MathFunctionsTargets.cmake file. This is done by adding
-the following to the bottom of the top-level CMakeLists.txt:
-
-  # install the configuration targets
-  install(EXPORT MathFunctionsTargets
-    FILE MathFunctionsTargets.cmake
-    DESTINATION lib/cmake/MathFunctions
-  )
-
-At this point you should try and run CMake. If everything is setup properly
-you will see that CMake will generate an error that looks like:
-
-  Target "MathFunctions" INTERFACE_INCLUDE_DIRECTORIES property contains
-  path:
-
-    "/Users/robert/Documents/CMakeClass/Tutorial/Step11/MathFunctions"
-
-  which is prefixed in the source directory.
-
-What CMake is trying to say is that during generating the export information
-it will export a path that is intrinsically tied to the current machine and
-will not be valid on other machines. The solution to this is to update the
-MathFunctions target_include_directories to understand that it needs different
-INTERFACE locations when being used from within the build directory and from an
-install / package. This means converting the target_include_directories
-call for MathFunctions to look like:
-
-  target_include_directories(MathFunctions
-                             INTERFACE
-                              $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
-                              $<INSTALL_INTERFACE:include>
-                             )
-
-Once this has been updated, we can re-run CMake and see verify that it doesn't
-warn anymore.
-
-At this point, we have CMake properly packaging the target information that is
-required but we will still need to generate a MathFunctionsConfig.cmake, so
-that the CMake find_package command can find our project. So let's go ahead and
-add a new file to the top-level of the project called Config.cmake.in with the
-following contents:
-
-  @PACKAGE_INIT@
-
-  include ( "${CMAKE_CURRENT_LIST_DIR}/MathFunctionsTargets.cmake" )
-
-Then, to properly configure and install that file, add the following to the
-bottom of the top-level CMakeLists:
-
-  include(CMakePackageConfigHelpers)
-  # generate the config file that is includes the exports
-  configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in
-    "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake"
-    INSTALL_DESTINATION "lib/cmake/example"
-    NO_SET_AND_CHECK_MACRO
-    NO_CHECK_REQUIRED_COMPONENTS_MACRO
-    )
-  # generate the version file for the config file
-  write_basic_package_version_file(
-    "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake"
-    VERSION "${Tutorial_VERSION_MAJOR}.${Tutorial_VERSION_MINOR}"
-    COMPATIBILITY AnyNewerVersion
-  )
-
-  # install the configuration file
-  install(FILES
-    ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake
-    DESTINATION lib/cmake/MathFunctions
-    )
-
-At this point, we have generated a relocatable CMake Configuration for our project
-that can be used after the project has been installed or packaged. If we want
-our project to also be used from a build directory we only have to add
-the following to the bottom of the top level CMakeLists:
-
-  # generate the export targets for the build tree
-  # needs to be after the install(TARGETS ) command
-  export(EXPORT MathFunctionsTargets
-    FILE "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsTargets.cmake"
-  )
-
-With this export call we now generate a Targets.cmake, allowing the configured
-MathFunctionsConfig.cmake in the build directory to be used by other projects,
-without needing it to be installed.

Help/guide/tutorial/Step11/tutorial.cxx

@@ -9,6 +9,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;

Help/guide/tutorial/Step2/CMakeLists.txt

@@ -2,7 +2,8 @@ cmake_minimum_required(VERSION 3.3)
 project(Tutorial)
 
 set(CMAKE_CXX_STANDARD 14)
-# the version number.
+
+# set the version number
 set(Tutorial_VERSION_MAJOR 1)
 set(Tutorial_VERSION_MINOR 0)
 

Help/guide/tutorial/Step2/directions.txt

@@ -1,101 +0,0 @@
-# Adding a Library #
-
-Now we will add a library to our project. This library will contain our own
-implementation for computing the square root of a number. The executable can
-then use this library instead of the standard square root function provided by
-the compiler.
-
-For this tutorial we will put the library into a subdirectory
-called MathFunctions. It will have the following one line CMakeLists file:
-
-  add_library(MathFunctions mysqrt.cxx)
-
-The source file mysqrt.cxx has one function called mysqrt that provides similar
-functionality to the compiler’s sqrt function. To make use of the new library
-we add an add_subdirectory call in the top-level CMakeLists file so that the
-library will get built. We add the new library to the executable, and add the
-MathFunctions as an include directory so that mqsqrt.h header file can be
-found. The last few lines of the top-level CMakeLists file now look like:
-
-
-  add_subdirectory(MathFunctions)
-
-  #add the executable
-  add_executable(Tutorial tutorial.cxx)
-
-  target_link_libraries(Tutorial ${EXTRA_LIBS})
-
-
-Now let us make the MathFunctions library optional. While for the tutorial
-there really isn’t any need to do so, but with larger projects this is a common
-occurrence. The first step is to add an option to the top-level CMakeLists file.
-
-  option (USE_MYMATH
-          "Use tutorial provided math implementation" ON)
-
-This will show up in CMake GUI and ccmake with a default value of ON that can
-be changed by the user. This setting will be stored so that the user does not
-need to set the value each time they run CMake on this build directory.
-
-The next change is to make building and linking the MathFunctions library
-conditional. To do this we change the top-level CMakeLists file to look like
-the following:
-
-  cmake_minimum_required(VERSION 3.3)
-  project(Tutorial)
-
-  set(CMAKE_CXX_STANDARD 14)
-
-  # the version number.
-  set(Tutorial_VERSION_MAJOR 1)
-  set(Tutorial_VERSION_MINOR 0)
-
-  # configure a header file to pass some of the CMake settings
-  # to the source code
-  configure_file(
-    "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"
-    "${PROJECT_BINARY_DIR}/TutorialConfig.h"
-    )
-
-  # should we use our own math functions
-  option(USE_MYMATH "Use tutorial provided math implementation" ON)
-
-  # add the MathFunctions library?
-  if(USE_MYMATH)
-    add_subdirectory(MathFunctions)
-    list(APPEND EXTRA_LIBS MathFunctions)
-    list(APPEND EXTRA_INCLUDES "${PROJECT_SOURCE_DIR}/MathFunctions")
-  endif(USE_MYMATH)
-
-  # add the executable
-  add_executable(Tutorial tutorial.cxx)
-
-  target_link_libraries(Tutorial ${EXTRA_LIBS})
-
-  # add the binary tree to the search path for include files
-  # so that we will find TutorialConfig.h
-  target_include_directories(Tutorial PUBLIC
-                             "${PROJECT_BINARY_DIR}"
-                             ${EXTRA_INCLUDES}
-                             )
-
-Note the use of the variables EXTRA_LIBS, and EXTRA_INCLUDES to collect
-up any optional libraries to later be linked into the executable. This is a
-classic approach when dealing with many optional components, we will cover the
-modern approach in the next step. For now the corresponding changes to the
-source code are fairly straightforward and leave us with:
-
-  #ifdef USE_MYMATH
-    double outputValue = mysqrt(inputValue);
-  #else
-    double outputValue = sqrt(inputValue);
-  #endif
-
-Since the source code now requires USE_MYMATH we can add it to the
-TutorialConfig.h.in. Simply add the following line:
-  #cmakedefine USE_MYMATH
-
-Run cmake or cmake-gui to configure the project and then build it with your
-chosen build tool and then run the built Tutorial executable.
-
-Which function gives better results, Step1’s sqrt or Step2’s mysqrt?

Help/guide/tutorial/Step2/tutorial.cxx

@@ -8,6 +8,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;

Help/guide/tutorial/Step3/CMakeLists.txt

@@ -6,7 +6,7 @@ set(CMAKE_CXX_STANDARD 14)
 # should we use our own math functions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
-# the version number.
+# set the version number
 set(Tutorial_VERSION_MAJOR 1)
 set(Tutorial_VERSION_MINOR 0)
 

Help/guide/tutorial/Step3/directions.txt

@@ -1,26 +0,0 @@
-# Adding Usage Requirements for Library #
-
-Usage requirements allow for far better control over a library / executable's
-link and include line. While also giving more control over the transitive
-property of targets inside CMake. The primary commands that leverage usage
-requirements are:
-
-  - target_compile_definitions
-  - target_compile_options
-  - target_include_directories
-  - target_link_libraries
-
-First up is MathFunctions. We first state that anybody linking to MathFunctions
-needs to include the current source directory, while MathFunctions itself
-doesn't. So this can become an INTERFACE usage requirement.
-
-Remember INTERFACE means things that consumers require but the producer doesn't.
-
-  target_include_directories(MathFunctions
-            INTERFACE ${CMAKE_CURRENT_SOURCE_DIR})
-
-Now that we've specified usage requirements for MathFunctions we can safely remove
-our uses of the EXTRA_INCLUDES variable.
-
-Run cmake or cmake-gui to configure the project and then build it with your
-chosen build tool.

Help/guide/tutorial/Step3/tutorial.cxx

@@ -5,6 +5,7 @@
 
 #include "TutorialConfig.h"
 
+// should we include the MathFunctions header?
 #ifdef USE_MYMATH
 #  include "MathFunctions.h"
 #endif
@@ -12,6 +13,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -20,6 +22,7 @@ int main(int argc, char* argv[])
 
   double inputValue = std::stod(argv[1]);
 
+  // which square root function should we use?
 #ifdef USE_MYMATH
   double outputValue = mysqrt(inputValue);
 #else

Help/guide/tutorial/Step4/CMakeLists.txt

@@ -6,7 +6,7 @@ set(CMAKE_CXX_STANDARD 14)
 # should we use our own math functions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
-# the version number.
+# set the version number
 set(Tutorial_VERSION_MAJOR 1)
 set(Tutorial_VERSION_MINOR 0)
 

Help/guide/tutorial/Step4/directions.txt

@@ -1,72 +0,0 @@
-# Installing and Testing #
-
-Now we can start adding testing support and install rules to our project.
-
-The install rules are fairly simple; for MathFunctions we install the library
-and header file, for the application we install the executable and configured
-header.
-
-So to MathFunctions/CMakeLists.txt we add:
-
-  install (TARGETS MathFunctions DESTINATION bin)
-  install (FILES MathFunctions.h DESTINATION include)
-
-And the to top-level CMakeLists.txt we add:
-
-  install(TARGETS Tutorial DESTINATION bin)
-  install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h"
-          DESTINATION include
-          )
-
-That is all that is needed to create a basic local install of the tutorial.
-
-Run cmake or cmake-gui to configure the project and then build it with your
-chosen build tool. Then build the “install” target by typing 'make install'
-from the command line or build the INSTALL target from an IDE. This will
-install the appropriate header files, libraries, and executables.
-
-Verify that the installed Tutorial runs. Note: The CMake variable
-CMAKE_INSTALL_PREFIX is used to determine the root of where the files will
-be installed.
-
-Next let's test our application. Adding testing is an easy process. At the
-end of the top-level CMakeLists file we can add a number of basic tests to
-verify that the application is working correctly.
-
-  # enable testing
-  enable_testing()
-
-  # does the application run
-  add_test(NAME Runs COMMAND Tutorial 25)
-
-  # does the usage message work?
-  add_test(NAME Usage COMMAND Tutorial)
-  set_tests_properties(Usage
-    PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number"
-    )
-
-  # define a function to simplify adding tests
-  function(do_test target arg result)
-    add_test(NAME Comp${arg} COMMAND ${target} ${arg})
-    set_tests_properties(Comp${arg}
-      PROPERTIES PASS_REGULAR_EXPRESSION ${result}
-      )
-  endfunction(do_test)
-
-  # do a bunch of result based tests
-  do_test(Tutorial 25 "25 is 5")
-  do_test(Tutorial -25 "-25 is [-nan|nan|0]")
-  do_test(Tutorial 0.0001 "0.0001 is 0.01")
-
-The first test simply verifies that the application runs, does not segfault or
-otherwise crash, and has a zero return value. This is the basic form of a CTest
-test.
-
-The Usage test uses a regular expression to verify that the usage message
-is printed when an incorrect number of arguments are provided.
-
-Lastly, we have a function called do_test that simplifies running the
-application and verifying that the computed square root is correct for given
-input.
-
-To run tests, cd to the binary directory and run “ctest -N” and “ctest -VV”.

Help/guide/tutorial/Step4/tutorial.cxx

@@ -5,6 +5,7 @@
 
 #include "TutorialConfig.h"
 
+// should we include the MathFunctions header?
 #ifdef USE_MYMATH
 #  include "MathFunctions.h"
 #endif
@@ -12,6 +13,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -20,6 +22,7 @@ int main(int argc, char* argv[])
 
   double inputValue = std::stod(argv[1]);
 
+  // which square root function should we use?
 #ifdef USE_MYMATH
   double outputValue = mysqrt(inputValue);
 #else

Help/guide/tutorial/Step5/CMakeLists.txt

@@ -6,7 +6,7 @@ set(CMAKE_CXX_STANDARD 14)
 # should we use our own math functions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
-# the version number.
+# set the version number
 set(Tutorial_VERSION_MAJOR 1)
 set(Tutorial_VERSION_MINOR 0)
 

Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt

@@ -6,5 +6,6 @@ target_include_directories(MathFunctions
           INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
           )
 
+# install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

Help/guide/tutorial/Step5/directions.txt

@@ -1,69 +0,0 @@
-# Adding System Introspection #
-
-Let us consider adding some code to our project that depends on features the
-target platform may not have. For this example, we will add some code that
-depends on whether or not the target platform has the log and exp functions. Of
-course almost every platform has these functions but for this tutorial assume
-that they are not common.
-
-If the platform has log and exp then we will use them to compute the square
-root in the mysqrt function. We first test for the availability of these
-functions using the CheckSymbolExists.cmake macro in the top-level CMakeLists
-file as follows:
-
-  # does this system provide the log and exp functions?
-  include(CheckSymbolExists)
-  set(CMAKE_REQUIRED_LIBRARIES "m")
-  check_symbol_exists(log "math.h" HAVE_LOG)
-  check_symbol_exists(exp "math.h" HAVE_EXP)
-
-Now let's add these defines to TutorialConfig.h.in so that we can use them
-from mysqrt.cxx:
-
-  // does the platform provide exp and log functions?
-  #cmakedefine HAVE_LOG
-  #cmakedefine HAVE_EXP
-
-Modify mysqrt.cxx to include math.h. Next, in the mysqrt function we can
-provide an alternate implementation based on log and exp if they are available
-on the system using the following code:
-
-  // if we have both log and exp then use them
-  #if defined(HAVE_LOG) && defined (HAVE_EXP)
-    double result = exp(log(x)*0.5);
-    std::cout << "Computing sqrt of " << x << " to be " << result << " using log" << std::endl;
-  #else
-    ...
-
-Run cmake or cmake-gui to configure the project and then build it with your
-chosen build tool.
-
-You will notice that even though HAVE_LOG and HAVE_EXP are both defined mysqrt
-isn't using them. We should realize quickly that we have forgotten to include
-TutorialConfig.h in mysqrt.cxx. We will also need to update
-MathFunctions/CMakeLists.txt with where it is located.
-
-So let's go ahead and update MathFunctions/CMakeLists.txt to look like:
-
-  add_library(MathFunctions mysqrt.cxx)
-
-  target_include_directories(MathFunctions
-            INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
-            PRIVATE ${Tutorial_BINARY_DIR}
-            )
-
-  install(TARGETS MathFunctions DESTINATION lib)
-  install(FILES MathFunctions.h DESTINATION include)
-
-Now all we need to do is include TutorialConfig.h in mysqrt.cxx
-
-At this point you should go ahead and build the project again.
-
-Run the built Tutorial executable. Which function gives better results now,
-Step1’s sqrt or Step5’s mysqrt?
-
-Exercise: Why is it important that we configure TutorialConfig.h.in after the
-checks for HAVE_LOG and HAVE_EXP? What would happen if we inverted the two?
-
-Exercise: Is there a better place for us to save the HAVE_LOG and HAVE_EXP
-values other than in TutorialConfig.h?

Help/guide/tutorial/Step5/tutorial.cxx

@@ -5,6 +5,7 @@
 
 #include "TutorialConfig.h"
 
+// should we include the MathFunctions header?
 #ifdef USE_MYMATH
 #  include "MathFunctions.h"
 #endif
@@ -12,6 +13,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -20,6 +22,7 @@ int main(int argc, char* argv[])
 
   double inputValue = std::stod(argv[1]);
 
+  // which square root function should we use?
 #ifdef USE_MYMATH
   double outputValue = mysqrt(inputValue);
 #else

Help/guide/tutorial/Step6/CMakeLists.txt

@@ -3,7 +3,7 @@ project(Tutorial)
 
 set(CMAKE_CXX_STANDARD 14)
 
-# the version number.
+# set the version number
 set(Tutorial_VERSION_MAJOR 1)
 set(Tutorial_VERSION_MINOR 0)
 

Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt

@@ -4,11 +4,11 @@ add_library(MathFunctions mysqrt.cxx)
 # to find MathFunctions.h, while we don't.
 # state that we depend on Tutorial_BINARY_DIR but consumers don't, as the
 # TutorialConfig.h include is an implementation detail
-
 target_include_directories(MathFunctions
           INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
           PRIVATE ${Tutorial_BINARY_DIR}
           )
 
+# install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

Help/guide/tutorial/Step6/directions.txt

@@ -1,104 +0,0 @@
-# Adding a Custom Command and Generated File #
-
-In this section we will show how you can add a generated source file into the
-build process of an application. For this example, we will create a table of
-precomputed square roots as part of the build process, and then compile that
-table into our application.
-
-To accomplish this, we first need a program that will generate the table. In the
-MathFunctions subdirectory a new source file named MakeTable.cxx will do just that.
-
-  // A simple program that builds a sqrt table
-  #include <iostream>
-  #include <fstream>
-  #include <cmath>
-
-  int main (int argc, char *argv[])
-  {
-    // make sure we have enough arguments
-    if (argc < 2) {
-      return 1;
-    }
-
-    std::ofstream fout(argv[1],std::ios_base::out);
-    const bool fileOpen = fout.is_open();
-    if(fileOpen) {
-      fout << "double sqrtTable[] = {" << std::endl;
-      for (int i = 0; i < 10; ++i) {
-        fout << sqrt(static_cast<double>(i)) << "," << std::endl;
-      }
-      // close the table with a zero
-      fout << "0};" << std::endl;
-      fout.close();
-    }
-    return fileOpen ? 0 : 1; // return 0 if wrote the file
-  }
-
-Note that the table is produced as valid C++ code and that the output filename
-is passed in as an argument.
-
-The next step is to add the appropriate commands to MathFunctions’ CMakeLists
-file to build the MakeTable executable and then run it as part of the build
-process. A few commands are needed to accomplish this, as shown below:
-
-  # first we add the executable that generates the table
-  add_executable(MakeTable MakeTable.cxx)
-
-  # add the command to generate the source code
-  add_custom_command(
-    OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h
-    COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h
-    DEPENDS MakeTable
-    )
-
-  # add the main library
-  add_library(MathFunctions
-              mysqrt.cxx
-              ${CMAKE_CURRENT_BINARY_DIR}/Table.h
-              )
-
-  target_include_directories(MathFunctions
-          INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
-          PUBLIC ${Tutorial_BINARY_DIR}
-                 # add the binary tree directory to the search path for include files
-                 ${CMAKE_CURRENT_BINARY_DIR}
-          )
-
-  install(TARGETS MathFunctions DESTINATION lib)
-  install(FILES MathFunctions.h DESTINATION include)
-
-First, the executable for MakeTable is added as any other executable would be
-added. Then we add a custom command that specifies how to produce Table.h by
-running MakeTable. Next we have to let CMake know that mysqrt.cxx depends on
-the generated file Table.h. This is done by adding the generated Table.h to the
-list of sources for the library MathFunctions. We also have to add the current
-binary directory to the list of include directories so that Table.h can be
-found and included by mysqrt.cxx.
-
-Now let's use the generated table. First, modify mysqrt.cxx to include Table.h.
-Next, we can rewrite the mysqrt function to use the table:
-
-  if (x <= 0) {
-    return 0;
-  }
-
-  // use the table to help find an initial value
-  double result = x;
-  if (x >= 1 && x < 10) {
-    result = sqrtTable[static_cast<int>(x)];
-  }
-
-  // do ten iterations
-  for (int i = 0; i < 10; ++i) {
-    if (result <= 0) {
-      result = 0.1;
-    }
-    double delta = x - (result*result);
-    result = result + 0.5*delta/result;
-    std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
-  }
-
-Run cmake or cmake-gui to configure the project and then build it with your
-chosen build tool. When this project is built it will first build the MakeTable
-executable. It will then run MakeTable to produce Table.h. Finally, it will
-compile mysqrt.cxx which includes Table.h to produce the MathFunctions library.

Help/guide/tutorial/Step6/tutorial.cxx

@@ -5,6 +5,7 @@
 
 #include "TutorialConfig.h"
 
+// should we include the MathFunctions header?
 #ifdef USE_MYMATH
 #  include "MathFunctions.h"
 #endif
@@ -12,6 +13,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -20,6 +22,7 @@ int main(int argc, char* argv[])
 
   double inputValue = std::stod(argv[1]);
 
+  // which square root function should we use?
 #ifdef USE_MYMATH
   double outputValue = mysqrt(inputValue);
 #else

Help/guide/tutorial/Step7/CMakeLists.txt

@@ -3,7 +3,7 @@ project(Tutorial)
 
 set(CMAKE_CXX_STANDARD 14)
 
-# the version number.
+# set the version number
 set(Tutorial_VERSION_MAJOR 1)
 set(Tutorial_VERSION_MINOR 0)
 

Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt

@@ -25,5 +25,6 @@ target_include_directories(MathFunctions
                   ${CMAKE_CURRENT_BINARY_DIR}
           )
 
+# install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

Help/guide/tutorial/Step7/directions.txt

@@ -1,40 +0,0 @@
-# Building an Installer #
-
-Next suppose that we want to distribute our project to other people so that they
-can use it. We want to provide both binary and source distributions on a variety
-of platforms. This is a little different from the install we did previously in
-the Installing and Testing section (Step 4), where we were installing the
-binaries that we had built from the source code. In this example we will be
-building installation packages that support binary installations and package
-management features. To accomplish this we will use CPack to create platform
-specific installers. Specifically we need to add a few lines to the bottom of
-our top-level CMakeLists.txt file.
-
-  include(InstallRequiredSystemLibraries)
-  set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
-  set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")
-  set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}")
-  include(CPack)
-
-That is all there is to it. We start by including InstallRequiredSystemLibraries.
-This module will include any runtime libraries that are needed by the project
-for the current platform. Next we set some CPack variables to where we have
-stored the license and version information for this project. The version
-information makes use of the variables we set earlier in this tutorial. Finally
-we include the CPack module which will use these variables and some other
-properties of the system you are on to setup an installer.
-
-The next step is to build the project in the usual manner and then run CPack
-on it. To build a binary distribution you would run:
-
-  cpack
-
-To create a source distribution you would type:
-
-  cpack -C CPackSourceConfig.cmake
-
-Alternatively, run “make package” or right click the Package target and
-“Build Project” from an IDE.
-
-Run the installer executable found  in the binary directory. Then run the
-installed executable and verify that it works.

Help/guide/tutorial/Step7/tutorial.cxx

@@ -5,6 +5,7 @@
 
 #include "TutorialConfig.h"
 
+// should we include the MathFunctions header?
 #ifdef USE_MYMATH
 #  include "MathFunctions.h"
 #endif
@@ -12,6 +13,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -20,6 +22,7 @@ int main(int argc, char* argv[])
 
   double inputValue = std::stod(argv[1]);
 
+  // which square root function should we use?
 #ifdef USE_MYMATH
   double outputValue = mysqrt(inputValue);
 #else

Help/guide/tutorial/Step8/CMakeLists.txt

@@ -3,7 +3,7 @@ project(Tutorial)
 
 set(CMAKE_CXX_STANDARD 14)
 
-# the version number.
+# set the version number
 set(Tutorial_VERSION_MAJOR 1)
 set(Tutorial_VERSION_MINOR 0)
 
@@ -74,6 +74,7 @@ do_test(Tutorial 25 "25 is 5")
 do_test(Tutorial -25 "-25 is [-nan|nan|0]")
 do_test(Tutorial 0.0001 "0.0001 is 0.01")
 
+# setup installer
 include(InstallRequiredSystemLibraries)
 set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
 set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")

Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt

@@ -25,5 +25,6 @@ target_include_directories(MathFunctions
                   ${CMAKE_CURRENT_BINARY_DIR}
           )
 
+# install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

Help/guide/tutorial/Step8/directions.txt

@@ -1,38 +0,0 @@
-# Adding Support for a Dashboard #
-
-Adding support for submitting our test results to a dashboard is very easy. We
-already defined a number of tests for our project in the earlier steps of this
-tutorial. We just have to run those tests and submit them to a dashboard. To
-include support for dashboards we include the CTest module in our top-level
-CMakeLists.txt.
-
-Replace:
-  # enable testing
-  enable_testing()
-
-With:
-  # enable dashboard scripting
-  include(CTest)
-
-The CTest module will automatically call enable_testing(), so
-we can remove it from our CMake files.
-
-We will also need to create a CTestConfig.cmake file where we can specify the
-name of the project and where to submit the dashboard.
-
-  set(CTEST_PROJECT_NAME "CMakeTutorial")
-  set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
-
-  set(CTEST_DROP_METHOD "http")
-  set(CTEST_DROP_SITE "my.cdash.org/")
-  set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial")
-  set(CTEST_DROP_SITE_CDASH TRUE)
-
-CTest will read in this file when it runs. To create a simple dashboard you can
-run cmake or cmake-gui to configure the project, but do not build it yet.
-Instead, change directory to the binary tree, and then run:
- 'ctest [-VV] –D Experimental'. On Windows, build the EXPERIMENTAL target.
-
-Ctest will build and test the project and submit results to the Kitware public
-dashboard. The results of your dashboard will be uploaded to Kitware's public
-dashboard here: https://my.cdash.org/index.php?project=CMakeTutorial.

Help/guide/tutorial/Step8/tutorial.cxx

@@ -5,6 +5,7 @@
 
 #include "TutorialConfig.h"
 
+// should we include the MathFunctions header?
 #ifdef USE_MYMATH
 #  include "MathFunctions.h"
 #endif
@@ -12,6 +13,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -20,6 +22,7 @@ int main(int argc, char* argv[])
 
   double inputValue = std::stod(argv[1]);
 
+  // which square root function should we use?
 #ifdef USE_MYMATH
   double outputValue = mysqrt(inputValue);
 #else

Help/guide/tutorial/Step9/CMakeLists.txt

@@ -3,7 +3,7 @@ project(Tutorial)
 
 set(CMAKE_CXX_STANDARD 14)
 
-# the version number.
+# set the version number
 set(Tutorial_VERSION_MAJOR 1)
 set(Tutorial_VERSION_MINOR 0)
 

Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt

@@ -31,5 +31,6 @@ if(HAVE_LOG AND HAVE_EXP)
                              PRIVATE "HAVE_LOG" "HAVE_EXP")
 endif()
 
+# install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

Help/guide/tutorial/Step9/directions.txt

@@ -1,166 +0,0 @@
-# Mixing Static and Shared #
-
-In this section we will show how by using the BUILD_SHARED_LIBS variable we can
-control the default behavior of add_library, and allow control over how
-libraries without an explicit type ( STATIC/SHARED/MODULE/OBJECT ) are built.
-
-To accomplish this we need to add BUILD_SHARED_LIBS to the top level
-CMakeLists.txt. We use the option command as it allows users to optionally
-select if the value should be On or Off.
-
-Next we are going to refactor MathFunctions to become a real library that
-encapsulates using mysqrt or sqrt, instead of requiring the calling code
-to do this logic. This will also mean that USE_MYMATH will not control building
-MathFuctions, but instead will control the behavior of this library.
-
-The first step is to update the starting section of the top level CMakeLists.txt
-to look like:
-
-  cmake_minimum_required(VERSION 3.3)
-  project(Tutorial)
-
-  # control where the static and shared libraries are built so that on windows
-  # we don't need to tinker with the path to run the executable
-  set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
-  set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
-
-  set(CMAKE_CXX_STANDARD 11)
-  set(CMAKE_CXX_STANDARD_REQUIRED True)
-
-  option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
-
-  # the version number.
-  set(Tutorial_VERSION_MAJOR 1)
-  set(Tutorial_VERSION_MINOR 0)
-
-  # configure a header file to pass the version number only
-  configure_file(
-    "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"
-    "${PROJECT_BINARY_DIR}/TutorialConfig.h"
-    )
-
-  # add the MathFunctions library
-  add_subdirectory(MathFunctions)
-
-  # add the executable
-  add_executable(Tutorial tutorial.cxx)
-  target_link_libraries(Tutorial PUBLIC MathFunctions)
-
-Now that we have made MathFunctions always be used, we will need to update
-the logic of that library. So, in MathFunctions/CMakeLists.txt we need to
-create a SqrtLibrary that will conditionally be built when USE_MYMATH is
-enabled. Now, since this is a tutorial, we are going to explicitly require
-that SqrtLibrary is built statically.
-
-The end result is that MathFunctions/CMakeLists.txt should look like:
-
-  # add the library that runs
-  add_library(MathFunctions MathFunctions.cxx)
-
-  # state that anybody linking to us needs to include the current source dir
-  # to find MathFunctions.h, while we don't.
-  target_include_directories(MathFunctions
-                             INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
-                             )
-
-  # should we use our own math functions
-  option(USE_MYMATH "Use tutorial provided math implementation" ON)
-  if(USE_MYMATH)
-
-    # does this system provide the log and exp functions?
-    include(CheckSymbolExists)
-    set(CMAKE_REQUIRED_LIBRARIES "m")
-    check_symbol_exists(log "math.h" HAVE_LOG)
-    check_symbol_exists(exp "math.h" HAVE_EXP)
-
-    # first we add the executable that generates the table
-    add_executable(MakeTable MakeTable.cxx)
-
-    # add the command to generate the source code
-    add_custom_command(
-      OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h
-      COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h
-      DEPENDS MakeTable
-      )
-
-    # library that just does sqrt
-    add_library(SqrtLibrary STATIC
-                mysqrt.cxx
-                ${CMAKE_CURRENT_BINARY_DIR}/Table.h
-                )
-
-    # state that we depend on our binary dir to find Table.h
-    target_include_directories(SqrtLibrary PRIVATE
-                               ${CMAKE_CURRENT_BINARY_DIR}
-                               )
-
-    target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH")
-    if(HAVE_LOG AND HAVE_EXP)
-      target_compile_definitions(SqrtLibrary
-                                 PRIVATE "HAVE_LOG" "HAVE_EXP")
-    endif()
-
-    target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
-  endif()
-
-  # define the symbol stating we are using the declspec(dllexport) when
-  # building on windows
-  target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
-
-  install(TARGETS MathFunctions DESTINATION lib)
-  install(FILES MathFunctions.h DESTINATION include)
-
-Next, update MathFunctions/mysqrt.cxx to use the mathfunctions and detail namespaces:
-
-  #include <iostream>
-  #include "MathFunctions.h"
-
-  // include the generated table
-  #include "Table.h"
-
-  #include <cmath>
-
-  namespace mathfunctions {
-  namespace detail {
-  // a hack square root calculation using simple operations
-  double mysqrt(double x)
-  {
-    ...
-
-    return result;
-  }
-  }
-  }
-
-We also need to make some changes in tutorial.cxx, so that it no longer uses USE_MYMATH:
-1. Always include MathFunctions.h
-2. Always use mathfunctions::sqrt
-
-Finally, update MathFunctions/MathFunctions.h to use dll export defines:
-
-  #if defined(_WIN32)
-  #if defined(EXPORTING_MYMATH)
-    #define DECLSPEC  __declspec(dllexport)
-  #else
-    #define DECLSPEC  __declspec(dllimport)
-  #endif
-  #else //non windows
-    #define DECLSPEC
-  #endif
-
-  namespace mathfunctions
-  {
-    double DECLSPEC sqrt(double x);
-  }
-
-At this point, if you build everything, you will notice that linking fails
-as we are combining a static library without position enabled code with a
-library that has position enabled code. This solution to this is to explicitly
-set the POSITION_INDEPENDENT_CODE target property of SqrtLibrary to be True no
-matter the build type.
-
-Exercise: We modified MathFunctions.h to use dll export defines. Using CMake
-documentation can you find a helper module to simplify this?
-
-Exercise: Determine what command is enabling PIC for SqrtLibrary.
-What happens if we remove said command?

Help/guide/tutorial/Step9/tutorial.cxx

@@ -6,6 +6,7 @@
 
 #include "TutorialConfig.h"
 
+// should we include the MathFunctions header?
 #ifdef USE_MYMATH
 #  include "MathFunctions.h"
 #endif
@@ -13,6 +14,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -21,6 +23,7 @@ int main(int argc, char* argv[])
 
   double inputValue = std::stod(argv[1]);
 
+  // which square root function should we use?
 #ifdef USE_MYMATH
   double outputValue = mysqrt(inputValue);
 #else

Help/guide/tutorial/index.rst

@@ -1,2 +1,719 @@
 CMake Tutorial
 **************
+
+A Basic Starting Point (Step 1)
+===============================
+
+Adding a Version Number and Configured Header File
+--------------------------------------------------
+
+The first feature we will add is to provide our executable and project with a
+version number. While we could do this exclusively in the source code, using
+CMakeLists provides more flexibility.
+
+To add a version number we modify the CMakeLists file as follows:
+
+.. literalinclude:: Step2/CMakeLists.txt
+  :language: cmake
+  :start-after: # set the version number
+  :end-before: # configure a header file
+
+We then create a ``TutorialConfig.h.in`` file in the source tree with the
+following contents:
+
+.. literalinclude:: Step1/TutorialConfig.h.in
+  :language: cmake
+
+When CMake configures this header file the values for
+``@Tutorial_VERSION_MAJOR@`` and ``@Tutorial_VERSION_MINOR@`` will be
+replaced by the values from the CMakeLists file. Next we modify
+``tutorial.cxx`` to include the configured header file and to make use of the
+version numbers. The updated source code is listed below.
+
+.. literalinclude:: Step2/tutorial.cxx
+  :language: c++
+  :start-after: // report version
+  :end-before: return 1;
+
+
+Specify the C++ Standard
+-------------------------
+
+Next let's add some C++11 features to our project. We will need to explicitly
+state in the CMake code that it should use the correct flags. The easiest way
+to enable C++11 support for CMake is by using the ``CMAKE_CXX_STANDARD``
+variable.
+
+First, replace ``atof`` with ``std::stod`` in ``tutorial.cxx``.
+
+Then, set the ``CMAKE_CXX_STANDARD`` variable in the CMakeLists file.
+
+Which variable can we set in the CMakeLists file to treat the
+``CMAKE_CXX_STANDARD`` value as a requirement?
+
+Build and Test
+--------------
+
+Run **cmake** or **cmake-gui** to configure the project and then build it
+with your chosen build tool.
+
+cd to the directory where Tutorial was built (likely the make directory or
+a Debug or Release build configuration subdirectory) and run these commands:
+
+.. code-block:: console
+
+  Tutorial 4294967296
+  Tutorial 10
+  Tutorial
+
+Adding a Library (Step 2)
+=========================
+
+Now we will add a library to our project. This library will contain our own
+implementation for computing the square root of a number. The executable can
+then use this library instead of the standard square root function provided by
+the compiler.
+
+For this tutorial we will put the library into a subdirectory
+called MathFunctions. It will have the following one line CMakeLists file:
+
+.. literalinclude:: Step2/MathFunctions/CMakeLists.txt
+  :language: cmake
+
+The source file ``mysqrt.cxx`` has one function called ``mysqrt`` that
+provides similar functionality to the compiler’s ``sqrt`` function. To make use
+of the new library we add an ``add_subdirectory`` call in the top-level
+CMakeLists file so that the library will get built. We add the new library to
+the executable, and add MathFunctions as an include directory so that the
+``mqsqrt.h`` header file can be found. The last few lines of the top-level
+CMakeLists file now look like:
+
+.. code-block:: cmake
+
+        # add the MathFunctions library
+        add_subdirectory(MathFunctions)
+
+        # add the executable
+        add_executable(Tutorial tutorial.cxx)
+
+        target_link_libraries(Tutorial MathFunctions)
+
+        # add the binary tree to the search path for include files
+        # so that we will find TutorialConfig.h
+        target_include_directories(Tutorial PUBLIC
+                                  "${PROJECT_BINARY_DIR}"
+                                  "${PROJECT_SOURCE_DIR}/MathFunctions"
+                                  )
+
+Now let us make the MathFunctions library optional. While for the tutorial
+there really isn’t any need to do so, for larger projects this is a common
+occurrence. The first step is to add an option to the top-level CMakeLists
+file.
+
+.. literalinclude:: Step3/CMakeLists.txt
+  :language: cmake
+  :start-after: # should we use our own math functions
+  :end-before: # set the version number
+
+This will show up in the CMake GUI and ccmake with a default value of ON
+that can be changed by the user. This setting will be stored in the cache so
+that the user does not need to set the value each time they run CMake on this
+build directory.
+
+The next change is to make building and linking the MathFunctions library
+conditional. To do this we change the end of the top-level CMakeLists file to
+look like the following:
+
+.. literalinclude:: Step3/CMakeLists.txt
+  :language: cmake
+  :start-after: # add the MathFunctions library?
+
+Note the use of the variables ``EXTRA_LIBS`` and ``EXTRA_INCLUDES`` to collect
+up any optional libraries to later be linked into the executable. This is a
+classic approach when dealing with many optional components, we will cover the
+modern approach in the next step.
+
+The corresponding changes to the source code are fairly straightforward. First,
+include the MathFunctions header if we need it:
+
+.. literalinclude:: Step3/tutorial.cxx
+  :language: c++
+  :start-after: // should we include the MathFunctions header
+  :end-before: int main
+
+Then make which square root function is used dependent on ``USE_MYMATH``:
+
+.. literalinclude:: Step3/tutorial.cxx
+  :language: c++
+  :start-after: // which square root function should we use?
+  :end-before: std::cout << "The square root of
+
+Since the source code now requires ``USE_MYMATH`` we can add it to
+``TutorialConfig.h.in`` with the following line:
+
+.. literalinclude:: Step3/TutorialConfig.h.in
+  :language: c
+  :lines: 4
+
+Run **cmake** or **cmake-gui** to configure the project and then build it
+with your chosen build tool. Then run the built Tutorial executable.
+
+Which function gives better results, Step1’s sqrt or Step2’s mysqrt?
+
+Adding Usage Requirements for Library (Step 3)
+==============================================
+
+Usage requirements allow for far better control over a library or executable's
+link and include line while also giving more control over the transitive
+property of targets inside CMake. The primary commands that leverage usage
+requirements are:
+
+  - ``target_compile_definitions``
+  - ``target_compile_options``
+  - ``target_include_directories``
+  - ``target_link_libraries``
+
+First up is MathFunctions. We first state that anybody linking to MathFunctions
+needs to include the current source directory, while MathFunctions itself
+doesn't. So this can become an ``INTERFACE`` usage requirement.
+
+Remember ``INTERFACE`` means things that consumers require but the producer
+doesn't. Update ``MathFunctions/CMakeLists.txt`` with:
+
+.. literalinclude:: Step4/MathFunctions/CMakeLists.txt
+  :language: cmake
+  :start-after: # to find MathFunctions.h
+
+Now that we've specified usage requirements for MathFunctions we can safely
+remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level
+CMakeLists.
+
+Once this is done, run **cmake** or **cmake-gui** to configure the project
+and then build it with your chosen build tool.
+
+Installing and Testing (Step 4)
+===============================
+
+Now we can start adding install rules and testing support to our project.
+
+Install Rules
+-------------
+
+The install rules are fairly simple for MathFunctions we want to install the
+library and header file and for the application we want to install the
+executable and configured header.
+
+So to ``MathFunctions/CMakeLists.txt`` we add:
+
+.. literalinclude:: Step5/MathFunctions/CMakeLists.txt
+  :language: cmake
+  :start-after: # install rules
+
+And the to top-level ``CMakeLists.txt`` we add:
+
+.. literalinclude:: Step5/CMakeLists.txt
+  :language: cmake
+  :start-after: # add the install targets
+  :end-before: # enable testing
+
+That is all that is needed to create a basic local install of the tutorial.
+
+Run **cmake** or **cmake-gui** to configure the project and then build it
+with your chosen build tool. Build the ``install`` target by typing
+``make install`` from the command line or build the ``INSTALL`` target from
+an IDE. This will install the appropriate header files, libraries, and
+executables.
+
+Verify that the installed Tutorial runs. Note: The CMake variable
+``CMAKE_INSTALL_PREFIX`` is used to determine the root of where the files will
+be installed.
+
+Testing Support
+---------------
+
+Next let's test our application. At the end of the top-level CMakeLists file we
+can add a number of basic tests to verify that the application is
+working correctly.
+
+.. literalinclude:: Step5/CMakeLists.txt
+  :language: cmake
+  :start-after: # enable testing
+
+The first test simply verifies that the application runs, does not segfault or
+otherwise crash, and has a zero return value. This is the basic form of a CTest
+test.
+
+The next test makes use of the ``PASS_REGULAR_EXPRESSION`` test property to
+verify that the output of the test contains certain strings, in this case:
+verifying that the the usage message is printed when an incorrect number of
+arguments are provided.
+
+Lastly, we have a function called ``do_test`` that runs the application and
+verifies that the computed square root is correct for given input. For each
+invocation of ``do_test``, another test is added to the project with a name,
+input, and expected results based on the passed arguments.
+
+Rebuild the application and then cd to the binary directory and run
+``ctest -N`` and ``ctest -VV``.
+
+Adding System Introspection (Step 5)
+====================================
+
+Let us consider adding some code to our project that depends on features the
+target platform may not have. For this example, we will add some code that
+depends on whether or not the target platform has the ``log`` and ``exp``
+functions. Of course almost every platform has these functions but for this
+tutorial assume that they are not common.
+
+If the platform has ``log`` and ``exp`` then we will use them to compute the
+square root in the ``mysqrt`` function. We first test for the availability of
+these functions using the ``CheckSymbolExists.cmake`` macro in the top-level
+CMakeLists file as follows:
+
+.. literalinclude:: Step6/CMakeLists.txt
+  :language: cmake
+  :start-after: # does this system provide the log and exp functions?
+  :end-before: # should we use our own math functions
+
+Now let's add these defines to ``TutorialConfig.h.in`` so that we can use them
+from ``mysqrt.cxx``:
+
+.. literalinclude:: Step6/TutorialConfig.h.in
+  :language: c
+  :start-after: // does the platform provide exp and log functions?
+
+Finally, in the ``mysqrt`` function we can provide an alternate implementation
+based on ``log`` and ``exp`` if they are available on the system using the
+following code:
+
+.. literalinclude:: Step6/MathFunctions/mysqrt.cxx
+  :language: c++
+  :start-after: // if we have both log and exp then use them
+  :end-before: #else
+
+Run **cmake** or **cmake-gui** to configure the project and then build it
+with your chosen build tool.
+
+You will notice that even though ``HAVE_LOG`` and ``HAVE_EXP`` are both
+defined ``mysqrt`` isn't using them. We should realize quickly that we have
+forgotten to include ``TutorialConfig.h`` in ``mysqrt.cxx``.
+
+After making this update, go ahead and build the project again.
+
+Run the built Tutorial executable. Which function gives better results now,
+Step1’s sqrt or Step5’s mysqrt?
+
+**Exercise**: Why is it important that we configure ``TutorialConfig.h.in``
+after the checks for ``HAVE_LOG`` and ``HAVE_EXP``? What would happen if we
+inverted the two?
+
+**Exercise**: Is there a better place for us to save the ``HAVE_LOG`` and
+``HAVE_EXP`` values other than in ``TutorialConfig.h``?
+
+Adding a Custom Command and Generated File (Step 6)
+===================================================
+
+In this section, we will add a generated source file into the build process
+of an application. For this example, we will create a table of precomputed
+square roots as part of the build process, and then compile that
+table into our application.
+
+To accomplish this, we first need a program that will generate the table. In
+the MathFunctions subdirectory a new source file named ``MakeTable.cxx`` will
+do just that.
+
+.. literalinclude:: Step7/MathFunctions/MakeTable.cxx
+  :language: c++
+
+Note that the table is produced as valid C++ code and that the output filename
+is passed in as an argument.
+
+The next step is to add the appropriate commands to MathFunctions' CMakeLists
+file to build the MakeTable executable and then run it as part of the build
+process. A few commands are needed to accomplish this.
+
+First, the executable for ``MakeTable`` is added as any other executable would
+be added.
+
+.. literalinclude:: Step7/MathFunctions/CMakeLists.txt
+  :language: cmake
+  :start-after: # first we add the executable that generates the table
+  :end-before: # add the command to generate the source code
+
+Then we add a custom command that specifies how to produce ``Table.h``
+by running MakeTable.
+
+.. literalinclude:: Step7/MathFunctions/CMakeLists.txt
+  :language: cmake
+  :start-after: # add the command to generate the source code
+  :end-before: # add the main library
+
+Next we have to let CMake know that ``mysqrt.cxx`` depends on the generated
+file ``Table.h``. This is done by adding the generated ``Table.h`` to the list
+of sources for the library MathFunctions.
+
+.. literalinclude:: Step7/MathFunctions/CMakeLists.txt
+  :language: cmake
+  :start-after: # add the main library
+  :end-before: # state that anybody linking
+
+We also have to add the current binary directory to the list of include
+directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``.
+
+.. literalinclude:: Step7/MathFunctions/CMakeLists.txt
+  :start-after: # state that we depend on our bin
+  :end-before: # install rules
+
+Now let's use the generated table. First, modify ``mysqrt.cxx`` to include
+``Table.h``. Next, we can rewrite the mysqrt function to use the table:
+
+.. literalinclude:: Step7/MathFunctions/mysqrt.cxx
+  :language: c++
+  :start-after: // a hack square root calculation using simple operations
+
+Run **cmake** or **cmake-gui** to configure the project and then build it
+with your chosen build tool. When this project is built it will first build
+the ``MakeTable`` executable. It will then run ``MakeTable`` to produce
+``Table.h``. Finally, it will compile ``mysqrt.cxx`` which includes
+``Table.h`` to produce the MathFunctions library.
+
+Building an Installer (Step 7)
+==============================
+
+Next suppose that we want to distribute our project to other people so that
+they can use it. We want to provide both binary and source distributions on a
+variety of platforms. This is a little different from the install we did
+previously in `Installing and Testing (Step 4)`_ , where we were
+installing the binaries that we had built from the source code. In this
+example we will be building installation packages that support binary
+installations and package management features. To accomplish this we will use
+CPack to create platform specific installers. Specifically we need to add
+a few lines to the bottom of our top-level ``CMakeLists.txt`` file.
+
+.. literalinclude:: Step8/CMakeLists.txt
+  :language: cmake
+  :start-after: # setup installer
+
+That is all there is to it. We start by including
+``InstallRequiredSystemLibraries``. This module will include any runtime
+libraries that are needed by the project for the current platform. Next we
+set some CPack variables to where we have stored the license and version
+information for this project. The version information makes use of the
+variables we set earlier in this tutorial. Finally we include the CPack
+module which will use these variables and some other properties of the system
+you are on to setup an installer.
+
+The next step is to build the project in the usual manner and then run
+CPack on it. To build a binary distribution you would run:
+
+.. code-block:: console
+
+  cpack
+
+To create a source distribution you would type:
+
+.. code-block:: console
+
+  cpack -C CPackSourceConfig.cmake
+
+Alternatively, run ``make package`` or right click the ``Package`` target and
+``Build Project`` from an IDE.
+
+Run the installer executable found in the binary directory. Then run the
+installed executable and verify that it works.
+
+Adding Support for a Dashboard (Step 8)
+=======================================
+
+Adding support for submitting our test results to a dashboard is very easy. We
+already defined a number of tests for our project in the earlier steps of this
+tutorial. We just have to run those tests and submit them to a dashboard. To
+include support for dashboards we include the CTest module in our top-level
+``CMakeLists.txt``.
+
+Replace:
+
+.. code-block:: cmake
+
+  # enable testing
+  enable_testing()
+
+With:
+
+.. code-block:: cmake
+
+  # enable dashboard scripting
+  include(CTest)
+
+The CTest module will automatically call ``enable_testing()``, so
+we can remove it from our CMake files.
+
+We will also need to create a ``CTestConfig.cmake`` file where we can specify
+the name of the project and where to submit the dashboard.
+
+.. literalinclude:: Step9/CTestConfig.cmake
+  :language: cmake
+
+CTest will read in this file when it runs. To create a simple dashboard you can
+run **cmake** or **cmake-gui** to configure the project, but do not build it
+yet. Instead, change directory to the binary tree, and then run:
+
+.. code-block:: console
+
+ 'ctest [-VV] –D Experimental'
+
+On Windows, build the EXPERIMENTAL target.
+
+Ctest will build and test the project and submit the results to the Kitware
+public dashboard. The results of your dashboard will be uploaded to Kitware's
+public dashboard here: https://my.cdash.org/index.php?project=CMakeTutorial.
+
+Mixing Static and Shared (Step 9)
+=================================
+
+In this section we will show how by using the ``BUILD_SHARED_LIBS`` variable
+we can control the default behavior of ``add_library``, and allow control
+over how libraries without an explicit type (STATIC/SHARED/MODULE/OBJECT) are
+built.
+
+To accomplish this we need to add ``BUILD_SHARED_LIBS`` to the top-level
+``CMakeLists.txt``. We use the ``option`` command as it allows users to
+optionally select if the value should be On or Off.
+
+Next we are going to refactor MathFunctions to become a real library that
+encapsulates using ``mysqrt`` or ``sqrt``, instead of requiring the calling
+code to do this logic. This will also mean that ``USE_MYMATH`` will not control
+building MathFuctions, but instead will control the behavior of this library.
+
+The first step is to update the starting section of the top-level
+``CMakeLists.txt`` to look like:
+
+.. literalinclude:: Step10/CMakeLists.txt
+  :language: cmake
+  :start-after: set(Tutorial_VERSION_MINOR
+  :end-before: # add the binary tree
+
+Now that we have made MathFunctions always be used, we will need to update
+the logic of that library. So, in ``MathFunctions/CMakeLists.txt`` we need to
+create a SqrtLibrary that will conditionally be built when ``USE_MYMATH`` is
+enabled. Now, since this is a tutorial, we are going to explicitly require
+that SqrtLibrary is built statically.
+
+The end result is that ``MathFunctions/CMakeLists.txt`` should look like:
+
+.. literalinclude:: Step10/MathFunctions/CMakeLists.txt
+  :language: cmake
+  :lines: 1-40,46-
+
+Next, update ``MathFunctions/mysqrt.cxx`` to use the ``mathfunctions`` and
+``detail`` namespaces:
+
+.. literalinclude:: Step10/MathFunctions/mysqrt.cxx
+  :language: c++
+
+We also need to make some changes in ``tutorial.cxx``, so that it no longer
+uses ``USE_MYMATH``:
+
+#. Always include ``MathFunctions.h``
+#. Always use ``mathfunctions::sqrt``
+
+Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines:
+
+.. literalinclude:: Step10/MathFunctions/MathFunctions.h
+  :language: c++
+
+At this point, if you build everything, you will notice that linking fails
+as we are combining a static library without position enabled code with a
+library that has position enabled code. The solution to this is to explicitly
+set the ``POSITION_INDEPENDENT_CODE`` target property of SqrtLibrary to be
+True no matter the build type.
+
+**Exercise**: We modified ``MathFunctions.h`` to use dll export defines.
+Using CMake documentation can you find a helper module to simplify this?
+
+Adding Generator Expressions (Step 10)
+======================================
+
+Generator expressions are evaluated during build system generation to produce
+information specific to each build configuration.
+
+Generator expressions are allowed in the context of many target properties,
+such as ``LINK_LIBRARIES``, ``INCLUDE_DIRECTORIES``, ``COMPILE_DEFINITIONS``
+and others. They may also be used when using commands to populate those
+properties, such as ``target_link_libraries()``,
+``target_include_directories()``,
+``target_compile_definitions()`` and others.
+
+Generator expressions may be used to enable conditional linking, conditional
+definitions used when compiling, conditional include directories and more.
+The conditions may be based on the build configuration, target properties,
+platform information or any other queryable information.
+
+There are different types of generator expressions including Logical,
+Informational, and Output expressions.
+
+Logical expressions are used to create conditional output. The basic
+expressions are the 0 and 1 expressions. A ``$<0:...>`` results in the empty
+string, and ``<1:...>`` results in the content of "...".  They can also be
+nested.
+
+For example:
+
+.. code-block:: cmake
+
+  if(HAVE_LOG AND HAVE_EXP)
+    target_compile_definitions(SqrtLibrary
+                               PRIVATE "HAVE_LOG" "HAVE_EXP")
+  endif()
+
+Can be rewritten with generator expressions:
+
+.. code-block:: cmake
+
+  target_compile_definitions(SqrtLibrary PRIVATE
+                             "$<$<BOOL:${HAVE_LOG}>:HAVE_LOG>"
+                             "$<$<BOOL:${HAVE_EXP}>:HAVE_EXP>"
+                            )
+
+Note that ``${HAVE_LOG}`` is evaluated at CMake configure time while
+``$<$<BOOL:${HAVE_LOG}>:HAVE_LOG>`` is evaluated at build system generation
+time.
+
+Adding Export Configuration (Step 11)
+=====================================
+
+During `Installing and Testing (Step 4)`_ of the tutorial we added the ability
+for CMake to install the library and headers of the project. During
+`Building an Installer (Step 7)`_ we added the ability to package up this
+information so it could be distributed to other people.
+
+The next step is to add the necessary information so that other CMake projects
+can use our project, be it from a build directory, a local install or when
+packaged.
+
+The first step is to update our ``install(TARGETS)`` commands to not only
+specify a ``DESTINATION`` but also an ``EXPORT``. The ``EXPORT`` keyword
+generates and installs a CMake file containing code to import all targets
+listed in the install command from the installation tree. So let's go ahead
+and explicitly ``EXPORT`` the MathFunctions library by updating the
+``install`` command in ``MathFunctions/CMakeLists.txt`` to look like:
+
+.. literalinclude:: Complete/MathFunctions/CMakeLists.txt
+  :language: cmake
+  :start-after: # install rules
+
+Now that we have MathFunctions being exported, we also need to explicitly
+install the generated ``MathFunctionsTargets.cmake`` file. This is done by
+adding the following to the bottom of the top-level ``CMakeLists.txt``:
+
+.. literalinclude:: Complete/CMakeLists.txt
+  :language: cmake
+  :start-after: # install the configuration targets
+  :end-before: include(CMakePackageConfigHelpers)
+
+At this point you should try and run CMake. If everything is setup properly
+you will see that CMake will generate an error that looks like:
+
+.. code-block:: console
+
+  Target "MathFunctions" INTERFACE_INCLUDE_DIRECTORIES property contains
+  path:
+
+    "/Users/robert/Documents/CMakeClass/Tutorial/Step11/MathFunctions"
+
+  which is prefixed in the source directory.
+
+What CMake is trying to say is that during generating the export information
+it will export a path that is intrinsically tied to the current machine and
+will not be valid on other machines. The solution to this is to update the
+MathFunctions ``target_include_directories`` to understand that it needs
+different ``INTERFACE`` locations when being used from within the build
+directory and from an install / package. This means converting the
+``target_include_directories`` call for MathFunctions to look like:
+
+.. literalinclude:: Complete/MathFunctions/CMakeLists.txt
+  :language: cmake
+  :start-after: # to find MathFunctions.h, while we don't.
+  :end-before: # should we use our own math functions
+
+Once this has been updated, we can re-run CMake and see verify that it doesn't
+warn anymore.
+
+At this point, we have CMake properly packaging the target information that is
+required but we will still need to generate a ``MathFunctionsConfig.cmake`` so
+that the CMake ``find_package command`` can find our project. So let's go
+ahead and add a new file to the top-level of the project called
+``Config.cmake.in`` with the following contents:
+
+.. literalinclude:: Complete/Config.cmake.in
+
+Then, to properly configure and install that file, add the following to the
+bottom of the top-level CMakeLists:
+
+.. literalinclude:: Complete/CMakeLists.txt
+  :language: cmake
+  :start-after: # install the configuration targets
+  :end-before: # generate the export
+
+At this point, we have generated a relocatable CMake Configuration for our
+project that can be used after the project has been installed or packaged. If
+we want our project to also be used from a build directory we only have to add
+the following to the bottom of the top level CMakeLists:
+
+.. literalinclude:: Complete/CMakeLists.txt
+  :language: cmake
+  :start-after: # needs to be after the install(TARGETS ) command
+
+With this export call we now generate a ``Targets.cmake``, allowing the
+configured ``MathFunctionsConfig.cmake`` in the build directory to be used by
+other projects, without needing it to be installed.
+
+Import a CMake Project (Consumer)
+=================================
+
+This examples shows how a project can find other CMake packages that
+generate ``Config.cmake`` files.
+
+It also shows how to state a project's external dependencies when generating
+a ``Config.cmake``.
+
+Packaging Debug and Release (MultiPackage)
+==========================================
+
+By default CMake is model is that a build directory only contains a single
+configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo.
+
+But it is possible to setup CPack to bundle multiple build directories at the
+same time to build a package that contains multiple configurations of the
+same project.
+
+First we need to ahead and construct a directory called ``multi_config`` this
+will contain all the builds that we want to package together.
+
+Second create a ``debug`` and ``release`` directory underneath
+``multi_config``. At the end you should have a layout that looks like:
+
+─ multi_config
+    ├── debug
+    └── release
+
+Now we need to setup debug and release builds, which would roughly entail
+the following:
+
+.. code-block:: console
+
+  cd debug
+  cmake -DCMAKE_BUILD_TYPE=Debug ../../MultiPackage/
+  cmake --build .
+  cd ../release
+  cmake -DCMAKE_BUILD_TYPE=Release ../../MultiPackage/
+  cmake --build .
+  cd ..
+
+
+Now that both the debug and release builds are complete we can now use
+the custom MultiCPackConfig to package both builds into a single release.
+
+.. code-block:: console
+
+  cpack --config ../../MultiPackage/MultiCPackConfig.cmake