Tutorial: Improve Step 5

* Updated output message
* Use 'target_compile_definitions' for HAVE_LOG and HAVE_EXP

Previously, the change from using TutorialConfig.h to
target_compile_definitions happened without explanation as part of Step 8.

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

@@ -13,12 +13,6 @@ target_include_directories(MathFunctions
 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)
   target_link_libraries(MakeTable tutorial_compiler_flags)

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

@@ -18,8 +18,8 @@ double mysqrt(double x)
   // 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;
+  std::cout << "Computing sqrt of " << x << " to be " << result
+            << " using log and exp" << std::endl;
 #else
   // use the table to help find an initial value
   double result = x;

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

@@ -18,8 +18,8 @@ double mysqrt(double x)
   // 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;
+  std::cout << "Computing sqrt of " << x << " to be " << result
+            << " using log and exp" << std::endl;
 #else
   // use the table to help find an initial value
   double result = x;

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

@@ -11,12 +11,6 @@ target_include_directories(MathFunctions
 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)
 
@@ -43,6 +37,19 @@ if(USE_MYMATH)
                         POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
                         )
 
+  target_compile_definitions(MathFunctions PRIVATE "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)
+
+  if(HAVE_LOG AND HAVE_EXP)
+    target_compile_definitions(SqrtLibrary
+                               PRIVATE "HAVE_LOG" "HAVE_EXP")
+  endif()
+
   target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
 endif()
 

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

@@ -18,8 +18,8 @@ double mysqrt(double x)
   // 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;
+  std::cout << "Computing sqrt of " << x << " to be " << result
+            << " using log and exp" << std::endl;
 #else
   // use the table to help find an initial value
   double result = x;

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

@@ -11,12 +11,6 @@ target_include_directories(MathFunctions
 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)
   target_link_libraries(MakeTable tutorial_compiler_flags)

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

@@ -18,8 +18,8 @@ double mysqrt(double x)
   // 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;
+  std::cout << "Computing sqrt of " << x << " to be " << result
+            << " using log and exp" << std::endl;
 #else
   // use the table to help find an initial value
   double result = x;
@@ -38,7 +38,7 @@ double mysqrt(double x)
     result = result + 0.5 * delta / result;
     std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
   }
-#endif
+
   return result;
 }
 }

Help/guide/tutorial/Step6/CMakeLists.txt

@@ -10,12 +10,6 @@ set(CMAKE_CXX_STANDARD_REQUIRED True)
 # should we use our own math functions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
-# 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)
-
 # configure a header file to pass some of the CMake settings
 # to the source code
 configure_file(TutorialConfig.h.in TutorialConfig.h)

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

@@ -2,13 +2,21 @@ add_library(MathFunctions mysqrt.cxx)
 
 # 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 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}
           )
 
+# 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)
+
+if(HAVE_LOG AND HAVE_EXP)
+  target_compile_definitions(MathFunctions
+                             PRIVATE "HAVE_LOG" "HAVE_EXP")
+endif()
+
 # install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

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

@@ -1,5 +1,4 @@
 #include "MathFunctions.h"
-#include "TutorialConfig.h"
 #include <iostream>
 
 #include <cmath>
@@ -14,8 +13,8 @@ double mysqrt(double x)
   // 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;
+  std::cout << "Computing sqrt of " << x << " to be " << result
+            << " using log and exp" << std::endl;
 #else
   double result = x;
 

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

@@ -2,7 +2,3 @@
 #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
 #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
 #cmakedefine USE_MYMATH
-
-// does the platform provide exp and log functions?
-#cmakedefine HAVE_LOG
-#cmakedefine HAVE_EXP

Help/guide/tutorial/Step7/CMakeLists.txt

@@ -10,12 +10,6 @@ set(CMAKE_CXX_STANDARD_REQUIRED True)
 # should we use our own math functions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
-# 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)
-
 # configure a header file to pass some of the CMake settings
 # to the source code
 configure_file(TutorialConfig.h.in TutorialConfig.h)

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

@@ -21,10 +21,20 @@ add_library(MathFunctions
 # state that we depend on our binary dir to find Table.h
 target_include_directories(MathFunctions
           INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
-          PRIVATE ${Tutorial_BINARY_DIR}
-                  ${CMAKE_CURRENT_BINARY_DIR}
+          PRIVATE ${CMAKE_CURRENT_BINARY_DIR}
           )
 
+# 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)
+
+if(HAVE_LOG AND HAVE_EXP)
+  target_compile_definitions(MathFunctions
+                             PRIVATE "HAVE_LOG" "HAVE_EXP")
+endif()
+
 # install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

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

@@ -1,5 +1,4 @@
 #include "MathFunctions.h"
-#include "TutorialConfig.h"
 #include <iostream>
 
 // include the generated table

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

@@ -2,7 +2,3 @@
 #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
 #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
 #cmakedefine USE_MYMATH
-
-// does the platform provide exp and log functions?
-#cmakedefine HAVE_LOG
-#cmakedefine HAVE_EXP

Help/guide/tutorial/Step8/CMakeLists.txt

@@ -10,12 +10,6 @@ set(CMAKE_CXX_STANDARD_REQUIRED True)
 # should we use our own math functions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
-# 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)
-
 # configure a header file to pass some of the CMake settings
 # to the source code
 configure_file(TutorialConfig.h.in TutorialConfig.h)

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

@@ -21,10 +21,20 @@ add_library(MathFunctions
 # state that we depend on our binary dir to find Table.h
 target_include_directories(MathFunctions
           INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
-          PRIVATE ${Tutorial_BINARY_DIR}
-                  ${CMAKE_CURRENT_BINARY_DIR}
+          PRIVATE ${CMAKE_CURRENT_BINARY_DIR}
           )
 
+# 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)
+
+if(HAVE_LOG AND HAVE_EXP)
+  target_compile_definitions(MathFunctions
+                             PRIVATE "HAVE_LOG" "HAVE_EXP")
+endif()
+
 # install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

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

@@ -1,5 +1,4 @@
 #include "MathFunctions.h"
-#include "TutorialConfig.h"
 #include <iostream>
 
 // include the generated table
@@ -17,8 +16,8 @@ double mysqrt(double x)
   // 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;
+  std::cout << "Computing sqrt of " << x << " to be " << result
+            << " using log and exp" << std::endl;
 #else
   // use the table to help find an initial value
   double result = x;

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

@@ -2,7 +2,3 @@
 #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
 #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
 #cmakedefine USE_MYMATH
-
-// does the platform provide exp and log functions?
-#cmakedefine HAVE_LOG
-#cmakedefine HAVE_EXP

Help/guide/tutorial/Step9/CMakeLists.txt

@@ -10,12 +10,6 @@ set(CMAKE_CXX_STANDARD_REQUIRED True)
 # should we use our own math functions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
-# 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)
-
 # configure a header file to pass the version number only
 configure_file(TutorialConfig.h.in TutorialConfig.h)
 

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

@@ -26,6 +26,12 @@ target_include_directories(MathFunctions
 # and that anything that links to use will get this define
 target_compile_definitions(MathFunctions INTERFACE "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)
+
 if(HAVE_LOG AND HAVE_EXP)
   target_compile_definitions(MathFunctions
                              PRIVATE "HAVE_LOG" "HAVE_EXP")

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

@@ -16,8 +16,8 @@ double mysqrt(double x)
   // 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;
+  std::cout << "Computing sqrt of " << x << " to be " << result
+            << " using log and exp" << std::endl;
 #else
   // use the table to help find an initial value
   double result = x;

Help/guide/tutorial/index.rst

@@ -371,43 +371,81 @@ 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:
+CMakeLists. We're going to use the new defines in ``TutorialConfig.h.in``,
+so be sure to set them before that file is configured.
 
-.. literalinclude:: Step6/CMakeLists.txt
+.. literalinclude:: Step6/MathFunctions/CMakeLists.txt
   :language: cmake
   :start-after: # does this system provide the log and exp functions?
-  :end-before: # configure a header file to pass some of the CMake settings
+  :end-before: if(HAVE_LOG AND HAVE_EXP)
 
 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?
+.. code-block:: console
 
-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:
+  // does the platform provide exp and log functions?
+  #cmakedefine HAVE_LOG
+  #cmakedefine HAVE_EXP
+
+Modify ``mysqrt.cxx`` to include cmath. Next, in that same file 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 (don't forget the ``#endif`` before returning the result!):
 
 .. literalinclude:: Step6/MathFunctions/mysqrt.cxx
   :language: c++
   :start-after: // if we have both log and exp then use them
-  :end-before: #else
+  :end-before: // do ten iterations
 
 Run **cmake** or **cmake-gui** to configure the project and then build it
-with your chosen build tool.
+with your chosen build tool and run the Tutorial executable.
 
-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``.
+You will notice that we're not using ``log`` and ``exp``, even if we think they
+should be available. 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.
+We will also need to update MathFunctions/CMakeLists so ``mysqrt.cxx`` knows
+where this file is located:
 
-Run the built Tutorial executable. Which function gives better results now,
-Step1’s sqrt or Step5’s mysqrt?
 
-**Exercise**: Is there a better place for us to save the ``HAVE_LOG`` and
-``HAVE_EXP`` values other than in ``TutorialConfig.h``?
+.. code-block:: cmake
+
+  target_include_directories(MathFunctions
+            INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
+            PRIVATE ${CMAKE_BINARY_DIR}
+            )
+
+After making this update, go ahead and build the project again and run the built
+Tutorial executable. If ``log`` and ``exp`` are still not being used, open the
+generated ``TutorialConfig.h`` file from the build directory. Maybe they aren't
+available on the current system?
+
+Which function gives better results now, sqrt or mysqrt?
+
+Specify Compile Definition
+--------------------------
+
+Is there a better place for us to save the ``HAVE_LOG`` and ``HAVE_EXP`` values
+other than in ``TutorialConfig.h``? Let's try to use
+``target_compile_definitions``.
+
+First, remove the defines from ``TutorialConfig.h.in``. We no longer need to
+include ``TutorialConfig.h`` from ``mysqrt.cxx`` or the extra include in
+MathFunctions/CMakeLists.
+
+Next, we can move the check for ``HAVE_LOG`` and ``HAVE_EXP`` to
+MathFunctions/CMakeLists and then add specify those values as ``PRIVATE``
+compile definitions.
+
+.. literalinclude:: Step6/MathFunctions/CMakeLists.txt
+  :language: cmake
+  :start-after: # does this system provide the log and exp functions?
+  :end-before: # install rules
+
+After making these updates, go ahead and build the project again. Run the
+built  Tutorial executable and verify that the results are same as earlier in
+this step.
 
 Adding a Custom Command and Generated File (Step 6)
 ===================================================