Tutorial: Move step 10 to step 4

Shifts steps 4-9 to 5-10.

Help/guide/tutorial/Adding Generator Expressions.rst

-Step 10: Adding Generator Expressions
+Step 4: Adding Generator Expressions
 =====================================
 
 :manual:`Generator expressions <cmake-generator-expressions(7)>` are evaluated
@@ -37,16 +37,16 @@ instead of using :variable:`CMAKE_CXX_STANDARD`.
 
 So the following code:
 
-.. literalinclude:: Step10/CMakeLists.txt
+.. literalinclude:: Step4/CMakeLists.txt
   :caption: CMakeLists.txt
   :name: CMakeLists.txt-CXX_STANDARD-variable-remove
   :language: cmake
   :start-after: project(Tutorial VERSION 1.0)
-  :end-before: # control where the static and shared libraries are built so that on windows
+  :end-before: # should we use our own math functions
 
 Would be replaced with:
 
-.. literalinclude:: Step11/CMakeLists.txt
+.. literalinclude:: Step5/CMakeLists.txt
   :caption: CMakeLists.txt
   :name: CMakeLists.txt-cxx_std-feature
   :language: cmake
@@ -69,12 +69,12 @@ warning flags vary based on the compiler we use the ``COMPILE_LANG_AND_ID``
 generator expression to control which flags to apply given a language and a set
 of compiler ids as seen below:
 
-.. literalinclude:: Step11/CMakeLists.txt
+.. literalinclude:: Step5/CMakeLists.txt
   :caption: CMakeLists.txt
   :name: CMakeLists.txt-target_compile_options-genex
   :language: cmake
   :start-after: # the BUILD_INTERFACE genex
-  :end-before: # control where the static and shared libraries are built so that on windows
+  :end-before: # should we use our own math functions
 
 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

Help/guide/tutorial/Adding Support for a Testing Dashboard.rst

-Step 5: Adding Support for a Testing Dashboard
+Step 6: Adding Support for a Testing Dashboard
 ==============================================
 
 Adding support for submitting our test results to a dashboard is simple. We
@@ -9,7 +9,7 @@ we include the :module:`CTest` module in our top-level ``CMakeLists.txt``.
 
 Replace:
 
-.. literalinclude:: Step5/CMakeLists.txt
+.. literalinclude:: Step6/CMakeLists.txt
   :caption: CMakeLists.txt
   :name: CMakeLists.txt-enable_testing-remove
   :language: cmake
@@ -18,7 +18,7 @@ Replace:
 
 With:
 
-.. literalinclude:: Step6/CMakeLists.txt
+.. literalinclude:: Step7/CMakeLists.txt
   :caption: CMakeLists.txt
   :name: CMakeLists.txt-include-CTest
   :language: cmake
@@ -46,7 +46,7 @@ downloaded from the ``Settings`` page of the project on the CDash
 instance that will host and display the test results.  Once downloaded from
 CDash, the file should not be modified locally.
 
-.. literalinclude:: Step6/CTestConfig.cmake
+.. literalinclude:: Step7/CTestConfig.cmake
   :caption: CTestConfig.cmake
   :name: CTestConfig.cmake
   :language: cmake

Help/guide/tutorial/Adding System Introspection.rst

-Step 6: Adding System Introspection
+Step 7: Adding System Introspection
 ===================================
 
 Let us consider adding some code to our project that depends on features the
@@ -15,7 +15,7 @@ these functions using the :module:`CheckCXXSourceCompiles` module in
 Add the checks for ``log`` and ``exp`` to ``MathFunctions/CMakeLists.txt``,
 after the call to :command:`target_include_directories`:
 
-.. literalinclude:: Step7/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step8/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-check_cxx_source_compiles
   :language: cmake
@@ -25,7 +25,7 @@ after the call to :command:`target_include_directories`:
 If available, use :command:`target_compile_definitions` to specify
 ``HAVE_LOG`` and ``HAVE_EXP`` as ``PRIVATE`` compile definitions.
 
-.. literalinclude:: Step7/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step8/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-target_compile_definitions
   :language: cmake
@@ -37,7 +37,7 @@ compute the square root in the ``mysqrt`` function. Add the following code to
 the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (don't forget the
 ``#endif`` before returning the result!):
 
-.. literalinclude:: Step7/MathFunctions/mysqrt.cxx
+.. literalinclude:: Step8/MathFunctions/mysqrt.cxx
   :caption: MathFunctions/mysqrt.cxx
   :name: MathFunctions/mysqrt.cxx-ifdef
   :language: c++
@@ -46,7 +46,7 @@ the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (don't forget the
 
 We will also need to modify ``mysqrt.cxx`` to include ``cmath``.
 
-.. literalinclude:: Step7/MathFunctions/mysqrt.cxx
+.. literalinclude:: Step8/MathFunctions/mysqrt.cxx
   :caption: MathFunctions/mysqrt.cxx
   :name: MathFunctions/mysqrt.cxx-include-cmath
   :language: c++

Help/guide/tutorial/Adding a Custom Command and Generated File.rst

-Step 7: Adding a Custom Command and Generated File
+Step 8: Adding a Custom Command and Generated File
 ==================================================
 
 Suppose, for the purpose of this tutorial, we decide that we never want to use
@@ -26,7 +26,7 @@ accomplish this.
 First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for
 ``MakeTable`` is added as any other executable would be added.
 
-.. literalinclude:: Step8/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step9/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-add_executable-MakeTable
   :language: cmake
@@ -36,7 +36,7 @@ First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for
 Then we add a custom command that specifies how to produce ``Table.h``
 by running MakeTable.
 
-.. literalinclude:: Step8/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step9/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-add_custom_command-Table.h
   :language: cmake
@@ -47,7 +47,7 @@ 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:: Step8/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step9/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-add_library-Table.h
   :language: cmake
@@ -57,7 +57,7 @@ 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``.
 
-.. literalinclude:: Step8/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step9/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-target_include_directories-Table.h
   :language: cmake
@@ -67,7 +67,7 @@ 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:
 
-.. literalinclude:: Step8/MathFunctions/mysqrt.cxx
+.. literalinclude:: Step9/MathFunctions/mysqrt.cxx
   :caption: MathFunctions/mysqrt.cxx
   :name: MathFunctions/mysqrt.cxx
   :language: c++

Help/guide/tutorial/Complete/CMakeLists.txt

@@ -84,6 +84,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/Complete/License.txt

 This is the open source License.txt file introduced in
-CMake/Tutorial/Step7...
+CMake/Tutorial/Step9...

Help/guide/tutorial/Installing and Testing.rst

-Step 4: Installing and Testing
+Step 5: Installing and Testing
 ==============================
 
 Now we can start adding install rules and testing support to our project.
@@ -12,7 +12,7 @@ executable and configured header.
 
 So to the end of ``MathFunctions/CMakeLists.txt`` we add:
 
-.. literalinclude:: Step5/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step6/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-install-TARGETS
   :language: cmake
@@ -20,7 +20,7 @@ So to the end of ``MathFunctions/CMakeLists.txt`` we add:
 
 And to the end of the top-level ``CMakeLists.txt`` we add:
 
-.. literalinclude:: Step5/CMakeLists.txt
+.. literalinclude:: Step6/CMakeLists.txt
   :caption: CMakeLists.txt
   :name: CMakeLists.txt-install-TARGETS
   :language: cmake
@@ -65,7 +65,7 @@ Next let's test our application. At the end of the top-level ``CMakeLists.txt``
 file we can enable testing and then add a number of basic tests to verify that
 the application is working correctly.
 
-.. literalinclude:: Step5/CMakeLists.txt
+.. literalinclude:: Step6/CMakeLists.txt
   :caption: CMakeLists.txt
   :name: CMakeLists.txt-enable_testing
   :language: cmake

Help/guide/tutorial/Packaging an Installer.rst

-Step 8: Packaging an Installer
+Step 9: Packaging an Installer
 ==============================
 
 Next suppose that we want to distribute our project to other people so that
@@ -11,7 +11,7 @@ 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:: Step9/CMakeLists.txt
+.. literalinclude:: Step10/CMakeLists.txt
   :caption: CMakeLists.txt
   :name: CMakeLists.txt-include-CPack
   :language: cmake

Help/guide/tutorial/Selecting Static or Shared Libraries.rst

-Step 9: Selecting Static or Shared Libraries
-============================================
+Step 10: Selecting Static or Shared Libraries
+=============================================
 
 In this section we will show how the :variable:`BUILD_SHARED_LIBS` variable can
 be used to control the default behavior of :command:`add_library`,
@@ -19,7 +19,7 @@ library.
 The first step is to update the starting section of the top-level
 ``CMakeLists.txt`` to look like:
 
-.. literalinclude:: Step10/CMakeLists.txt
+.. literalinclude:: Step11/CMakeLists.txt
   :caption: CMakeLists.txt
   :name: CMakeLists.txt-option-BUILD_SHARED_LIBS
   :language: cmake
@@ -33,7 +33,7 @@ explicitly require that SqrtLibrary is built statically.
 
 The end result is that ``MathFunctions/CMakeLists.txt`` should look like:
 
-.. literalinclude:: Step10/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step11/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-add_library-STATIC
   :language: cmake
@@ -42,7 +42,7 @@ The end result is that ``MathFunctions/CMakeLists.txt`` should look like:
 Next, update ``MathFunctions/mysqrt.cxx`` to use the ``mathfunctions`` and
 ``detail`` namespaces:
 
-.. literalinclude:: Step10/MathFunctions/mysqrt.cxx
+.. literalinclude:: Step11/MathFunctions/mysqrt.cxx
   :caption: MathFunctions/mysqrt.cxx
   :name: MathFunctions/mysqrt.cxx-namespace
   :language: c++
@@ -56,7 +56,7 @@ uses ``USE_MYMATH``:
 
 Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines:
 
-.. literalinclude:: Step10/MathFunctions/MathFunctions.h
+.. literalinclude:: Step11/MathFunctions/MathFunctions.h
   :caption: MathFunctions/MathFunctions.h
   :name: MathFunctions/MathFunctions.h
   :language: c++
@@ -67,7 +67,7 @@ library that has position independent code. The solution to this is to
 explicitly set the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property of
 SqrtLibrary to be ``True`` no matter the build type.
 
-.. literalinclude:: Step10/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step11/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-POSITION_INDEPENDENT_CODE
   :language: cmake

Help/guide/tutorial/Step10/CMakeLists.txt

-cmake_minimum_required(VERSION 3.10)
+cmake_minimum_required(VERSION 3.15)
 
 # 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)
+add_library(tutorial_compiler_flags INTERFACE)
+target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
 
-# 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}")
+# add compiler warning flags just when building this project via
+# the BUILD_INTERFACE genex
+set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>")
+set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>")
+target_compile_options(tutorial_compiler_flags INTERFACE
+  "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>"
+  "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>"
+)
 
-option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
+# should we use our own math functions
+option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
-# configure a header file to pass the version number only
+# configure a header file to pass some of the CMake settings
+# to the source code
 configure_file(TutorialConfig.h.in TutorialConfig.h)
 
 # add the MathFunctions library
-add_subdirectory(MathFunctions)
+if(USE_MYMATH)
+  add_subdirectory(MathFunctions)
+  list(APPEND EXTRA_LIBS MathFunctions)
+endif()
 
 # add the executable
 add_executable(Tutorial tutorial.cxx)
-target_link_libraries(Tutorial PUBLIC MathFunctions)
+target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS})
 
 # add the binary tree to the search path for include files
 # so that we will find TutorialConfig.h
@@ -66,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/Step10/License.txt

 This is the open source License.txt file introduced in
-CMake/Tutorial/Step7...
+CMake/Tutorial/Step9...

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

-# add the library that runs
-add_library(MathFunctions MathFunctions.cxx)
+# 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
+            )
 
 # state that anybody linking to us needs to include the current source dir
 # to find MathFunctions.h, while we don't.
+# state that we depend on our binary dir to find Table.h
 target_include_directories(MathFunctions
-                           INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
-                           )
+          INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
+          PRIVATE   ${CMAKE_CURRENT_BINARY_DIR}
+          )
 
-# should we use our own math functions
-option(USE_MYMATH "Use tutorial provided math implementation" ON)
-if(USE_MYMATH)
-
-  target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH")
-
-  # 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}
-                             )
-
-  # state that SqrtLibrary need PIC when the default is shared libraries
-  set_target_properties(SqrtLibrary PROPERTIES
-                        POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
-                        )
-
-  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 rules
-set(installable_libs MathFunctions)
-if(TARGET SqrtLibrary)
-  list(APPEND installable_libs SqrtLibrary)
-endif()
-install(TARGETS ${installable_libs} DESTINATION lib)
+install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h

-
-#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);
-}
+double mysqrt(double x);

Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx

@@ -5,8 +5,6 @@
 // include the generated table
 #include "Table.h"
 
-namespace mathfunctions {
-namespace detail {
 // a hack square root calculation using simple operations
 double mysqrt(double x)
 {
@@ -33,5 +31,3 @@ double mysqrt(double x)
 
   return result;
 }
-}
-}

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

 // the configured options and settings for Tutorial
 #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
 #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
+#cmakedefine USE_MYMATH

Help/guide/tutorial/Step10/tutorial.cxx

 // A simple program that computes the square root of a number
+#include <cmath>
 #include <iostream>
-#include <sstream>
 #include <string>
 
-#include "MathFunctions.h"
 #include "TutorialConfig.h"
 
+// should we include the MathFunctions header?
+#ifdef USE_MYMATH
+#  include "MathFunctions.h"
+#endif
+
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
@@ -19,7 +23,12 @@ int main(int argc, char* argv[])
   // convert input to double
   const double inputValue = std::stod(argv[1]);
 
-  const double outputValue = mathfunctions::sqrt(inputValue);
+  // which square root function should we use?
+#ifdef USE_MYMATH
+  const double outputValue = mysqrt(inputValue);
+#else
+  const double outputValue = sqrt(inputValue);
+#endif
 
   std::cout << "The square root of " << inputValue << " is " << outputValue
             << std::endl;

Help/guide/tutorial/Step11/CMakeLists.txt

@@ -3,6 +3,7 @@ cmake_minimum_required(VERSION 3.15)
 # set the project name and version
 project(Tutorial VERSION 1.0)
 
+# specify the C++ standard
 add_library(tutorial_compiler_flags INTERFACE)
 target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
 
@@ -46,7 +47,7 @@ install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h"
   )
 
 # enable testing
-enable_testing()
+include(CTest)
 
 # does the application run
 add_test(NAME Runs COMMAND Tutorial 25)
@@ -74,6 +75,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/Step11/License.txt

 This is the open source License.txt file introduced in
-CMake/Tutorial/Step7...
+CMake/Tutorial/Step9...

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

@@ -47,7 +47,7 @@ endif()
 target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
 
 # define the symbol stating we are using the declspec(dllexport) when
-#building on windows
+# building on windows
 target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
 
 # install rules

Help/guide/tutorial/Step11/tutorial.cxx

 // A simple program that computes the square root of a number
 #include <iostream>
+#include <sstream>
 #include <string>
 
 #include "MathFunctions.h"