Help/guide/tutorial/Adding a Custom Command and Generated File.rst

   1 Step 6: Adding a Custom Command and Generated File
   2 ==================================================
   3
   4 Suppose, for the purpose of this tutorial, we decide that we never want to use
   5 the platform ``log`` and ``exp`` functions and instead would like to
   6 generate a table of precomputed values to use in the ``mysqrt`` function.
   7 In this section, we will create the table as part of the build process,
   8 and then compile that table into our application.
   9
  10 First, let's remove the check for the ``log`` and ``exp`` functions in
  11 ``MathFunctions/CMakeLists.txt``. Then remove the check for ``HAVE_LOG`` and
  12 ``HAVE_EXP`` from ``mysqrt.cxx``. At the same time, we can remove
  13 :code:`#include <cmath>`.
  14
  15 In the ``MathFunctions`` subdirectory, a new source file named
  16 ``MakeTable.cxx`` has been provided to generate the table.
  17
  18 After reviewing the file, we can see that the table is produced as valid C++
  19 code and that the output filename is passed in as an argument.
  20
  21 The next step is to add the appropriate commands to the
  22 ``MathFunctions/CMakeLists.txt`` file to build the MakeTable executable and
  23 then run it as part of the build process. A few commands are needed to
  24 accomplish this.
  25
  26 First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for
  27 ``MakeTable`` is added as any other executable would be added.
  28
  29 .. literalinclude:: Step7/MathFunctions/CMakeLists.txt
  30   :caption: MathFunctions/CMakeLists.txt
  31   :name: MathFunctions/CMakeLists.txt-add_executable-MakeTable
  32   :language: cmake
  33   :start-after: # first we add the executable that generates the table
  34   :end-before: # add the command to generate the source code
  35
  36 Then we add a custom command that specifies how to produce ``Table.h``
  37 by running MakeTable.
  38
  39 .. literalinclude:: Step7/MathFunctions/CMakeLists.txt
  40   :caption: MathFunctions/CMakeLists.txt
  41   :name: MathFunctions/CMakeLists.txt-add_custom_command-Table.h
  42   :language: cmake
  43   :start-after: # add the command to generate the source code
  44   :end-before: # add the main library
  45
  46 Next we have to let CMake know that ``mysqrt.cxx`` depends on the generated
  47 file ``Table.h``. This is done by adding the generated ``Table.h`` to the list
  48 of sources for the library MathFunctions.
  49
  50 .. literalinclude:: Step7/MathFunctions/CMakeLists.txt
  51   :caption: MathFunctions/CMakeLists.txt
  52   :name: MathFunctions/CMakeLists.txt-add_library-Table.h
  53   :language: cmake
  54   :start-after: # add the main library
  55   :end-before: # state that anybody linking
  56
  57 We also have to add the current binary directory to the list of include
  58 directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``.
  59
  60 .. literalinclude:: Step7/MathFunctions/CMakeLists.txt
  61   :caption: MathFunctions/CMakeLists.txt
  62   :name: MathFunctions/CMakeLists.txt-target_include_directories-Table.h
  63   :language: cmake
  64   :start-after: # state that we depend on our bin
  65   :end-before: # install rules
  66
  67 Now let's use the generated table. First, modify ``mysqrt.cxx`` to include
  68 ``Table.h``. Next, we can rewrite the ``mysqrt`` function to use the table:
  69
  70 .. literalinclude:: Step7/MathFunctions/mysqrt.cxx
  71   :caption: MathFunctions/mysqrt.cxx
  72   :name: MathFunctions/mysqrt.cxx
  73   :language: c++
  74   :start-after: // a hack square root calculation using simple operations
  75
  76 Run the :manual:`cmake  <cmake(1)>` executable or the
  77 :manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
  78 with your chosen build tool.
  79
  80 When this project is built it will first build the ``MakeTable`` executable.
  81 It will then run ``MakeTable`` to produce ``Table.h``. Finally, it will
  82 compile ``mysqrt.cxx`` which includes ``Table.h`` to produce the
  83 ``MathFunctions`` library.
  84
  85 Run the Tutorial executable and verify that it is using the table.