diff options
Diffstat (limited to 'Help/guide/tutorial')
119 files changed, 4822 insertions, 0 deletions
diff --git a/Help/guide/tutorial/A Basic Starting Point.rst b/Help/guide/tutorial/A Basic Starting Point.rst new file mode 100644 index 0000000..3dac68a --- /dev/null +++ b/Help/guide/tutorial/A Basic Starting Point.rst @@ -0,0 +1,461 @@ +Step 1: A Basic Starting Point +============================== + +Where do I start with CMake? This step will provide an introduction to some of +CMake's basic syntax, commands, and variables. As these concepts are +introduced, we will work through three exercises and create a simple CMake +project. + +Each exercise in this step will start with some background information. Then, a +goal and list of helpful resources are provided. Each file in the +``Files to Edit`` section is in the ``Step1`` directory and contains one or +more ``TODO`` comments. Each ``TODO`` represents a line or two of code to +change or add. The ``TODO`` s are intended to be completed in numerical order, +first complete ``TODO 1`` then ``TODO 2``, etc. The ``Getting Started`` +section will give some helpful hints and guide you through the exercise. Then +the ``Build and Run`` section will walk step-by-step through how to build and +test the exercise. Finally, at the end of each exercise the intended solution +is discussed. + +Also note that each step in the tutorial builds on the next. So, for example, +the starting code for ``Step2`` is the complete solution to ``Step1``. + +Exercise 1 - Building a Basic Project +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The most basic CMake project is an executable built from a single source code +file. For simple projects like this, a ``CMakeLists.txt`` file with three +commands is all that is required. + +**Note:** Although upper, lower and mixed case commands are supported by CMake, +lower case commands are preferred and will be used throughout the tutorial. + +Any project's top most CMakeLists.txt must start by specifying a minimum CMake +version using the :command:`cmake_minimum_required` command. This establishes +policy settings and ensures that the following CMake functions are run with a +compatible version of CMake. + +To start a project, we use the :command:`project` command to set the project +name. This call is required with every project and should be called soon after +:command:`cmake_minimum_required`. As we will see later, this command can +also be used to specify other project level information such as the language +or version number. + +Finally, the :command:`add_executable` command tells CMake to create an +executable using the specified source code files. + +Goal +---- + +Understand how to create a simple CMake project. + +Helpful Resources +----------------- + +* :command:`add_executable` +* :command:`cmake_minimum_required` +* :command:`project` + +Files to Edit +------------- + +* ``CMakeLists.txt`` + +Getting Started +---------------- + +The source code for ``tutorial.cxx`` is provided in the +``Help/guide/tutorial/Step1`` directory and can be used to compute the square +root of a number. This file does not need to be edited in this step. + +In the same directory is a ``CMakeLists.txt`` file which you will complete. +Start with ``TODO 1`` and work through ``TODO 3``. + +Build and Run +------------- + +Once ``TODO 1`` through ``TODO 3`` have been completed, we are ready to build +and run our project! First, 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. + +For example, from the command line we could navigate to the +``Help/guide/tutorial`` directory of the CMake source code tree and create a +build directory: + +.. code-block:: console + + mkdir Step1_build + +Next, navigate to that build directory and run +:manual:`cmake <cmake(1)>` to configure the project and generate a native build +system: + +.. code-block:: console + + cd Step1_build + cmake ../Step1 + +Then call that build system to actually compile/link the project: + +.. code-block:: console + + cmake --build . + +Finally, try to use the newly built ``Tutorial`` with these commands: + +.. code-block:: console + + Tutorial 4294967296 + Tutorial 10 + Tutorial + +Solution +-------- + +As mentioned above, a three line ``CMakeLists.txt`` is all that we need to get +up and running. The first line is to use :command:`cmake_minimum_required` to +set the CMake version as follows: + +.. raw:: html + + <details><summary>TODO 1: Click to show/hide answer</summary> + +.. literalinclude:: Step2/CMakeLists.txt + :caption: TODO 1: CMakeLists.txt + :name: CMakeLists.txt-cmake_minimum_required + :language: cmake + :end-before: # set the project name and version + +.. raw:: html + + </details> + +The next step to make a basic project is to use the :command:`project` +command as follows to set the project name: + +.. raw:: html + + <details><summary>TODO 2: Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 2: CMakeLists.txt + :name: CMakeLists.txt-project + + project(Tutorial) + +.. raw:: html + + </details> + +The last command to call for a basic project is +:command:`add_executable`. We call it as follows: + +.. raw:: html + + <details><summary>TODO 3: Click to show/hide answer</summary> + +.. literalinclude:: Step2/CMakeLists.txt + :caption: TODO 3: CMakeLists.txt + :name: CMakeLists.txt-add_executable + :language: cmake + :start-after: # add the executable + :end-before: # TODO 9: + +.. raw:: html + + </details> + +Exercise 2 - Specifying the C++ Standard +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +CMake has some special variables that are either created behind the scenes or +have meaning to CMake when set by project code. Many of these variables start +with ``CMAKE_``. Avoid this naming convention when creating variables for your +projects. Two of these special user settable variables are +:variable:`CMAKE_CXX_STANDARD` and :variable:`CMAKE_CXX_STANDARD_REQUIRED`. +These may be used together to specify the C++ standard needed to build the +project. + +Goal +---- + +Add a feature that requires C++11. + +Helpful Resources +----------------- + +* :variable:`CMAKE_CXX_STANDARD` +* :variable:`CMAKE_CXX_STANDARD_REQUIRED` +* :command:`set` + +Files to Edit +------------- + +* ``CMakeLists.txt`` +* ``tutorial.cxx`` + +Getting Started +--------------- + +Continue editing files in the ``Step1`` directory. Start with ``TODO 4`` and +complete through ``TODO 6``. + +First, edit ``tutorial.cxx`` by adding a feature that requires C++11. Then +update ``CMakeLists.txt`` to require C++11. + +Build and Run +------------- + +Let's build our project again. Since we already created a build directory and +ran CMake for Exercise 1, we can skip to the build step: + +.. code-block:: console + + cd Step1_build + cmake --build . + +Now we can try to use the newly built ``Tutorial`` with same commands as +before: + +.. code-block:: console + + Tutorial 4294967296 + Tutorial 10 + Tutorial + +Solution +-------- + +We start by adding some C++11 features to our project by replacing +``atof`` with ``std::stod`` in ``tutorial.cxx``. This looks like +the following: + +.. raw:: html + + <details><summary>TODO 4: Click to show/hide answer</summary> + +.. literalinclude:: Step2/tutorial.cxx + :caption: TODO 4: tutorial.cxx + :name: tutorial.cxx-cxx11 + :language: c++ + :start-after: // convert input to double + :end-before: // TODO 12: + +.. raw:: html + + </details> + +To complete ``TODO 5``, simply remove ``#include <cstdlib>``. + +We will need to explicitly state in the CMake code that it should use the +correct flags. One way to enable support for a specific C++ standard in CMake +is by using the :variable:`CMAKE_CXX_STANDARD` variable. For this tutorial, set +the :variable:`CMAKE_CXX_STANDARD` variable in the ``CMakeLists.txt`` file to +``11`` and :variable:`CMAKE_CXX_STANDARD_REQUIRED` to ``True``. Make sure to +add the :variable:`CMAKE_CXX_STANDARD` declarations above the call to +:command:`add_executable`. + +.. raw:: html + + <details><summary>TODO 6: Click to show/hide answer</summary> + +.. literalinclude:: Step2/CMakeLists.txt + :caption: TODO 6: CMakeLists.txt + :name: CMakeLists.txt-CXX_STANDARD + :language: cmake + :start-after: # specify the C++ standard + :end-before: # TODO 7: + +.. raw:: html + + </details> + +Exercise 3 - Adding a Version Number and Configured Header File +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sometimes it may be useful to have a variable that is defined in your +``CMakelists.txt`` file also be available in your source code. In this case, we +would like to print the project version. + +One way to accomplish this is by using a configured header file. We create an +input file with one or more variables to replace. These variables have special +syntax which looks like ``@VAR@``. +Then, we use the :command:`configure_file` command to copy the input file to a +given output file and replace these variables with the current value of ``VAR`` +in the ``CMakelists.txt`` file. + +While we could edit the version directly in the source code, using this +feature is preferred since it creates a single source of truth and avoids +duplication. + +Goal +---- + +Define and report the project's version number. + +Helpful Resources +----------------- + +* :variable:`<PROJECT-NAME>_VERSION_MAJOR` +* :variable:`<PROJECT-NAME>_VERSION_MINOR` +* :command:`configure_file` +* :command:`target_include_directories` + +Files to Edit +------------- + +* ``CMakeLists.txt`` +* ``tutorial.cxx`` + +Getting Started +--------------- + +Continue to edit files from ``Step1``. Start on ``TODO 7`` and complete through +``TODO 12``. In this exercise, we start by adding a project version number in +``CMakeLists.txt``. In that same file, use :command:`configure_file` to copy a +given input file to an output file and substitute some variable values in the +input file content. + +Next, create an input header file ``TutorialConfig.h.in`` defining version +numbers which will accept variables passed from :command:`configure_file`. + +Finally, update ``tutorial.cxx`` to print out its version number. + +Build and Run +------------- + +Let's build our project again. As before, we already created a build directory +and ran CMake so we can skip to the build step: + +.. code-block:: console + + cd Step1_build + cmake --build . + +Verify that the version number is now reported when running the executable +without any arguments. + +Solution +-------- + +In this exercise, we improve our executable by printing a version number. +While we could do this exclusively in the source code, using ``CMakeLists.txt`` +lets us maintain a single source of data for the version number. + +First, we modify the ``CMakeLists.txt`` file to use the +:command:`project` command to set both the project name and version number. +When the :command:`project` command is called, CMake defines +``Tutorial_VERSION_MAJOR`` and ``Tutorial_VERSION_MINOR`` behind the scenes. + +.. raw:: html + + <details><summary>TODO 7: Click to show/hide answer</summary> + +.. literalinclude:: Step2/CMakeLists.txt + :caption: TODO 7: CMakeLists.txt + :name: CMakeLists.txt-project-VERSION + :language: cmake + :start-after: # set the project name and version + :end-before: # specify the C++ standard + +.. raw:: html + + </details> + +Then we used :command:`configure_file` to copy the input file with the +specified CMake variables replaced: + +.. raw:: html + + <details><summary>TODO 8: Click to show/hide answer</summary> + +.. literalinclude:: Step2/CMakeLists.txt + :caption: TODO 8: CMakeLists.txt + :name: CMakeLists.txt-configure_file + :language: cmake + :start-after: # to the source code + :end-before: # TODO 8: + +.. raw:: html + + </details> + +Since the configured file will be written into the project binary +directory, we must add that directory to the list of paths to search for +include files. + +**Note:** Throughout this tutorial, we will refer to the project build and +the project binary directory interchangeably. These are the same and are not +meant to refer to a `bin/` directory. + +We used :command:`target_include_directories` to specify +where the executable target should look for include files. + +.. raw:: html + + <details><summary>TODO 9: Click to show/hide answer</summary> + +.. literalinclude:: Step2/CMakeLists.txt + :caption: TODO 9: CMakeLists.txt + :name: CMakeLists.txt-target_include_directories + :language: cmake + :start-after: # so that we will find TutorialConfig.h + +.. raw:: html + + </details> + +``TutorialConfig.h.in`` is the input header file to be configured. +When :command:`configure_file` is called from our ``CMakeLists.txt``, the +values for ``@Tutorial_VERSION_MAJOR@`` and ``@Tutorial_VERSION_MINOR@`` will +be replaced with the corresponding version numbers from the project in +``TutorialConfig.h``. + +.. raw:: html + + <details><summary>TODO 10: Click to show/hide answer</summary> + +.. literalinclude:: Step2/TutorialConfig.h.in + :caption: TODO 10: TutorialConfig.h.in + :name: TutorialConfig.h.in + :language: c++ + :end-before: // TODO 13: + +.. raw:: html + + </details> + +Next, we need to modify ``tutorial.cxx`` to include the configured header file, +``TutorialConfig.h``. + +.. raw:: html + + <details><summary>TODO 11: Click to show/hide answer</summary> + +.. code-block:: c++ + :caption: TODO 11: tutorial.cxx + + #include "TutorialConfig.h" + +.. raw:: html + + </details> + +Finally, we print out the executable name and version number by updating +``tutorial.cxx`` as follows: + +.. raw:: html + + <details><summary>TODO 12: Click to show/hide answer</summary> + +.. literalinclude:: Step2/tutorial.cxx + :caption: TODO 12 : tutorial.cxx + :name: tutorial.cxx-print-version + :language: c++ + :start-after: { + :end-before: // convert input to double + +.. raw:: html + + </details> diff --git a/Help/guide/tutorial/Adding Export Configuration.rst b/Help/guide/tutorial/Adding Export Configuration.rst new file mode 100644 index 0000000..eb14f42 --- /dev/null +++ b/Help/guide/tutorial/Adding Export Configuration.rst @@ -0,0 +1,140 @@ +Step 11: Adding Export Configuration +==================================== + +During :guide:`tutorial/Installing and Testing` of the tutorial we added the +ability for CMake to install the library and headers of the project. During +:guide:`tutorial/Packaging an Installer` we added the ability to package up +this information so it could be distributed to other people. + +The next step is to add the necessary information so that other CMake projects +can use our project, be it from a build directory, a local install or when +packaged. + +The first step is to update our :command:`install(TARGETS)` commands to not +only specify a ``DESTINATION`` but also an ``EXPORT``. The ``EXPORT`` keyword +generates a CMake file containing code to import all targets listed in the +install command from the installation tree. So let's go ahead and explicitly +``EXPORT`` the ``MathFunctions`` library by updating the ``install`` command +in ``MathFunctions/CMakeLists.txt`` to look like: + +.. literalinclude:: Complete/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-install-TARGETS-EXPORT + :language: cmake + :start-after: # install libs + +Now that we have ``MathFunctions`` being exported, we also need to explicitly +install the generated ``MathFunctionsTargets.cmake`` file. This is done by +adding the following to the bottom of the top-level ``CMakeLists.txt``: + +.. literalinclude:: Complete/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-install-EXPORT + :language: cmake + :start-after: # install the configuration targets + :end-before: include(CMakePackageConfigHelpers) + +At this point you should try and run CMake. If everything is setup properly +you will see that CMake will generate an error that looks like: + +.. code-block:: console + + Target "MathFunctions" INTERFACE_INCLUDE_DIRECTORIES property contains + path: + + "/Users/robert/Documents/CMakeClass/Tutorial/Step11/MathFunctions" + + which is prefixed in the source directory. + +What CMake is trying to say is that during generating the export information +it will export a path that is intrinsically tied to the current machine and +will not be valid on other machines. The solution to this is to update the +``MathFunctions`` :command:`target_include_directories` to understand that it +needs different ``INTERFACE`` locations when being used from within the build +directory and from an install / package. This means converting the +:command:`target_include_directories` call for ``MathFunctions`` to look like: + +.. literalinclude:: Step12/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-target_include_directories + :language: cmake + :start-after: # to find MathFunctions.h, while we don't. + :end-before: # should we use our own math functions + +Once this has been updated, we can re-run CMake and verify that it doesn't +warn anymore. + +At this point, we have CMake properly packaging the target information that is +required but we will still need to generate a ``MathFunctionsConfig.cmake`` so +that the CMake :command:`find_package` command can find our project. So let's go +ahead and add a new file to the top-level of the project called +``Config.cmake.in`` with the following contents: + +.. literalinclude:: Step12/Config.cmake.in + :caption: Config.cmake.in + :name: Config.cmake.in + +Then, to properly configure and install that file, add the following to the +bottom of the top-level ``CMakeLists.txt``: + +.. literalinclude:: Step12/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-install-Config.cmake + :language: cmake + :start-after: # install the configuration targets + :end-before: # generate the config file + + +Next, we execute the :command:`configure_package_config_file`. This command +will configure a provided file but with a few specific differences from the +standard :command:`configure_file` way. +To properly utilize this function, the input file should have a single line +with the text ``@PACKAGE_INIT@`` in addition to the content that is desired. +That variable will be replaced with a block of code which turns set values into +relative paths. These values which are new can be referenced by the same name +but prepended with a ``PACKAGE_`` prefix. + +.. literalinclude:: Step12/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-configure-package-config.cmake + :language: cmake + :start-after: # install the configuration targets + :end-before: # generate the version file + +The :command:`write_basic_package_version_file` is next. This command writes +a file which is used by the "find_package" document the version and +compatibility of the desired package. Here, we use the ``Tutorial_VERSION_*`` +variables and say that it is compatible with ``AnyNewerVersion``, which +denotes that this version or any higher one are compatible with the requested +version. + +.. literalinclude:: Step12/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-basic-version-file.cmake + :language: cmake + :start-after: # generate the version file + :end-before: # install the generated configuration files + +Finally, set both generated files to be installed: + +.. literalinclude:: Step12/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-install-configured-files.cmake + :language: cmake + :start-after: # install the generated configuration files + :end-before: # generate the export + +At this point, we have generated a relocatable CMake Configuration for our +project that can be used after the project has been installed or packaged. If +we want our project to also be used from a build directory we only have to add +the following to the bottom of the top level ``CMakeLists.txt``: + +.. literalinclude:: Step12/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-export + :language: cmake + :start-after: # needs to be after the install(TARGETS ) command + +With this export call we now generate a ``Targets.cmake``, allowing the +configured ``MathFunctionsConfig.cmake`` in the build directory to be used by +other projects, without needing it to be installed. diff --git a/Help/guide/tutorial/Adding Generator Expressions.rst b/Help/guide/tutorial/Adding Generator Expressions.rst new file mode 100644 index 0000000..6f9714e --- /dev/null +++ b/Help/guide/tutorial/Adding Generator Expressions.rst @@ -0,0 +1,306 @@ +Step 4: Adding Generator Expressions +===================================== + +:manual:`Generator expressions <cmake-generator-expressions(7)>` are evaluated +during build system generation to produce information specific to each build +configuration. + +:manual:`Generator expressions <cmake-generator-expressions(7)>` are allowed in +the context of many target properties, such as :prop_tgt:`LINK_LIBRARIES`, +:prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and others. +They may also be used when using commands to populate those properties, such as +:command:`target_link_libraries`, :command:`target_include_directories`, +:command:`target_compile_definitions` and others. + +:manual:`Generator expressions <cmake-generator-expressions(7)>` may be used +to enable conditional linking, conditional definitions used when compiling, +conditional include directories and more. The conditions may be based on the +build configuration, target properties, platform information or any other +queryable information. + +There are different types of +:manual:`generator expressions <cmake-generator-expressions(7)>` including +Logical, Informational, and Output expressions. + +Logical expressions are used to create conditional output. The basic +expressions are the ``0`` and ``1`` expressions. A ``$<0:...>`` results in the +empty string, and ``<1:...>`` results in the content of ``...``. They can also +be nested. + +Exercise 1 - Setting the C++ Standard with Interface Libraries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before we use :manual:`generator expressions <cmake-generator-expressions(7)>` +let's refactor our existing code to use an ``INTERFACE`` library. We will +use that library in the next step to demonstrate a common use for +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +Goal +---- + +Add an ``INTERFACE`` library target to specify the required C++ standard. + +Helpful Resources +----------------- + +* :command:`add_library` +* :command:`target_compile_features` +* :command:`target_link_libraries` + +Files to Edit +------------- + +* ``CMakeLists.txt`` +* ``MathFunctions/CMakeLists.txt`` + +Getting Started +--------------- + +In this exercise, we will refactor our code to use an ``INTERFACE`` library to +specify the C++ standard. + +The starting source code is provided in the ``Step4`` directory. In this +exercise, complete ``TODO 1`` through ``TODO 3``. + +Start by editing the top level ``CMakeLists.txt`` file. Construct an +``INTERFACE`` library target called ``tutorial_compiler_flags`` and +specify ``cxx_std_11`` as a target compiler feature. + +Modify ``CMakeLists.txt`` and ``MathFunctions/CMakeLists.txt`` so that all +targets have a :command:`target_link_libraries` call to +``tutorial_compiler_flags``. + +Build and Run +------------- + +Make a new directory called ``Step4_build``, 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. + +Here's a refresher of what that looks like from the command line: + +.. code-block:: console + + mkdir Step4_build + cd Step4_build + cmake ../Step4 + cmake --build . + +Next, use the newly built ``Tutorial`` and verify that it is working as +expected. + +Solution +-------- + +Let's update our code from the previous step to use interface libraries +to set our C++ requirements. + +To start, we need to remove the two :command:`set` calls on the variables +:variable:`CMAKE_CXX_STANDARD` and :variable:`CMAKE_CXX_STANDARD_REQUIRED`. +The specific lines to remove are as follows: + +.. literalinclude:: Step4/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-CXX_STANDARD-variable-remove + :language: cmake + :start-after: # specify the C++ standard + :end-before: # TODO 5: Create helper variables + +Next, we need to create an interface library, ``tutorial_compiler_flags``. And +then use :command:`target_compile_features` to add the compiler feature +``cxx_std_11``. + + +.. raw:: html + + <details><summary>TODO 1: Click to show/hide answer</summary> + +.. literalinclude:: Step5/CMakeLists.txt + :caption: TODO 1: CMakeLists.txt + :name: CMakeLists.txt-cxx_std-feature + :language: cmake + :start-after: # specify the C++ standard + :end-before: # add compiler warning flags just + +.. raw:: html + + </details> + +Finally, with our interface library set up, we need to link our +executable ``Target`` and our ``MathFunctions`` library to our new +``tutorial_compiler_flags`` library. Respectively, the code will look like +this: + +.. raw:: html + + <details><summary>TODO 2: Click to show/hide answer</summary> + +.. literalinclude:: Step5/CMakeLists.txt + :caption: TODO 2: CMakeLists.txt + :name: CMakeLists.txt-target_link_libraries-step4 + :language: cmake + :start-after: add_executable(Tutorial tutorial.cxx) + :end-before: # add the binary tree to the search path for include file + +.. raw:: html + + </details> + +and this: + +.. raw:: html + + <details><summary>TODO 3: Click to show/hide answer</summary> + +.. literalinclude:: Step5/MathFunctions/CMakeLists.txt + :caption: TODO 3: MathFunctions/CMakeLists.txt + :name: MathFunctions-CMakeLists.txt-target_link_libraries-step4 + :language: cmake + :start-after: # link our compiler flags interface library + :end-before: # TODO 1 + +.. raw:: html + + </details> + +With this, all of our code still requires C++ 11 to build. Notice +though that with this method, it gives us the ability to be specific about +which targets get specific requirements. In addition, we create a single +source of truth in our interface library. + +Exercise 2 - Adding Compiler Warning Flags with Generator Expressions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A common usage of +:manual:`generator expressions <cmake-generator-expressions(7)>` is to +conditionally add compiler flags, such as those for language levels or +warnings. A nice pattern is to associate this information to an ``INTERFACE`` +target allowing this information to propagate. + +Goal +---- + +Add compiler warning flags when building but not for installed versions. + +Helpful Resources +----------------- + +* :manual:`cmake-generator-expressions(7)` +* :command:`cmake_minimum_required` +* :command:`set` +* :command:`target_compile_options` + +Files to Edit +------------- + +* ``CMakeLists.txt`` + +Getting Started +--------------- + +Start with the resulting files from Exercise 1. Complete ``TODO 4`` through +``TODO 7``. + +First, in the top level ``CMakeLists.txt`` file, we need to set the +:command:`cmake_minimum_required` to ``3.15``. In this exercise we are going +to use a generator expression which was introduced in CMake 3.15. + +Next we add the desired compiler warning flags that we want for our project. +As warning flags vary based on the compiler, we use the +``COMPILE_LANG_AND_ID`` generator expression to control which flags to apply +given a language and a set of compiler ids. + +Build and Run +------------- + +Since we have our build directory already configured from Exercise 1, simply +rebuild our code by calling the following: + +.. code-block:: console + + cd Step4_build + cmake --build . + +Solution +-------- + +Update the :command:`cmake_minimum_required` to require at least CMake +version ``3.15``: + +.. raw:: html + + <details><summary>TODO 4: Click to show/hide answer</summary> + +.. literalinclude:: Step5/CMakeLists.txt + :caption: TODO 4: CMakeLists.txt + :name: MathFunctions-CMakeLists.txt-minimum-required-step4 + :language: cmake + :end-before: # set the project name and version + +.. raw:: html + + </details> + +Next we determine which compiler our system is currently using to build +since warning flags vary based on the compiler we use. This is done with +the ``COMPILE_LANG_AND_ID`` generator expression. We set the result in the +variables ``gcc_like_cxx`` and ``msvc_cxx`` as follows: + +.. raw:: html + + <details><summary>TODO 5: Click to show/hide answer</summary> + +.. literalinclude:: Step5/CMakeLists.txt + :caption: TODO 5: CMakeLists.txt + :name: CMakeLists.txt-compile_lang_and_id + :language: cmake + :start-after: # the BUILD_INTERFACE genex + :end-before: target_compile_options(tutorial_compiler_flags INTERFACE + +.. raw:: html + + </details> + +Next we add the desired compiler warning flags that we want for our project. +Using our variables ``gcc_like_cxx`` and ``msvc_cxx``, we can use another +generator expression to apply the respective flags only when the variables are +true. We use :command:`target_compile_options` to apply these flags to our +interface library. + +.. raw:: html + + <details><summary>TODO 6: Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 6: CMakeLists.txt + :name: CMakeLists.txt-compile_flags + + target_compile_options(tutorial_compiler_flags INTERFACE + "$<${gcc_like_cxx}:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>" + "$<${msvc_cxx}:-W3>" + ) + +.. raw:: html + + </details> + +Lastly, we only want these warning flags to be used during builds. Consumers +of our installed project should not inherit our warning flags. To specify +this, we wrap our flags in a generator expression using the ``BUILD_INTERFACE`` +condition. The resulting full code looks like the following: + +.. raw:: html + + <details><summary>TODO 7: Click to show/hide answer</summary> + +.. literalinclude:: Step5/CMakeLists.txt + :caption: TODO 7: CMakeLists.txt + :name: CMakeLists.txt-target_compile_options-genex + :language: cmake + :start-after: set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") + :end-before: # should we use our own math functions + +.. raw:: html + + </details> diff --git a/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst b/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst new file mode 100644 index 0000000..45d5976 --- /dev/null +++ b/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst @@ -0,0 +1,75 @@ +Step 6: Adding Support for a Testing Dashboard +============================================== + +Adding support for submitting our test results to a dashboard is simple. We +already defined a number of tests for our project in +:ref:`Testing Support <Tutorial Testing Support>`. Now we just have to run +those tests and submit them to a dashboard. To include support for dashboards +we include the :module:`CTest` module in our top-level ``CMakeLists.txt``. + +Replace: + +.. literalinclude:: Step6/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-enable_testing-remove + :language: cmake + :start-after: # enable testing + :end-before: # does the application run + +With: + +.. literalinclude:: Step7/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-include-CTest + :language: cmake + :start-after: # enable testing + :end-before: # does the application run + +The :module:`CTest` module will automatically call ``enable_testing()``, so we +can remove it from our CMake files. + +We will also need to acquire a ``CTestConfig.cmake`` file to be placed in the +top-level directory where we can specify information to CTest about the +project. It contains: + +* The project name + +* The project "Nightly" start time + + * The time when a 24 hour "day" starts for this project. + +* The URL of the CDash instance where the submission's generated documents + will be sent + +One has been provided for you in this directory. It would normally be +downloaded from the ``Settings`` page of the project on the CDash +instance that will host and display the test results. Once downloaded from +CDash, the file should not be modified locally. + +.. literalinclude:: Step7/CTestConfig.cmake + :caption: CTestConfig.cmake + :name: CTestConfig.cmake + :language: cmake + +The :manual:`ctest <ctest(1)>` executable will read in this file when it runs. +To create a simple dashboard you can run the :manual:`cmake <cmake(1)>` +executable or the :manual:`cmake-gui <cmake-gui(1)>` to configure the project, +but do not build it yet. Instead, change directory to the binary tree, and then +run: + +.. code-block:: console + + ctest [-VV] -D Experimental + +Remember, for multi-config generators (e.g. Visual Studio), the configuration +type must be specified: + +.. code-block:: console + + ctest [-VV] -C Debug -D Experimental + +Or, from an IDE, build the ``Experimental`` target. + +The :manual:`ctest <ctest(1)>` executable will build and test the project and +submit the results to Kitware's public dashboard: +https://my.cdash.org/index.php?project=CMakeTutorial. diff --git a/Help/guide/tutorial/Adding System Introspection.rst b/Help/guide/tutorial/Adding System Introspection.rst new file mode 100644 index 0000000..ba91df4 --- /dev/null +++ b/Help/guide/tutorial/Adding System Introspection.rst @@ -0,0 +1,59 @@ +Step 7: Adding System Introspection +=================================== + +Let us consider adding some code to our project that depends on features the +target platform may not have. For this example, we will add some code that +depends on whether or not the target platform has the ``log`` and ``exp`` +functions. Of course almost every platform has these functions but for this +tutorial assume that they are not common. + +If the platform has ``log`` and ``exp`` then we will use them to compute the +square root in the ``mysqrt`` function. We first test for the availability of +these functions using the :module:`CheckCXXSourceCompiles` module in +``MathFunctions/CMakeLists.txt``. + +Add the checks for ``log`` and ``exp`` to ``MathFunctions/CMakeLists.txt``, +after the call to :command:`target_include_directories`: + +.. literalinclude:: Step8/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-check_cxx_source_compiles + :language: cmake + :start-after: # to find MathFunctions.h, while we don't. + :end-before: # add compile definitions + +If available, use :command:`target_compile_definitions` to specify +``HAVE_LOG`` and ``HAVE_EXP`` as ``PRIVATE`` compile definitions. + +.. literalinclude:: Step8/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-target_compile_definitions + :language: cmake + :start-after: # add compile definitions + :end-before: # install libs + +If ``log`` and ``exp`` are available on the system, then we will use them to +compute the square root in the ``mysqrt`` function. Add the following code to +the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (don't forget the +``#endif`` before returning the result!): + +.. literalinclude:: Step8/MathFunctions/mysqrt.cxx + :caption: MathFunctions/mysqrt.cxx + :name: MathFunctions/mysqrt.cxx-ifdef + :language: c++ + :start-after: // if we have both log and exp then use them + :end-before: // do ten iterations + +We will also need to modify ``mysqrt.cxx`` to include ``cmath``. + +.. literalinclude:: Step8/MathFunctions/mysqrt.cxx + :caption: MathFunctions/mysqrt.cxx + :name: MathFunctions/mysqrt.cxx-include-cmath + :language: c++ + :end-before: #include <iostream> + +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 and run the Tutorial executable. + +Which function gives better results now, ``sqrt`` or ``mysqrt``? 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..4aef050 --- /dev/null +++ b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst @@ -0,0 +1,147 @@ +Step 3: Adding Usage Requirements for a Library +=============================================== + +Exercise 1 - Adding Usage Requirements for a Library +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Usage requirements <Target Usage Requirements>` of a target parameters +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_directories` +* :command:`target_link_options` +* :command:`target_precompile_headers` +* :command:`target_sources` + + +Goal +---- + +Add usage requirements for a library. + +Helpful Materials +----------------- + +* :variable:`CMAKE_CURRENT_SOURCE_DIR` + +Files to Edit +------------- + +* ``MathFunctions/CMakeLists.txt`` +* ``CMakeLists.txt`` + +Getting Started +--------------- + +In this exercise, we will refactor our code from +:guide:`tutorial/Adding a Library` to use the modern CMake approach. We will +let our library define its own usage requirements so they are passed +transitively to other targets as necessary. In this case, ``MathFunctions`` +will specify any needed include directories itself. Then, the consuming target +``Tutorial`` simply needs to link to ``MathFunctions`` and not worry about +any additional include directories. + +The starting source code is provided in the ``Step3`` directory. In this +exercise, complete ``TODO 1`` through ``TODO 3``. + +First, add a call to :command:`target_include_directories` in +``MathFunctions/CMakeLists``. Remember that +:variable:`CMAKE_CURRENT_SOURCE_DIR` is the path to the source directory +currently being processed. + +Then, update (and simplify!) the call to +:command:`target_include_directories` in the top-level ``CMakeLists.txt``. + +Build and Run +------------- + +Make a new directory called ``Step3_build``, 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 :option:`cmake --build . <cmake --build>` from the build directory. +Here's a refresher of what that looks like from the command line: + +.. code-block:: console + + mkdir Step3_build + cd Step3_build + cmake ../Step3 + cmake --build . + +Next, use the newly built ``Tutorial`` and verify that it is working as +expected. + +Solution +-------- + +Let's update the code from the previous step to use the modern CMake +approach of usage requirements. + +We want to state that anybody linking to ``MathFunctions`` needs to include +the current source directory, while ``MathFunctions`` itself doesn't. This +can be expressed with an ``INTERFACE`` usage requirement. Remember +``INTERFACE`` means things that consumers require but the producer doesn't. + +At the end of ``MathFunctions/CMakeLists.txt``, use +:command:`target_include_directories` with the ``INTERFACE`` keyword, as +follows: + +.. raw:: html + + <details><summary>TODO 1: Click to show/hide answer</summary> + +.. literalinclude:: Step4/MathFunctions/CMakeLists.txt + :caption: TODO 1: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-target_include_directories-INTERFACE + :language: cmake + :start-after: # to find MathFunctions.h + :end-before: # TODO 3: Link to + +.. raw:: html + + </details> + +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: + +.. raw:: html + + <details><summary>TODO 2: Click to show/hide answer</summary> + +.. literalinclude:: Step4/CMakeLists.txt + :caption: TODO 2: CMakeLists.txt + :name: CMakeLists.txt-remove-EXTRA_INCLUDES + :language: cmake + :start-after: # add the MathFunctions library + :end-before: # add the executable + +.. raw:: html + + </details> + +And here: + +.. raw:: html + + <details><summary>TODO 3: Click to show/hide answer</summary> + +.. literalinclude:: Step4/CMakeLists.txt + :caption: TODO 3: CMakeLists.txt + :name: CMakeLists.txt-target_include_directories-remove-EXTRA_INCLUDES + :language: cmake + :start-after: # so that we will find TutorialConfig.h + +.. raw:: html + + </details> + +Notice that with this technique, the only thing our executable target does to +use our library is call :command:`target_link_libraries` with the name +of the library target. In larger projects, the classic method of specifying +library dependencies manually becomes very complicated very quickly. diff --git a/Help/guide/tutorial/Adding a Custom Command and Generated File.rst b/Help/guide/tutorial/Adding a Custom Command and Generated File.rst new file mode 100644 index 0000000..b1f9840 --- /dev/null +++ b/Help/guide/tutorial/Adding a Custom Command and Generated File.rst @@ -0,0 +1,85 @@ +Step 8: Adding a Custom Command and Generated File +================================================== + +Suppose, for the purpose of this tutorial, we decide that we never want to use +the platform ``log`` and ``exp`` functions and instead would like to +generate a table of precomputed values to use in the ``mysqrt`` function. +In this section, we will create the table as part of the build process, +and then compile that table into our application. + +First, let's remove the check for the ``log`` and ``exp`` functions in +``MathFunctions/CMakeLists.txt``. Then remove the check for ``HAVE_LOG`` and +``HAVE_EXP`` from ``mysqrt.cxx``. At the same time, we can remove +:code:`#include <cmath>`. + +In the ``MathFunctions`` subdirectory, a new source file named +``MakeTable.cxx`` has been provided to generate the table. + +After reviewing the file, we can see that the table is produced as valid C++ +code and that the output filename is passed in as an argument. + +The next step is to add the appropriate commands to the +``MathFunctions/CMakeLists.txt`` file to build the MakeTable executable and +then run it as part of the build process. A few commands are needed to +accomplish this. + +First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for +``MakeTable`` is added as any other executable would be added. + +.. literalinclude:: Step9/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-add_executable-MakeTable + :language: cmake + :start-after: # first we add the executable that generates the table + :end-before: # add the command to generate the source code + +Then we add a custom command that specifies how to produce ``Table.h`` +by running MakeTable. + +.. literalinclude:: Step9/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-add_custom_command-Table.h + :language: cmake + :start-after: # add the command to generate the source code + :end-before: # add the main library + +Next we have to let CMake know that ``mysqrt.cxx`` depends on the generated +file ``Table.h``. This is done by adding the generated ``Table.h`` to the list +of sources for the library MathFunctions. + +.. literalinclude:: Step9/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-add_library-Table.h + :language: cmake + :start-after: # add the main library + :end-before: # state that anybody linking + +We also have to add the current binary directory to the list of include +directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``. + +.. literalinclude:: Step9/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-target_include_directories-Table.h + :language: cmake + :start-after: # state that we depend on our bin + :end-before: # install libs + +Now let's use the generated table. First, modify ``mysqrt.cxx`` to include +``Table.h``. Next, we can rewrite the ``mysqrt`` function to use the table: + +.. literalinclude:: Step9/MathFunctions/mysqrt.cxx + :caption: MathFunctions/mysqrt.cxx + :name: MathFunctions/mysqrt.cxx + :language: c++ + :start-after: // a hack square root calculation using simple operations + +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. + +When this project is built it will first build the ``MakeTable`` executable. +It will then run ``MakeTable`` to produce ``Table.h``. Finally, it will +compile ``mysqrt.cxx`` which includes ``Table.h`` to produce the +``MathFunctions`` library. + +Run the Tutorial executable and verify that it is using the table. diff --git a/Help/guide/tutorial/Adding a Library.rst b/Help/guide/tutorial/Adding a Library.rst new file mode 100644 index 0000000..a56c327 --- /dev/null +++ b/Help/guide/tutorial/Adding a Library.rst @@ -0,0 +1,459 @@ +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> diff --git a/Help/guide/tutorial/Complete/CMakeLists.txt b/Help/guide/tutorial/Complete/CMakeLists.txt new file mode 100644 index 0000000..3cdaaae --- /dev/null +++ b/Help/guide/tutorial/Complete/CMakeLists.txt @@ -0,0 +1,126 @@ +cmake_minimum_required(VERSION 3.15) + +# set the project name and version +project(Tutorial VERSION 1.0) + +set(CMAKE_DEBUG_POSTFIX d) + +add_library(tutorial_compiler_flags INTERFACE) +target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) + +# add compiler warning flags just when building this project via +# the BUILD_INTERFACE genex +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") +set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") +target_compile_options(tutorial_compiler_flags INTERFACE + "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" + "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" +) + +# control where the static and shared libraries are built so that on windows +# we don't need to tinker with the path to run the executable +set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") + +option(BUILD_SHARED_LIBS "Build using shared libraries" ON) + +if(APPLE) + set(CMAKE_INSTALL_RPATH "@executable_path/../lib") +elseif(UNIX) + set(CMAKE_INSTALL_RPATH "$ORIGIN/../lib") +endif() + +# configure a header file to pass the version number only +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +add_subdirectory(MathFunctions) + +# add the executable +add_executable(Tutorial tutorial.cxx) +set_target_properties(Tutorial PROPERTIES DEBUG_POSTFIX ${CMAKE_DEBUG_POSTFIX}) + +target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +enable_testing() + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction() + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") +do_test(Tutorial 0.0001 "0.0001 is 0.01") + +# setup installer +include(InstallRequiredSystemLibraries) +set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") +set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") +set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +set(CPACK_SOURCE_GENERATOR "TGZ") +include(CPack) + +# install the configuration targets +install(EXPORT MathFunctionsTargets + FILE MathFunctionsTargets.cmake + DESTINATION lib/cmake/MathFunctions +) + +include(CMakePackageConfigHelpers) +# generate the config file that is includes the exports +configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" + INSTALL_DESTINATION "lib/cmake/example" + NO_SET_AND_CHECK_MACRO + NO_CHECK_REQUIRED_COMPONENTS_MACRO + ) +# generate the version file for the config file +write_basic_package_version_file( + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake" + VERSION "${Tutorial_VERSION_MAJOR}.${Tutorial_VERSION_MINOR}" + COMPATIBILITY AnyNewerVersion +) + +# install the configuration file +install(FILES + ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake + DESTINATION lib/cmake/MathFunctions + ) + +# generate the export targets for the build tree +# needs to be after the install(TARGETS ) command +export(EXPORT MathFunctionsTargets + FILE "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsTargets.cmake" +) diff --git a/Help/guide/tutorial/Complete/CTestConfig.cmake b/Help/guide/tutorial/Complete/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Complete/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Complete/Config.cmake.in b/Help/guide/tutorial/Complete/Config.cmake.in new file mode 100644 index 0000000..17cbabd --- /dev/null +++ b/Help/guide/tutorial/Complete/Config.cmake.in @@ -0,0 +1,4 @@ + +@PACKAGE_INIT@ + +include ( "${CMAKE_CURRENT_LIST_DIR}/MathFunctionsTargets.cmake" ) diff --git a/Help/guide/tutorial/Complete/License.txt b/Help/guide/tutorial/Complete/License.txt new file mode 100644 index 0000000..85760e5 --- /dev/null +++ b/Help/guide/tutorial/Complete/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step9... diff --git a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..d256db2 --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt @@ -0,0 +1,68 @@ +# add the library that runs +add_library(MathFunctions MathFunctions.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE + $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}> + $<INSTALL_INTERFACE:include> + ) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if(USE_MYMATH) + + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # first we add the executable that generates the table + add_executable(MakeTable MakeTable.cxx) + target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) + + # add the command to generate the source code + add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + + # state that we depend on our binary dir to find Table.h + target_include_directories(SqrtLibrary PRIVATE + ${CMAKE_CURRENT_BINARY_DIR} + ) + + # state that SqrtLibrary need PIC when the default is shared libraries + set_target_properties(SqrtLibrary PROPERTIES + POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} + ) + + target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() + +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) + +# define the symbol stating we are using the declspec(dllexport) when +# building on windows +target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH") + +# setup the version numbering +set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0") +set_property(TARGET MathFunctions PROPERTY SOVERSION "1") + +# install libs +set(installable_libs MathFunctions tutorial_compiler_flags) +if(TARGET SqrtLibrary) + list(APPEND installable_libs SqrtLibrary) +endif() +install(TARGETS ${installable_libs} + EXPORT MathFunctionsTargets + DESTINATION lib) +# install include headers +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Complete/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Complete/MathFunctions/MakeTable.cxx new file mode 100644 index 0000000..ee58556 --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..0145300 --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ + +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..3fb547b --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.h @@ -0,0 +1,14 @@ + +#if defined(_WIN32) +# if defined(EXPORTING_MYMATH) +# define DECLSPEC __declspec(dllexport) +# else +# define DECLSPEC __declspec(dllimport) +# endif +#else // non windows +# define DECLSPEC +#endif + +namespace mathfunctions { +double DECLSPEC sqrt(double x); +} diff --git a/Help/guide/tutorial/Complete/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Complete/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..8153f18 --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/mysqrt.cxx @@ -0,0 +1,37 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +namespace mathfunctions { +namespace detail { +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + std::cout << "Use the table to help find an initial value " << std::endl; + result = sqrtTable[static_cast<int>(x)]; + } + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} +} +} diff --git a/Help/guide/tutorial/Complete/MathFunctions/mysqrt.h b/Help/guide/tutorial/Complete/MathFunctions/mysqrt.h new file mode 100644 index 0000000..e1c42ef --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/mysqrt.h @@ -0,0 +1,6 @@ + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Complete/MultiCPackConfig.cmake b/Help/guide/tutorial/Complete/MultiCPackConfig.cmake new file mode 100644 index 0000000..c2583df --- /dev/null +++ b/Help/guide/tutorial/Complete/MultiCPackConfig.cmake @@ -0,0 +1,6 @@ +include("release/CPackConfig.cmake") + +set(CPACK_INSTALL_CMAKE_PROJECTS + "debug;Tutorial;ALL;/" + "release;Tutorial;ALL;/" + ) diff --git a/Help/guide/tutorial/Complete/TutorialConfig.h.in b/Help/guide/tutorial/Complete/TutorialConfig.h.in new file mode 100644 index 0000000..7e4d7fa --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialConfig.h.in @@ -0,0 +1,3 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ diff --git a/Help/guide/tutorial/Complete/tutorial.cxx b/Help/guide/tutorial/Complete/tutorial.cxx new file mode 100644 index 0000000..a4f44d5 --- /dev/null +++ b/Help/guide/tutorial/Complete/tutorial.cxx @@ -0,0 +1,26 @@ +// A simple program that computes the square root of a number +#include <iostream> +#include <string> + +#include "MathFunctions.h" +#include "TutorialConfig.h" + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + const double outputValue = mathfunctions::sqrt(inputValue); + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Installing and Testing.rst b/Help/guide/tutorial/Installing and Testing.rst new file mode 100644 index 0000000..fa13040 --- /dev/null +++ b/Help/guide/tutorial/Installing and Testing.rst @@ -0,0 +1,311 @@ +Step 5: Installing and Testing +============================== + +.. _`Tutorial Testing Support`: + +Exercise 1 - Install Rules +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Often, it is not enough to only build an executable, it should also be +installable. With CMake, we can specify install rules using the +:command:`install` command. Supporting local installations for your builds in +CMake is often as simple as specifying an install location and the targets and +files to be installed. + +Goal +---- + +Install the ``Tutorial`` executable and the ``MathFunctions`` library. + +Helpful Materials +----------------- + +* :command:`install` + +Files to Edit +------------- + +* ``MathFunctions/CMakeLists.txt`` +* ``CMakeLists.txt`` + +Getting Started +--------------- + +The starting code is provided in the ``Step5`` directory. In this +exercise, complete ``TODO 1`` through ``TODO 4``. + +First, update ``MathFunctions/CMakeLists.txt`` to install the +``MathFunctions`` and ``tutorial_compiler_flags`` libraries to the ``lib`` +directory. In that same file, specify the install rules needed to install +``MathFunctions.h`` to the ``include`` directory. + +Then, update the top level ``CMakeLists.txt`` to install +the ``Tutorial`` executable to the ``bin`` directory. Lastly, any header files +should be installed to the ``include`` directory. Remember that +``TutorialConfig.h`` is in the :variable:`PROJECT_BINARY_DIR`. + +Build and Run +------------- + +Make a new directory called ``Step5_build``. 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. + +Then, run the install step by using the :option:`--install <cmake --install>` +option of the :manual:`cmake <cmake(1)>` command (introduced in 3.15, older +versions of CMake must use ``make install``) from the command line. This step +will install the appropriate header files, libraries, and executables. +For example: + +.. code-block:: console + + cmake --install . + +For multi-configuration tools, don't forget to use the +:option:`--config <cmake--build --config>` argument to specify the configuration. + +.. code-block:: console + + cmake --install . --config Release + +If using an IDE, simply build the ``INSTALL`` target. You can build the same +install target from the command line like the following: + +.. code-block:: console + + cmake --build . --target install --config Debug + +The CMake variable :variable:`CMAKE_INSTALL_PREFIX` is used to determine the +root of where the files will be installed. If using the :option:`cmake --install` +command, the installation prefix can be overridden via the +:option:`--prefix <cmake--install --prefix>` argument. For example: + +.. code-block:: console + + cmake --install . --prefix "/home/myuser/installdir" + +Navigate to the install directory and verify that the installed ``Tutorial`` +runs. + +Solution +-------- + +The install rules for our project are fairly simple: + +* For ``MathFunctions``, we want to install the libraries and header file to + the ``lib`` and ``include`` directories respectively. + +* For the ``Tutorial`` executable, we want to install the executable and + configured header file to the ``bin`` and ``include`` directories + respectively. + +So to the end of ``MathFunctions/CMakeLists.txt`` we add: + +.. raw:: html + + <details><summary>TODO 1: Click to show/hide answer</summary> + +.. literalinclude:: Step6/MathFunctions/CMakeLists.txt + :caption: TODO 1: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-install-TARGETS + :language: cmake + :start-after: # install libs + :end-before: # install include headers + +.. raw:: html + + </details> + +and + +.. raw:: html + + <details><summary>TODO 2: Click to show/hide answer</summary> + +.. literalinclude:: Step6/MathFunctions/CMakeLists.txt + :caption: TODO 2: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-install-headers + :language: cmake + :start-after: # install include headers + +.. raw:: html + + </details> + +The install rules for the ``Tutorial`` executable and configured header file +are similar. To the end of the top-level ``CMakeLists.txt`` we add: + +.. raw:: html + + <details><summary>TODO 3,4: Click to show/hide answer</summary> + +.. literalinclude:: Step6/CMakeLists.txt + :caption: CMakeLists.txt + :name: TODO 3,4: CMakeLists.txt-install-TARGETS + :language: cmake + :start-after: # add the install targets + :end-before: # enable testing + +.. raw:: html + + </details> + +That is all that is needed to create a basic local +install of the tutorial. + +Exercise 2 - Testing Support +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +CTest offers a way to easily manage tests for your project. Tests can be +added through the :command:`add_test` command. Although it is not +explicitly covered in this tutorial, there is a lot of compatibility +between CTest and other testing frameworks such as :module:`GoogleTest`. + +Goal +---- + +Create unit tests for our executable using CTest. + +Helpful Materials +----------------- + +* :command:`enable_testing` +* :command:`add_test` +* :command:`function` +* :command:`set_tests_properties` +* :manual:`ctest <ctest(1)>` + +Files to Edit +------------- + +* ``CMakeLists.txt`` + +Getting Started +--------------- + +The starting source code is provided in the ``Step5`` directory. In this +exercise, complete ``TODO 5`` through ``TODO 9``. + +First, we need to enable testing. Next, begin adding tests to our project +using :command:`add_test`. We will work through adding 3 simple tests and +then you can add additional testing as you see fit. + +Build and Run +------------- + +Navigate to the build directory and rebuild the application. Then, run the +``ctest`` executable: :option:`ctest -N` and :option:`ctest -VV`. For +multi-config generators (e.g. Visual Studio), the configuration type must be +specified with the :option:`-C \<mode\> <ctest -C>` flag. For example, to run tests in Debug +mode use ``ctest -C Debug -VV`` from the build directory +(not the Debug subdirectory!). Release mode would be executed from the same +location but with a ``-C Release``. Alternatively, build the ``RUN_TESTS`` +target from the IDE. + +Solution +-------- + +Let's test our application. At the end of the top-level ``CMakeLists.txt`` +file we first need to enable testing with the +:command:`enable_testing` command. + +.. raw:: html + + <details><summary>TODO 5: Click to show/hide answer</summary> + +.. literalinclude:: Step6/CMakeLists.txt + :caption: TODO 5: CMakeLists.txt + :name: CMakeLists.txt-enable_testing + :language: cmake + :start-after: # enable testing + :end-before: # does the application run + +.. raw:: html + + </details> + +With testing enabled, we will add a number of basic tests to verify +that the application is working correctly. First, we create a test using +:command:`add_test` which runs the ``Tutorial`` executable with the +parameter 25 passed in. For this test, we are not going to check the +executable's computed answer. This test will verify that +application runs, does not segfault or otherwise crash, and has a zero +return value. This is the basic form of a CTest test. + +.. raw:: html + + <details><summary>TODO 6: Click to show/hide answer</summary> + +.. literalinclude:: Step6/CMakeLists.txt + :caption: TODO 6: CMakeLists.txt + :name: CMakeLists.txt-test-runs + :language: cmake + :start-after: # does the application run + :end-before: # does the usage message work + +.. raw:: html + + </details> + +Next, let's use the :prop_test:`PASS_REGULAR_EXPRESSION` test property to +verify that the output of the test contains certain strings. In this case, +verifying that the usage message is printed when an incorrect number of +arguments are provided. + +.. raw:: html + + <details><summary>TODO 7: Click to show/hide answer</summary> + +.. literalinclude:: Step6/CMakeLists.txt + :caption: TODO 7: CMakeLists.txt + :name: CMakeLists.txt-test-usage + :language: cmake + :start-after: # does the usage message work? + :end-before: # define a function to simplify adding tests + +.. raw:: html + + </details> + +The next test we will add verifies the computed value is truly the +square root. + +.. raw:: html + + <details><summary>TODO 8: Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 8: CMakeLists.txt + :name: CMakeLists.txt-test-standard + + add_test(NAME StandardUse COMMAND Tutorial 4) + set_tests_properties(StandardUse + PROPERTIES PASS_REGULAR_EXPRESSION "4 is 2" + ) + +.. raw:: html + + </details> + +This one test is not enough to give us confidence that it will +work for all values passed in. We should add more tests to verify this. +To easily add more tests, we make a function called ``do_test`` that runs the +application and verifies that the computed square root is correct for +given input. For each invocation of ``do_test``, another test is added to +the project with a name, input, and expected results based on the passed +arguments. + +.. raw:: html + + <details><summary>TODO 9: Click to show/hide answer</summary> + +.. literalinclude:: Step6/CMakeLists.txt + :caption: TODO 9: CMakeLists.txt + :name: CMakeLists.txt-generalized-tests + :language: cmake + :start-after: # define a function to simplify adding tests + +.. raw:: html + + </details> diff --git a/Help/guide/tutorial/Packaging Debug and Release.rst b/Help/guide/tutorial/Packaging Debug and Release.rst new file mode 100644 index 0000000..8c660a3 --- /dev/null +++ b/Help/guide/tutorial/Packaging Debug and Release.rst @@ -0,0 +1,86 @@ +Step 12: Packaging Debug and Release +==================================== + +**Note:** This example is valid for single-configuration generators and will +not work for multi-configuration generators (e.g. Visual Studio). + +By default, CMake's model is that a build directory only contains a single +configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo. It is +possible, however, to setup CPack to bundle multiple build directories and +construct a package that contains multiple configurations of the same project. + +First, we want to ensure that the debug and release builds use different names +for the libraries that will be installed. Let's use `d` as the +postfix for the debug libraries. + +Set :variable:`CMAKE_DEBUG_POSTFIX` near the beginning of the top-level +``CMakeLists.txt`` file: + +.. literalinclude:: Complete/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-CMAKE_DEBUG_POSTFIX-variable + :language: cmake + :start-after: project(Tutorial VERSION 1.0) + :end-before: target_compile_features(tutorial_compiler_flags + +And the :prop_tgt:`DEBUG_POSTFIX` property on the tutorial executable: + +.. literalinclude:: Complete/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-DEBUG_POSTFIX-property + :language: cmake + :start-after: # add the executable + :end-before: # add the binary tree to the search path for include files + +Let's also add version numbering to the ``MathFunctions`` library. In +``MathFunctions/CMakeLists.txt``, set the :prop_tgt:`VERSION` and +:prop_tgt:`SOVERSION` properties: + +.. literalinclude:: Complete/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-VERSION-properties + :language: cmake + :start-after: # setup the version numbering + :end-before: # install libs + +From the ``Step12`` directory, create ``debug`` and ``release`` +subdirectories. The layout will look like: + +.. code-block:: none + + - Step12 + - debug + - release + +Now we need to setup debug and release builds. We can use +:variable:`CMAKE_BUILD_TYPE` to set the configuration type: + +.. code-block:: console + + cd debug + cmake -DCMAKE_BUILD_TYPE=Debug .. + cmake --build . + cd ../release + cmake -DCMAKE_BUILD_TYPE=Release .. + cmake --build . + +Now that both the debug and release builds are complete, we can use a custom +configuration file to package both builds into a single release. In the +``Step12`` directory, create a file called ``MultiCPackConfig.cmake``. In this +file, first include the default configuration file that was created by the +:manual:`cmake <cmake(1)>` executable. + +Next, use the ``CPACK_INSTALL_CMAKE_PROJECTS`` variable to specify which +projects to install. In this case, we want to install both debug and release. + +.. literalinclude:: Complete/MultiCPackConfig.cmake + :caption: MultiCPackConfig.cmake + :name: MultiCPackConfig.cmake + :language: cmake + +From the ``Step12`` directory, run :manual:`cpack <cpack(1)>` specifying our +custom configuration file with the ``config`` option: + +.. code-block:: console + + cpack --config MultiCPackConfig.cmake diff --git a/Help/guide/tutorial/Packaging an Installer.rst b/Help/guide/tutorial/Packaging an Installer.rst new file mode 100644 index 0000000..11a1952 --- /dev/null +++ b/Help/guide/tutorial/Packaging an Installer.rst @@ -0,0 +1,62 @@ +Step 9: Packaging an Installer +============================== + +Next suppose that we want to distribute our project to other people so that +they can use it. We want to provide both binary and source distributions on a +variety of platforms. This is a little different from the install we did +previously in :guide:`tutorial/Installing and Testing`, where we were +installing the binaries that we had built from the source code. In this +example we will be building installation packages that support binary +installations and package management features. To accomplish this we will use +CPack to create platform specific installers. Specifically we need to add a +few lines to the bottom of our top-level ``CMakeLists.txt`` file. + +.. literalinclude:: Step10/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-include-CPack + :language: cmake + :start-after: # setup installer + +That is all there is to it. We start by including +:module:`InstallRequiredSystemLibraries`. This module will include any runtime +libraries that are needed by the project for the current platform. Next we set +some CPack variables to where we have stored the license and version +information for this project. The version information was set earlier in this +tutorial and the ``License.txt`` has been included in the top-level source +directory for this step. The :variable:`CPACK_SOURCE_GENERATOR` variable +selects a file format for the source package. + +Finally we include the :module:`CPack module <CPack>` which will use these +variables and some other properties of the current system to setup an +installer. + +The next step is to build the project in the usual manner and then run the +:manual:`cpack <cpack(1)>` executable. To build a binary distribution, from the +binary directory run: + +.. code-block:: console + + cpack + +To specify the generator, use the :option:`-G <cpack -G>` option. For multi-config builds, +use :option:`-C <cpack -C>` to specify the configuration. For example: + +.. code-block:: console + + cpack -G ZIP -C Debug + +For a list of available generators, see :manual:`cpack-generators(7)` or call +:option:`cpack --help`. An :cpack_gen:`archive generator <CPack Archive Generator>` +like ZIP creates a compressed archive of all *installed* files. + +To create an archive of the *full* source tree you would type: + +.. code-block:: console + + cpack --config CPackSourceConfig.cmake + +Alternatively, run ``make package`` or right click the ``Package`` target and +``Build Project`` from an IDE. + +Run the installer found in the binary directory. Then run the installed +executable and verify that it works. diff --git a/Help/guide/tutorial/Selecting Static or Shared Libraries.rst b/Help/guide/tutorial/Selecting Static or Shared Libraries.rst new file mode 100644 index 0000000..1c49c23 --- /dev/null +++ b/Help/guide/tutorial/Selecting Static or Shared Libraries.rst @@ -0,0 +1,77 @@ +Step 10: Selecting Static or Shared Libraries +============================================= + +In this section we will show how the :variable:`BUILD_SHARED_LIBS` variable can +be used to control the default behavior of :command:`add_library`, +and allow control over how libraries without an explicit type (``STATIC``, +``SHARED``, ``MODULE`` or ``OBJECT``) are built. + +To accomplish this we need to add :variable:`BUILD_SHARED_LIBS` to the +top-level ``CMakeLists.txt``. We use the :command:`option` command as it allows +users to optionally select if the value should be ``ON`` or ``OFF``. + +Next we are going to refactor ``MathFunctions`` to become a real library that +encapsulates using ``mysqrt`` or ``sqrt``, instead of requiring the calling +code to do this logic. This will also mean that ``USE_MYMATH`` will not control +building ``MathFunctions``, but instead will control the behavior of this +library. + +The first step is to update the starting section of the top-level +``CMakeLists.txt`` to look like: + +.. literalinclude:: Step11/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-option-BUILD_SHARED_LIBS + :language: cmake + :end-before: # add the binary tree + +Now that we have made ``MathFunctions`` always be used, we will need to update +the logic of that library. So, in ``MathFunctions/CMakeLists.txt`` we need to +create a SqrtLibrary that will conditionally be built and installed when +``USE_MYMATH`` is enabled. Now, since this is a tutorial, we are going to +explicitly require that SqrtLibrary is built statically. + +The end result is that ``MathFunctions/CMakeLists.txt`` should look like: + +.. literalinclude:: Step11/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-add_library-STATIC + :language: cmake + :lines: 1-36,42- + +Next, update ``MathFunctions/mysqrt.cxx`` to use the ``mathfunctions`` and +``detail`` namespaces: + +.. literalinclude:: Step11/MathFunctions/mysqrt.cxx + :caption: MathFunctions/mysqrt.cxx + :name: MathFunctions/mysqrt.cxx-namespace + :language: c++ + +We also need to make some changes in ``tutorial.cxx``, so that it no longer +uses ``USE_MYMATH``: + +#. Always include ``MathFunctions.h`` +#. Always use ``mathfunctions::sqrt`` +#. Don't include ``cmath`` + +Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines: + +.. literalinclude:: Step11/MathFunctions/MathFunctions.h + :caption: MathFunctions/MathFunctions.h + :name: MathFunctions/MathFunctions.h + :language: c++ + +At this point, if you build everything, you may notice that linking fails +as we are combining a static library without position independent code with a +library that has position independent code. The solution to this is to +explicitly set the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property of +SqrtLibrary to be ``True`` no matter the build type. + +.. literalinclude:: Step11/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-POSITION_INDEPENDENT_CODE + :language: cmake + :lines: 37-42 + +**Exercise**: We modified ``MathFunctions.h`` to use dll export defines. +Using CMake documentation can you find a helper module to simplify this? diff --git a/Help/guide/tutorial/Step1/CMakeLists.txt b/Help/guide/tutorial/Step1/CMakeLists.txt new file mode 100644 index 0000000..6fcce90 --- /dev/null +++ b/Help/guide/tutorial/Step1/CMakeLists.txt @@ -0,0 +1,16 @@ +# TODO 1: Set the minimum required version of CMake to be 3.10 + +# TODO 2: Create a project named Tutorial + +# TODO 7: Set the project version number as 1.0 in the above project command + +# TODO 6: Set the variable CMAKE_CXX_STANDARD to 11 +# and the variable CMAKE_CXX_STANDARD_REQUIRED to True + +# TODO 8: Use configure_file to configure and copy TutorialConfig.h.in to +# TutorialConfig.h + +# TODO 3: Add an executable called Tutorial to the project +# Hint: Be sure to specify the source file as tutorial.cxx + +# TODO 9: Use target_include_directories to include ${PROJECT_BINARY_DIR} diff --git a/Help/guide/tutorial/Step1/TutorialConfig.h.in b/Help/guide/tutorial/Step1/TutorialConfig.h.in new file mode 100644 index 0000000..990bfbd --- /dev/null +++ b/Help/guide/tutorial/Step1/TutorialConfig.h.in @@ -0,0 +1,2 @@ +// the configured options and settings for Tutorial +// TODO 10: Define Tutorial_VERSION_MAJOR and Tutorial_VERSION_MINOR diff --git a/Help/guide/tutorial/Step1/tutorial.cxx b/Help/guide/tutorial/Step1/tutorial.cxx new file mode 100644 index 0000000..64d0916 --- /dev/null +++ b/Help/guide/tutorial/Step1/tutorial.cxx @@ -0,0 +1,27 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <cstdlib> // TODO 5: Remove this line +#include <iostream> +#include <string> + +// TODO 11: Include TutorialConfig.h + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // TODO 12: Create a print statement using Tutorial_VERSION_MAJOR + // and Tutorial_VERSION_MINOR + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + // TODO 4: Replace atof(argv[1]) with std::stod(argv[1]) + const double inputValue = atof(argv[1]); + + // calculate square root + const double outputValue = sqrt(inputValue); + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step10/CMakeLists.txt b/Help/guide/tutorial/Step10/CMakeLists.txt new file mode 100644 index 0000000..5c661aa --- /dev/null +++ b/Help/guide/tutorial/Step10/CMakeLists.txt @@ -0,0 +1,83 @@ +cmake_minimum_required(VERSION 3.15) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +add_library(tutorial_compiler_flags INTERFACE) +target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) + +# add compiler warning flags just when building this project via +# the BUILD_INTERFACE genex +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") +set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") +target_compile_options(tutorial_compiler_flags INTERFACE + "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" + "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" +) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +if(USE_MYMATH) + add_subdirectory(MathFunctions) + list(APPEND EXTRA_LIBS MathFunctions) +endif() + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS} tutorial_compiler_flags) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +include(CTest) + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction() + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") +do_test(Tutorial 0.0001 "0.0001 is 0.01") + +# setup installer +include(InstallRequiredSystemLibraries) +set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") +set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") +set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +set(CPACK_SOURCE_GENERATOR "TGZ") +include(CPack) diff --git a/Help/guide/tutorial/Step10/CTestConfig.cmake b/Help/guide/tutorial/Step10/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Step10/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step10/License.txt b/Help/guide/tutorial/Step10/License.txt new file mode 100644 index 0000000..85760e5 --- /dev/null +++ b/Help/guide/tutorial/Step10/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step9... diff --git a/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..fa73321 --- /dev/null +++ b/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt @@ -0,0 +1,32 @@ +# first we add the executable that generates the table +add_executable(MakeTable MakeTable.cxx) + +# add the command to generate the source code +add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) + +# add the main library +add_library(MathFunctions + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +# state that we depend on our binary dir to find Table.h +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + PRIVATE ${CMAKE_CURRENT_BINARY_DIR} + ) + +# link our compiler flags interface library +target_link_libraries(MathFunctions tutorial_compiler_flags) + +# install libs +set(installable_libs MathFunctions tutorial_compiler_flags) +install(TARGETS ${installable_libs} DESTINATION lib) +# install include headers +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step10/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step10/MathFunctions/MakeTable.cxx new file mode 100644 index 0000000..ee58556 --- /dev/null +++ b/Help/guide/tutorial/Step10/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..0145300 --- /dev/null +++ b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ + +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..cd36bcc --- /dev/null +++ b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..7d80ee9 --- /dev/null +++ b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx @@ -0,0 +1,33 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + std::cout << "Use the table to help find an initial value " << std::endl; + result = sqrtTable[static_cast<int>(x)]; + } + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} diff --git a/Help/guide/tutorial/Step10/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.h new file mode 100644 index 0000000..e1c42ef --- /dev/null +++ b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.h @@ -0,0 +1,6 @@ + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step10/TutorialConfig.h.in b/Help/guide/tutorial/Step10/TutorialConfig.h.in new file mode 100644 index 0000000..e23f521 --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ +#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step10/tutorial.cxx b/Help/guide/tutorial/Step10/tutorial.cxx new file mode 100644 index 0000000..b3c6a4f --- /dev/null +++ b/Help/guide/tutorial/Step10/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#include "TutorialConfig.h" + +// should we include the MathFunctions header? +#ifdef USE_MYMATH +# include "MathFunctions.h" +#endif + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step11/CMakeLists.txt b/Help/guide/tutorial/Step11/CMakeLists.txt new file mode 100644 index 0000000..046bfc9 --- /dev/null +++ b/Help/guide/tutorial/Step11/CMakeLists.txt @@ -0,0 +1,84 @@ +cmake_minimum_required(VERSION 3.15) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +add_library(tutorial_compiler_flags INTERFACE) +target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) + +# add compiler warning flags just when building this project via +# the BUILD_INTERFACE genex +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") +set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") +target_compile_options(tutorial_compiler_flags INTERFACE + "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" + "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" +) + +# control where the static and shared libraries are built so that on windows +# we don't need to tinker with the path to run the executable +set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") + +option(BUILD_SHARED_LIBS "Build using shared libraries" ON) + +# configure a header file to pass the version number only +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +add_subdirectory(MathFunctions) + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +include(CTest) + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction() + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") +do_test(Tutorial 0.0001 "0.0001 is 0.01") + +# setup installer +include(InstallRequiredSystemLibraries) +set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") +set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") +set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +set(CPACK_SOURCE_GENERATOR "TGZ") +include(CPack) diff --git a/Help/guide/tutorial/Step11/CTestConfig.cmake b/Help/guide/tutorial/Step11/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Step11/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step11/License.txt b/Help/guide/tutorial/Step11/License.txt new file mode 100644 index 0000000..85760e5 --- /dev/null +++ b/Help/guide/tutorial/Step11/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step9... diff --git a/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..a60fb63 --- /dev/null +++ b/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt @@ -0,0 +1,60 @@ +# add the library that runs +add_library(MathFunctions MathFunctions.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if(USE_MYMATH) + + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # first we add the executable that generates the table + add_executable(MakeTable MakeTable.cxx) + target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) + + # add the command to generate the source code + add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + + # state that we depend on our binary dir to find Table.h + target_include_directories(SqrtLibrary PRIVATE + ${CMAKE_CURRENT_BINARY_DIR} + ) + + # state that SqrtLibrary need PIC when the default is shared libraries + set_target_properties(SqrtLibrary PROPERTIES + POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} + ) + + target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() + +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) + +# define the symbol stating we are using the declspec(dllexport) when +# building on windows +target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH") + +# install libs +set(installable_libs MathFunctions tutorial_compiler_flags) +if(TARGET SqrtLibrary) + list(APPEND installable_libs SqrtLibrary) +endif() +install(TARGETS ${installable_libs} DESTINATION lib) +# install include headers +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step11/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step11/MathFunctions/MakeTable.cxx new file mode 100644 index 0000000..ee58556 --- /dev/null +++ b/Help/guide/tutorial/Step11/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..0145300 --- /dev/null +++ b/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ + +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..3fb547b --- /dev/null +++ b/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.h @@ -0,0 +1,14 @@ + +#if defined(_WIN32) +# if defined(EXPORTING_MYMATH) +# define DECLSPEC __declspec(dllexport) +# else +# define DECLSPEC __declspec(dllimport) +# endif +#else // non windows +# define DECLSPEC +#endif + +namespace mathfunctions { +double DECLSPEC sqrt(double x); +} diff --git a/Help/guide/tutorial/Step11/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step11/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..8153f18 --- /dev/null +++ b/Help/guide/tutorial/Step11/MathFunctions/mysqrt.cxx @@ -0,0 +1,37 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +namespace mathfunctions { +namespace detail { +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + std::cout << "Use the table to help find an initial value " << std::endl; + result = sqrtTable[static_cast<int>(x)]; + } + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} +} +} diff --git a/Help/guide/tutorial/Step11/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step11/MathFunctions/mysqrt.h new file mode 100644 index 0000000..e1c42ef --- /dev/null +++ b/Help/guide/tutorial/Step11/MathFunctions/mysqrt.h @@ -0,0 +1,6 @@ + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step11/TutorialConfig.h.in b/Help/guide/tutorial/Step11/TutorialConfig.h.in new file mode 100644 index 0000000..7e4d7fa --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialConfig.h.in @@ -0,0 +1,3 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ diff --git a/Help/guide/tutorial/Step11/tutorial.cxx b/Help/guide/tutorial/Step11/tutorial.cxx new file mode 100644 index 0000000..37a0333 --- /dev/null +++ b/Help/guide/tutorial/Step11/tutorial.cxx @@ -0,0 +1,27 @@ +// A simple program that computes the square root of a number +#include <iostream> +#include <sstream> +#include <string> + +#include "MathFunctions.h" +#include "TutorialConfig.h" + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + const double outputValue = mathfunctions::sqrt(inputValue); + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step12/CMakeLists.txt b/Help/guide/tutorial/Step12/CMakeLists.txt new file mode 100644 index 0000000..220ed4b --- /dev/null +++ b/Help/guide/tutorial/Step12/CMakeLists.txt @@ -0,0 +1,122 @@ +cmake_minimum_required(VERSION 3.15) + +# set the project name and version +project(Tutorial VERSION 1.0) + +add_library(tutorial_compiler_flags INTERFACE) +target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) + +# add compiler warning flags just when building this project via +# the BUILD_INTERFACE genex +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") +set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") +target_compile_options(tutorial_compiler_flags INTERFACE + "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" + "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" +) + +# control where the static and shared libraries are built so that on windows +# we don't need to tinker with the path to run the executable +set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") + +option(BUILD_SHARED_LIBS "Build using shared libraries" ON) + +if(APPLE) + set(CMAKE_INSTALL_RPATH "@executable_path/../lib") +elseif(UNIX) + set(CMAKE_INSTALL_RPATH "$ORIGIN/../lib") +endif() + +# configure a header file to pass the version number only +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +add_subdirectory(MathFunctions) + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +enable_testing() + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction() + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") +do_test(Tutorial 0.0001 "0.0001 is 0.01") + +# setup installer +include(InstallRequiredSystemLibraries) +set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") +set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") +set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +include(CPack) + +# install the configuration targets +install(EXPORT MathFunctionsTargets + FILE MathFunctionsTargets.cmake + DESTINATION lib/cmake/MathFunctions +) + +include(CMakePackageConfigHelpers) +# generate the config file that is includes the exports +configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" + INSTALL_DESTINATION "lib/cmake/example" + NO_SET_AND_CHECK_MACRO + NO_CHECK_REQUIRED_COMPONENTS_MACRO + ) +# generate the version file for the config file +write_basic_package_version_file( + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake" + VERSION "${Tutorial_VERSION_MAJOR}.${Tutorial_VERSION_MINOR}" + COMPATIBILITY AnyNewerVersion +) + +# install the generated configuration files +install(FILES + ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake + ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake + DESTINATION lib/cmake/MathFunctions + ) + +# generate the export targets for the build tree +# needs to be after the install(TARGETS ) command +export(EXPORT MathFunctionsTargets + FILE "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsTargets.cmake" +) diff --git a/Help/guide/tutorial/Step12/CTestConfig.cmake b/Help/guide/tutorial/Step12/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Step12/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step12/Config.cmake.in b/Help/guide/tutorial/Step12/Config.cmake.in new file mode 100644 index 0000000..17cbabd --- /dev/null +++ b/Help/guide/tutorial/Step12/Config.cmake.in @@ -0,0 +1,4 @@ + +@PACKAGE_INIT@ + +include ( "${CMAKE_CURRENT_LIST_DIR}/MathFunctionsTargets.cmake" ) diff --git a/Help/guide/tutorial/Step12/License.txt b/Help/guide/tutorial/Step12/License.txt new file mode 100644 index 0000000..85760e5 --- /dev/null +++ b/Help/guide/tutorial/Step12/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step9... diff --git a/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..a85f3cb --- /dev/null +++ b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt @@ -0,0 +1,64 @@ +# add the library that runs +add_library(MathFunctions MathFunctions.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE + $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}> + $<INSTALL_INTERFACE:include> + ) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if(USE_MYMATH) + + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # first we add the executable that generates the table + add_executable(MakeTable MakeTable.cxx) + target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) + + # add the command to generate the source code + add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + + # state that we depend on our binary dir to find Table.h + target_include_directories(SqrtLibrary PRIVATE + ${CMAKE_CURRENT_BINARY_DIR} + ) + + # state that SqrtLibrary need PIC when the default is shared libraries + set_target_properties(SqrtLibrary PROPERTIES + POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} + ) + + target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() + +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) + +# define the symbol stating we are using the declspec(dllexport) when +# building on windows +target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH") + +# install libs +set(installable_libs MathFunctions tutorial_compiler_flags) +if(TARGET SqrtLibrary) + list(APPEND installable_libs SqrtLibrary) +endif() +install(TARGETS ${installable_libs} + EXPORT MathFunctionsTargets + DESTINATION lib) +# install include headers +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cxx new file mode 100644 index 0000000..ee58556 --- /dev/null +++ b/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..0145300 --- /dev/null +++ b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ + +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..3fb547b --- /dev/null +++ b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.h @@ -0,0 +1,14 @@ + +#if defined(_WIN32) +# if defined(EXPORTING_MYMATH) +# define DECLSPEC __declspec(dllexport) +# else +# define DECLSPEC __declspec(dllimport) +# endif +#else // non windows +# define DECLSPEC +#endif + +namespace mathfunctions { +double DECLSPEC sqrt(double x); +} diff --git a/Help/guide/tutorial/Step12/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..8153f18 --- /dev/null +++ b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.cxx @@ -0,0 +1,37 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +namespace mathfunctions { +namespace detail { +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + std::cout << "Use the table to help find an initial value " << std::endl; + result = sqrtTable[static_cast<int>(x)]; + } + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} +} +} diff --git a/Help/guide/tutorial/Step12/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.h new file mode 100644 index 0000000..e1c42ef --- /dev/null +++ b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.h @@ -0,0 +1,6 @@ + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step12/TutorialConfig.h.in b/Help/guide/tutorial/Step12/TutorialConfig.h.in new file mode 100644 index 0000000..7e4d7fa --- /dev/null +++ b/Help/guide/tutorial/Step12/TutorialConfig.h.in @@ -0,0 +1,3 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ diff --git a/Help/guide/tutorial/Step12/tutorial.cxx b/Help/guide/tutorial/Step12/tutorial.cxx new file mode 100644 index 0000000..a4f44d5 --- /dev/null +++ b/Help/guide/tutorial/Step12/tutorial.cxx @@ -0,0 +1,26 @@ +// A simple program that computes the square root of a number +#include <iostream> +#include <string> + +#include "MathFunctions.h" +#include "TutorialConfig.h" + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + const double outputValue = mathfunctions::sqrt(inputValue); + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step2/CMakeLists.txt b/Help/guide/tutorial/Step2/CMakeLists.txt new file mode 100644 index 0000000..2b96128 --- /dev/null +++ b/Help/guide/tutorial/Step2/CMakeLists.txt @@ -0,0 +1,44 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# TODO 7: Create a variable USE_MYMATH using option and set default to ON + +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# TODO 8: Use list() and APPEND to create a list of optional libraries +# called EXTRA_LIBS and a list of optional include directories called +# EXTRA_INCLUDES. Add the MathFunctions library and source directory to +# the appropriate lists. +# +# Only call add_subdirectory and only add MathFunctions specific values +# to EXTRA_LIBS and EXTRA_INCLUDES if USE_MYMATH is true. + +# TODO 2: Use add_subdirectory() to add MathFunctions to this project + +# add the executable +add_executable(Tutorial tutorial.cxx) + +# TODO 9: Use EXTRA_LIBS instead of the MathFunctions specific values +# in target_link_libraries. + +# TODO 3: Use target_link_libraries to link the library to our executable + +# TODO 4: Add MathFunctions to Tutorial's target_include_directories() +# Hint: ${PROJECT_SOURCE_DIR} is a path to the project source. AKA This folder! + +# TODO 10: Use EXTRA_INCLUDES instead of the MathFunctions specific values +# in target_include_directories. + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) diff --git a/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..b7779b7 --- /dev/null +++ b/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt @@ -0,0 +1,2 @@ +# TODO 1: Add a library called MathFunctions +# Hint: You will need the add_library command diff --git a/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..cd36bcc --- /dev/null +++ b/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..1e4d97a --- /dev/null +++ b/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx @@ -0,0 +1,22 @@ +#include <iostream> + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + return result; +} diff --git a/Help/guide/tutorial/Step2/TutorialConfig.h.in b/Help/guide/tutorial/Step2/TutorialConfig.h.in new file mode 100644 index 0000000..6c09e1a --- /dev/null +++ b/Help/guide/tutorial/Step2/TutorialConfig.h.in @@ -0,0 +1,5 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ + +// TODO 13: use cmakedefine to define USE_MYMATH diff --git a/Help/guide/tutorial/Step2/tutorial.cxx b/Help/guide/tutorial/Step2/tutorial.cxx new file mode 100644 index 0000000..87f5e0f --- /dev/null +++ b/Help/guide/tutorial/Step2/tutorial.cxx @@ -0,0 +1,34 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#include "TutorialConfig.h" + +// TODO 11: Only include MathFunctions if USE_MYMATH is defined + +// TODO 5: Include MathFunctions.h + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // TODO 12: Use mysqrt if USE_MYMATH is defined and sqrt otherwise + + // TODO 6: Replace sqrt with mysqrt + + // calculate square root + const double outputValue = sqrt(inputValue); + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step3/CMakeLists.txt b/Help/guide/tutorial/Step3/CMakeLists.txt new file mode 100644 index 0000000..007770a --- /dev/null +++ b/Help/guide/tutorial/Step3/CMakeLists.txt @@ -0,0 +1,38 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# TODO 2: Remove EXTRA_INCLUDES list + +# add the MathFunctions library +if(USE_MYMATH) + add_subdirectory(MathFunctions) + list(APPEND EXTRA_LIBS MathFunctions) + list(APPEND EXTRA_INCLUDES "${PROJECT_SOURCE_DIR}/MathFunctions") +endif() + +# add the executable +add_executable(Tutorial tutorial.cxx) + +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) + +# TODO 3: Remove use of EXTRA_INCLUDES + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ${EXTRA_INCLUDES} + ) diff --git a/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..7bf05e0 --- /dev/null +++ b/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt @@ -0,0 +1,5 @@ +add_library(MathFunctions mysqrt.cxx) + +# TODO 1: State that anybody linking to MathFunctions needs to include the +# current source directory, while MathFunctions itself doesn't. +# Hint: Use target_include_directories with the INTERFACE keyword diff --git a/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..cd36bcc --- /dev/null +++ b/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..abe767d --- /dev/null +++ b/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx @@ -0,0 +1,24 @@ +#include <iostream> + +#include "MathFunctions.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + return result; +} diff --git a/Help/guide/tutorial/Step3/TutorialConfig.h.in b/Help/guide/tutorial/Step3/TutorialConfig.h.in new file mode 100644 index 0000000..e23f521 --- /dev/null +++ b/Help/guide/tutorial/Step3/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ +#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step3/tutorial.cxx b/Help/guide/tutorial/Step3/tutorial.cxx new file mode 100644 index 0000000..b3c6a4f --- /dev/null +++ b/Help/guide/tutorial/Step3/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#include "TutorialConfig.h" + +// should we include the MathFunctions header? +#ifdef USE_MYMATH +# include "MathFunctions.h" +#endif + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step4/CMakeLists.txt b/Help/guide/tutorial/Step4/CMakeLists.txt new file mode 100644 index 0000000..fa4aab2 --- /dev/null +++ b/Help/guide/tutorial/Step4/CMakeLists.txt @@ -0,0 +1,58 @@ +# TODO 4: Update the minimum required version to 3.15 + +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# TODO 1: Replace the following code by: +# * Creating an interface library called tutorial_compiler_flags +# Hint: use add_library() with the INTERFACE signature +# * Add compiler feature cxx_std_11 to tutorial_compiler_flags +# Hint: Use target_compile_features() + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# TODO 5: Create helper variables to determine which compiler we are using: +# * Create a new variable gcc_like_cxx that is true if we are using CXX and +# any of the following compilers: ARMClang, AppleClang, Clang, GNU, LCC +# * Create a new variable msvc_cxx that is true if we are using CXX and MSVC +# Hint: Use set() and COMPILE_LANG_AND_ID + +# TODO 6: Add warning flag compile options to the interface library +# tutorial_compiler_flags. +# * For gcc_like_cxx, add flags -Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused +# * For msvc_cxx, add flags -W3 +# Hint: Use target_compile_options() + +# TODO 7: With nested generator expressions, only use the flags for the +# build-tree +# Hint: Use BUILD_INTERFACE + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +if(USE_MYMATH) + add_subdirectory(MathFunctions) + list(APPEND EXTRA_LIBS MathFunctions) +endif() + +# add the executable +add_executable(Tutorial tutorial.cxx) + +# TODO 2: Link to tutorial_compiler_flags + +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) diff --git a/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..5f7369c --- /dev/null +++ b/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt @@ -0,0 +1,9 @@ +add_library(MathFunctions mysqrt.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) + +# TODO 3: Link to tutorial_compiler_flags diff --git a/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..cd36bcc --- /dev/null +++ b/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..abe767d --- /dev/null +++ b/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx @@ -0,0 +1,24 @@ +#include <iostream> + +#include "MathFunctions.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + return result; +} diff --git a/Help/guide/tutorial/Step4/TutorialConfig.h.in b/Help/guide/tutorial/Step4/TutorialConfig.h.in new file mode 100644 index 0000000..e23f521 --- /dev/null +++ b/Help/guide/tutorial/Step4/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ +#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step4/tutorial.cxx b/Help/guide/tutorial/Step4/tutorial.cxx new file mode 100644 index 0000000..b3c6a4f --- /dev/null +++ b/Help/guide/tutorial/Step4/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#include "TutorialConfig.h" + +// should we include the MathFunctions header? +#ifdef USE_MYMATH +# include "MathFunctions.h" +#endif + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step5/CMakeLists.txt b/Help/guide/tutorial/Step5/CMakeLists.txt new file mode 100644 index 0000000..a8f241a --- /dev/null +++ b/Help/guide/tutorial/Step5/CMakeLists.txt @@ -0,0 +1,64 @@ +cmake_minimum_required(VERSION 3.15) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +add_library(tutorial_compiler_flags INTERFACE) +target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) + +# add compiler warning flags just when building this project via +# the BUILD_INTERFACE genex +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") +set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") +target_compile_options(tutorial_compiler_flags INTERFACE + "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" + "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" +) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +if(USE_MYMATH) + add_subdirectory(MathFunctions) + list(APPEND EXTRA_LIBS MathFunctions) +endif() + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS} tutorial_compiler_flags) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# TODO 3: Install Tutorial in the bin directory +# Hint: Use the TARGETS and DESTINATION parameters + +# TODO 4: Install Tutorial.h to the include directory +# Hint: Use the FILES and DESTINATION parameters + +# TODO 5: Enable testing + +# TODO 6: Add a test called Runs which runs the following command: +# $ Tutorial 25 + +# TODO 7: Add a test called Usage which runs the following command: +# $ Tutorial +# Make sure the expected output is displayed. +# Hint: Use the PASS_REGULAR_EXPRESSION property with "Usage.*number" + +# TODO 8: Add a test which runs the following command: +# $ Tutorial 4 +# Make sure the result is correct. +# Hint: Use the PASS_REGULAR_EXPRESSION property with "4 is 2" + +# TODO 9: Add more tests. Create a function called do_test to avoid copy + +# paste. Test the following values: 4, 9, 5, 7, 25, -25 and 0.00001. diff --git a/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..6cd88d7 --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt @@ -0,0 +1,18 @@ +add_library(MathFunctions mysqrt.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) + +# link our compiler flags interface library +target_link_libraries(MathFunctions tutorial_compiler_flags) + +# TODO 1: Create a variable called installable_libs that is a list of all +# libraries we want to install (e.g. MathFunctions and tutorial_compiler_flags) +# Then install the installable libraries to the lib folder. +# Hint: Use the TARGETS and DESTINATION parameters + +# TODO 2: Install the library headers to the include folder. +# Hint: Use the FILES and DESTINATION parameters diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..cd36bcc --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..abe767d --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx @@ -0,0 +1,24 @@ +#include <iostream> + +#include "MathFunctions.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + return result; +} diff --git a/Help/guide/tutorial/Step5/TutorialConfig.h.in b/Help/guide/tutorial/Step5/TutorialConfig.h.in new file mode 100644 index 0000000..e23f521 --- /dev/null +++ b/Help/guide/tutorial/Step5/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ +#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step5/tutorial.cxx b/Help/guide/tutorial/Step5/tutorial.cxx new file mode 100644 index 0000000..b3c6a4f --- /dev/null +++ b/Help/guide/tutorial/Step5/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#include "TutorialConfig.h" + +// should we include the MathFunctions header? +#ifdef USE_MYMATH +# include "MathFunctions.h" +#endif + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step6/CMakeLists.txt b/Help/guide/tutorial/Step6/CMakeLists.txt new file mode 100644 index 0000000..da9e852 --- /dev/null +++ b/Help/guide/tutorial/Step6/CMakeLists.txt @@ -0,0 +1,75 @@ +cmake_minimum_required(VERSION 3.15) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +add_library(tutorial_compiler_flags INTERFACE) +target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) + +# add compiler warning flags just when building this project via +# the BUILD_INTERFACE genex +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") +set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") +target_compile_options(tutorial_compiler_flags INTERFACE + "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" + "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" +) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +if(USE_MYMATH) + add_subdirectory(MathFunctions) + list(APPEND EXTRA_LIBS MathFunctions) +endif() + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS} tutorial_compiler_flags) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +enable_testing() + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction() + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") +do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step6/CTestConfig.cmake b/Help/guide/tutorial/Step6/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Step6/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..b4724c4 --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt @@ -0,0 +1,16 @@ +add_library(MathFunctions mysqrt.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) + +# link our compiler flags interface library +target_link_libraries(MathFunctions tutorial_compiler_flags) + +# install libs +set(installable_libs MathFunctions tutorial_compiler_flags) +install(TARGETS ${installable_libs} DESTINATION lib) +# install include headers +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..cd36bcc --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..abe767d --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx @@ -0,0 +1,24 @@ +#include <iostream> + +#include "MathFunctions.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + return result; +} diff --git a/Help/guide/tutorial/Step6/TutorialConfig.h.in b/Help/guide/tutorial/Step6/TutorialConfig.h.in new file mode 100644 index 0000000..e23f521 --- /dev/null +++ b/Help/guide/tutorial/Step6/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ +#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step6/tutorial.cxx b/Help/guide/tutorial/Step6/tutorial.cxx new file mode 100644 index 0000000..b3c6a4f --- /dev/null +++ b/Help/guide/tutorial/Step6/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#include "TutorialConfig.h" + +// should we include the MathFunctions header? +#ifdef USE_MYMATH +# include "MathFunctions.h" +#endif + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step7/CMakeLists.txt b/Help/guide/tutorial/Step7/CMakeLists.txt new file mode 100644 index 0000000..d26a90c --- /dev/null +++ b/Help/guide/tutorial/Step7/CMakeLists.txt @@ -0,0 +1,75 @@ +cmake_minimum_required(VERSION 3.15) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +add_library(tutorial_compiler_flags INTERFACE) +target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) + +# add compiler warning flags just when building this project via +# the BUILD_INTERFACE genex +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") +set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") +target_compile_options(tutorial_compiler_flags INTERFACE + "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" + "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" +) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +if(USE_MYMATH) + add_subdirectory(MathFunctions) + list(APPEND EXTRA_LIBS MathFunctions) +endif() + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS} tutorial_compiler_flags) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +include(CTest) + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction() + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") +do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step7/CTestConfig.cmake b/Help/guide/tutorial/Step7/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Step7/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..b4724c4 --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt @@ -0,0 +1,16 @@ +add_library(MathFunctions mysqrt.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) + +# link our compiler flags interface library +target_link_libraries(MathFunctions tutorial_compiler_flags) + +# install libs +set(installable_libs MathFunctions tutorial_compiler_flags) +install(TARGETS ${installable_libs} DESTINATION lib) +# install include headers +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..cd36bcc --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..abe767d --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx @@ -0,0 +1,24 @@ +#include <iostream> + +#include "MathFunctions.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + return result; +} diff --git a/Help/guide/tutorial/Step7/TutorialConfig.h.in b/Help/guide/tutorial/Step7/TutorialConfig.h.in new file mode 100644 index 0000000..e23f521 --- /dev/null +++ b/Help/guide/tutorial/Step7/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ +#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step7/tutorial.cxx b/Help/guide/tutorial/Step7/tutorial.cxx new file mode 100644 index 0000000..b3c6a4f --- /dev/null +++ b/Help/guide/tutorial/Step7/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#include "TutorialConfig.h" + +// should we include the MathFunctions header? +#ifdef USE_MYMATH +# include "MathFunctions.h" +#endif + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step8/CMakeLists.txt b/Help/guide/tutorial/Step8/CMakeLists.txt new file mode 100644 index 0000000..cb87281 --- /dev/null +++ b/Help/guide/tutorial/Step8/CMakeLists.txt @@ -0,0 +1,76 @@ +cmake_minimum_required(VERSION 3.15) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +add_library(tutorial_compiler_flags INTERFACE) +target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) + +# add compiler warning flags just when building this project via +# the BUILD_INTERFACE genex +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") +set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") +target_compile_options(tutorial_compiler_flags INTERFACE + "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" + "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" +) + + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +if(USE_MYMATH) + add_subdirectory(MathFunctions) + list(APPEND EXTRA_LIBS MathFunctions) +endif() + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS} tutorial_compiler_flags) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +include(CTest) + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction() + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") +do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step8/CTestConfig.cmake b/Help/guide/tutorial/Step8/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Step8/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..f81b563 --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt @@ -0,0 +1,39 @@ +add_library(MathFunctions mysqrt.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) + +# link our compiler flags interface library +target_link_libraries(MathFunctions tutorial_compiler_flags) + +# does this system provide the log and exp functions? +include(CheckCXXSourceCompiles) +check_cxx_source_compiles(" + #include <cmath> + int main() { + std::log(1.0); + return 0; + } +" HAVE_LOG) +check_cxx_source_compiles(" + #include <cmath> + int main() { + std::exp(1.0); + return 0; + } +" HAVE_EXP) + +# add compile definitions +if(HAVE_LOG AND HAVE_EXP) + target_compile_definitions(MathFunctions + PRIVATE "HAVE_LOG" "HAVE_EXP") +endif() + +# install libs +set(installable_libs MathFunctions tutorial_compiler_flags) +install(TARGETS ${installable_libs} DESTINATION lib) +# install include headers +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step8/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step8/MathFunctions/MakeTable.cxx new file mode 100644 index 0000000..ee58556 --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..cd36bcc --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..7eecd26 --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx @@ -0,0 +1,32 @@ +#include <cmath> +#include <iostream> + +#include "MathFunctions.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // if we have both log and exp then use them +#if defined(HAVE_LOG) && defined(HAVE_EXP) + double result = std::exp(std::log(x) * 0.5); + std::cout << "Computing sqrt of " << x << " to be " << result + << " using log and exp" << std::endl; +#else + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } +#endif + return result; +} diff --git a/Help/guide/tutorial/Step8/TutorialConfig.h.in b/Help/guide/tutorial/Step8/TutorialConfig.h.in new file mode 100644 index 0000000..e23f521 --- /dev/null +++ b/Help/guide/tutorial/Step8/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ +#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step8/tutorial.cxx b/Help/guide/tutorial/Step8/tutorial.cxx new file mode 100644 index 0000000..b3c6a4f --- /dev/null +++ b/Help/guide/tutorial/Step8/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#include "TutorialConfig.h" + +// should we include the MathFunctions header? +#ifdef USE_MYMATH +# include "MathFunctions.h" +#endif + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step9/CMakeLists.txt b/Help/guide/tutorial/Step9/CMakeLists.txt new file mode 100644 index 0000000..d26a90c --- /dev/null +++ b/Help/guide/tutorial/Step9/CMakeLists.txt @@ -0,0 +1,75 @@ +cmake_minimum_required(VERSION 3.15) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +add_library(tutorial_compiler_flags INTERFACE) +target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) + +# add compiler warning flags just when building this project via +# the BUILD_INTERFACE genex +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") +set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") +target_compile_options(tutorial_compiler_flags INTERFACE + "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" + "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" +) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +if(USE_MYMATH) + add_subdirectory(MathFunctions) + list(APPEND EXTRA_LIBS MathFunctions) +endif() + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS} tutorial_compiler_flags) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +include(CTest) + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction() + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") +do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step9/CTestConfig.cmake b/Help/guide/tutorial/Step9/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Step9/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step9/License.txt b/Help/guide/tutorial/Step9/License.txt new file mode 100644 index 0000000..85760e5 --- /dev/null +++ b/Help/guide/tutorial/Step9/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step9... diff --git a/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..8e04f97 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt @@ -0,0 +1,34 @@ +# first we add the executable that generates the table +add_executable(MakeTable MakeTable.cxx) + +# add the command to generate the source code +add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) + +# add the main library +add_library(MathFunctions + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +# state that we depend on Tutorial_BINARY_DIR but consumers don't, as the +# TutorialConfig.h include is an implementation detail +# state that we depend on our binary dir to find Table.h +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + PRIVATE ${CMAKE_CURRENT_BINARY_DIR} + ) + +# link our compiler flags interface library +target_link_libraries(MathFunctions tutorial_compiler_flags) + +# install libs +set(installable_libs MathFunctions tutorial_compiler_flags) +install(TARGETS ${installable_libs} DESTINATION lib) +# install include headers +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step9/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step9/MathFunctions/MakeTable.cxx new file mode 100644 index 0000000..ee58556 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..cd36bcc --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..7d80ee9 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx @@ -0,0 +1,33 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + std::cout << "Use the table to help find an initial value " << std::endl; + result = sqrtTable[static_cast<int>(x)]; + } + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} diff --git a/Help/guide/tutorial/Step9/TutorialConfig.h.in b/Help/guide/tutorial/Step9/TutorialConfig.h.in new file mode 100644 index 0000000..e23f521 --- /dev/null +++ b/Help/guide/tutorial/Step9/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ +#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step9/tutorial.cxx b/Help/guide/tutorial/Step9/tutorial.cxx new file mode 100644 index 0000000..b3c6a4f --- /dev/null +++ b/Help/guide/tutorial/Step9/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#include "TutorialConfig.h" + +// should we include the MathFunctions header? +#ifdef USE_MYMATH +# include "MathFunctions.h" +#endif + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst new file mode 100644 index 0000000..1ab0009 --- /dev/null +++ b/Help/guide/tutorial/index.rst @@ -0,0 +1,44 @@ +CMake Tutorial +************** + +Introduction +============ + +The CMake tutorial provides a step-by-step guide that covers common build +system issues that CMake helps address. Seeing how various topics all +work together in an example project can be very helpful. + +Steps +===== + +.. include:: source.txt + +|tutorial_source| +Each step has its own subdirectory containing code that may be used as a +starting point. The tutorial examples are progressive so that each step +provides the complete solution for the previous step. + +.. toctree:: + :maxdepth: 2 + + A Basic Starting Point + Adding a Library + Adding Usage Requirements for a Library + Adding Generator Expressions + Installing and Testing + Adding Support for a Testing Dashboard + Adding System Introspection + Adding a Custom Command and Generated File + Packaging an Installer + Selecting Static or Shared Libraries + Adding Export Configuration + Packaging Debug and Release + +.. + Whenever a step above is renamed or removed, leave forwarding text in + its original document file, and list it below to preserve old links + to cmake.org/cmake/help/latest/ URLs. + +.. toctree:: + :maxdepth: 1 + :hidden: diff --git a/Help/guide/tutorial/source.txt b/Help/guide/tutorial/source.txt new file mode 100644 index 0000000..bb45e86 --- /dev/null +++ b/Help/guide/tutorial/source.txt @@ -0,0 +1,3 @@ +.. |tutorial_source| replace:: + The tutorial documentation and source code examples can be found in + the ``Help/guide/tutorial`` directory of the CMake source code tree. |