diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/file.rst | 46 | ||||
| -rw-r--r-- | Help/command/get_filename_component.rst | 7 | ||||
| -rw-r--r-- | Help/command/try_compile.rst | 44 | ||||
| -rw-r--r-- | Help/command/try_run.rst | 14 | ||||
| -rw-r--r-- | Help/manual/cmake-modules.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/ctest.1.rst | 5 | ||||
| -rw-r--r-- | Help/module/FindOctave.rst | 1 | ||||
| -rw-r--r-- | Help/policy/CMP0083.rst | 7 | ||||
| -rw-r--r-- | Help/prop_tgt/BUILD_RPATH_USE_ORIGIN.rst | 14 | ||||
| -rw-r--r-- | Help/prop_tgt/EXCLUDE_FROM_ALL.rst | 12 | ||||
| -rw-r--r-- | Help/release/3.14.rst | 13 | ||||
| -rw-r--r-- | Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst | 7 |
12 files changed, 99 insertions, 72 deletions
diff --git a/Help/command/file.rst b/Help/command/file.rst index db4d6fce7b..465e567439 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -26,8 +26,8 @@ Synopsis file(`MAKE_DIRECTORY`_ [<dir>...]) file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...]) file(`SIZE`_ <filename> <out-var>) - file(`READ_SYMLINK`_ <filename> <out-var>) - file(`CREATE_LINK`_ <file> <new-file> [...]) + file(`READ_SYMLINK`_ <linkname> <out-var>) + file(`CREATE_LINK`_ <original> <linkname> [...]) `Path Conversion`_ file(`RELATIVE_PATH`_ <out-var> <directory> <file>) @@ -350,22 +350,22 @@ pointing to a file and is readable. .. code-block:: cmake - file(READ_SYMLINK <filename> <variable>) + file(READ_SYMLINK <linkname> <variable>) -Read the symlink at ``<filename>`` and put the result in ``<variable>``. -Requires that ``<filename>`` is a valid path pointing to a symlink. If -``<filename>`` does not exist, or is not a symlink, an error is thrown. +This subcommand queries the symlink ``<linkname>`` and stores the path it +points to in the result ``<variable>``. If ``<linkname>`` does not exist or +is not a symlink, CMake issues a fatal error. Note that this command returns the raw symlink path and does not resolve -relative symlinks. If you want to resolve the relative symlink yourself, you -could do something like this: +a relative path. The following is an example of how to ensure that an +absolute path is obtained: .. code-block:: cmake - set(filename "/path/to/foo.sym") - file(READ_SYMLINK "${filename}" result) + set(linkname "/path/to/foo.sym") + file(READ_SYMLINK "${linkname}" result) if(NOT IS_ABSOLUTE "${result}") - get_filename_component(dir "${filename}" DIRECTORY) + get_filename_component(dir "${linkname}" DIRECTORY) set(result "${dir}/${result}") endif() @@ -373,23 +373,23 @@ could do something like this: .. code-block:: cmake - file(CREATE_LINK <file> <new-file> + file(CREATE_LINK <original> <linkname> [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC]) -Create a link to ``<file>`` at ``<new-file>``. +Create a link ``<linkname>`` that points to ``<original>``. +It will be a hard link by default, but providing the ``SYMBOLIC`` option +results in a symbolic link instead. Hard links require that ``original`` +exists and is a file, not a directory. If ``<linkname>`` already exists, +it will be overwritten. -It is a hard link by default. This can be changed to symbolic links by -using ``SYMBOLIC``. The original file needs to exist for hard links. - -The ``<result>`` variable, if specified, gets the status of the operation. -It is set to ``0`` in case of success. Otherwise, it contains the error -generated. In case of failures, if ``RESULT`` is not specified, a fatal error -is emitted. +The ``<result>`` variable, if specified, receives the status of the operation. +It is set to ``0`` upon success or an error message otherwise. If ``RESULT`` +is not specified and the operation fails, a fatal error is emitted. Specifying ``COPY_ON_ERROR`` enables copying the file as a fallback if -creating the link fails. - -Overwrites the ``<new-file>`` if it exists. +creating the link fails. It can be useful for handling situations such as +``<original>`` and ``<linkname>`` being on different drives or mount points, +which would make them unable to support a hard link. Path Conversion ^^^^^^^^^^^^^^^ diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst index f55499ac51..9bbf87714b 100644 --- a/Help/command/get_filename_component.rst +++ b/Help/command/get_filename_component.rst @@ -15,14 +15,13 @@ Sets ``<var>`` to a component of ``<FileName>``, where ``<mode>`` is one of: NAME = File name without directory EXT = File name longest extension (.b.c from d/a.b.c) NAME_WE = File name without directory or longest extension - LAST_EXT = File name last extention (.c from d/a.b.c) + LAST_EXT = File name last extension (.c from d/a.b.c) NAME_WLE = File name without directory or last extension PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11) Paths are returned with forward slashes and have no trailing slashes. -The longest file extension is always considered. If the optional -``CACHE`` argument is specified, the result variable is added to the -cache. +If the optional ``CACHE`` argument is specified, the result variable is +added to the cache. .. code-block:: cmake diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 77f42a1be5..ca8fc77fab 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -12,12 +12,12 @@ Try Compiling Whole Projects .. code-block:: cmake - try_compile(RESULT_VAR <bindir> <srcdir> + try_compile(<resultVar> <bindir> <srcdir> <projectName> [<targetName>] [CMAKE_FLAGS <flags>...] [OUTPUT_VARIABLE <var>]) Try building a project. The success or failure of the ``try_compile``, -i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``RESULT_VAR``. +i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``. In this form, ``<srcdir>`` should contain a complete CMake project with a ``CMakeLists.txt`` file and all sources. The ``<bindir>`` and ``<srcdir>`` @@ -30,7 +30,7 @@ Try Compiling Source Files .. code-block:: cmake - try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...> + try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...> [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] [LINK_OPTIONS <options>...] @@ -42,13 +42,19 @@ Try Compiling Source Files [<LANG>_EXTENSIONS <bool>] ) -Try building an executable from one or more source files. The success or -failure of the ``try_compile``, i.e. ``TRUE`` or ``FALSE`` respectively, is -returned in ``RESULT_VAR``. +Try building an executable or static library from one or more source files +(which one is determined by the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` +variable). The success or failure of the ``try_compile``, i.e. ``TRUE`` or +``FALSE`` respectively, is returned in ``<resultVar>``. -In this form the user need only supply one or more source files that include a -definition for ``main``. CMake will create a ``CMakeLists.txt`` file to build -the source(s) as an executable that looks something like this: +In this form, one or more source files must be provided. If +:variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is unset or is set to ``EXECUTABLE``, +the sources must include a definition for ``main`` and CMake will create a +``CMakeLists.txt`` file to build the source(s) as an executable. +If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``STATIC_LIBRARY``, +a static library will be built instead and no definition for ``main`` is +required. For an executable, the generated ``CMakeLists.txt`` file would +contain something like the following: .. code-block:: cmake @@ -73,7 +79,7 @@ The options are: in the generated test project. ``COPY_FILE <fileName>`` - Copy the linked executable to the given ``<fileName>``. + Copy the built executable or static library to the given ``<fileName>``. ``COPY_FILE_ERROR <var>`` Use after ``COPY_FILE`` to capture into variable ``<var>`` any error @@ -88,12 +94,12 @@ The options are: given to the ``CMAKE_FLAGS`` option will be ignored. ``LINK_OPTIONS <options>...`` - Specify link step options to pass to :command:`target_link_options` or - to :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated - project, depending of the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable. + Specify link step options to pass to :command:`target_link_options` or to + set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated + project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable. ``OUTPUT_VARIABLE <var>`` - Store the output from the build process the given variable. + Store the output from the build process in the given variable. ``<LANG>_STANDARD <std>`` Specify the :prop_tgt:`C_STANDARD`, :prop_tgt:`CXX_STANDARD`, @@ -114,7 +120,7 @@ passed to ``cmake`` to avoid this clean. However, multiple sequential ``try_compile`` operations reuse this single output directory. If you use ``--debug-trycompile``, you can only debug one ``try_compile`` call at a time. The recommended procedure is to protect all ``try_compile`` calls in your -project by ``if(NOT DEFINED RESULT_VAR)`` logic, configure with cmake +project by ``if(NOT DEFINED <resultVar>)`` logic, configure with cmake all the way through once, then delete the cache entry associated with the try_compile call of interest, and then re-run cmake again with ``--debug-trycompile``. @@ -139,8 +145,8 @@ behavior at link time, the ``check_pie_supported()`` command from the :module:`CheckPIESupported` module must be called before using the :command:`try_compile` command. -The current settings of :policy:`CMP0065` and :policy:`CMP0083` are set in the -generated project. +The current settings of :policy:`CMP0065` and :policy:`CMP0083` are propagated +through to the generated test project. Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose a build configuration. @@ -150,7 +156,9 @@ the type of target used for the source file signature. Set the :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable to specify variables that must be propagated into the test project. This variable is -meant for use only in toolchain files. +meant for use only in toolchain files and is only honored by the +``try_compile()`` command for the source files form, not when given a whole +project. If :policy:`CMP0067` is set to ``NEW``, or any of the ``<LANG>_STANDARD``, ``<LANG>_STANDARD_REQUIRED``, or ``<LANG>_EXTENSIONS`` options are used, diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index 137402f34b..d401ebe929 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst @@ -12,8 +12,8 @@ Try Compiling and Running Source Files .. code-block:: cmake - try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR - bindir srcfile [CMAKE_FLAGS <flags>...] + try_run(<runResultVar> <compileResultVar> + <bindir> <srcfile> [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] [LINK_OPTIONS <options>...] [LINK_LIBRARIES <libs>...] @@ -23,9 +23,9 @@ Try Compiling and Running Source Files [ARGS <args>...]) Try compiling a ``<srcfile>``. Returns ``TRUE`` or ``FALSE`` for success -or failure in ``COMPILE_RESULT_VAR``. If the compile succeeded, runs the -executable and returns its exit code in ``RUN_RESULT_VAR``. If the -executable was built, but failed to run, then ``RUN_RESULT_VAR`` will be +or failure in ``<compileResultVar>``. If the compile succeeded, runs the +executable and returns its exit code in ``<runResultVar>``. If the +executable was built, but failed to run, then ``<runResultVar>`` will be set to ``FAILED_TO_RUN``. See the :command:`try_compile` command for information on how the test project is constructed to build the source file. @@ -85,10 +85,10 @@ presetting them in some CMake script file to the values the executable would have produced if it had been run on its actual target platform. These cache entries are: -``<RUN_RESULT_VAR>`` +``<runResultVar>`` Exit code if the executable were to be run on the target platform. -``<RUN_RESULT_VAR>__TRYRUN_OUTPUT`` +``<runResultVar>__TRYRUN_OUTPUT`` Output from stdout and stderr if the executable were to be run on the target platform. This is created only if the ``RUN_OUTPUT_VARIABLE`` or ``OUTPUT_VARIABLE`` option was used. diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 71a8b009b9..d9b939f3bf 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -178,7 +178,6 @@ They are normally called through the :command:`find_package` command. /module/FindMPEG2 /module/FindMPEG /module/FindMPI - /module/FindOctave /module/FindODBC /module/FindOpenACC /module/FindOpenAL diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index bcf75ac7f1..d1bd69b664 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -11,8 +11,9 @@ Synopsis .. parsed-literal:: ctest [<options>] - ctest <path-to-source> <path-to-build> --build-generator <generator> - [<options>...] [-- <build-options>...] [--test-command <test>] + ctest --build-and-test <path-to-source> <path-to-build> + --build-generator <generator> [<options>...] + [--build-options <opts>...] [--test-command <command> [<args>...]] ctest {-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>} [-- <dashboard-options>...] diff --git a/Help/module/FindOctave.rst b/Help/module/FindOctave.rst deleted file mode 100644 index 2dbcec4339..0000000000 --- a/Help/module/FindOctave.rst +++ /dev/null @@ -1 +0,0 @@ -.. cmake-module:: ../../Modules/FindOctave.cmake diff --git a/Help/policy/CMP0083.rst b/Help/policy/CMP0083.rst index b26d6c8d96..32acf1f126 100644 --- a/Help/policy/CMP0083.rst +++ b/Help/policy/CMP0083.rst @@ -23,9 +23,10 @@ which it is used, it is the project's responsibility to use the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property for executables will be honored at link time. -This policy was introduced in CMake version 3.14. CMake version -|release| warns when the policy is not set and uses ``OLD`` behavior. Use -the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +This policy was introduced in CMake version 3.14. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike most policies, CMake version |release| does not warn when this policy is +not set and simply uses ``OLD`` behavior. .. include:: DEPRECATED.txt diff --git a/Help/prop_tgt/BUILD_RPATH_USE_ORIGIN.rst b/Help/prop_tgt/BUILD_RPATH_USE_ORIGIN.rst index 511de7a4e4..3378797802 100644 --- a/Help/prop_tgt/BUILD_RPATH_USE_ORIGIN.rst +++ b/Help/prop_tgt/BUILD_RPATH_USE_ORIGIN.rst @@ -8,14 +8,14 @@ This property is initialized by the value of the variable On platforms that support runtime paths (``RPATH``) with the ``$ORIGIN`` token, setting this property to ``TRUE`` enables relative -paths in the build ``RPATH`` for executables that point to shared -libraries in the same build tree. +paths in the build ``RPATH`` for executables and shared libraries that +point to shared libraries in the same build tree. -Normally the build ``RPATH`` of an executable contains absolute paths -to the directory of shared libraries. Directories contained within the -build tree can be made relative to enable relocatable builds and to -help achieving reproducible builds by omitting the build directory -from the build environment. +Normally the build ``RPATH`` of a binary contains absolute paths +to the directory of each shared library it links to. The ``RPATH`` +entries for directories contained within the build tree can be made +relative to enable relocatable builds and to help achieve reproducible +builds by omitting the build directory from the build environment. This property has no effect on platforms that do not support the ``$ORIGIN`` token in ``RPATH``, or when the :variable:`CMAKE_SKIP_RPATH` diff --git a/Help/prop_tgt/EXCLUDE_FROM_ALL.rst b/Help/prop_tgt/EXCLUDE_FROM_ALL.rst index e7457e1e29..0eee297921 100644 --- a/Help/prop_tgt/EXCLUDE_FROM_ALL.rst +++ b/Help/prop_tgt/EXCLUDE_FROM_ALL.rst @@ -6,8 +6,16 @@ Exclude the target from the all target. A property on a target that indicates if the target is excluded from the default build target. If it is not, then with a Makefile for example typing make will cause this target to be built. The same -concept applies to the default build of other generators. Installing -a target with EXCLUDE_FROM_ALL set to true has undefined behavior. +concept applies to the default build of other generators. + +With ``EXCLUDE_FROM_ALL`` set to false or not set at all, the target +will be brought up to date as part of doing a ``make install`` or its +equivalent for the CMake generator being used. If a target has +``EXCLUDE_FROM_ALL`` set to true, then any attempt to install that +target has undefined behavior. Note that such a target can still safely +be listed in an :command:`install(TARGETS)` command as long as the install +components the target belongs to are not part of the set of components +that anything tries to install. This property is enabled by default for targets that are created in directories that have :prop_dir:`EXCLUDE_FROM_ALL` set to ``TRUE``. diff --git a/Help/release/3.14.rst b/Help/release/3.14.rst index 39e65559c3..5038a75175 100644 --- a/Help/release/3.14.rst +++ b/Help/release/3.14.rst @@ -166,13 +166,18 @@ Modules :command:`check_fortran_source_runs` command to check if a Fortran source snippet compiles and runs. +* The :module:`CMakePackageConfigHelpers` module's + :command:`write_basic_package_version_file` command gained a new + ``ARCH_INDEPENDENT`` option for supporting architecture-independent + packages. + * The :module:`ExternalProject` module :command:`ExternalProject_Add` command gained ``LOG_DIR`` and ``LOG_MERGED_STDOUTERR`` options to control logging. * The :module:`ExternalProject` module :command:`ExternalProject_Add` command gained ``LOG_PATCH`` to optionally log the patch step. -* The :module:`ExternalProject` module's ``ExternalProject_Add`` command +* The :module:`ExternalProject` module :command:`ExternalProject_Add` command learned to apply ``SOURCE_SUBDIR`` when ``BUILD_IN_SOURCE`` is also used. The ``BUILD_COMMAND`` is run in the given ``SOURCE_SUBDIR`` of the ``SOURCE_DIR``. @@ -211,8 +216,6 @@ Modules mirror the new options to the ``mex`` command in MATLAB R2018a. The option ``MX_LIBRARY`` is no longer needed. -* A :module:`FindOctave` module was added to find GNU octave. - * The :module:`FindPostgreSQL` module now provides imported targets. * The :module:`FindPython`, :module:`FindPython2`, and :module:`FindPython3` @@ -370,3 +373,7 @@ Other Changes :variable:`CPACK_DEBIAN_ARCHIVE_TYPE` variable, because ``dpkg`` has never supported the PAX tar format. The ``paxr`` value will be mapped to ``gnutar`` and a deprecation message emitted. + +* CMake no longer issues a warning if a target listed in an + :command:`install(TARGETS)` command has its :prop_tgt:`EXCLUDE_FROM_ALL` + property set to true. diff --git a/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst index cc80851074..e361fd98e7 100644 --- a/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst +++ b/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst @@ -6,4 +6,9 @@ Directories implicitly searched by the compiler for header files. CMake does not explicitly specify these directories on compiler command lines for language ``<LANG>``. This prevents system include directories from being treated as user include directories on some -compilers. +compilers, which is important for ``C``, ``CXX``, and ``CUDA`` to +avoid overriding standard library headers. + +This value is not used for ``Fortran`` because it has no standard +library headers and some compilers do not search their implicit +include directories for module ``.mod`` files. |