Tutorial: Expand Generator Expression step

Help/guide/tutorial/Adding Generator Expressions.rst

@@ -82,3 +82,90 @@ project will not inherit our warning flags.
 
 **Exercise**: Modify ``MathFunctions/CMakeLists.txt`` so that all targets have
 a :command:`target_link_libraries` call to ``tutorial_compiler_flags``.
+
+After finishing the exercise, be sure to build like you did in prior steps to
+ensure that the project is still building correctly. To see the exercise
+answers, take a look at the starting code for Step 5.
+
+Next, let's move some our informational printouts to be a debug only feature.
+Generator expressions can help with that. As mentioned earlier, generator
+expressions can be nested. For this example, we will be using a Conditional
+Expression where the ``condition`` itself is a Configuration Expression.
+
+Add the following line to the end of ``MathFunctions/CMakeList``:
+
+.. literalinclude:: Step5/MathFunctions/CMakeLists.txt
+  :caption: CMakeLists.txt
+  :name: CMakeLists.txt-target_compile_definitions-genex
+  :language: cmake
+  :start-after: # set DEBUG if configured in debug mode
+
+Here we're adding the preprocessor definition ``DEBUG`` only when the ``Debug``
+configuration is used.
+
+Now in ``mysqrt.cxx`` we can check if ``DEBUG`` is defined before printing a
+status message:
+
+.. literalinclude:: Step5/MathFunctions/mysqrt.cxx
+  :caption: mysqrt.cxx
+  :name: mysqrt.cxx-debug-ifdef
+  :language: c++
+  :start-after: result = result + 0.5 * delta / result;
+  :end-before: }
+
+With this all set, we can build our project in both release and debug mode and
+verify we see extra output in the debug version.
+
+When using a multi-configuration tool such as Visual Studio, build in debug mode by
+calling the following from the command line from the existing build directory:
+
+.. code-block:: console
+  :caption: console
+  :name: build-debug-config-multi
+
+  cmake --build . --config Debug
+
+Then to build in release mode:
+
+.. code-block:: console
+  :caption: console
+  :name: build-release-config-multi
+
+  cmake --build . --config Release
+
+These commands will create Debug and Release folders in your build directory.
+
+To build in debug mode with a single-configuration generator, first we must
+create a separate debug build directory. Navigate to the
+``Help/guide/tutorial`` directory of the CMake source code tree and create a
+build directory:
+
+.. code-block:: console
+  :caption: console
+  :name: create-debug-build-directory
+
+  mkdir Step4_debug_build
+  cd Step4_debug_build
+
+Then use :variable:`CMAKE_BUILD_TYPE` to set the configuration type:
+
+.. code-block:: console
+  :caption: console
+  :name: build-debug-config-single
+
+  cmake -DCMAKE_BUILD_TYPE=Debug ../Step4
+  cmake --build .
+
+Follow a similar process for the release build:
+
+.. code-block:: console
+  :caption: console
+  :name: build-release-config-single
+
+  mkdir Step4_release_build
+  cd Step4_release_build
+  cmake -DCMAKE_BUILD_TYPE=Release ../Step4
+  cmake --build .
+
+Now that both the debug and release builds are complete, verify that the
+extra output is only produced in debug mode.

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

@@ -9,6 +9,9 @@ target_include_directories(MathFunctions
                             $<INSTALL_INTERFACE:include>
                            )
 
+# set DEBUG if configured in debug mode
+target_compile_definitions(MathFunctions PRIVATE $<$<CONFIG:Debug>:DEBUG>)
+
 # should we use our own math functions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 if(USE_MYMATH)

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

@@ -28,7 +28,10 @@ double mysqrt(double x)
     }
     double delta = x - (result * result);
     result = result + 0.5 * delta / result;
+
+#ifdef DEBUG
     std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
+#endif
   }
 
   return result;

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

@@ -7,6 +7,9 @@ target_include_directories(MathFunctions
                            INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
                            )
 
+# set DEBUG if configured in debug mode
+target_compile_definitions(MathFunctions PRIVATE $<$<CONFIG:Debug>:DEBUG>)
+
 # should we use our own math functions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 if(USE_MYMATH)

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

@@ -28,7 +28,10 @@ double mysqrt(double x)
     }
     double delta = x - (result * result);
     result = result + 0.5 * delta / result;
+
+#ifdef DEBUG
     std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
+#endif
   }
 
   return result;

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

@@ -9,6 +9,9 @@ target_include_directories(MathFunctions
                             $<INSTALL_INTERFACE:include>
                            )
 
+# set DEBUG if configured in debug mode
+target_compile_definitions(MathFunctions PRIVATE $<$<CONFIG:Debug>:DEBUG>)
+
 # should we use our own math functions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 if(USE_MYMATH)

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

@@ -28,7 +28,10 @@ double mysqrt(double x)
     }
     double delta = x - (result * result);
     result = result + 0.5 * delta / result;
+
+#ifdef DEBUG
     std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
+#endif
   }
 
   return result;

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

@@ -5,3 +5,6 @@ add_library(MathFunctions mysqrt.cxx)
 target_include_directories(MathFunctions
           INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
           )
+
+# set DEBUG if configured in debug mode
+target_compile_definitions(MathFunctions PRIVATE $<$<CONFIG:Debug>:DEBUG>)

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

@@ -18,7 +18,10 @@ double mysqrt(double x)
     }
     double delta = x - (result * result);
     result = result + 0.5 * delta / result;
+
+#ifdef DEBUG
     std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
+#endif
   }
   return result;
 }

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

@@ -6,6 +6,9 @@ target_include_directories(MathFunctions
           INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
           )
 
+# set DEBUG if configured in debug mode
+target_compile_definitions(MathFunctions PRIVATE $<$<CONFIG:Debug>:DEBUG>)
+
 # install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

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

@@ -18,7 +18,10 @@ double mysqrt(double x)
     }
     double delta = x - (result * result);
     result = result + 0.5 * delta / result;
+
+#ifdef DEBUG
     std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
+#endif
   }
   return result;
 }

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

@@ -6,6 +6,9 @@ target_include_directories(MathFunctions
           INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
           )
 
+# set DEBUG if configured in debug mode
+target_compile_definitions(MathFunctions PRIVATE $<$<CONFIG:Debug>:DEBUG>)
+
 # install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

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

@@ -18,7 +18,10 @@ double mysqrt(double x)
     }
     double delta = x - (result * result);
     result = result + 0.5 * delta / result;
+
+#ifdef DEBUG
     std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
+#endif
   }
   return result;
 }

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

@@ -6,6 +6,9 @@ target_include_directories(MathFunctions
           INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
           )
 
+# set DEBUG if configured in debug mode
+target_compile_definitions(MathFunctions PRIVATE $<$<CONFIG:Debug>:DEBUG>)
+
 # does this system provide the log and exp functions?
 include(CheckCXXSourceCompiles)
 check_cxx_source_compiles("

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

@@ -25,7 +25,10 @@ double mysqrt(double x)
     }
     double delta = x - (result * result);
     result = result + 0.5 * delta / result;
+
+#  ifdef DEBUG
     std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
+#  endif
   }
 #endif
   return result;

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

@@ -24,6 +24,9 @@ target_include_directories(MathFunctions
           PRIVATE   ${CMAKE_CURRENT_BINARY_DIR}
           )
 
+# set DEBUG if configured in debug mode
+target_compile_definitions(MathFunctions PRIVATE $<$<CONFIG:Debug>:DEBUG>)
+
 # install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

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

@@ -26,7 +26,10 @@ double mysqrt(double x)
     }
     double delta = x - (result * result);
     result = result + 0.5 * delta / result;
+
+#ifdef DEBUG
     std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
+#endif
   }
 
   return result;