Help/guide/tutorial/Installing and Testing.rst

   1 Step 4: Installing and Testing
   2 ==============================
   3
   4 Now we can start adding install rules and testing support to our project.
   5
   6 Install Rules
   7 -------------
   8
   9 The install rules are fairly simple: for ``MathFunctions`` we want to install
  10 the library and header file and for the application we want to install the
  11 executable and configured header.
  12
  13 So to the end of ``MathFunctions/CMakeLists.txt`` we add:
  14
  15 .. literalinclude:: Step5/MathFunctions/CMakeLists.txt
  16   :caption: MathFunctions/CMakeLists.txt
  17   :name: MathFunctions/CMakeLists.txt-install-TARGETS
  18   :language: cmake
  19   :start-after: # install rules
  20
  21 And to the end of the top-level ``CMakeLists.txt`` we add:
  22
  23 .. literalinclude:: Step5/CMakeLists.txt
  24   :caption: CMakeLists.txt
  25   :name: CMakeLists.txt-install-TARGETS
  26   :language: cmake
  27   :start-after: # add the install targets
  28   :end-before: # enable testing
  29
  30 That is all that is needed to create a basic local install of the tutorial.
  31
  32 Now run the :manual:`cmake  <cmake(1)>` executable or the
  33 :manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
  34 with your chosen build tool.
  35
  36 Then run the install step by using the ``install`` option of the
  37 :manual:`cmake  <cmake(1)>` command (introduced in 3.15, older versions of
  38 CMake must use ``make install``) from the command line. For
  39 multi-configuration tools, don't forget to use the ``--config`` argument to
  40 specify the configuration. If using an IDE, simply build the ``INSTALL``
  41 target. This step will install the appropriate header files, libraries, and
  42 executables. For example:
  43
  44 .. code-block:: console
  45
  46   cmake --install .
  47
  48 The CMake variable :variable:`CMAKE_INSTALL_PREFIX` is used to determine the
  49 root of where the files will be installed. If using the ``cmake --install``
  50 command, the installation prefix can be overridden via the ``--prefix``
  51 argument. For example:
  52
  53 .. code-block:: console
  54
  55   cmake --install . --prefix "/home/myuser/installdir"
  56
  57 Navigate to the install directory and verify that the installed Tutorial runs.
  58
  59 .. _`Tutorial Testing Support`:
  60
  61 Testing Support
  62 ---------------
  63
  64 Next let's test our application. At the end of the top-level ``CMakeLists.txt``
  65 file we can enable testing and then add a number of basic tests to verify that
  66 the application is working correctly.
  67
  68 .. literalinclude:: Step5/CMakeLists.txt
  69   :caption: CMakeLists.txt
  70   :name: CMakeLists.txt-enable_testing
  71   :language: cmake
  72   :start-after: # enable testing
  73
  74 The first test simply verifies that the application runs, does not segfault or
  75 otherwise crash, and has a zero return value. This is the basic form of a
  76 CTest test.
  77
  78 The next test makes use of the :prop_test:`PASS_REGULAR_EXPRESSION` test
  79 property to verify that the output of the test contains certain strings. In
  80 this case, verifying that the usage message is printed when an incorrect number
  81 of arguments are provided.
  82
  83 Lastly, we have a function called ``do_test`` that runs the application and
  84 verifies that the computed square root is correct for given input. For each
  85 invocation of ``do_test``, another test is added to the project with a name,
  86 input, and expected results based on the passed arguments.
  87
  88 Rebuild the application and then cd to the binary directory and run the
  89 :manual:`ctest <ctest(1)>` executable: ``ctest -N`` and ``ctest -VV``. For
  90 multi-config generators (e.g. Visual Studio), the configuration type must be
  91 specified with the ``-C <mode>`` flag.  For example, to run tests in Debug
  92 mode use ``ctest -C Debug -VV`` from the binary directory
  93 (not the Debug subdirectory!). Release mode would be executed from the same
  94 location but with a ``-C Release``.  Alternatively, build the ``RUN_TESTS``
  95 target from the IDE.