Tutorial: Split steps into separate files

Fixes: #21737

1 files changed, 46 insertions, 0 deletions

diff --git a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst
new file mode 100644
index 0000000..a625d90
--- /dev/null
+++ b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst
@@ -0,0 +1,46 @@
+Step 3: Adding Usage Requirements for a Library
+===============================================
+
+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:
+
+  - :command:`target_compile_definitions`
+  - :command:`target_compile_options`
+  - :command:`target_include_directories`
+  - :command:`target_link_libraries`
+
+Let's refactor our code from `Adding a Library (Step 2)`_ to use the modern
+CMake approach of usage requirements. 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. Add the following lines to the end of
+``MathFunctions/CMakeLists.txt``:
+
+.. 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.txt``, here:
+
+.. literalinclude:: Step4/CMakeLists.txt
+  :language: cmake
+  :start-after: # add the MathFunctions library
+  :end-before: # add the executable
+
+And here:
+
+.. literalinclude:: Step4/CMakeLists.txt
+  :language: cmake
+  :start-after: # so that we will find TutorialConfig.h
+
+Once this is done, run the :manual:`cmake  <cmake(1)>` executable or the
+:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
+with your chosen build tool or by using ``cmake --build .`` from the build
+directory.