CMake/Help/guide/tutorial/Adding Usage Requirements for a Library.rst

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.