Tutorial: Improve Step 1

* Update minimum required version to 3.10
* Use VERSION argument to project command rather than separate variables
* Replace `endif(USE_MYMATH)` with  more modern `endif()`
* Simplify the call to 'configure_file()'
* Add comments to tutorial.cxx to use as anchors in documentation
* Remove CMakeLists and TutorialConfig.h.in files that users should
  create. Consequently, remove Step1 from CMake tests.

Help/guide/tutorial/Complete/CMakeLists.txt

@@ -1,5 +1,7 @@
 cmake_minimum_required(VERSION 3.15)
-project(Tutorial)
+
+# set the project name and version
+project(Tutorial VERSION 1.0)
 
 add_library(tutorial_compiler_flags INTERFACE)
 target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
@@ -13,10 +15,6 @@ target_compile_options(tutorial_compiler_flags INTERFACE
   "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>"
 )
 
-# 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}")
@@ -32,10 +30,7 @@ elseif(UNIX)
 endif()
 
 # configure a header file to pass the version number only
-configure_file(
-  "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"
-  "${PROJECT_BINARY_DIR}/TutorialConfig.h"
-  )
+configure_file(TutorialConfig.h.in TutorialConfig.h)
 
 # add the MathFunctions library
 add_subdirectory(MathFunctions)

Help/guide/tutorial/Complete/tutorial.cxx

@@ -15,10 +15,11 @@ int main(int argc, char* argv[])
     return 1;
   }
 
-  double inputValue = std::stod(argv[1]);
+  // convert input to double
+  const double inputValue = std::stod(argv[1]);
 
+  // calculate square root
   const double outputValue = mathfunctions::sqrt(inputValue);
-
   std::cout << "The square root of " << inputValue << " is " << outputValue
             << std::endl;
   return 0;

Help/guide/tutorial/Consumer/CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 3.3)
+cmake_minimum_required(VERSION 3.10)
 
 if(NOT DEFINED CMAKE_CXX_STANDARD)
   set(CMAKE_CXX_STANDARD 11)

Help/guide/tutorial/MultiPackage/CMakeLists.txt

@@ -1,12 +1,11 @@
-cmake_minimum_required(VERSION 3.3)
-project(Tutorial)
+cmake_minimum_required(VERSION 3.10)
+
+# set the project name and version
+project(Tutorial VERSION 1.0)
 
 set(CMAKE_CXX_STANDARD 11)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 
-# 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
@@ -23,10 +22,7 @@ elseif(UNIX)
 endif()
 
 # configure a header file to pass the version number only
-configure_file(
-  "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"
-  "${PROJECT_BINARY_DIR}/TutorialConfig.h"
-  )
+configure_file(TutorialConfig.h.in TutorialConfig.h)
 
 # add the MathFunctions library
 add_subdirectory(MathFunctions)

Help/guide/tutorial/MultiPackage/tutorial.cxx

@@ -15,6 +15,7 @@ int main(int argc, char* argv[])
     return 1;
   }
 
+  // convert input to double
   double inputValue = std::stod(argv[1]);
 
   const double outputValue = mathfunctions::sqrt(inputValue);

Help/guide/tutorial/Step1/CMakeLists.txt

@@ -1,3 +0,0 @@
-project(Tutorial)
-
-add_executable(Tutorial tutorial.cxx)

Help/guide/tutorial/Step1/TutorialConfig.h.in

@@ -1,3 +0,0 @@
-// the configured options and settings for Tutorial
-#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
-#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@

Help/guide/tutorial/Step1/tutorial.cxx

@@ -11,9 +11,11 @@ int main(int argc, char* argv[])
     return 1;
   }
 
-  double inputValue = atof(argv[1]);
+  // convert input to double
+  const double inputValue = atof(argv[1]);
 
-  double outputValue = sqrt(inputValue);
+  // calculate square root
+  const double outputValue = sqrt(inputValue);
   std::cout << "The square root of " << inputValue << " is " << outputValue
             << std::endl;
   return 0;

Help/guide/tutorial/Step10/CMakeLists.txt

@@ -1,13 +1,12 @@
-cmake_minimum_required(VERSION 3.3)
-project(Tutorial)
+cmake_minimum_required(VERSION 3.10)
 
+# set the project name and version
+project(Tutorial VERSION 1.0)
+
+# specify the C++ standard
 set(CMAKE_CXX_STANDARD 11)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 
-# 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}")
@@ -17,10 +16,7 @@ set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
 
 # configure a header file to pass the version number only
-configure_file(
-  "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"
-  "${PROJECT_BINARY_DIR}/TutorialConfig.h"
-  )
+configure_file(TutorialConfig.h.in TutorialConfig.h)
 
 # add the MathFunctions library
 add_subdirectory(MathFunctions)

Help/guide/tutorial/Step10/tutorial.cxx

@@ -16,7 +16,8 @@ int main(int argc, char* argv[])
     return 1;
   }
 
-  double inputValue = std::stod(argv[1]);
+  // convert input to double
+  const double inputValue = std::stod(argv[1]);
 
   const double outputValue = mathfunctions::sqrt(inputValue);
 

Help/guide/tutorial/Step11/CMakeLists.txt

@@ -1,5 +1,7 @@
 cmake_minimum_required(VERSION 3.15)
-project(Tutorial)
+
+# set the project name and version
+project(Tutorial VERSION 1.0)
 
 add_library(tutorial_compiler_flags INTERFACE)
 target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
@@ -13,10 +15,6 @@ target_compile_options(tutorial_compiler_flags INTERFACE
   "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>"
 )
 
-# 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}")
@@ -26,10 +24,7 @@ set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
 
 # configure a header file to pass the version number only
-configure_file(
-  "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"
-  "${PROJECT_BINARY_DIR}/TutorialConfig.h"
-  )
+configure_file(TutorialConfig.h.in TutorialConfig.h)
 
 # add the MathFunctions library
 add_subdirectory(MathFunctions)

Help/guide/tutorial/Step11/tutorial.cxx

@@ -16,7 +16,8 @@ int main(int argc, char* argv[])
     return 1;
   }
 
-  double inputValue = std::stod(argv[1]);
+  // convert input to double
+  const double inputValue = std::stod(argv[1]);
 
   const double outputValue = mathfunctions::sqrt(inputValue);
 

Help/guide/tutorial/Step2/CMakeLists.txt

@@ -1,19 +1,15 @@
-cmake_minimum_required(VERSION 3.3)
-project(Tutorial)
+cmake_minimum_required(VERSION 3.10)
 
+# set the project name and version
+project(Tutorial VERSION 1.0)
+
+# specify the C++ standard
 set(CMAKE_CXX_STANDARD 11)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 
-# set 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"
-  )
+configure_file(TutorialConfig.h.in TutorialConfig.h)
 
 # add the executable
 add_executable(Tutorial tutorial.cxx)

Help/guide/tutorial/Step2/tutorial.cxx

@@ -15,9 +15,11 @@ int main(int argc, char* argv[])
     return 1;
   }
 
-  double inputValue = std::stod(argv[1]);
+  // convert input to double
+  const double inputValue = std::stod(argv[1]);
 
-  double outputValue = sqrt(inputValue);
+  // calculate square root
+  const double outputValue = sqrt(inputValue);
   std::cout << "The square root of " << inputValue << " is " << outputValue
             << std::endl;
   return 0;

Help/guide/tutorial/Step3/CMakeLists.txt

@@ -1,29 +1,25 @@
-cmake_minimum_required(VERSION 3.3)
-project(Tutorial)
+cmake_minimum_required(VERSION 3.10)
 
+# set the project name and version
+project(Tutorial VERSION 1.0)
+
+# specify the C++ standard
 set(CMAKE_CXX_STANDARD 11)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 
 # should we use our own math functions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
-# set 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"
-  )
+configure_file(TutorialConfig.h.in TutorialConfig.h)
 
 # 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)
+endif()
 
 # add the executable
 add_executable(Tutorial tutorial.cxx)

Help/guide/tutorial/Step3/tutorial.cxx

@@ -20,13 +20,14 @@ int main(int argc, char* argv[])
     return 1;
   }
 
-  double inputValue = std::stod(argv[1]);
+  // convert input to double
+  const double inputValue = std::stod(argv[1]);
 
   // which square root function should we use?
 #ifdef USE_MYMATH
-  double outputValue = mysqrt(inputValue);
+  const double outputValue = mysqrt(inputValue);
 #else
-  double outputValue = sqrt(inputValue);
+  const double outputValue = sqrt(inputValue);
 #endif
 
   std::cout << "The square root of " << inputValue << " is " << outputValue

Help/guide/tutorial/Step4/CMakeLists.txt

@@ -1,28 +1,24 @@
-cmake_minimum_required(VERSION 3.3)
-project(Tutorial)
+cmake_minimum_required(VERSION 3.10)
 
+# set the project name and version
+project(Tutorial VERSION 1.0)
+
+# specify the C++ standard
 set(CMAKE_CXX_STANDARD 11)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 
 # should we use our own math functions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
-# set 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"
-  )
+configure_file(TutorialConfig.h.in TutorialConfig.h)
 
 # add the MathFunctions library?
 if(USE_MYMATH)
   add_subdirectory(MathFunctions)
   list(APPEND EXTRA_LIBS MathFunctions)
-endif(USE_MYMATH)
+endif()
 
 # add the executable
 add_executable(Tutorial tutorial.cxx)

Help/guide/tutorial/Step4/tutorial.cxx

@@ -20,13 +20,14 @@ int main(int argc, char* argv[])
     return 1;
   }
 
-  double inputValue = std::stod(argv[1]);
+  // convert input to double
+  const double inputValue = std::stod(argv[1]);
 
   // which square root function should we use?
 #ifdef USE_MYMATH
-  double outputValue = mysqrt(inputValue);
+  const double outputValue = mysqrt(inputValue);
 #else
-  double outputValue = sqrt(inputValue);
+  const double outputValue = sqrt(inputValue);
 #endif
 
   std::cout << "The square root of " << inputValue << " is " << outputValue

Help/guide/tutorial/Step5/CMakeLists.txt

@@ -1,22 +1,18 @@
-cmake_minimum_required(VERSION 3.3)
-project(Tutorial)
+cmake_minimum_required(VERSION 3.10)
 
+# set the project name and version
+project(Tutorial VERSION 1.0)
+
+# specify the C++ standard
 set(CMAKE_CXX_STANDARD 11)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 
 # should we use our own math functions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
-# set 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"
-  )
+configure_file(TutorialConfig.h.in TutorialConfig.h)
 
 # add the MathFunctions library?
 if(USE_MYMATH)

Help/guide/tutorial/Step5/tutorial.cxx

@@ -20,13 +20,14 @@ int main(int argc, char* argv[])
     return 1;
   }
 
-  double inputValue = std::stod(argv[1]);
+  // convert input to double
+  const double inputValue = std::stod(argv[1]);
 
   // which square root function should we use?
 #ifdef USE_MYMATH
-  double outputValue = mysqrt(inputValue);
+  const double outputValue = mysqrt(inputValue);
 #else
-  double outputValue = sqrt(inputValue);
+  const double outputValue = sqrt(inputValue);
 #endif
 
   std::cout << "The square root of " << inputValue << " is " << outputValue

Help/guide/tutorial/Step6/CMakeLists.txt

@@ -1,13 +1,12 @@
-cmake_minimum_required(VERSION 3.3)
-project(Tutorial)
+cmake_minimum_required(VERSION 3.10)
 
+# set the project name and version
+project(Tutorial VERSION 1.0)
+
+# specify the C++ standard
 set(CMAKE_CXX_STANDARD 11)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 
-# set the version number
-set(Tutorial_VERSION_MAJOR 1)
-set(Tutorial_VERSION_MINOR 0)
-
 # does this system provide the log and exp functions?
 include(CheckSymbolExists)
 set(CMAKE_REQUIRED_LIBRARIES "m")
@@ -19,10 +18,7 @@ option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
 # 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"
-  )
+configure_file(TutorialConfig.h.in TutorialConfig.h)
 
 # add the MathFunctions library?
 if(USE_MYMATH)

Help/guide/tutorial/Step6/tutorial.cxx

@@ -20,13 +20,14 @@ int main(int argc, char* argv[])
     return 1;
   }
 
-  double inputValue = std::stod(argv[1]);
+  // convert input to double
+  const double inputValue = std::stod(argv[1]);
 
   // which square root function should we use?
 #ifdef USE_MYMATH
-  double outputValue = mysqrt(inputValue);
+  const double outputValue = mysqrt(inputValue);
 #else
-  double outputValue = sqrt(inputValue);
+  const double outputValue = sqrt(inputValue);
 #endif
 
   std::cout << "The square root of " << inputValue << " is " << outputValue

Help/guide/tutorial/Step7/CMakeLists.txt

@@ -1,13 +1,12 @@
-cmake_minimum_required(VERSION 3.3)
-project(Tutorial)
+cmake_minimum_required(VERSION 3.10)
 
+# set the project name and version
+project(Tutorial VERSION 1.0)
+
+# specify the C++ standard
 set(CMAKE_CXX_STANDARD 11)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 
-# set the version number
-set(Tutorial_VERSION_MAJOR 1)
-set(Tutorial_VERSION_MINOR 0)
-
 # does this system provide the log and exp functions?
 include(CheckSymbolExists)
 set(CMAKE_REQUIRED_LIBRARIES "m")
@@ -19,16 +18,13 @@ option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
 # 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"
-  )
+configure_file(TutorialConfig.h.in TutorialConfig.h)
 
 # add the MathFunctions library?
 if(USE_MYMATH)
   add_subdirectory(MathFunctions)
   list(APPEND EXTRA_LIBS MathFunctions)
-endif(USE_MYMATH)
+endif()
 
 # add the executable
 add_executable(Tutorial tutorial.cxx)

Help/guide/tutorial/Step7/tutorial.cxx

@@ -20,13 +20,14 @@ int main(int argc, char* argv[])
     return 1;
   }
 
-  double inputValue = std::stod(argv[1]);
+  // convert input to double
+  const double inputValue = std::stod(argv[1]);
 
   // which square root function should we use?
 #ifdef USE_MYMATH
-  double outputValue = mysqrt(inputValue);
+  const double outputValue = mysqrt(inputValue);
 #else
-  double outputValue = sqrt(inputValue);
+  const double outputValue = sqrt(inputValue);
 #endif
 
   std::cout << "The square root of " << inputValue << " is " << outputValue

Help/guide/tutorial/Step8/CMakeLists.txt

@@ -1,13 +1,12 @@
-cmake_minimum_required(VERSION 3.3)
-project(Tutorial)
+cmake_minimum_required(VERSION 3.10)
 
+# set the project name and version
+project(Tutorial VERSION 1.0)
+
+# specify the C++ standard
 set(CMAKE_CXX_STANDARD 11)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 
-# set the version number
-set(Tutorial_VERSION_MAJOR 1)
-set(Tutorial_VERSION_MINOR 0)
-
 # does this system provide the log and exp functions?
 include(CheckSymbolExists)
 set(CMAKE_REQUIRED_LIBRARIES "m")
@@ -19,16 +18,13 @@ option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
 # 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"
-  )
+configure_file(TutorialConfig.h.in TutorialConfig.h)
 
 # add the MathFunctions library?
 if(USE_MYMATH)
   add_subdirectory(MathFunctions)
   list(APPEND EXTRA_LIBS MathFunctions)
-endif(USE_MYMATH)
+endif()
 
 # add the executable
 add_executable(Tutorial tutorial.cxx)

Help/guide/tutorial/Step8/tutorial.cxx

@@ -20,13 +20,14 @@ int main(int argc, char* argv[])
     return 1;
   }
 
-  double inputValue = std::stod(argv[1]);
+  // convert input to double
+  const double inputValue = std::stod(argv[1]);
 
   // which square root function should we use?
 #ifdef USE_MYMATH
-  double outputValue = mysqrt(inputValue);
+  const double outputValue = mysqrt(inputValue);
 #else
-  double outputValue = sqrt(inputValue);
+  const double outputValue = sqrt(inputValue);
 #endif
 
   std::cout << "The square root of " << inputValue << " is " << outputValue

Help/guide/tutorial/Step9/CMakeLists.txt

@@ -1,13 +1,12 @@
-cmake_minimum_required(VERSION 3.3)
-project(Tutorial)
+cmake_minimum_required(VERSION 3.10)
 
+# set the project name and version
+project(Tutorial VERSION 1.0)
+
+# specify the C++ standard
 set(CMAKE_CXX_STANDARD 11)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 
-# set the version number
-set(Tutorial_VERSION_MAJOR 1)
-set(Tutorial_VERSION_MINOR 0)
-
 # does this system provide the log and exp functions?
 include(CheckSymbolExists)
 set(CMAKE_REQUIRED_LIBRARIES "m")
@@ -18,10 +17,7 @@ check_symbol_exists(exp "math.h" HAVE_EXP)
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
 # configure a header file to pass the version number only
-configure_file(
-  "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"
-  "${PROJECT_BINARY_DIR}/TutorialConfig.h"
-  )
+configure_file(TutorialConfig.h.in TutorialConfig.h)
 
 # add the MathFunctions library?
 if(USE_MYMATH)

Help/guide/tutorial/Step9/tutorial.cxx

@@ -21,13 +21,14 @@ int main(int argc, char* argv[])
     return 1;
   }
 
-  double inputValue = std::stod(argv[1]);
+  // convert input to double
+  const double inputValue = std::stod(argv[1]);
 
   // which square root function should we use?
 #ifdef USE_MYMATH
-  double outputValue = mysqrt(inputValue);
+  const double outputValue = mysqrt(inputValue);
 #else
-  double outputValue = sqrt(inputValue);
+  const double outputValue = sqrt(inputValue);
 #endif
 
   std::cout << "The square root of " << inputValue << " is " << outputValue

Help/guide/tutorial/index.rst

@@ -5,33 +5,38 @@ CMake Tutorial
 
    .. contents::
 
-This tutorial provides a step-by-step guide that covers common build
+The CMake tutorial provides a step-by-step guide that covers common build
 system issues that CMake helps address. Seeing how various topics all
-work together in an example project can be very helpful. This tutorial
-can be found in the ``Help/guide/tutorial`` directory of the CMake
-source code tree. Each topic has its own subdirectory containing code
-that may be used as a starting point for that step. The tutorial
-examples are progressive so that each step provides the complete
+work together in an example project can be very helpful. The tutorial
+documentation and source code for examples can be found in the
+``Help/guide/tutorial`` directory of the CMake source code tree. Each step has
+its own subdirectory containing code that may be used as a starting point. The
+tutorial examples are progressive so that each step provides the complete
 solution for the previous step.
 
 A Basic Starting Point (Step 1)
 ===============================
 
 The most basic project is an executable built from source code files.
-For simple projects, a two line CMakeLists file is all that is required.
-This will be the starting point for our tutorial. The CMakeLists file
-looks like:
+For simple projects, a three line CMakeLists file is all that is required.
+This will be the starting point for our tutorial. Create a ``CMakeLists.txt``
+file in the ``Step1`` directory that looks like:
+
+.. code-block:: cmake
+
+  cmake_minimum_required(VERSION 3.10)
+
+  # set the project name
+  project(Tutorial)
+
+  # add the executable
+  add_executable(Tutorial tutorial.cxx)
 
-.. literalinclude:: Step1/CMakeLists.txt
-  :language: cmake
 
 Note that this example uses lower case commands in the CMakeLists file.
 Upper, lower, and mixed case commands are supported by CMake. The source
-code for ``tutorial.cxx`` will compute the square root of a number and
-the first version of it is very simple, as follows:
-
-.. literalinclude:: Step1/tutorial.cxx
-  :language: c++
+code for ``tutorial.cxx`` is provided in the ``Step1`` directory and can be
+used to compute the square root of a number.
 
 Adding a Version Number and Configured Header File
 --------------------------------------------------
@@ -40,55 +45,70 @@ 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:
+First, modify the CMakeLists file to set the version number.
 
 .. literalinclude:: Step2/CMakeLists.txt
   :language: cmake
-  :start-after: # set the version number
-  :end-before: # configure a header file
+  :end-before: # specify the C++ standard
+
+Then, configure a header file to pass the version number to the source
+code:
+
+.. literalinclude:: Step2/CMakeLists.txt
+  :language: cmake
+  :start-after: # to the source code
+  :end-before: # add the executable
 
 Since the configured file will be written into the binary tree, we
 must add that directory to the list of paths to search for include
-files.
+files. Add the following lines to the end of the CMakeLists file:
 
 .. literalinclude:: Step2/CMakeLists.txt
   :language: cmake
   :start-after: # so that we will find TutorialConfig.h
 
-We then create a ``TutorialConfig.h.in`` file in the source tree with the
-following contents:
+Using your favorite editor, create ``TutorialConfig.h.in`` in the source
+directory with the following contents:
 
-.. literalinclude:: Step1/TutorialConfig.h.in
+.. literalinclude:: Step2/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.
+replaced.
+
+Next modify ``tutorial.cxx`` to include the configured header file,
+``TutorialConfig.h``.
+
+Finally, let's print out the version number by updating ``tutorial.cxx`` as
+follows:
 
 .. literalinclude:: Step2/tutorial.cxx
   :language: c++
-  :start-after: // report version
-  :end-before: return 1;
-
-The main changes are the inclusion of the ``TutorialConfig.h`` header
-file and printing out a version number as part of the usage message.
+  :start-after: {
+  :end-before: // convert input to double
 
 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.
+Next let's add some C++11 features to our project by replacing ``atof`` with
+``std::stod`` in ``tutorial.cxx``.  At the same time, remove
+``#include <cstdlib>``.
 
-First, replace ``atof`` with ``std::stod`` in ``tutorial.cxx``.
+.. literalinclude:: Step2/tutorial.cxx
+  :language: c++
+  :start-after: // convert input to double
+  :end-before: // calculate square root
 
-Then, set the ``CMAKE_CXX_STANDARD`` variable in the CMakeLists file.
+We will need to explicitly state in the CMake code that it should use the
+correct flags. The easiest way to enable support for a specific C++ standard
+in CMake is by using the ``CMAKE_CXX_STANDARD`` variable. For this tutorial,
+set the ``CMAKE_CXX_STANDARD`` variable in the CMakeLists file to 11 and
+``CMAKE_CXX_STANDARD_REQUIRED`` to True:
 
-Which variable can we set in the CMakeLists file to treat the
-``CMAKE_CXX_STANDARD`` value as a requirement?
+.. literalinclude:: Step2/CMakeLists.txt
+  :language: cmake
+  :end-before: # configure a header file to pass some of the CMake settings
 
 Build and Test
 --------------
@@ -96,8 +116,19 @@ 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:
+For example, from the command line we could navigate to the
+``Help/guide/tutorial`` directory of the CMake source code tree and run the
+following commands:
+
+.. code-block:: console
+
+  mkdir Step1_build
+  cd Step1_build
+  cmake ../Step1
+  cmake --build .
+
+Navigate 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
 
@@ -152,7 +183,7 @@ file.
 .. literalinclude:: Step3/CMakeLists.txt
   :language: cmake
   :start-after: # should we use our own math functions
-  :end-before: # set the version number
+  :end-before: # configure a header file to pass some of the CMake settings
 
 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
@@ -531,7 +562,7 @@ The first step is to update the starting section of the top-level
 
 .. literalinclude:: Step10/CMakeLists.txt
   :language: cmake
-  :start-after: set(Tutorial_VERSION_MINOR
+  :start-after: set(CMAKE_CXX_STANDARD 14)
   :end-before: # add the binary tree
 
 Now that we have made MathFunctions always be used, we will need to update
@@ -609,14 +640,14 @@ So the following code:
 
 .. literalinclude:: Step10/CMakeLists.txt
   :language: cmake
-  :start-after: project(Tutorial)
-  :end-before: # Set the version number
+  :start-after: project(Tutorial VERSION 1.0)
+  :end-before: # control where the static and shared libraries are built so that on windows
 
 Would be replaced with:
 
 .. literalinclude:: Step11/CMakeLists.txt
   :language: cmake
-  :start-after: project(Tutorial)
+  :start-after: project(Tutorial VERSION 1.0)
   :end-before: # add compiler warning flags just when building this project via
 
 
@@ -629,7 +660,7 @@ below:
 .. literalinclude:: Step11/CMakeLists.txt
   :language: cmake
   :start-after: # the BUILD_INTERFACE genex
-  :end-before: # set the version number
+  :end-before: # control where the static and shared libraries are built so that on windows
 
 Looking at this we see that the warning flags are encapsulated inside a
 ``BUILD_INTERFACE`` condition. This is done so that consumers of our installed

Tests/CMakeLists.txt

@@ -1597,7 +1597,7 @@ ${CMake_SOURCE_DIR}/Utilities/Release/push.bash --dir dev -- '${CMake_BUILD_NIGH
   endfunction()
 
   if(NOT CMake_TEST_EXTERNAL_CMAKE)
-    foreach(STP RANGE 1 11)
+    foreach(STP RANGE 2 11)
       add_tutorial_test(Step${STP} TRUE)
     endforeach()
     add_tutorial_test(Complete TRUE)
@@ -2129,8 +2129,8 @@ ${CMake_SOURCE_DIR}/Utilities/Release/push.bash --dir dev -- '${CMake_BUILD_NIGH
     macro(add_test_VSWinCE name generator systemName systemVersion generatorPlatform)
       # TODO: Fix the tutorial to make it work in cross compile
       # currently the MakeTable is build for target and can not be used on the host
-      # This happens in part 5 so we build only part 1-4 of the tutorial
-      foreach(STP RANGE 1 4)
+      # This happens in part 5 so we build only through part 4 of the tutorial.
+      foreach(STP RANGE 2 4)
         add_test(NAME "TutorialStep${STP}.${name}" COMMAND ${CMAKE_CTEST_COMMAND}
           --build-and-test
           "${CMake_SOURCE_DIR}/Help/guide/tutorial/Step${STP}"