You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
460 lines
12 KiB
460 lines
12 KiB
Step 2: Adding a Library
|
|
========================
|
|
|
|
At this point, we have seen how to create a basic project using CMake. In this
|
|
step, we will learn how to create and use a library in our project. We will
|
|
also see how to make the use of our library optional.
|
|
|
|
Exercise 1 - Creating a Library
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
To add a library in CMake, use the :command:`add_library` command and specify
|
|
which source files should make up the library.
|
|
|
|
Rather than placing all of the source files in one directory, we can organize
|
|
our project with one or more subdirectories. In this case, we will create a
|
|
subdirectory specifically for our library. Here, we can add a new
|
|
``CMakeLists.txt`` file and one or more source files. In the top level
|
|
``CMakeLists.txt`` file, we will use the :command:`add_subdirectory` command
|
|
to add the subdirectory to the build.
|
|
|
|
Once the library is created, it is connected to our executable target with
|
|
:command:`target_include_directories` and :command:`target_link_libraries`.
|
|
|
|
Goal
|
|
----
|
|
|
|
Add and use a library.
|
|
|
|
Helpful Resources
|
|
-----------------
|
|
|
|
* :command:`add_library`
|
|
* :command:`add_subdirectory`
|
|
* :command:`target_include_directories`
|
|
* :command:`target_link_libraries`
|
|
* :variable:`PROJECT_SOURCE_DIR`
|
|
|
|
Files to Edit
|
|
-------------
|
|
|
|
* ``CMakeLists.txt``
|
|
* ``tutorial.cxx``
|
|
* ``MathFunctions/CMakeLists.txt``
|
|
|
|
Getting Started
|
|
---------------
|
|
|
|
In this exercise, we will add a library to our project that contains our own
|
|
implementation for computing the square root of a number. The executable can
|
|
then use this library instead of the standard square root function provided by
|
|
the compiler.
|
|
|
|
For this tutorial we will put the library into a subdirectory called
|
|
``MathFunctions``. This directory already contains a header file,
|
|
``MathFunctions.h``, and a source file ``mysqrt.cxx``. We will not need to
|
|
modify either of these files. The source file has one function called
|
|
``mysqrt`` that provides similar functionality to the compiler's ``sqrt``
|
|
function.
|
|
|
|
From the ``Help/guide/tutorial/Step2`` directory, start with ``TODO 1`` and
|
|
complete through ``TODO 6``.
|
|
|
|
First, fill in the one line ``CMakeLists.txt`` in the ``MathFunctions``
|
|
subdirectory.
|
|
|
|
Next, edit the top level ``CMakeLists.txt``.
|
|
|
|
Finally, use the newly created ``MathFunctions`` library in ``tutorial.cxx``
|
|
|
|
Build and Run
|
|
-------------
|
|
|
|
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.
|
|
|
|
Below is a refresher of what that looks like from the command line:
|
|
|
|
.. code-block:: console
|
|
|
|
mkdir Step2_build
|
|
cd Step2_build
|
|
cmake ../Step2
|
|
cmake --build .
|
|
|
|
Try to use the newly built ``Tutorial`` and ensure that it is still
|
|
producing accurate square root values.
|
|
|
|
Solution
|
|
--------
|
|
|
|
In the ``CMakeLists.txt`` file in the ``MathFunctions`` directory, we create
|
|
a library target called ``MathFunctions`` with :command:`add_library`. The
|
|
source file for the library is passed as an argument to
|
|
:command:`add_library`. This looks like the following line:
|
|
|
|
.. raw:: html
|
|
|
|
<details><summary>TODO 1: Click to show/hide answer</summary>
|
|
|
|
.. literalinclude:: Step3/MathFunctions/CMakeLists.txt
|
|
:caption: TODO 1: MathFunctions/CMakeLists.txt
|
|
:name: MathFunctions/CMakeLists.txt-add_library
|
|
:language: cmake
|
|
:end-before: # TODO 1
|
|
|
|
.. raw:: html
|
|
|
|
</details>
|
|
|
|
To make use of the new library we will add an :command:`add_subdirectory`
|
|
call in the top-level ``CMakeLists.txt`` file so that the library will get
|
|
built.
|
|
|
|
.. raw:: html
|
|
|
|
<details><summary>TODO 2: Click to show/hide answer</summary>
|
|
|
|
.. code-block:: cmake
|
|
:caption: TODO 2: CMakeLists.txt
|
|
:name: CMakeLists.txt-add_subdirectory
|
|
|
|
add_subdirectory(MathFunctions)
|
|
|
|
.. raw:: html
|
|
|
|
</details>
|
|
|
|
Next, the new library target is linked to the executable target using
|
|
:command:`target_link_libraries`.
|
|
|
|
.. raw:: html
|
|
|
|
<details><summary>TODO 3: Click to show/hide answer</summary>
|
|
|
|
.. code-block:: cmake
|
|
:caption: TODO 3: CMakeLists.txt
|
|
:name: CMakeLists.txt-target_link_libraries
|
|
|
|
target_link_libraries(Tutorial PUBLIC MathFunctions)
|
|
|
|
.. raw:: html
|
|
|
|
</details>
|
|
|
|
Finally we need to specify the library's header file location. Modify
|
|
:command:`target_include_directories` to add the ``MathFunctions`` subdirectory
|
|
as an include directory so that the ``MathFunctions.h`` header file can be
|
|
found.
|
|
|
|
.. raw:: html
|
|
|
|
<details><summary>TODO 4: Click to show/hide answer</summary>
|
|
|
|
.. code-block:: cmake
|
|
:caption: TODO 4: CMakeLists.txt
|
|
:name: CMakeLists.txt-target_include_directories-step2
|
|
|
|
target_include_directories(Tutorial PUBLIC
|
|
"${PROJECT_BINARY_DIR}"
|
|
"${PROJECT_SOURCE_DIR}/MathFunctions"
|
|
)
|
|
|
|
.. raw:: html
|
|
|
|
</details>
|
|
|
|
Now let's use our library. In ``tutorial.cxx``, include ``MathFunctions.h``:
|
|
|
|
.. raw:: html
|
|
|
|
<details><summary>TODO 5: Click to show/hide answer</summary>
|
|
|
|
.. code-block:: c++
|
|
:caption: TODO 5 : tutorial.cxx
|
|
:name: tutorial.cxx-include_MathFunctions.h
|
|
|
|
#include "MathFunctions.h"
|
|
|
|
.. raw:: html
|
|
|
|
</details>
|
|
|
|
Lastly, replace ``sqrt`` with our library function ``mysqrt``.
|
|
|
|
.. raw:: html
|
|
|
|
<details><summary>TODO 6: Click to show/hide answer</summary>
|
|
|
|
.. code-block:: c++
|
|
:caption: TODO 6 : tutorial.cxx
|
|
:name: tutorial.cxx-call_mysqrt
|
|
|
|
const double outputValue = mysqrt(inputValue);
|
|
|
|
.. raw:: html
|
|
|
|
</details>
|
|
|
|
Exercise 2 - Making Our Library Optional
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Now let us make the MathFunctions library optional. While for the tutorial
|
|
there really isn't any need to do so, for larger projects this is a common
|
|
occurrence.
|
|
|
|
CMake can do this using the :command:`option` command. This gives users a
|
|
variable which they can change when configuring their cmake build. This
|
|
setting will be stored in the cache so that the user does not need to set
|
|
the value each time they run CMake on a build directory.
|
|
|
|
Goal
|
|
----
|
|
|
|
Add the option to build without ``MathFunctions``.
|
|
|
|
|
|
Helpful Resources
|
|
-----------------
|
|
|
|
* :command:`if`
|
|
* :command:`list`
|
|
* :command:`option`
|
|
* :command:`cmakedefine <configure_file>`
|
|
|
|
Files to Edit
|
|
-------------
|
|
|
|
* ``CMakeLists.txt``
|
|
* ``tutorial.cxx``
|
|
* ``TutorialConfig.h.in``
|
|
|
|
Getting Started
|
|
---------------
|
|
|
|
Start with the resulting files from Exercise 1. Complete ``TODO 7`` through
|
|
``TODO 13``.
|
|
|
|
First create a variable ``USE_MYMATH`` using the :command:`option` command
|
|
in the top-level ``CMakeLists.txt`` file. In that same file, use that option
|
|
to determine whether to build and use the ``MathFunctions`` library.
|
|
|
|
Then, update ``tutorial.cxx`` and ``TutorialConfig.h.in`` to use
|
|
``USE_MYMATH``.
|
|
|
|
Build and Run
|
|
-------------
|
|
|
|
Since we have our build directory already configured from Exercise 1, we can
|
|
rebuild by simply calling the following:
|
|
|
|
.. code-block:: console
|
|
|
|
cd ../Step2_build
|
|
cmake --build .
|
|
|
|
Next, run the ``Tutorial`` executable on a few numbers to verify that it's
|
|
still correct.
|
|
|
|
Now let's update the value of ``USE_MYMATH`` to ``OFF``. The easiest way is to
|
|
use the :manual:`cmake-gui <cmake-gui(1)>` or :manual:`ccmake <ccmake(1)>`
|
|
if you're in the terminal. Or, alternatively, if you want to change the
|
|
option from the command-line, try:
|
|
|
|
.. code-block:: console
|
|
|
|
cmake ../Step2 -DUSE_MYMATH=OFF
|
|
|
|
Now, rebuild the code with the following:
|
|
|
|
.. code-block:: console
|
|
|
|
cmake --build .
|
|
|
|
Then, run the executable again to ensure that it still works with
|
|
``USE_MYMATH`` set to ``OFF``. Which function gives better results, ``sqrt``
|
|
or ``mysqrt``?
|
|
|
|
Solution
|
|
--------
|
|
|
|
The first step is to add an option to the top-level ``CMakeLists.txt`` file.
|
|
This option will be displayed in the :manual:`cmake-gui <cmake-gui(1)>` and
|
|
:manual:`ccmake <ccmake(1)>` with a default value of ``ON`` that can be
|
|
changed by the user.
|
|
|
|
.. raw:: html
|
|
|
|
<details><summary>TODO 7: Click to show/hide answer</summary>
|
|
|
|
.. literalinclude:: Step3/CMakeLists.txt
|
|
:caption: TODO 7: CMakeLists.txt
|
|
:name: CMakeLists.txt-option
|
|
:language: cmake
|
|
:start-after: # should we use our own math functions
|
|
:end-before: # configure a header file to pass some of the CMake settings
|
|
|
|
.. raw:: html
|
|
|
|
</details>
|
|
|
|
Next, make building and linking the ``MathFunctions`` library
|
|
conditional.
|
|
|
|
Start by creating a :command:`list` of the optional library targets for our
|
|
project. At the moment, it is just ``MathFunctions``. Let's name our list
|
|
``EXTRA_LIBS``.
|
|
|
|
Similarly, we need to make a :command:`list` for the optional includes which
|
|
we will call ``EXTRA_INCLUDES``. In this list, we will ``APPEND`` the path of
|
|
the header file needed for our library.
|
|
|
|
Next, create an :command:`if` statement which checks the value of
|
|
``USE_MYMATH``. Inside the :command:`if` block, put the
|
|
:command:`add_subdirectory` command from Exercise 1 with the additional
|
|
:command:`list` commands.
|
|
|
|
When ``USE_MYMATH`` is ``ON``, the lists will be generated and will be added to
|
|
our project. When ``USE_MYMATH`` is ``OFF``, the lists stay empty. With this
|
|
strategy, we allow users to toggle ``USE_MYMATH`` to manipulate what library is
|
|
used in the build.
|
|
|
|
The top-level CMakeLists.txt file will now look like the following:
|
|
|
|
.. raw:: html
|
|
|
|
<details><summary>TODO 8: Click to show/hide answer</summary>
|
|
|
|
.. literalinclude:: Step3/CMakeLists.txt
|
|
:caption: TODO 8: CMakeLists.txt
|
|
:name: CMakeLists.txt-USE_MYMATH
|
|
:language: cmake
|
|
:start-after: # add the MathFunctions library
|
|
:end-before: # add the executable
|
|
|
|
.. raw:: html
|
|
|
|
</details>
|
|
|
|
Now that we have these two lists, we need to update
|
|
:command:`target_link_libraries` and :command:`target_include_directories` to
|
|
use them. Changing them is fairly straightforward.
|
|
|
|
For :command:`target_link_libraries`, we replace the written out
|
|
library names with ``EXTRA_LIBS``. This looks like the following:
|
|
|
|
.. raw:: html
|
|
|
|
<details><summary>TODO 9: Click to show/hide answer</summary>
|
|
|
|
.. literalinclude:: Step3/CMakeLists.txt
|
|
:caption: TODO 9: CMakeLists.txt
|
|
:name: CMakeLists.txt-target_link_libraries-EXTRA_LIBS
|
|
:language: cmake
|
|
:start-after: add_executable(Tutorial tutorial.cxx)
|
|
:end-before: # TODO 3
|
|
|
|
.. raw:: html
|
|
|
|
</details>
|
|
|
|
Then, we do the same thing with :command:`target_include_directories` and
|
|
``EXTRA_INCLUDES``.
|
|
|
|
.. raw:: html
|
|
|
|
<details><summary>TODO 10: Click to show/hide answer</summary>
|
|
|
|
.. literalinclude:: Step3/CMakeLists.txt
|
|
:caption: TODO 10 : CMakeLists.txt
|
|
:name: CMakeLists.txt-target_link_libraries-EXTRA_INCLUDES
|
|
:language: cmake
|
|
:start-after: # so that we will find TutorialConfig.h
|
|
|
|
.. raw:: html
|
|
|
|
</details>
|
|
|
|
Note that this is a classic approach when dealing with many components. We
|
|
will cover the modern approach in the Step 3 of the tutorial.
|
|
|
|
The corresponding changes to the source code are fairly straightforward.
|
|
First, in ``tutorial.cxx``, we include the ``MathFunctions.h`` header if
|
|
``USE_MYMATH`` is defined.
|
|
|
|
.. raw:: html
|
|
|
|
<details><summary>TODO 11: Click to show/hide answer</summary>
|
|
|
|
.. literalinclude:: Step3/tutorial.cxx
|
|
:caption: TODO 11 : tutorial.cxx
|
|
:name: tutorial.cxx-ifdef-include
|
|
:language: c++
|
|
:start-after: // should we include the MathFunctions header
|
|
:end-before: int main
|
|
|
|
.. raw:: html
|
|
|
|
</details>
|
|
|
|
Then, in the same file, we make ``USE_MYMATH`` control which square root
|
|
function is used:
|
|
|
|
.. raw:: html
|
|
|
|
<details><summary>TODO 12: Click to show/hide answer</summary>
|
|
|
|
.. literalinclude:: Step3/tutorial.cxx
|
|
:caption: TODO 12 : tutorial.cxx
|
|
:name: tutorial.cxx-ifdef-const
|
|
:language: c++
|
|
:start-after: // which square root function should we use?
|
|
:end-before: std::cout << "The square root of
|
|
|
|
.. raw:: html
|
|
|
|
</details>
|
|
|
|
Since the source code now requires ``USE_MYMATH`` we can add it to
|
|
``TutorialConfig.h.in`` with the following line:
|
|
|
|
.. raw:: html
|
|
|
|
<details><summary>TODO 13: Click to show/hide answer</summary>
|
|
|
|
.. literalinclude:: Step3/TutorialConfig.h.in
|
|
:caption: TODO 13 : TutorialConfig.h.in
|
|
:name: TutorialConfig.h.in-cmakedefine
|
|
:language: c++
|
|
:lines: 4
|
|
|
|
.. raw:: html
|
|
|
|
</details>
|
|
|
|
With these changes, our library is now completely optional to whoever is
|
|
building and using it.
|
|
|
|
Bonus Question
|
|
--------------
|
|
|
|
Why is it important that we configure ``TutorialConfig.h.in``
|
|
after the option for ``USE_MYMATH``? What would happen if we inverted the two?
|
|
|
|
Answer
|
|
------
|
|
|
|
.. raw:: html
|
|
|
|
<details><summary>Click to show/hide answer</summary>
|
|
|
|
We configure after because ``TutorialConfig.h.in`` uses the value of
|
|
``USE_MYMATH``. If we configure the file before
|
|
calling :command:`option`, we won't be using the expected value of
|
|
``USE_MYMATH``.
|
|
|
|
.. raw:: html
|
|
|
|
</details>
|