From 8a80b8fbe4a4f45a26b9fd7f075c14ae06176ad7 Mon Sep 17 00:00:00 2001 From: Betsy McPhail Date: Fri, 17 Jul 2020 12:17:26 -0400 Subject: Tutorial: Clarify Steps 1, 2 and 3 --- Help/guide/tutorial/index.rst | 78 ++++++++++++++++++++++++++++++------------- 1 file changed, 55 insertions(+), 23 deletions(-) diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst index e7ea290..e42b4f0 100644 --- a/Help/guide/tutorial/index.rst +++ b/Help/guide/tutorial/index.rst @@ -81,8 +81,8 @@ replaced. Next modify ``tutorial.cxx`` to include the configured header file, ``TutorialConfig.h``. -Finally, let's print out the version number by updating ``tutorial.cxx`` as -follows: +Finally, let's print out the executable name and version number by updating +``tutorial.cxx`` as follows: .. literalinclude:: Step2/tutorial.cxx :language: c++ @@ -106,7 +106,8 @@ correct flags. The easiest 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: +True. Make sure to add the ``CMAKE_CXX_STANDARD`` declarations above the call +to ``add_executable``. .. literalinclude:: Step2/CMakeLists.txt :language: cmake @@ -120,18 +121,28 @@ Run the :manual:`cmake ` executable or the 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 run the -following commands: +``Help/guide/tutorial`` directory of the CMake source code tree and create a +build directory: .. code-block:: console mkdir Step1_build + +Next, navigate to the build directory and run CMake 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 . -Navigate to the directory where Tutorial was built (likely the make directory -or a Debug or Release build configuration subdirectory) and run these commands: +Finally, try to use the newly built ``Tutorial`` with these commands: .. code-block:: console @@ -212,8 +223,9 @@ libraries to later be linked into the executable. The variable classic approach when dealing with many optional components, we will cover the modern approach in the next step. -The corresponding changes to the source code are fairly straightforward. First, -in ``tutorial.cxx``, include the ``MathFunctions.h`` header if we need it: +The corresponding changes to the source code are fairly straightforward. +First, in ``tutorial.cxx``, include the ``MathFunctions.h`` header if we +need it: .. literalinclude:: Step3/tutorial.cxx :language: c++ @@ -242,8 +254,17 @@ Run the :manual:`cmake ` executable or the :manual:`cmake-gui ` to configure the project and then build it with your chosen build tool. Then run the built Tutorial executable. -Use the :manual:`ccmake ` executable or the :manual:`cmake-gui ` -to update the value of ``USE_MYMATH``. Rebuild and run the tutorial again. +Now let's update the value of ``USE_MYMATH``. The easiest way is to use the +:manual:`cmake-gui ` or :manual:`ccmake ` 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 + +Rebuild and run the tutorial again. + Which function gives better results, sqrt or mysqrt? Adding Usage Requirements for Library (Step 3) @@ -320,21 +341,32 @@ And to the end of the top-level ``CMakeLists.txt`` we add: That is all that is needed to create a basic local install of the tutorial. -Run the :manual:`cmake ` executable or the +Now run the :manual:`cmake ` executable or the :manual:`cmake-gui ` to configure the project and then build it -with your chosen build tool. Run the install step by using the ``install`` -option of the :manual:`cmake ` command (introduced in 3.15, older -versions of CMake must use ``make install``) from the command line, or build -the ``INSTALL`` target from an IDE. This will install the appropriate header -files, libraries, and executables. +with your chosen build tool. + +Then run the install step by using the ``install`` option of the +:manual:`cmake ` command (introduced in 3.15, older versions of +CMake must use ``make install``) from the command line. For +multi-configuration tools, don't forget to use the ``--config`` argument to +specify the configuration. If using an IDE, simply build the ``INSTALL`` +target. This step will install the appropriate header files, libraries, and +executables. For example: + +.. code-block:: console + + cmake --install . The CMake variable :variable:`CMAKE_INSTALL_PREFIX` is used to determine the -root of where the files will be installed. If using ``cmake --install`` a -custom installation directory can be given via the ``--prefix`` argument. For -multi-configuration tools, use the ``--config`` argument to specify the -configuration. +root of where the files will be installed. If using the ``cmake --install`` +command, the installation prefix can be overidden via the ``--prefix`` +argument. For example: + +.. code-block:: console + + cmake --install . --prefix "/home/myuser/installdir" -Verify that the installed Tutorial runs. +Navigate to the install directory and verify that the installed Tutorial runs. Testing Support --------------- @@ -750,7 +782,7 @@ A common usage of :manual:`generator expressions ` 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. Lets start by constructing an +target allowing this information to propagate. Let's start by constructing an ``INTERFACE`` target and specifying the required C++ standard level of ``11`` instead of using :variable:`CMAKE_CXX_STANDARD`. -- cgit v0.12