diff options
Diffstat (limited to 'Help')
-rw-r--r-- | Help/command/file.rst | 20 | ||||
-rw-r--r-- | Help/command/list.rst | 2 | ||||
-rw-r--r-- | Help/command/load_cache.rst | 4 | ||||
-rw-r--r-- | Help/guide/tutorial/index.rst | 129 | ||||
-rw-r--r-- | Help/manual/cmake-compile-features.7.rst | 22 | ||||
-rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 4 |
6 files changed, 92 insertions, 89 deletions
diff --git a/Help/command/file.rst b/Help/command/file.rst index 83e4516..b186177 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -187,14 +187,14 @@ The arguments are as follows: are typically created with :command:`add_executable`, but they do not have to be created by CMake. On Apple platforms, the paths to these files determine the value of ``@executable_path`` when recursively resolving the libraries. - Specifying ``STATIC`` libraries, ``MODULE`` s, or ``SHARED`` libraries here + Specifying any kind of library (``STATIC``, ``MODULE``, or ``SHARED``) here will result in undefined behavior. ``LIBRARIES <library_files>`` List of library files to read for dependencies. These are libraries that are typically created with :command:`add_library(SHARED)`, but they do not have - to be created by CMake. Specifying ``STATIC`` libraries, ``MODULE`` s, or - executables here will result in undefined behavior. + to be created by CMake. Specifying ``STATIC`` libraries, ``MODULE`` + libraries, or executables here will result in undefined behavior. ``MODULES <module_files>`` List of loadable module files to read for dependencies. These are modules @@ -209,13 +209,13 @@ The arguments are as follows: platforms, these directories are searched if the dependency is not found in any of the other usual paths. If it is found in such a directory, a warning is issued, because it means that the file is incomplete (it does not list all - of the directories that contain its dependencies.) On Windows platforms, + of the directories that contain its dependencies). On Windows platforms, these directories are searched if the dependency is not found in any of the other search paths, but no warning is issued, because searching other paths is a normal part of Windows dependency resolution. On Apple platforms, this argument has no effect. -``BUNDLE_EXECTUBLE <bundle_executable_file>`` +``BUNDLE_EXECUTABLE <bundle_executable_file>`` Executable to treat as the "bundle executable" when resolving libraries. On Apple platforms, this argument determines the value of ``@executable_path`` when recursively resolving libraries for ``LIBRARIES`` and ``MODULES`` files. @@ -284,7 +284,7 @@ On Linux platforms, library resolution works as follows: dependency is resolved to that file. In this case, a warning is issued, because finding a file in one of the ``DIRECTORIES`` means that the depending file is not complete (it does not list all the directories from - which it pulls dependencies.) + which it pulls dependencies). 5. Otherwise, the dependency is unresolved. On Windows platforms, library resolution works as follows: @@ -331,8 +331,8 @@ On Windows platforms, library resolution works as follows: dependency is resolved to that file. 5. Otherwise, if the library exists in one of the directories specified by ``DIRECTORIES``, in the order they are listed, the dependency is resolved to - that file. (In this case, a warning is not issued, because searching other - directories is a normal part of Windows library resolution.) + that file. In this case, a warning is not issued, because searching other + directories is a normal part of Windows library resolution. 6. Otherwise, the dependency is unresolved. On Apple platforms, library resolution works as follows: @@ -350,9 +350,9 @@ On Apple platforms, library resolution works as follows: existing file, the dependency is resolved to that file. 4. Otherwise, if the dependency starts with ``@rpath/``, and replacing ``@rpath/`` with one of the ``RPATH`` entries of the depending file yields - an existing file, the dependency is resolved to that file. (Note that + an existing file, the dependency is resolved to that file. Note that ``RPATH`` entries that start with ``@executable_path/`` or ``@loader_path/`` - also have these items replaced with the appropriate path.) + also have these items replaced with the appropriate path. 5. Otherwise, if the dependency is an absolute file that exists, the dependency is resolved to that file. 6. Otherwise, the dependency is unresolved. diff --git a/Help/command/list.rst b/Help/command/list.rst index 39e7e2a..50bf417 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -180,7 +180,7 @@ Insert elements to the 0th position in the list. list(REMOVE_ITEM <list> <value> [<value> ...]) -Removes the given items from the list. +Removes all instances of the given items from the list. .. _REMOVE_AT: diff --git a/Help/command/load_cache.rst b/Help/command/load_cache.rst index 33625c4..b89eb61 100644 --- a/Help/command/load_cache.rst +++ b/Help/command/load_cache.rst @@ -5,7 +5,7 @@ Load in the values from another project's CMake cache. .. code-block:: cmake - load_cache(pathToCacheFile READ_WITH_PREFIX prefix entry1...) + load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...) Reads the cache and store the requested entries in variables with their name prefixed with the given prefix. This only reads the values, and @@ -13,7 +13,7 @@ does not create entries in the local project's cache. .. code-block:: cmake - load_cache(pathToCacheFile [EXCLUDE entry1...] + load_cache(pathToBuildDirectory [EXCLUDE entry1...] [INCLUDE_INTERNALS entry1...]) Loads in the values from another cache and store them in the local diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst index d858c25..3f20aa2 100644 --- a/Help/guide/tutorial/index.rst +++ b/Help/guide/tutorial/index.rst @@ -18,9 +18,9 @@ A Basic Starting Point (Step 1) =============================== The most basic project is an executable built from source code files. -For simple projects, a three line CMakeLists file is all that is required. -This will be the starting point for our tutorial. Create a ``CMakeLists.txt`` -file in the ``Step1`` directory that looks like: +For simple projects, a three line ``CMakeLists.txt`` file is all that is +required. This will be the starting point for our tutorial. Create a +``CMakeLists.txt`` file in the ``Step1`` directory that looks like: .. code-block:: cmake @@ -33,7 +33,7 @@ file in the ``Step1`` directory that looks like: add_executable(Tutorial tutorial.cxx) -Note that this example uses lower case commands in the CMakeLists file. +Note that this example uses lower case commands in the ``CMakeLists.txt`` file. Upper, lower, and mixed case commands are supported by CMake. The source code for ``tutorial.cxx`` is provided in the ``Step1`` directory and can be used to compute the square root of a number. @@ -43,9 +43,9 @@ Adding a Version Number and Configured Header File The first feature we will add is to provide our executable and project with a version number. While we could do this exclusively in the source code, using -CMakeLists provides more flexibility. +``CMakeLists.txt`` provides more flexibility. -First, modify the CMakeLists file to set the version number. +First, modify the ``CMakeLists.txt`` file to set the version number. .. literalinclude:: Step2/CMakeLists.txt :language: cmake @@ -61,7 +61,7 @@ code: Since the configured file will be written into the binary tree, we must add that directory to the list of paths to search for include -files. Add the following lines to the end of the CMakeLists file: +files. Add the following lines to the end of the ``CMakeLists.txt`` file: .. literalinclude:: Step2/CMakeLists.txt :language: cmake @@ -103,8 +103,8 @@ Next let's add some C++11 features to our project by replacing ``atof`` with We will need to explicitly state in the CMake code that it should use the correct flags. The easiest way to enable support for a specific C++ standard in CMake is by using the ``CMAKE_CXX_STANDARD`` variable. For this tutorial, -set the ``CMAKE_CXX_STANDARD`` variable in the CMakeLists file to 11 and -``CMAKE_CXX_STANDARD_REQUIRED`` to True: +set the ``CMAKE_CXX_STANDARD`` variable in the ``CMakeLists.txt`` file to 11 +and ``CMAKE_CXX_STANDARD_REQUIRED`` to True: .. literalinclude:: Step2/CMakeLists.txt :language: cmake @@ -145,22 +145,22 @@ 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, +called ``MathFunctions``. This directory already contains a header file, ``MathFunctions.h``, and a source file ``mysqrt.cxx``. The source file has one function called ``mysqrt`` that provides similar functionality to the compiler's ``sqrt`` function. -Add the following one line ``CMakeLists.txt`` file to the MathFunctions +Add the following one line ``CMakeLists.txt`` file to the ``MathFunctions`` directory: .. literalinclude:: Step3/MathFunctions/CMakeLists.txt :language: cmake To make use of the new library we will add an ``add_subdirectory`` call in the -top-level CMakeLists file so that the library will get built. We add the new -library to the executable, and add MathFunctions as an include directory so -that the ``mqsqrt.h`` header file can be found. The last few lines of the -top-level CMakeLists file should now look like: +top-level ``CMakeLists.txt`` file so that the library will get built. We add +the new library to the executable, and add ``MathFunctions`` as an include +directory so that the ``mqsqrt.h`` header file can be found. The last few lines +of the top-level ``CMakeLists.txt`` file should now look like: .. code-block:: cmake @@ -181,8 +181,8 @@ top-level CMakeLists file should now look like: 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. The first step is to add an option to the top-level CMakeLists -file. +occurrence. The first step is to add an option to the top-level +``CMakeLists.txt`` file. .. literalinclude:: Step3/CMakeLists.txt :language: cmake @@ -195,8 +195,8 @@ the cache so that the user does not need to set the value each time they run CMake on a build directory. The next change is to make building and linking the MathFunctions library -conditional. To do this we change the end of the top-level CMakeLists file to -look like the following: +conditional. To do this we change the end of the top-level ``CMakeLists.txt`` +file to look like the following: .. literalinclude:: Step3/CMakeLists.txt :language: cmake @@ -209,15 +209,15 @@ 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 header if we need it: +in ``tutorial.cxx``, include the ``MathFunctions.h`` header if we need it: .. literalinclude:: Step3/tutorial.cxx :language: c++ :start-after: // should we include the MathFunctions header :end-before: int main -Then, in the same file, make which square root function is used dependent on -``USE_MYMATH``: +Then, in the same file, make ``USE_MYMATH`` control which square root +function is used: .. literalinclude:: Step3/tutorial.cxx :language: c++ @@ -268,7 +268,7 @@ doesn't. Add the following lines to the end of ``MathFunctions/CMakeLists.txt``: 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, here: +``CMakeLists.txt``, here: .. literalinclude:: Step4/CMakeLists.txt :language: cmake @@ -330,9 +330,9 @@ Verify that the installed Tutorial runs. Testing Support --------------- -Next let's test our application. At the end of the top-level CMakeLists file we -can enable testing and then add a number of basic tests to verify that the -application is working correctly. +Next let's test our application. At the end of the top-level ``CMakeLists.txt`` +file we can enable testing and then add a number of basic tests to verify that +the application is working correctly. .. literalinclude:: Step5/CMakeLists.txt :language: cmake @@ -344,7 +344,7 @@ test. The next test makes use of the ``PASS_REGULAR_EXPRESSION`` test property to verify that the output of the test contains certain strings. In this case, -verifying that the the usage message is printed when an incorrect number of +verifying that the usage message is printed when an incorrect number of arguments are provided. Lastly, we have a function called ``do_test`` that runs the application and @@ -370,9 +370,9 @@ 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 ``CheckSymbolExists.cmake`` macro in the top-level -CMakeLists. We're going to use the new defines in ``TutorialConfig.h.in``, -so be sure to set them before that file is configured. +these functions using the ``CheckSymbolExists`` module in the top-level +``CMakeLists.txt``. We're going to use the new defines in +``TutorialConfig.h.in``, so be sure to set them before that file is configured. .. literalinclude:: Step6/MathFunctions/CMakeLists.txt :language: cmake @@ -405,9 +405,8 @@ You will notice that we're not using ``log`` and ``exp``, even if we think they should be available. We should realize quickly that we have forgotten to include ``TutorialConfig.h`` in ``mysqrt.cxx``. -We will also need to update MathFunctions/CMakeLists so ``mysqrt.cxx`` knows -where this file is located: - +We will also need to update ``MathFunctions/CMakeLists.txt`` so ``mysqrt.cxx`` +knows where this file is located: .. code-block:: cmake @@ -432,10 +431,10 @@ other than in ``TutorialConfig.h``? Let's try to use First, remove the defines from ``TutorialConfig.h.in``. We no longer need to include ``TutorialConfig.h`` from ``mysqrt.cxx`` or the extra include in -MathFunctions/CMakeLists. +``MathFunctions/CMakeLists.txt``. Next, we can move the check for ``HAVE_LOG`` and ``HAVE_EXP`` to -MathFunctions/CMakeLists and then add specify those values as ``PRIVATE`` +``MathFunctions/CMakeLists.txt`` and then specify those values as ``PRIVATE`` compile definitions. .. literalinclude:: Step6/MathFunctions/CMakeLists.txt @@ -444,7 +443,7 @@ compile definitions. :end-before: # install rules After making these updates, go ahead and build the project again. Run the -built Tutorial executable and verify that the results are same as earlier in +built Tutorial executable and verify that the results are same as earlier in this step. Adding a Custom Command and Generated File (Step 6) @@ -457,22 +456,23 @@ 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. Then remove the check for ``HAVE_LOG`` and +``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`` +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 MathFunctions CMakeLists -file to build the MakeTable executable and then run it as part of the build -process. A few commands are needed to accomplish this. +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, the executable for ``MakeTable`` -is added as any other executable would be added. +First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for +``MakeTable`` is added as any other executable would be added. .. literalinclude:: Step7/MathFunctions/CMakeLists.txt :language: cmake @@ -619,7 +619,7 @@ type must be specified:: Or, from an IDE, build the ``Experimental`` target. -Ctest will build and test the project and submit the results to the Kitware +``ctest`` will build and test the project and submit the results to the Kitware public dashboard. The results of your dashboard will be uploaded to Kitware's public dashboard here: https://my.cdash.org/index.php?project=CMakeTutorial. @@ -628,8 +628,8 @@ Mixing Static and Shared (Step 9) In this section we will show how by using the ``BUILD_SHARED_LIBS`` variable we can control the default behavior of ``add_library``, and allow control -over how libraries without an explicit type (STATIC/SHARED/MODULE/OBJECT) are -built. +over how libraries without an explicit type (``STATIC``, ``SHARED``, ``MODULE`` +or ``OBJECT``) are built. To accomplish this we need to add ``BUILD_SHARED_LIBS`` to the top-level ``CMakeLists.txt``. We use the ``option`` command as it allows users to @@ -678,10 +678,10 @@ Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines: :language: c++ At this point, if you build everything, you will notice that linking fails -as we are combining a static library without position enabled code with a -library that has position enabled code. The solution to this is to explicitly -set the ``POSITION_INDEPENDENT_CODE`` target property of SqrtLibrary to be -True no matter the build type. +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 ``POSITION_INDEPENDENT_CODE`` target property of SqrtLibrary +to be True no matter the build type. .. literalinclude:: Step10/MathFunctions/CMakeLists.txt :language: cmake @@ -718,7 +718,7 @@ string, and ``<1:...>`` results in the content of "...". They can also be nested. A common usage of generator expressions is to conditionally add compiler -flags, such as those as language levels or warnings. A nice pattern is +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 ``INTERFACE`` target and specifying the required C++ standard level of ``11`` instead @@ -816,19 +816,19 @@ directory and from an install / package. This means converting the :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 see verify that it doesn't +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 ``find_package command`` can find our project. So let's go +that the CMake ``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:: Complete/Config.cmake.in Then, to properly configure and install that file, add the following to the -bottom of the top-level CMakeLists: +bottom of the top-level ``CMakeLists.txt``: .. literalinclude:: Complete/CMakeLists.txt :language: cmake @@ -838,7 +838,7 @@ bottom of the top-level CMakeLists: 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: +the following to the bottom of the top level ``CMakeLists.txt``: .. literalinclude:: Complete/CMakeLists.txt :language: cmake @@ -851,7 +851,7 @@ other projects, without needing it to be installed. Import a CMake Project (Consumer) ================================= -This examples shows how a project can find other CMake packages that +This example shows how a project can find other CMake packages that generate ``Config.cmake`` files. It also shows how to state a project's external dependencies when generating @@ -860,22 +860,24 @@ a ``Config.cmake``. Packaging Debug and Release (MultiPackage) ========================================== -By default CMake is model is that a build directory only contains a single +By default CMake's model is that a build directory only contains a single configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo. But it is possible to setup CPack to bundle multiple build directories at the same time to build a package that contains multiple configurations of the same project. -First we need to ahead and construct a directory called ``multi_config`` this +First we need to construct a directory called ``multi_config``, which will contain all the builds that we want to package together. Second create a ``debug`` and ``release`` directory underneath ``multi_config``. At the end you should have a layout that looks like: -─ multi_config - ├── debug - └── release +.. code-block:: none + + ─ multi_config + ├── debug + └── release Now we need to setup debug and release builds, which would roughly entail the following: @@ -891,8 +893,9 @@ the following: cd .. -Now that both the debug and release builds are complete we can now use -the custom MultiCPackConfig to package both builds into a single release. +Now that both the debug and release builds are complete, we can use +a custom ``MultiCPackConfig.cmake`` file to package both builds into a single +release. .. code-block:: console diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 658694a..a9d4843 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -331,12 +331,12 @@ and :prop_gbl:`compile features <CMAKE_CXX_KNOWN_FEATURES>` available from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: -* ``AppleClang``: Apple Clang for Xcode versions 4.4 though 9.2. -* ``Clang``: Clang compiler versions 2.9 through 6.0. -* ``GNU``: GNU compiler versions 4.4 through 8.0. -* ``MSVC``: Microsoft Visual Studio versions 2010 through 2017. -* ``SunPro``: Oracle SolarisStudio versions 12.4 through 12.6. -* ``Intel``: Intel compiler versions 12.1 through 17.0. +* ``AppleClang``: Apple Clang for Xcode versions 4.4+. +* ``Clang``: Clang compiler versions 2.9+. +* ``GNU``: GNU compiler versions 4.4+. +* ``MSVC``: Microsoft Visual Studio versions 2010+. +* ``SunPro``: Oracle SolarisStudio versions 12.4+. +* ``Intel``: Intel compiler versions 12.1+. CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>` and :prop_gbl:`compile features <CMAKE_C_KNOWN_FEATURES>` available from @@ -344,16 +344,16 @@ the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: * all compilers and versions listed above for C++. -* ``GNU``: GNU compiler versions 3.4 through 8.0. +* ``GNU``: GNU compiler versions 3.4+ CMake is currently aware of the :prop_tgt:`C++ standards <CXX_STANDARD>` and their associated meta-features (e.g. ``cxx_std_11``) available from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: -* ``Cray``: Cray Compiler Environment version 8.1 through 8.5.8. -* ``PGI``: PGI version 12.10 through 17.5. -* ``XL``: IBM XL version 10.1 through 13.1.5. +* ``Cray``: Cray Compiler Environment version 8.1+. +* ``PGI``: PGI version 12.10+. +* ``XL``: IBM XL version 10.1+. CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>` and their associated meta-features (e.g. ``c_std_99``) available from the @@ -367,4 +367,4 @@ CMake is currently aware of the :prop_tgt:`CUDA standards <CUDA_STANDARD>` from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: -* ``NVIDIA``: NVIDIA nvcc compiler 7.5 though 9.1. +* ``NVIDIA``: NVIDIA nvcc compiler 7.5+. diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index ba9887c..75f4bd4 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -47,8 +47,8 @@ Logical Operators ----------------- ``$<BOOL:string>`` - Converts ``string`` to ``0`` or ``1`` according to the rules of the - :command:`if()` command. Evaluates to ``0`` if any of the following is true: + Converts ``string`` to ``0`` or ``1``. Evaluates to ``0`` if any of the + following is true: * ``string`` is empty, * ``string`` is a case-insensitive equal of |