1 files changed, 52 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..a8e914e
--- /dev/null
+++ b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst
@@ -0,0 +1,52 @@
+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 :guide:`tutorial/Adding a Library` 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
+  :caption: MathFunctions/CMakeLists.txt
+  :name: MathFunctions/CMakeLists.txt-target_include_directories-INTERFACE
+  :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
+  :caption: CMakeLists.txt
+  :name: CMakeLists.txt-remove-EXTRA_INCLUDES
+  :language: cmake
+  :start-after: # add the MathFunctions library
+  :end-before: # add the executable
+
+And here:
+
+.. literalinclude:: Step4/CMakeLists.txt
+  :caption: CMakeLists.txt
+  :name: CMakeLists.txt-target_include_directories-remove-EXTRA_INCLUDES
+  :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.