diff options
Diffstat (limited to 'Help')
248 files changed, 1105 insertions, 869 deletions
diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index ec6cb9d..b42fe42 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -80,12 +80,17 @@ option extends visibility. It may be referenced like any target built within the project. ``IMPORTED`` libraries are useful for convenient reference from commands like :command:`target_link_libraries`. Details about the imported library are specified by setting properties whose names -begin in ``IMPORTED_`` and ``INTERFACE_``. The most important such -property is :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration -variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the -location of the main library file on disk. Or, for object libraries, -:prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) -specifies the locations of object files on disk. +begin in ``IMPORTED_`` and ``INTERFACE_``. + +The most important properties are: + +* :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration + variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the + location of the main library file on disk. +* :prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) + for object libraries, specifies the locations of object files on disk. +* :prop_tgt:`PUBLIC_HEADER` files to be installed during :command:`install` invocation + See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties for more information. diff --git a/Help/command/aux_source_directory.rst b/Help/command/aux_source_directory.rst index e0af665..9619f35 100644 --- a/Help/command/aux_source_directory.rst +++ b/Help/command/aux_source_directory.rst @@ -11,14 +11,14 @@ Collects the names of all the source files in the specified directory and stores the list in the ``<variable>`` provided. This command is intended to be used by projects that use explicit template instantiation. Template instantiation files can be stored in a -"Templates" subdirectory and collected automatically using this +``Templates`` subdirectory and collected automatically using this command to avoid manually listing all instantiations. It is tempting to use this command to avoid writing the list of source files for a library or executable target. While this seems to work, there is no way for CMake to generate a build system that knows when a new source file has been added. Normally the generated build system -knows when it needs to rerun CMake because the CMakeLists.txt file is +knows when it needs to rerun CMake because the ``CMakeLists.txt`` file is modified to add a new source. When the source is just added to the directory without modifying this file, one would have to manually rerun CMake to generate a build system incorporating the new file. diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index ac9eac1..983fc20 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -7,6 +7,7 @@ Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`. ctest_submit([PARTS <part>...] [FILES <file>...] [SUBMIT_URL <url>] + [BUILD_ID <result-var>] [HTTPHEADER <header>] [RETRY_COUNT <count>] [RETRY_DELAY <delay>] @@ -44,6 +45,10 @@ The options are: The ``http`` or ``https`` URL of the dashboard server to send the submission to. If not given, the :variable:`CTEST_SUBMIT_URL` variable is used. +``BUILD_ID <result-var>`` + Store in the ``<result-var>`` variable the ID assigned to this build by + CDash. + ``HTTPHEADER <HTTP-header>`` Specify HTTP header to be included in the request to CDash during submission. For example, CDash can be configured to only accept submissions from @@ -94,5 +99,6 @@ with a content hash of the file. If CDash does not already have the file, then it is uploaded. Along with the file, a CDash type string is specified to tell CDash which handler to use to process the data. -This signature accepts the ``SUBMIT_URL``, ``HTTPHEADER``, ``RETRY_COUNT``, -``RETRY_DELAY``, ``RETURN_VALUE`` and ``QUIET`` options as described above. +This signature accepts the ``SUBMIT_URL``, ``BUILD_ID``, ``HTTPHEADER``, +``RETRY_COUNT``, ``RETRY_DELAY``, ``RETURN_VALUE`` and ``QUIET`` options +as described above. diff --git a/Help/command/export.rst b/Help/command/export.rst index ffd60e1..2ca7056 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -54,7 +54,7 @@ unspecified. export(PACKAGE <PackageName>) Store the current build directory in the CMake user package registry -for package ``<PackageName>``. The find_package command may consider the +for package ``<PackageName>``. The :command:`find_package` command may consider the directory while searching for package ``<PackageName>``. This helps dependent projects find and use a package from the current project's build tree without help from the user. Note that the entry in the package diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 54d5f68..eb44eb2 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -180,7 +180,7 @@ sets these variables: These variables are checked by the ``find_package`` command to determine whether the configuration file provides an acceptable version. They -are not available after the find_package call returns. If the version +are not available after the ``find_package`` call returns. If the version is acceptable the following variables are set: ``<PackageName>_VERSION`` @@ -220,8 +220,8 @@ Search Procedure CMake constructs a set of possible installation prefixes for the package. Under each prefix several directories are searched for a configuration file. The tables below show the directories searched. -Each entry is meant for installation trees following Windows (W), UNIX -(U), or Apple (A) conventions:: +Each entry is meant for installation trees following Windows (``W``), UNIX +(``U``), or Apple (``A``) conventions:: <prefix>/ (W) <prefix>/(cmake|CMake)/ (W) @@ -234,8 +234,8 @@ Each entry is meant for installation trees following Windows (W), UNIX <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/ (W/U) <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U) -On systems supporting macOS Frameworks and Application Bundles the -following directories are searched for frameworks or bundles +On systems supporting macOS :prop_tgt:`FRAMEWORK` and :prop_tgt:`BUNDLE`, the +following directories are searched for Frameworks or Application Bundles containing a configuration file:: <prefix>/<name>.framework/Resources/ (A) @@ -262,16 +262,16 @@ that order). * The ``lib`` path is always searched. If ``PATH_SUFFIXES`` is specified, the suffixes are appended to each -(W) or (U) directory entry one-by-one. +(``W``) or (``U``) directory entry one-by-one. This set of directories is intended to work in cooperation with projects that provide configuration files in their installation trees. -Directories above marked with (W) are intended for installations on +Directories above marked with (``W``) are intended for installations on Windows where the prefix may point at the top of an application's -installation directory. Those marked with (U) are intended for +installation directory. Those marked with (``U``) are intended for installations on UNIX platforms where the prefix is shared by multiple -packages. This is merely a convention, so all (W) and (U) directories -are still searched on all platforms. Directories marked with (A) are +packages. This is merely a convention, so all (``W``) and (``U``) directories +are still searched on all platforms. Directories marked with (``A``) are intended for installations on Apple platforms. The :variable:`CMAKE_FIND_FRAMEWORK` and :variable:`CMAKE_FIND_APPBUNDLE` variables determine the order of preference. diff --git a/Help/command/get_cmake_property.rst b/Help/command/get_cmake_property.rst index 58bf741..96764a3 100644 --- a/Help/command/get_cmake_property.rst +++ b/Help/command/get_cmake_property.rst @@ -9,7 +9,7 @@ Get a global property of the CMake instance. Gets a global property from the CMake instance. The value of the ``<property>`` is stored in the variable ``<var>``. -If the property is not found, ``<var>`` will be set to ``"NOTFOUND"``. +If the property is not found, ``<var>`` will be set to ``NOTFOUND``. See the :manual:`cmake-properties(7)` manual for available properties. See also the :command:`get_property` command ``GLOBAL`` option. diff --git a/Help/command/get_target_property.rst b/Help/command/get_target_property.rst index 4327681..11e07ea 100644 --- a/Help/command/get_target_property.rst +++ b/Help/command/get_target_property.rst @@ -11,7 +11,7 @@ Get a property from a target. The value of the property is stored in the variable ``VAR``. If the target property is not found, the behavior depends on whether it has been defined to be an ``INHERITED`` property or not (see :command:`define_property`). Non-inherited properties will -set ``VAR`` to "NOTFOUND", whereas inherited properties will search the +set ``VAR`` to ``NOTFOUND``, whereas inherited properties will search the relevant parent scope as described for the :command:`define_property` command and if still unable to find the property, ``VAR`` will be set to an empty string. diff --git a/Help/command/if.rst b/Help/command/if.rst index a48a0fa..d8e3a45 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -88,7 +88,9 @@ Possible conditions are: ``if(EXISTS path-to-file-or-directory)`` True if the named file or directory exists. Behavior is well-defined - only for full paths. + only for full paths. Resolves symbolic links, i.e. if the named file or + directory is a symbolic link, returns true if the target of the + symbolic link exists. ``if(file1 IS_NEWER_THAN file2)`` True if ``file1`` is newer than ``file2`` or if one of the two files doesn't @@ -227,7 +229,7 @@ above. The result is ``OFF`` which is false. However, if we remove the if(var2) -which is true because ``var2`` is defined to "var1" which is not a false +which is true because ``var2`` is defined to ``var1`` which is not a false constant. Automatic evaluation applies in the other cases whenever the diff --git a/Help/command/include_external_msproject.rst b/Help/command/include_external_msproject.rst index 375baf2..88bb2c6 100644 --- a/Help/command/include_external_msproject.rst +++ b/Help/command/include_external_msproject.rst @@ -13,7 +13,7 @@ Include an external Microsoft project file in a workspace. Includes an external Microsoft project in the generated workspace file. Currently does nothing on UNIX. This will create a target -named [projectname]. This can be used in the :command:`add_dependencies` +named ``[projectname]``. This can be used in the :command:`add_dependencies` command to make things depend on the external project. ``TYPE``, ``GUID`` and ``PLATFORM`` are optional parameters that allow one to diff --git a/Help/command/install.rst b/Help/command/install.rst index a4cee71..7571aae 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -148,13 +148,13 @@ project. There are several kinds of target files that may be installed: property are treated as ``FRAMEWORK`` targets on macOS. ``BUNDLE`` - Executables marked with the ``MACOSX_BUNDLE`` property are treated as + Executables marked with the :prop_tgt:`MACOSX_BUNDLE` property are treated as ``BUNDLE`` targets on macOS. ``PUBLIC_HEADER`` - Any ``PUBLIC_HEADER`` files associated with a library are installed in + Any :prop_tgt:`PUBLIC_HEADER` files associated with a library are installed in the destination specified by the ``PUBLIC_HEADER`` argument on non-Apple - platforms. Rules defined by this argument are ignored for ``FRAMEWORK`` + platforms. Rules defined by this argument are ignored for :prop_tgt:`FRAMEWORK` libraries on Apple platforms because the associated files are installed into the appropriate locations inside the framework folder. See :prop_tgt:`PUBLIC_HEADER` for details. diff --git a/Help/command/install_files.rst b/Help/command/install_files.rst index f5fb46d..ff074a8 100644 --- a/Help/command/install_files.rst +++ b/Help/command/install_files.rst @@ -21,7 +21,7 @@ or its corresponding location in the binary tree may be listed. If a file specified already has an extension, that extension will be removed first. This is useful for providing lists of source files such as foo.cxx when you want the corresponding foo.h to be installed. -A typical extension is '.h'. +A typical extension is ``.h``. :: diff --git a/Help/command/math.rst b/Help/command/math.rst index 4fa55f6..3cbe719 100644 --- a/Help/command/math.rst +++ b/Help/command/math.rst @@ -16,7 +16,7 @@ Supported operators are ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``, ``^``, ``~``, ``<<``, ``>>``, and ``(...)``; they have the same meaning as in C code. -Hexadecimal numbers are recognized when prefixed with "0x", as in C code. +Hexadecimal numbers are recognized when prefixed with ``0x``, as in C code. The result is formatted according to the option ``OUTPUT_FORMAT``, where ``<format>`` is one of diff --git a/Help/command/output_required_files.rst b/Help/command/output_required_files.rst index 8bc6a73..b3a6e86 100644 --- a/Help/command/output_required_files.rst +++ b/Help/command/output_required_files.rst @@ -14,6 +14,6 @@ more advanced scanner. output_required_files(srcfile outputfile) Outputs a list of all the source files that are required by the -specified srcfile. This list is written into outputfile. This is -similar to writing out the dependencies for srcfile except that it -jumps from .h files into .cxx, .c and .cpp files if possible. +specified ``srcfile``. This list is written into ``outputfile``. This is +similar to writing out the dependencies for ``srcfile`` except that it +jumps from ``.h`` files into ``.cxx``, ``.c`` and ``.cpp`` files if possible. diff --git a/Help/command/project.rst b/Help/command/project.rst index 688e56c..7e33ccd 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -31,9 +31,13 @@ Further variables are set by the optional arguments described in the following. If any of these arguments is not used, then the corresponding variables are set to the empty string. -If the variable :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` exists, -the file pointed to by that variable will be included as the last step of the -project command. +If the variable :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` exists, the file +pointed to by that variable will be included as the first step of the project +command. + +If the variable :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` +or :variable:`CMAKE_PROJECT_INCLUDE` exists, the file pointed to by that +variable will be included as the last step of the project command. Options ^^^^^^^ diff --git a/Help/command/string.rst b/Help/command/string.rst index 893fb43..2e89d7b 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -28,6 +28,7 @@ Synopsis string(`SUBSTRING`_ <string> <begin> <length> <out-var>) string(`STRIP`_ <string> <out-var>) string(`GENEX_STRIP`_ <string> <out-var>) + string(`REPEAT`_ <string> <count> <out-var>) `Comparison`_ string(`COMPARE`_ <op> <string1> <string2> <out-var>) @@ -269,6 +270,14 @@ trailing spaces removed. Strip any :manual:`generator expressions <cmake-generator-expressions(7)>` from the ``input string`` and store the result in the ``output variable``. +.. _REPEAT: + +.. code-block:: cmake + + string(REPEAT <input string> <count> <output variable>) + +Produce the output string as repetion of ``input string`` ``count`` times. + Comparison ^^^^^^^^^^ diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index c5e4f9f..c2e7e8a 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -57,7 +57,7 @@ Each ``<item>`` may be: as when a shared library is detected to have no ``SONAME`` field. See policy :policy:`CMP0060` for discussion of another case. - If the library file is in a Mac OSX framework, the ``Headers`` directory + If the library file is in a macOS framework, the ``Headers`` directory of the framework will also be processed as a :ref:`usage requirement <Target Usage Requirements>`. This has the same effect as passing the framework directory as an include directory. diff --git a/Help/command/use_mangled_mesa.rst b/Help/command/use_mangled_mesa.rst index 4d9e12b..5b0e2ee 100644 --- a/Help/command/use_mangled_mesa.rst +++ b/Help/command/use_mangled_mesa.rst @@ -9,7 +9,7 @@ Copy mesa headers for use in combination with system GL. use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY) -The path to mesa includes, should contain gl_mangle.h. The mesa +The path to mesa includes, should contain ``gl_mangle.h``. The mesa headers are copied to the specified output directory. This allows mangled mesa headers to override other GL headers by being added to the include directory path earlier. diff --git a/Help/command/variable_requires.rst b/Help/command/variable_requires.rst index b4742a5..322b154 100644 --- a/Help/command/variable_requires.rst +++ b/Help/command/variable_requires.rst @@ -18,5 +18,5 @@ tested, if that variable is false nothing else is done. If ``TEST_VARIABLE`` is true, then the next argument (``RESULT_VARIABLE``) is a variable that is set to true if all the required variables are set. The rest of the arguments are variables that must be true or not set -to NOTFOUND to avoid an error. If any are not true, an error is +to ``NOTFOUND`` to avoid an error. If any are not true, an error is reported. diff --git a/Help/cpack_gen/bundle.rst b/Help/cpack_gen/bundle.rst index 29727e2..b16dbda 100644 --- a/Help/cpack_gen/bundle.rst +++ b/Help/cpack_gen/bundle.rst @@ -12,26 +12,27 @@ Bundle-specific parameters (``CPACK_BUNDLE_xxx``). .. variable:: CPACK_BUNDLE_NAME - The name of the generated bundle. This appears in the OSX finder as the + The name of the generated bundle. This appears in the macOS Finder as the bundle name. Required. .. variable:: CPACK_BUNDLE_PLIST - Path to an OSX plist file that will be used for the generated bundle. This - assumes that the caller has generated or specified their own Info.plist + Path to an macOS Property List (``.plist``) file that will be used + for the generated bundle. This + assumes that the caller has generated or specified their own ``Info.plist`` file. Required. .. variable:: CPACK_BUNDLE_ICON - Path to an OSX icon file that will be used as the icon for the generated - bundle. This is the icon that appears in the OSX finder for the bundle, and - in the OSX dock when the bundle is opened. Required. + Path to an macOS icon file that will be used as the icon for the generated + bundle. This is the icon that appears in the macOS Finder for the bundle, and + in the macOS dock when the bundle is opened. Required. .. variable:: CPACK_BUNDLE_STARTUP_COMMAND Path to a startup script. This is a path to an executable or script that will be run whenever an end-user double-clicks the generated bundle in the - OSX Finder. Optional. + macOS Finder. Optional. .. variable:: CPACK_BUNDLE_APPLE_CERT_APP @@ -42,8 +43,9 @@ Bundle-specific parameters (``CPACK_BUNDLE_xxx``). .. variable:: CPACK_BUNDLE_APPLE_ENTITLEMENTS - The name of the ``Plist`` file that contains your apple entitlements for sandboxing - your application. This file is required for submission to the Mac App Store. + The name of the Property List (``.plist``) file that contains your Apple + entitlements for sandboxing your application. This file is required + for submission to the macOS App Store. .. variable:: CPACK_BUNDLE_APPLE_CODESIGN_FILES diff --git a/Help/cpack_gen/external.rst b/Help/cpack_gen/external.rst index e4912a4..406f6be 100644 --- a/Help/cpack_gen/external.rst +++ b/Help/cpack_gen/external.rst @@ -13,7 +13,7 @@ provided by CPack, such as component installation and the dependency graph. Integration with External Packaging Tools ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The CPack External generator generates a .json file containing the +The CPack External generator generates a ``.json`` file containing the CPack internal metadata, which gives external software information on how to package the software. External packaging software may itself invoke CPack, consume the generated metadata, diff --git a/Help/cpack_gen/nsis.rst b/Help/cpack_gen/nsis.rst index 9f82a04..cd2aea6 100644 --- a/Help/cpack_gen/nsis.rst +++ b/Help/cpack_gen/nsis.rst @@ -1,19 +1,19 @@ CPack NSIS Generator -------------------- -CPack NSIS generator specific options +CPack Nullsoft Scriptable Install System (NSIS) generator specific options Variables specific to CPack NSIS generator ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following variables are specific to the graphical installers built -on Windows using the Nullsoft Installation System. +on Windows Nullsoft Scriptable Install System. .. variable:: CPACK_NSIS_INSTALL_ROOT The default installation directory presented to the end user by the NSIS installer is under this root dir. The full directory presented to the end - user is: ${CPACK_NSIS_INSTALL_ROOT}/${CPACK_PACKAGE_INSTALL_DIRECTORY} + user is: ``${CPACK_NSIS_INSTALL_ROOT}/${CPACK_PACKAGE_INSTALL_DIRECTORY}`` .. variable:: CPACK_NSIS_MUI_ICON @@ -31,11 +31,11 @@ on Windows using the Nullsoft Installation System. .. variable:: CPACK_NSIS_MUI_WELCOMEFINISHPAGE_BITMAP - The filename of a bitmap to use as the NSIS MUI_WELCOMEFINISHPAGE_BITMAP. + The filename of a bitmap to use as the NSIS ``MUI_WELCOMEFINISHPAGE_BITMAP``. .. variable:: CPACK_NSIS_MUI_UNWELCOMEFINISHPAGE_BITMAP - The filename of a bitmap to use as the NSIS MUI_UNWELCOMEFINISHPAGE_BITMAP. + The filename of a bitmap to use as the NSIS ``MUI_UNWELCOMEFINISHPAGE_BITMAP``. .. variable:: CPACK_NSIS_EXTRA_PREINSTALL_COMMANDS @@ -54,25 +54,25 @@ on Windows using the Nullsoft Installation System. .. variable:: CPACK_NSIS_COMPRESSOR - The arguments that will be passed to the NSIS SetCompressor command. + The arguments that will be passed to the NSIS `SetCompressor` command. .. variable:: CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL - Ask about uninstalling previous versions first. If this is set to "ON", + Ask about uninstalling previous versions first. If this is set to ``ON``, then an installer will look for previous installed versions and if one is found, ask the user whether to uninstall it before proceeding with the install. .. variable:: CPACK_NSIS_MODIFY_PATH - Modify PATH toggle. If this is set to "ON", then an extra page will appear + Modify ``PATH`` toggle. If this is set to ``ON``, then an extra page will appear in the installer that will allow the user to choose whether the program - directory should be added to the system PATH variable. + directory should be added to the system ``PATH`` variable. .. variable:: CPACK_NSIS_DISPLAY_NAME - The display name string that appears in the Windows Add/Remove Program - control panel + The display name string that appears in the Windows `Apps & features` + in `Control Panel` .. variable:: CPACK_NSIS_PACKAGE_NAME @@ -97,21 +97,21 @@ on Windows using the Nullsoft Installation System. .. variable:: CPACK_NSIS_<compName>_INSTALL_DIRECTORY - Custom install directory for the specified component <compName> instead - of $INSTDIR. + Custom install directory for the specified component ``<compName>`` instead + of ``$INSTDIR``. .. variable:: CPACK_NSIS_CREATE_ICONS_EXTRA - Additional NSIS commands for creating start menu shortcuts. + Additional NSIS commands for creating `Start Menu` shortcuts. .. variable:: CPACK_NSIS_DELETE_ICONS_EXTRA - Additional NSIS commands to uninstall start menu shortcuts. + Additional NSIS commands to uninstall `Start Menu` shortcuts. .. variable:: CPACK_NSIS_EXECUTABLES_DIRECTORY - Creating NSIS start menu links assumes that they are in 'bin' unless this - variable is set. For example, you would set this to 'exec' if your + Creating NSIS `Start Menu` links assumes that they are in ``bin`` unless this + variable is set. For example, you would set this to ``exec`` if your executables are in an exec directory. .. variable:: CPACK_NSIS_MUI_FINISHPAGE_RUN @@ -121,8 +121,8 @@ on Windows using the Nullsoft Installation System. .. variable:: CPACK_NSIS_MENU_LINKS - Specify links in [application] menu. This should contain a list of pair - "link" "link name". The link may be a URL or a path relative to + Specify links in ``[application]`` menu. This should contain a list of pair + ``link`` ``link name``. The link may be a URL or a path relative to installation prefix. Like:: set(CPACK_NSIS_MENU_LINKS diff --git a/Help/cpack_gen/rpm.rst b/Help/cpack_gen/rpm.rst index 65009db..2693c7b 100644 --- a/Help/cpack_gen/rpm.rst +++ b/Help/cpack_gen/rpm.rst @@ -22,19 +22,19 @@ http://www.rpm.org/wiki/Docs .. note:: - `<COMPONENT>` part of variables is preferred to be in upper case (for e.g. if - component is named `foo` then use `CPACK_RPM_FOO_XXXX` variable name format) - as is with other `CPACK_<COMPONENT>_XXXX` variables. + `<COMPONENT>` part of variables is preferred to be in upper case (e.g. if + component is named ``foo`` then use ``CPACK_RPM_FOO_XXXX`` variable name format) + as is with other ``CPACK_<COMPONENT>_XXXX`` variables. For the purposes of back compatibility (CMake/CPack version 3.5 and lower) - support for same cased component (e.g. `fOo` would be used as - `CPACK_RPM_fOo_XXXX`) is still supported for variables defined in older + support for same cased component (e.g. ``fOo`` would be used as + ``CPACK_RPM_fOo_XXXX``) is still supported for variables defined in older versions of CMake/CPack but is not guaranteed for variables that will be added in the future. For the sake of back compatibility same cased component variables also override upper cased versions where both are present. -Here are some CPack RPM generator wiki resources that are here for historic reasons and -are no longer maintained but may still prove useful: +Here are some CPack RPM generator wiki resources that are here for historic +reasons and are no longer maintained but may still prove useful: - https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/Configuration - https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/PackageGenerators#rpm-unix-only @@ -48,8 +48,8 @@ List of CPack RPM generator specific variables: * Mandatory : NO * Default : OFF - If enabled (ON) multiple packages are generated. By default a single package - containing files of all components is generated. + If enabled (``ON``) multiple packages are generated. By default + a single package containing files of all components is generated. .. variable:: CPACK_RPM_PACKAGE_SUMMARY CPACK_RPM_<component>_PACKAGE_SUMMARY @@ -76,14 +76,14 @@ List of CPack RPM generator specific variables: * Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].rpm`` with spaces replaced by '-' - This may be set to ``RPM-DEFAULT`` to allow rpmbuild tool to generate package + This may be set to ``RPM-DEFAULT`` to allow ``rpmbuild`` tool to generate package file name by itself. Alternatively provided package file name must end with ``.rpm`` suffix. .. note:: By using user provided spec file, rpm macro extensions such as for - generating debuginfo packages or by simply using multiple components more + generating ``debuginfo`` packages or by simply using multiple components more than one rpm file may be generated, either from a single spec file or from multiple spec files (each component execution produces its own spec file). In such cases duplicate file names may occur as a result of this variable @@ -127,7 +127,7 @@ List of CPack RPM generator specific variables: * Mandatory : YES * Default : Native architecture output by ``uname -m`` - This may be set to ``noarch`` if you know you are building a noarch package. + This may be set to ``noarch`` if you know you are building a ``noarch`` package. .. variable:: CPACK_RPM_PACKAGE_RELEASE @@ -207,7 +207,7 @@ List of CPack RPM generator specific variables: * Default : - May be used to override RPM compression type to be used to build the - RPM. For example some Linux distribution now default to lzma or xz + RPM. For example some Linux distribution now default to ``lzma`` or ``xz`` compression whereas older cannot use such RPM. Using this one can enforce compression type to be used. @@ -226,8 +226,8 @@ List of CPack RPM generator specific variables: * Mandatory : NO * Default : - - May be used to enable (1, yes) or disable (0, no) automatic shared libraries - dependency detection. Dependencies are added to requires list. + May be used to enable (``1``, ``yes``) or disable (``0``, ``no``) automatic + shared libraries dependency detection. Dependencies are added to requires list. .. note:: @@ -241,9 +241,9 @@ List of CPack RPM generator specific variables: * Mandatory : NO * Default : - - May be used to enable (1, yes) or disable (0, no) automatic listing of shared - libraries that are provided by the package. Shared libraries are added to - provides list. + May be used to enable (``1``, ``yes``) or disable (``0``, ``no``) + automatic listing of shared libraries that are provided by the package. + Shared libraries are added to provides list. .. note:: @@ -258,8 +258,8 @@ List of CPack RPM generator specific variables: * Default : - Variable enables/disables autoreq and autoprov at the same time. - See :variable:`CPACK_RPM_PACKAGE_AUTOREQ` and :variable:`CPACK_RPM_PACKAGE_AUTOPROV` - for more details. + See :variable:`CPACK_RPM_PACKAGE_AUTOREQ` and + :variable:`CPACK_RPM_PACKAGE_AUTOPROV` for more details. .. note:: diff --git a/Help/envvar/ASM_DIALECT.rst b/Help/envvar/ASM_DIALECT.rst index cabb959..a06e3cb 100644 --- a/Help/envvar/ASM_DIALECT.rst +++ b/Help/envvar/ASM_DIALECT.rst @@ -4,8 +4,9 @@ ASM<DIALECT> .. include:: ENV_VAR.txt Preferred executable for compiling a specific dialect of assembly language -files. ``ASM<DIALECT>`` can be ``ASM``, ``ASM_NASM``, ``ASM_MASM`` or -``ASM-ATT``. Will only be used by CMake on the first configuration to determine +files. ``ASM<DIALECT>`` can be ``ASM``, ``ASM_NASM`` (Netwide Assembler), +``ASM_MASM`` (Microsoft Assembler) or ``ASM-ATT`` (Assembler AT&T). +Will only be used by CMake on the first configuration to determine ``ASM<DIALECT>`` compiler, after which the value for ``ASM<DIALECT>`` is stored in the cache as :variable:`CMAKE_ASM<DIALECT>_COMPILER <CMAKE_<LANG>_COMPILER>`. For subsequent diff --git a/Help/envvar/ASM_DIALECTFLAGS.rst b/Help/envvar/ASM_DIALECTFLAGS.rst index 90cbbdb..3c3b02a 100644 --- a/Help/envvar/ASM_DIALECTFLAGS.rst +++ b/Help/envvar/ASM_DIALECTFLAGS.rst @@ -6,8 +6,8 @@ ASM<DIALECT>FLAGS Default compilation flags to be used when compiling a specific dialect of an assembly language. ``ASM<DIALECT>FLAGS`` can be ``ASMFLAGS``, ``ASM_NASMFLAGS``, ``ASM_MASMFLAGS`` or ``ASM-ATTFLAGS``. Will only be used by CMake on the -first configuration to determine ``ASM<DIALECT>`` default compilation flags, after -which the value for ``ASM<DIALECT>FLAGS`` is stored in the cache as -:variable:`CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration -run (including the first), the environment variable will be ignored if the -:variable:`CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. +first configuration to determine ``ASM_<DIALECT>`` default compilation +flags, after which the value for ``ASM<DIALECT>FLAGS`` is stored in the cache +as ``CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>``. For any configuration +run (including the first), the environment variable will be ignored, if the +``CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>`` variable is defined. diff --git a/Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst b/Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst index b769d51..e1991b2 100644 --- a/Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst +++ b/Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst @@ -4,4 +4,4 @@ CTEST_INTERACTIVE_DEBUG_MODE .. include:: ENV_VAR.txt Environment variable that will exist and be set to ``1`` when a test executed -by CTest is run in interactive mode. +by :manual:`ctest(1)` is run in interactive mode. diff --git a/Help/envvar/CTEST_OUTPUT_ON_FAILURE.rst b/Help/envvar/CTEST_OUTPUT_ON_FAILURE.rst index bf860cb..d8b4262 100644 --- a/Help/envvar/CTEST_OUTPUT_ON_FAILURE.rst +++ b/Help/envvar/CTEST_OUTPUT_ON_FAILURE.rst @@ -4,6 +4,6 @@ CTEST_OUTPUT_ON_FAILURE .. include:: ENV_VAR.txt Boolean environment variable that controls if the output should be logged for -failed tests. Set the value to 1, True, or ON to enable output on failure. +failed tests. Set the value to ``1``, ``True``, or ``ON`` to enable output on failure. See :manual:`ctest(1)` for more information on controlling output of failed tests. diff --git a/Help/envvar/CTEST_PROGRESS_OUTPUT.rst b/Help/envvar/CTEST_PROGRESS_OUTPUT.rst index de23e11..b36a6b8 100644 --- a/Help/envvar/CTEST_PROGRESS_OUTPUT.rst +++ b/Help/envvar/CTEST_PROGRESS_OUTPUT.rst @@ -4,7 +4,7 @@ CTEST_PROGRESS_OUTPUT .. include:: ENV_VAR.txt Boolean environment variable that affects how :manual:`ctest <ctest(1)>` -command output reports overall progress. When set to 1, TRUE, ON or anything +command output reports overall progress. When set to ``1``, ``TRUE``, ``ON`` or anything else that evaluates to boolean true, progress is reported by repeatedly updating the same line. This greatly reduces the overall verbosity, but is only supported when output is sent directly to a terminal. If the environment diff --git a/Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst b/Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst index 2b303a4..6a52d64 100644 --- a/Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst +++ b/Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst @@ -3,5 +3,6 @@ DASHBOARD_TEST_FROM_CTEST .. include:: ENV_VAR.txt -Environment variable that will exist when a test executed by CTest is run -in non-interactive mode. The value will be equal to :variable:`CMAKE_VERSION`. +Environment variable that will exist when a test executed by :manual:`ctest(1)` +is run in non-interactive mode. The value will be equal to +:variable:`CMAKE_VERSION`. diff --git a/Help/envvar/PackageName_ROOT.rst b/Help/envvar/PackageName_ROOT.rst index ecec63b..82b0a06 100644 --- a/Help/envvar/PackageName_ROOT.rst +++ b/Help/envvar/PackageName_ROOT.rst @@ -5,7 +5,7 @@ Calls to :command:`find_package(<PackageName>)` will search in prefixes specified by the ``<PackageName>_ROOT`` environment variable, where -``<PackageName>`` is the name given to the ``find_package`` call +``<PackageName>`` is the name given to the :command:`find_package` call and ``_ROOT`` is literal. For example, ``find_package(Foo)`` will search prefixes specified in the ``Foo_ROOT`` environment variable (if set). See policy :policy:`CMP0074`. diff --git a/Help/generator/CodeBlocks.rst b/Help/generator/CodeBlocks.rst index 06cc746..d830542 100644 --- a/Help/generator/CodeBlocks.rst +++ b/Help/generator/CodeBlocks.rst @@ -4,14 +4,14 @@ CodeBlocks Generates CodeBlocks project files. Project files for CodeBlocks will be created in the top directory and -in every subdirectory which features a CMakeLists.txt file containing -a PROJECT() call. Additionally a hierarchy of makefiles is generated +in every subdirectory which features a ``CMakeLists.txt`` file containing +a :command:`project` call. Additionally a hierarchy of makefiles is generated into the build tree. The :variable:`CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES` variable may be set to ``ON`` to exclude any files which are located outside of the project root directory. The appropriate make program can build the -project through the default make target. A "make install" target is +project through the default ``all`` target. An ``install`` target is also provided. This "extra" generator may be specified as: diff --git a/Help/generator/CodeLite.rst b/Help/generator/CodeLite.rst index 3e60aa6..46fa5be 100644 --- a/Help/generator/CodeLite.rst +++ b/Help/generator/CodeLite.rst @@ -7,11 +7,11 @@ Project files for CodeLite will be created in the top directory and in every subdirectory which features a CMakeLists.txt file containing a :command:`project` call. The :variable:`CMAKE_CODELITE_USE_TARGETS` variable may be set to ``ON`` -to change the default behaviour from projects to targets as the basis +to change the default behavior from projects to targets as the basis for project files. The appropriate make program can build the -project through the default make target. A "make install" target is -also provided. +project through the default ``all`` target. An ``install`` target +is also provided. This "extra" generator may be specified as: diff --git a/Help/generator/Eclipse CDT4.rst b/Help/generator/Eclipse CDT4.rst index eb68bf0..634e2b6 100644 --- a/Help/generator/Eclipse CDT4.rst +++ b/Help/generator/Eclipse CDT4.rst @@ -7,7 +7,7 @@ Project files for Eclipse will be created in the top directory. In out of source builds, a linked resource to the top level source directory will be created. Additionally a hierarchy of makefiles is generated into the build tree. The appropriate make program can build -the project through the default make target. A "make install" target +the project through the default ``all`` target. An ``install`` target is also provided. This "extra" generator may be specified as: diff --git a/Help/generator/Green Hills MULTI.rst b/Help/generator/Green Hills MULTI.rst index 09c5b15..dffc679 100644 --- a/Help/generator/Green Hills MULTI.rst +++ b/Help/generator/Green Hills MULTI.rst @@ -9,8 +9,9 @@ via the :variable:`CMAKE_BUILD_TYPE` variable. Customizations that are used to pick toolset and target system: The ``-A <arch>`` can be supplied for setting the target architecture. -``<arch>`` usually is one of "arm", "ppc", "86", etcetera. If the target architecture -is not specified then the default architecture of "arm" will be used. +``<arch>`` usually is one of ``arm``, ``ppc``, ``86``, etcetera. +If the target architecture is not specified then +the default architecture of ``arm`` will be used. The ``-T <toolset>`` option can be used to set the directory location of the toolset. Both absolute and relative paths are valid. Relative paths use ``GHS_TOOLSET_ROOT`` @@ -40,11 +41,12 @@ Cache variables that are used for toolset and target system customization: | Root path for RTOS searches. | Defaults to ``C:/ghs`` in Windows or ``/usr/ghs`` in Linux. -* ``GHS_OS_DIR`` +* ``GHS_OS_DIR`` and ``GHS_OS_DIR_OPTION`` | Sets ``-os_dir`` entry in project file. | Defaults to latest platform OS installation at ``GHS_OS_ROOT``. Set this value if a specific RTOS is to be used. + | ``GHS_OS_DIR_OPTION`` default value is ``-os_dir``. * ``GHS_BSP_NAME`` diff --git a/Help/generator/Kate.rst b/Help/generator/Kate.rst index 9b61a93..129bf63 100644 --- a/Help/generator/Kate.rst +++ b/Help/generator/Kate.rst @@ -5,10 +5,10 @@ Generates Kate project files. A project file for Kate will be created in the top directory in the top level build directory. -To use it in kate, the Project plugin must be enabled. -The project file is loaded in kate simply by opening the -ProjectName.kateproject file in the editor. -If the kate Build-plugin is enabled, all targets generated by CMake are +To use it in Kate, the Project plugin must be enabled. +The project file is loaded in Kate by opening the +``ProjectName.kateproject`` file in the editor. +If the Kate Build-plugin is enabled, all targets generated by CMake are available for building. This "extra" generator may be specified as: diff --git a/Help/generator/MSYS Makefiles.rst b/Help/generator/MSYS Makefiles.rst index f7cfa44..75b9fe5 100644 --- a/Help/generator/MSYS Makefiles.rst +++ b/Help/generator/MSYS Makefiles.rst @@ -1,7 +1,8 @@ MSYS Makefiles -------------- -Generates makefiles for use with MSYS ``make`` under the MSYS shell. +Generates makefiles for use with MSYS (Minimal SYStem) +``make`` under the MSYS shell. Use this generator in a MSYS shell prompt and using ``make`` as the build tool. The generated makefiles use ``/bin/sh`` as the shell to launch build diff --git a/Help/generator/MinGW Makefiles.rst b/Help/generator/MinGW Makefiles.rst index 9fe5fe3..134ea70 100644 --- a/Help/generator/MinGW Makefiles.rst +++ b/Help/generator/MinGW Makefiles.rst @@ -4,7 +4,8 @@ MinGW Makefiles Generates makefiles for use with ``mingw32-make`` under a Windows command prompt. -Use this generator under a Windows command prompt with MinGW in the ``PATH`` +Use this generator under a Windows command prompt with +MinGW (Minimalist GNU for Windows) in the ``PATH`` and using ``mingw32-make`` as the build tool. The generated makefiles use ``cmd.exe`` as the shell to launch build rules. They are not compatible with MSYS or a unix shell. diff --git a/Help/generator/Ninja.rst b/Help/generator/Ninja.rst index 3bbd9dc..51ef49b 100644 --- a/Help/generator/Ninja.rst +++ b/Help/generator/Ninja.rst @@ -4,8 +4,8 @@ Ninja Generates build.ninja files. A build.ninja file is generated into the build tree. Recent versions -of the ninja program can build the project through the "all" target. -An "install" target is also provided. +of the ninja program can build the project through the ``all`` target. +An ``install`` target is also provided. For each subdirectory ``sub/dir`` of the project, additional targets are generated: diff --git a/Help/generator/Sublime Text 2.rst b/Help/generator/Sublime Text 2.rst index 0597a95..0a07ea9 100644 --- a/Help/generator/Sublime Text 2.rst +++ b/Help/generator/Sublime Text 2.rst @@ -4,11 +4,11 @@ Sublime Text 2 Generates Sublime Text 2 project files. Project files for Sublime Text 2 will be created in the top directory -and in every subdirectory which features a CMakeLists.txt file -containing a PROJECT() call. Additionally Makefiles (or build.ninja -files) are generated into the build tree. The appropriate make -program can build the project through the default make target. A -"make install" target is also provided. +and in every subdirectory which features a ``CMakeLists.txt`` file +containing a :command:`project` call. Additionally ``Makefiles`` +(or ``build.ninja`` files) are generated into the build tree. +The appropriate make program can build the project through the default ``all`` +target. An ``install`` target is also provided. This "extra" generator may be specified as: diff --git a/Help/generator/Unix Makefiles.rst b/Help/generator/Unix Makefiles.rst index 97d74a8..1e65ee1 100644 --- a/Help/generator/Unix Makefiles.rst +++ b/Help/generator/Unix Makefiles.rst @@ -5,4 +5,4 @@ Generates standard UNIX makefiles. A hierarchy of UNIX makefiles is generated into the build tree. Any standard UNIX-style make program can build the project through the -default make target. A "make install" target is also provided. +default ``all`` target. An ``install`` target is also provided. diff --git a/Help/generator/VS_TOOLSET_HOST_ARCH.txt b/Help/generator/VS_TOOLSET_HOST_ARCH.txt index 4eb900f..0293631 100644 --- a/Help/generator/VS_TOOLSET_HOST_ARCH.txt +++ b/Help/generator/VS_TOOLSET_HOST_ARCH.txt @@ -1,6 +1,6 @@ For each toolset that comes with this version of Visual Studio, there are -variants that are themselves compiled for 32-bit (x86) and 64-bit (x64) hosts -(independent of the architecture they target). +variants that are themselves compiled for 32-bit (``x86``) and +64-bit (``x64``) hosts (independent of the architecture they target). |VS_TOOLSET_HOST_ARCH_DEFAULT| One may explicitly request use of either the 32-bit or 64-bit host tools by adding either ``host=x86`` or ``host=x64`` to the toolset specification. diff --git a/Help/manual/LINKS.txt b/Help/manual/LINKS.txt index 8e53c0c..60a260c 100644 --- a/Help/manual/LINKS.txt +++ b/Help/manual/LINKS.txt @@ -14,7 +14,7 @@ Online Documentation and Community Resources Mailing List https://cmake.org/mailing-lists - For help and discussion about using cmake, a mailing list is + For help and discussion about using CMake, a mailing list is provided at cmake@cmake.org. The list is member-post-only but one may sign up on the CMake web page. Please first read the full documentation at https://cmake.org before posting questions to diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index baa73d5..64fd816 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -9,23 +9,23 @@ ``-C <initial-cache>`` Pre-load a script to populate the cache. - When cmake is first run in an empty build tree, it creates a - CMakeCache.txt file and populates it with customizable settings for + When CMake is first run in an empty build tree, it creates a + ``CMakeCache.txt`` file and populates it with customizable settings for the project. This option may be used to specify a file from which to load cache entries before the first pass through the project's - cmake listfiles. The loaded entries take priority over the + CMake listfiles. The loaded entries take priority over the project's default values. The given file should be a CMake script - containing SET commands that use the CACHE option, not a + containing :command:`set` commands that use the ``CACHE`` option, not a cache-format file. ``-D <var>:<type>=<value>, -D <var>=<value>`` - Create or update a cmake cache entry. + Create or update a CMake ``CACHE`` entry. - When cmake is first run in an empty build tree, it creates a - CMakeCache.txt file and populates it with customizable settings for + When CMake is first run in an empty build tree, it creates a + ``CMakeCache.txt`` file and populates it with customizable settings for the project. This option may be used to specify a setting that takes priority over the project's default value. The option may be - repeated for as many cache entries as desired. + repeated for as many ``CACHE`` entries as desired. If the ``:<type>`` portion is given it must be one of the types specified by the :command:`set` command documentation for its @@ -39,14 +39,14 @@ ``-D<var>:<type>=<value>`` or ``-D<var>=<value>``. ``-U <globbing_expr>`` - Remove matching entries from CMake cache. + Remove matching entries from CMake ``CACHE``. This option may be used to remove one or more variables from the - CMakeCache.txt file, globbing expressions using * and ? are - supported. The option may be repeated for as many cache entries as + ``CMakeCache.txt`` file, globbing expressions using ``*`` and ``?`` are + supported. The option may be repeated for as many ``CACHE`` entries as desired. - Use with care, you can make your CMakeCache.txt non-working. + Use with care, you can make your ``CMakeCache.txt`` non-working. ``-G <generator-name>`` Specify a build system generator. @@ -74,47 +74,47 @@ Suppress developer warnings. Suppress warnings that are meant for the author of the - CMakeLists.txt files. By default this will also turn off + ``CMakeLists.txt`` files. By default this will also turn off deprecation warnings. ``-Wdev`` Enable developer warnings. - Enable warnings that are meant for the author of the CMakeLists.txt + Enable warnings that are meant for the author of the ``CMakeLists.txt`` files. By default this will also turn on deprecation warnings. ``-Werror=dev`` Make developer warnings errors. - Make warnings that are meant for the author of the CMakeLists.txt files + Make warnings that are meant for the author of the ``CMakeLists.txt`` files errors. By default this will also turn on deprecated warnings as errors. ``-Wno-error=dev`` Make developer warnings not errors. - Make warnings that are meant for the author of the CMakeLists.txt files not + Make warnings that are meant for the author of the ``CMakeLists.txt`` files not errors. By default this will also turn off deprecated warnings as errors. ``-Wdeprecated`` Enable deprecated functionality warnings. Enable warnings for usage of deprecated functionality, that are meant - for the author of the CMakeLists.txt files. + for the author of the ``CMakeLists.txt`` files. ``-Wno-deprecated`` Suppress deprecated functionality warnings. Suppress warnings for usage of deprecated functionality, that are meant - for the author of the CMakeLists.txt files. + for the author of the ``CMakeLists.txt`` files. ``-Werror=deprecated`` Make deprecated macro and function warnings errors. Make warnings for usage of deprecated macros and functions, that are meant - for the author of the CMakeLists.txt files, errors. + for the author of the ``CMakeLists.txt`` files, errors. ``-Wno-error=deprecated`` Make deprecated macro and function warnings not errors. Make warnings for usage of deprecated macros and functions, that are meant - for the author of the CMakeLists.txt files, not errors. + for the author of the ``CMakeLists.txt`` files, not errors. diff --git a/Help/manual/ccmake.1.rst b/Help/manual/ccmake.1.rst index 9548471..60d45a3 100644 --- a/Help/manual/ccmake.1.rst +++ b/Help/manual/ccmake.1.rst @@ -20,7 +20,7 @@ when the program is running. CMake is a cross-platform build system generator. Projects specify their build process with platform-independent CMake listfiles included -in each directory of a source tree with the name CMakeLists.txt. +in each directory of a source tree with the name ``CMakeLists.txt``. Users build a project by using CMake to generate a build system for a native tool on their platform. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index a1328f2..1ad3453 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -21,7 +21,7 @@ Binary Targets Executables and libraries are defined using the :command:`add_executable` and :command:`add_library` commands. The resulting binary files have -appropriate prefixes, suffixes and extensions for the platform targeted. +appropriate :prop_tgt:`PREFIX`, :prop_tgt:`SUFFIX` and extensions for the platform targeted. Dependencies between binary targets are expressed using the :command:`target_link_libraries` command: @@ -31,7 +31,7 @@ Dependencies between binary targets are expressed using the add_executable(zipapp zipapp.cpp) target_link_libraries(zipapp archive) -``archive`` is defined as a static library -- an archive containing objects +``archive`` is defined as a ``STATIC`` library -- an archive containing objects compiled from ``archive.cpp``, ``zip.cpp``, and ``lzma.cpp``. ``zipapp`` is defined as an executable formed by compiling and linking ``zipapp.cpp``. When linking the ``zipapp`` executable, the ``archive`` static library is @@ -59,7 +59,7 @@ Binary Library Types Normal Libraries ^^^^^^^^^^^^^^^^ -By default, the :command:`add_library` command defines a static library, +By default, the :command:`add_library` command defines a ``STATIC`` library, unless a type is specified. A type may be specified when using the command: .. code-block:: cmake @@ -141,8 +141,8 @@ Alternatively, object libraries may be linked into other targets: target_link_libraries(test_exe archive) The link (or archiving) step of those other targets will use the object -files from object libraries that are *directly* linked. Additionally, -usage requirements of the object libraries will be honored when compiling +files from ``OBJECT`` libraries that are *directly* linked. Additionally, +usage requirements of the ``OBJECT`` libraries will be honored when compiling sources in those other targets. Furthermore, those usage requirements will propagate transitively to dependents of those other targets. @@ -365,8 +365,8 @@ non-compatible requirements :manual:`cmake(1)` issues a diagnostic: target_link_libraries(exe2 lib1 lib2) The ``lib1`` requirement ``INTERFACE_POSITION_INDEPENDENT_CODE`` is not -"compatible" with the ``POSITION_INDEPENDENT_CODE`` property of the ``exe1`` -target. The library requires that consumers are built as +"compatible" with the :prop_tgt:`POSITION_INDEPENDENT_CODE` property of +the ``exe1`` target. The library requires that consumers are built as position-independent-code, while the executable specifies to not built as position-independent-code, so a diagnostic is issued. @@ -547,10 +547,10 @@ is not known until build-time. Therefore, code such as target_compile_definitions(exe1 PRIVATE DEBUG_BUILD) endif() -may appear to work for ``Makefile`` based and ``Ninja`` generators, but is not -portable to IDE generators. Additionally, the :prop_tgt:`IMPORTED` -configuration-mappings are not accounted for with code like this, so it should -be avoided. +may appear to work for :ref:`Makefile Generators` and :generator:`Ninja` +generators, but is not portable to IDE generators. Additionally, +the :prop_tgt:`IMPORTED` configuration-mappings are not accounted for +with code like this, so it should be avoided. The unary ``TARGET_PROPERTY`` generator expression and the ``TARGET_POLICY`` generator expression are evaluated with the consuming target context. This @@ -699,7 +699,7 @@ found in those directories. This behavior for :ref:`imported targets` may be controlled by setting the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property on the *consumers* of imported targets. -If a binary target is linked transitively to a Mac OX framework, the +If a binary target is linked transitively to a macOS :prop_tgt:`FRAMEWORK`, the ``Headers`` directory of the framework is also treated as a usage requirement. This has the same effect as passing the framework directory as an include directory. diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 8cb0fe7..7f4761f 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -86,7 +86,7 @@ String Comparisons ``$<EQUAL:value1,value2>`` ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0``. ``$<IN_LIST:string,list>`` - ``1`` if ``string`` is member of the comma-separated ``list``, else ``0``. + ``1`` if ``string`` is member of the semicolon-separated ``list``, else ``0``. Uses case-sensitive comparisons. ``$<VERSION_LESS:v1,v2>`` ``1`` if ``v1`` is a version less than ``v2``, else ``0``. @@ -291,6 +291,10 @@ String Transformations ``$<JOIN:list,string>`` Joins the list with the content of ``string``. +``$<REMOVE_DUPLICATES:list>`` + Removes duplicated items in the given ``list``. +``$<FILTER:list,INCLUDE|EXCLUDE,regex>`` + Includes or removes items from ``list`` that match the regular expression ``regex``. ``$<LOWER_CASE:string>`` Content of ``string`` converted to lower case. ``$<UPPER_CASE:string>`` @@ -384,13 +388,65 @@ Target-Dependent Queries Expands to the ``tgt`` if the given target exists, an empty string otherwise. ``$<TARGET_FILE:tgt>`` - Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a target. + Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a + target. +``$<TARGET_FILE_BASE_NAME:tgt>`` + Base name of main file where ``tgt`` is the name of a target. + + The base name corresponds to the target file name (see + ``$<TARGET_FILE_NAME:tgt>``) without prefix and suffix. For example, if + target file name is ``libbase.so``, the base name is ``base``. + + See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, + :prop_tgt:`LIBRARY_OUTPUT_NAME` and :prop_tgt:`RUNTIME_OUTPUT_NAME` + target properties and their configuration specific variants + :prop_tgt:`OUTPUT_NAME_<CONFIG>`, :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>`, + :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>` and + :prop_tgt:`RUNTIME_OUTPUT_NAME_<CONFIG>`. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. +``$<TARGET_FILE_PREFIX:tgt>`` + Prefix of main file where ``tgt`` is the name of a target. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. +``$<TARGET_FILE_SUFFIX:tgt>`` + Suffix of main file where ``tgt`` is the name of a target. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. ``$<TARGET_FILE_NAME:tgt>`` Name of main file (.exe, .so.1.2, .a). ``$<TARGET_FILE_DIR:tgt>`` Directory of main file (.exe, .so.1.2, .a). ``$<TARGET_LINKER_FILE:tgt>`` File used to link (.a, .lib, .so) where ``tgt`` is the name of a target. +``$<TARGET_LINKER_FILE_BASE_NAME:tgt>`` + Base name of file used to link where ``tgt`` is the name of a target. + + The base name corresponds to the target linker file name (see + ``$<TARGET_LINKER_FILE_NAME:tgt>``) without prefix and suffix. For example, + if target file name is ``libbase.a``, the base name is ``base``. + + See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, + and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties and their configuration + specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>`, + :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` and + :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>`. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. +``$<TARGET_LINKER_FILE_PREFIX:tgt>`` + Prefix of file used to link where ``tgt`` is the name of a target. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. +``$<TARGET_LINKER_FILE_SUFFIX:tgt>`` + Suffix of file used to link where ``tgt`` is the name of a target. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. ``$<TARGET_LINKER_FILE_NAME:tgt>`` Name of file used to link (.a, .lib, .so). ``$<TARGET_LINKER_FILE_DIR:tgt>`` @@ -408,6 +464,19 @@ Target-Dependent Queries See also the :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY` target properties and their configuration specific variants :prop_tgt:`PDB_NAME_<CONFIG>` and :prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>`. +``$<TARGET_PDB_FILE_BASE_NAME:tgt>`` + Base name of the linker generated program database file (.pdb) + where ``tgt`` is the name of a target. + + The base name corresponds to the target PDB file name (see + ``$<TARGET_PDB_FILE_NAME:tgt>``) without prefix and suffix. For example, + if target file name is ``base.pdb``, the base name is ``base``. + + See also the :prop_tgt:`PDB_NAME` target property and its configuration + specific variant :prop_tgt:`PDB_NAME_<CONFIG>`. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. ``$<TARGET_PDB_FILE_NAME:tgt>`` Name of the linker generated program database file (.pdb). ``$<TARGET_PDB_FILE_DIR:tgt>`` diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst index 856aa2f..ff8311b 100644 --- a/Help/manual/cmake-gui.1.rst +++ b/Help/manual/cmake-gui.1.rst @@ -21,7 +21,7 @@ provided at the bottom of the window when the program is running. CMake is a cross-platform build system generator. Projects specify their build process with platform-independent CMake listfiles included -in each directory of a source tree with the name CMakeLists.txt. +in each directory of a source tree with the name ``CMakeLists.txt``. Users build a project by using CMake to generate a build system for a native tool on their platform. diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index bbe742e..f5aa42d 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -12,7 +12,7 @@ Introduction Packages provide dependency information to CMake based buildsystems. Packages are found with the :command:`find_package` command. The result of -using ``find_package`` is either a set of :prop_tgt:`IMPORTED` targets, or +using :command:`find_package` is either a set of :prop_tgt:`IMPORTED` targets, or a set of variables corresponding to build-relevant information. Using Packages diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index ba44b7f..df4531b 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -26,13 +26,13 @@ built-in variables, such as :variable:`CMAKE_CXX_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` etc are set by invoking the :command:`project` command. If no project command is in the top-level CMakeLists file, one will be implicitly generated. By default -the enabled languages are C and CXX: +the enabled languages are ``C`` and ``CXX``: .. code-block:: cmake project(C_Only C) -A special value of NONE can also be used with the :command:`project` command +A special value of ``NONE`` can also be used with the :command:`project` command to enable no languages: .. code-block:: cmake @@ -468,10 +468,10 @@ The following variables will be computed and provided automatically: The Android ABI detected from the standalone toolchain. :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX` - The absolute path prefix to the binutils in the standalone toolchain. + The absolute path prefix to the ``binutils`` in the standalone toolchain. :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX` - The host platform suffix of the binutils in the standalone toolchain. + The host platform suffix of the ``binutils`` in the standalone toolchain. For example, a toolchain file might contain: @@ -533,7 +533,7 @@ generator is recommended. The :generator:`Unix Makefiles` or :generator:`Ninja` generators can also be used, but they require the project to handle more areas like target CPU selection and code signing. -Any of the three systems can be targetted by setting the +Any of the three systems can be targeted by setting the :variable:`CMAKE_SYSTEM_NAME` variable to a value from the table below. By default, the latest Device SDK is chosen. As for all Apple platforms, a different SDK (e.g. a simulator) can be selected by setting the @@ -609,7 +609,7 @@ Code Signing Some build artifacts for the embedded Apple platforms require mandatory code signing. If the :generator:`Xcode` generator is being used and -code signing is required or desired, the developmemt team ID can be +code signing is required or desired, the development team ID can be specified via the ``CMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM`` CMake variable. This team ID will then be included in the generated Xcode project. By default, CMake avoids the need for code signing during the internal diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 48d7550..18dd9d7 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -7,7 +7,7 @@ cmake-variables(7) .. contents:: -This page documents variables that are provided by CMake +This page documents variables that are provided by CMake or have meaning to CMake when set by project code. For general information on variables, see the @@ -195,6 +195,8 @@ Variables that Change Behavior /variable/CMAKE_POLICY_WARNING_CMPNNNN /variable/CMAKE_PREFIX_PATH /variable/CMAKE_PROGRAM_PATH + /variable/CMAKE_PROJECT_INCLUDE + /variable/CMAKE_PROJECT_INCLUDE_BEFORE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index b67fa3a..5b88694 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -172,12 +172,12 @@ Options ``-L[A][H]`` List non-advanced cached variables. - List cache variables will run CMake and list all the variables from - the CMake cache that are not marked as INTERNAL or ADVANCED. This - will effectively display current CMake settings, which can then be - changed with -D option. Changing some of the variables may result - in more variables being created. If A is specified, then it will - display also advanced variables. If H is specified, it will also + List ``CACHE`` variables will run CMake and list all the variables from + the CMake ``CACHE`` that are not marked as ``INTERNAL`` or :prop_cache:`ADVANCED`. + This will effectively display current CMake settings, which can then be + changed with ``-D`` option. Changing some of the variables may result + in more variables being created. If ``A`` is specified, then it will + display also advanced variables. If ``H`` is specified, it will also display help for each variable. ``-N`` @@ -201,9 +201,10 @@ Options additional information such as the cache, log files etc. ``--debug-trycompile`` - Do not delete the try_compile build tree. Only useful on one try_compile at a time. + Do not delete the :command:`try_compile` build tree. + Only useful on one :command:`try_compile` at a time. - Do not delete the files and directories created for try_compile + Do not delete the files and directories created for :command:`try_compile` calls. This is useful in debugging failed try_compiles. It may however change the results of the try-compiles as old junk from a previous try-compile may cause a different test to either pass or @@ -214,7 +215,7 @@ Options Put cmake in a debug mode. Print extra information during the cmake run like stack traces with - message(send_error ) calls. + :command:`message(SEND_ERROR)` calls. ``--trace`` Put cmake in trace mode. @@ -251,8 +252,8 @@ Options Find problems with variable usage in system files. Normally, unused and uninitialized variables are searched for only - in CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR. This flag tells CMake to - warn about other files as well. + in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`. + This flag tells CMake to warn about other files as well. .. _`Build Tool Mode`: @@ -329,10 +330,10 @@ The options are: Component-based install. Only install component ``<comp>``. ``--prefix <prefix>`` - The installation prefix CMAKE_INSTALL_PREFIX. + The installation prefix :variable:`CMAKE_INSTALL_PREFIX`. ``--strip`` - Strip before installing by setting CMAKE_INSTALL_DO_STRIP. + Strip before installing by setting ``CMAKE_INSTALL_DO_STRIP``. ``-v, --verbose`` Enable verbose output. @@ -363,8 +364,8 @@ Run a Script Process the given cmake file as a script written in the CMake language. No configure or generate step is performed and the cache -is not modified. If variables are defined using -D, this must be -done before the -P argument. +is not modified. If variables are defined using ``-D``, this must be +done before the ``-P`` argument. Run a Command-Line Tool @@ -421,7 +422,7 @@ Available commands are: ``compare_files [--ignore-eol] <file1> <file2>`` Check if ``<file1>`` is same as ``<file2>``. If files are the same, - then returns 0, if not it returns 1. The ``--ignore-eol`` option + then returns ``0``, if not it returns ``1``. The ``--ignore-eol`` option implies line-wise comparison and ignores LF/CRLF differences. ``copy <file>... <destination>`` diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index 679c547..10f617e 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -63,7 +63,7 @@ Options details. By default, ``CPackConfig.cmake`` in the current directory will be used. -``--verbose,-V`` +``--verbose, -V`` Run ``cpack`` with verbose output. This can be used to show more details from the package generation tools and is suitable for project developers. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index d1bd69b..5a6b329 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -22,8 +22,8 @@ Description The **ctest** executable is the CMake test driver program. CMake-generated build trees created for projects that use the -ENABLE_TESTING and ADD_TEST commands have testing support. This -program will run the tests and report results. +:command:`enable_testing` and :command:`add_test` commands have testing support. +This program will run the tests and report results. Options ======= @@ -33,8 +33,8 @@ Options Some CMake-generated build trees can have multiple build configurations in the same tree. This option can be used to specify - which one should be tested. Example configurations are "Debug" and - "Release". + which one should be tested. Example configurations are ``Debug`` and + ``Release``. ``--progress`` Enable short progress output from tests. @@ -108,7 +108,7 @@ Options ``-O <file>, --output-log <file>`` Output to log file. - This option tells CTest to write all its output to a log file. + This option tells CTest to write all its output to a ``<file>`` log file. ``-N,--show-only[=<format>]`` Disable actual execution of tests. @@ -172,9 +172,10 @@ Options Execute dashboard test. This option tells CTest to act as a CDash client and perform a - dashboard test. All tests are <Mode><Test>, where Mode can be - Experimental, Nightly, and Continuous, and Test can be Start, - Update, Configure, Build, Test, Coverage, and Submit. + dashboard test. All tests are ``<Mode><Test>``, where ``<Mode>`` can be + ``Experimental``, ``Nightly``, and ``Continuous``, and ``<Test>`` can be + ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``, + ``Coverage``, and ``Submit``. See `Dashboard Client`_. @@ -229,10 +230,10 @@ Options ``-I [Start,End,Stride,test#,test#|Test file], --tests-information`` Run a specific number of tests by number. - This option causes CTest to run tests starting at number Start, - ending at number End, and incrementing by Stride. Any additional - numbers after Stride are considered individual test numbers. Start, - End,or stride can be empty. Optionally a file can be given that + This option causes CTest to run tests starting at number ``Start``, + ending at number ``End``, and incrementing by ``Stride``. Any additional + numbers after ``Stride`` are considered individual test numbers. ``Start``, + ``End``, or ``Stride`` can be empty. Optionally a file can be given that contains the same syntax as the command line. ``-U, --union`` @@ -264,12 +265,12 @@ Options name which can be very annoying. ``--interactive-debug-mode [0|1]`` - Set the interactive mode to 0 or 1. + Set the interactive mode to ``0`` or ``1``. This option causes CTest to run tests in either an interactive mode or a non-interactive mode. On Windows this means that in non-interactive mode, all system debug pop up windows are blocked. - In dashboard mode (Experimental, Nightly, Continuous), the default + In dashboard mode (``Experimental``, ``Nightly``, ``Continuous``), the default is non-interactive. When just running tests not for a dashboard the default is to allow popups and interactive debugging. @@ -350,7 +351,7 @@ See `Build and Test Mode`_. Label and Subproject Summary ============================ -CTest prints timing summary information for each label and subproject +CTest prints timing summary information for each ``LABEL`` and subproject associated with the tests run. The label time summary will not include labels that are mapped to subprojects. @@ -358,8 +359,8 @@ When the :prop_test:`PROCESSORS` test property is set, CTest will display a weighted test timing result in label and subproject summaries. The time is reported with `sec*proc` instead of just `sec`. -The weighted time summary reported for each label or subproject j is computed -as:: +The weighted time summary reported for each label or subproject ``j`` +is computed as:: Weighted Time Summary for Label/Subproject j = sum(raw_test_time[j,i] * num_processors[j,i], i=1...num_tests[j]) @@ -368,25 +369,25 @@ as:: where: -* raw_test_time[j,i]: Wall-clock time for the ith test for the jth label or - subproject -* num_processors[j,i]: Value of the CTest PROCESSORS property for the ith test - for the jth label or subproject -* num_tests[j]: Number of tests associated with the jth label or subproject -* total: Total number of labels or subprojects that have at least one test run +* ``raw_test_time[j,i]``: Wall-clock time for the ``i`` test + for the ``j`` label or subproject +* ``num_processors[j,i]``: Value of the CTest :prop_test:`PROCESSORS` property + for the ``i`` test for the ``j`` label or subproject +* ``num_tests[j]``: Number of tests associated with the ``j`` label or subproject +* ``total``: Total number of labels or subprojects that have at least one test run Therefore, the weighted time summary for each label or subproject represents the amount of time that CTest gave to run the tests for each label or subproject and gives a good representation of the total expense of the tests for each label or subproject when compared to other labels or subprojects. -For example, if "SubprojectA" showed "100 sec*proc" and "SubprojectB" showed -"10 sec*proc", then CTest allocated approximately 10 times the CPU/core time -to run the tests for "SubprojectA" than for "SubprojectB" (e.g. so if effort +For example, if ``SubprojectA`` showed ``100 sec*proc`` and ``SubprojectB`` showed +``10 sec*proc``, then CTest allocated approximately 10 times the CPU/core time +to run the tests for ``SubprojectA`` than for ``SubprojectB`` (e.g. so if effort is going to be expended to reduce the cost of the test suite for the whole -project, then reducing the cost of the test suite for "SubprojectA" would +project, then reducing the cost of the test suite for ``SubprojectA`` would likely have a larger impact than effort to reduce the cost of the test suite -for "SubprojectB"). +for ``SubprojectB``). .. _`Build and Test Mode`: @@ -449,7 +450,7 @@ this mode include: ``--build-config-sample`` A sample executable to use to determine the configuration that - should be used. e.g. Debug/Release/etc. + should be used. e.g. ``Debug``, ``Release`` etc. ``--build-options`` Additional options for configuring the build (i.e. for CMake, not for @@ -495,7 +496,7 @@ Options for Dashboard Client include: dashboard. ``--tomorrow-tag`` - Nightly or experimental starts with next day tag. + ``Nightly`` or ``Experimental`` starts with next day tag. This is useful if the build will not finish in one day. @@ -505,10 +506,10 @@ Options for Dashboard Client include: This option will submit extra files to the dashboard. ``--http1.0`` - Submit using HTTP 1.0. + Submit using `HTTP 1.0`. - This option will force CTest to use HTTP 1.0 to submit files to the - dashboard, instead of HTTP 1.1. + This option will force CTest to use `HTTP 1.0` to submit files to the + dashboard, instead of `HTTP 1.1`. ``--no-compress-output`` Do not compress test output when submitting. @@ -711,7 +712,7 @@ Configuration settings to specify the version control tool include: The source tree is updated by ``git fetch`` followed by ``git reset --hard`` to the ``FETCH_HEAD``. The result is the same - as ``git pull`` except that any local moficiations are overwritten. + as ``git pull`` except that any local modifications are overwritten. Use ``GITUpdateCustom`` to specify a different approach. ``GITInitSubmodules`` diff --git a/Help/module/CPackWIX.rst b/Help/module/CPackWIX.rst index c88c723..fd378b8 100644 --- a/Help/module/CPackWIX.rst +++ b/Help/module/CPackWIX.rst @@ -1,4 +1,5 @@ CPackWIX -------- -The documentation for the CPack WIX generator has moved here: :cpack_gen:`CPack WIX Generator` +The documentation for the CPack WIX generator has moved here: +:cpack_gen:`CPack WIX Generator` diff --git a/Help/policy/CMP0000.rst b/Help/policy/CMP0000.rst index 97ea633..aecfa71 100644 --- a/Help/policy/CMP0000.rst +++ b/Help/policy/CMP0000.rst @@ -7,25 +7,27 @@ CMake requires that projects specify the version of CMake to which they have been written. This policy has been put in place so users trying to build the project may be told when they need to update their CMake. Specifying a version also helps the project build with CMake -versions newer than that specified. Use the cmake_minimum_required -command at the top of your main CMakeLists.txt file: +versions newer than that specified. Use the :command:`cmake_minimum_required` +command at the top of your main ``CMakeLists.txt`` file: :: cmake_minimum_required(VERSION <major>.<minor>) -where "<major>.<minor>" is the version of CMake you want to support -(such as "2.6"). The command will ensure that at least the given +where ``<major>.<minor>`` is the version of CMake you want to support +(such as ``3.14``). The command will ensure that at least the given version of CMake is running and help newer versions be compatible with -the project. See documentation of cmake_minimum_required for details. +the project. See documentation of :command:`cmake_minimum_required` for +details. -Note that the command invocation must appear in the CMakeLists.txt +Note that the command invocation must appear in the ``CMakeLists.txt`` file itself; a call in an included file is not sufficient. However, -the cmake_policy command may be called to set policy CMP0000 to OLD or -NEW behavior explicitly. The OLD behavior is to silently ignore the -missing invocation. The NEW behavior is to issue an error instead of -a warning. An included file may set CMP0000 explicitly to affect how -this policy is enforced for the main CMakeLists.txt file. +the :command:`cmake_policy` command may be called to set policy ``CMP0000`` +to ``OLD`` or ``NEW`` behavior explicitly. The ``OLD`` behavior is to +silently ignore the missing invocation. The ``NEW`` behavior is to issue +an error instead of a warning. An included file may set ``CMP0000`` +explicitly to affect how this policy is enforced for the main +``CMakeLists.txt`` file. This policy was introduced in CMake version 2.6.0. diff --git a/Help/policy/CMP0001.rst b/Help/policy/CMP0001.rst index 09ad387..6fa64d9 100644 --- a/Help/policy/CMP0001.rst +++ b/Help/policy/CMP0001.rst @@ -1,21 +1,21 @@ CMP0001 ------- -CMAKE_BACKWARDS_COMPATIBILITY should no longer be used. +``CMAKE_BACKWARDS_COMPATIBILITY`` should no longer be used. -The OLD behavior is to check CMAKE_BACKWARDS_COMPATIBILITY and present -it to the user. The NEW behavior is to ignore +The behavior is to check ``CMAKE_BACKWARDS_COMPATIBILITY`` and present +it to the user. The ``NEW`` behavior is to ignore CMAKE_BACKWARDS_COMPATIBILITY completely. -In CMake 2.4 and below the variable CMAKE_BACKWARDS_COMPATIBILITY was +In CMake 2.4 and below the variable ``CMAKE_BACKWARDS_COMPATIBILITY`` was used to request compatibility with earlier versions of CMake. In CMake 2.6 and above all compatibility issues are handled by policies -and the cmake_policy command. However, CMake must still check -CMAKE_BACKWARDS_COMPATIBILITY for projects written for CMake 2.4 and +and the :command:`cmake_policy` command. However, CMake must still check +``CMAKE_BACKWARDS_COMPATIBILITY`` for projects written for CMake 2.4 and below. This policy was introduced in CMake version 2.6.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0002.rst b/Help/policy/CMP0002.rst index 7cc53ef..dc68d51 100644 --- a/Help/policy/CMP0002.rst +++ b/Help/policy/CMP0002.rst @@ -3,8 +3,8 @@ CMP0002 Logical target names must be globally unique. -Targets names created with add_executable, add_library, or -add_custom_target are logical build target names. Logical target +Targets names created with :command:`add_executable`, :command:`add_library`, or +:command:`add_custom_target` are logical build target names. Logical target names must be globally unique because: :: @@ -16,13 +16,13 @@ names must be globally unique because: The logical name of executable and library targets does not have to correspond to the physical file names built. Consider using the -OUTPUT_NAME target property to create two targets with the same +:prop_tgt:`OUTPUT_NAME` target property to create two targets with the same physical name while keeping logical names distinct. Custom targets must simply have globally unique names (unless one uses the global -property ALLOW_DUPLICATE_CUSTOM_TARGETS with a Makefiles generator). +property :prop_gbl:`ALLOW_DUPLICATE_CUSTOM_TARGETS` with a Makefiles generator). This policy was introduced in CMake version 2.6.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0003.rst b/Help/policy/CMP0003.rst index 16b0451..dd90883 100644 --- a/Help/policy/CMP0003.rst +++ b/Help/policy/CMP0003.rst @@ -37,7 +37,7 @@ Unfortunately this change can break code like target_link_libraries(myexe /path/to/libA.so B) -where "B" is meant to find "/path/to/libB.so". This code is wrong +where ``B`` is meant to find ``/path/to/libB.so``. This code is wrong because the user is asking the linker to find library B but has not provided a linker search path (which may be added with the link_directories command). However, with the old linking @@ -45,9 +45,9 @@ implementation the code would work accidentally because the linker search path added for library A allowed library B to be found. In order to support projects depending on linker search paths added by -linking to libraries with known full paths, the OLD behavior for this +linking to libraries with known full paths, the ``OLD`` behavior for this policy will add the linker search paths even though they are not -needed for their own libraries. When this policy is set to OLD, CMake +needed for their own libraries. When this policy is set to ``OLD``, CMake will produce a link line such as :: @@ -98,7 +98,7 @@ target. This avoids flooding users with messages for every target when setting the policy once will probably fix all targets. This policy was introduced in CMake version 2.6.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0004.rst b/Help/policy/CMP0004.rst index 55da4d2..be6d307 100644 --- a/Help/policy/CMP0004.rst +++ b/Help/policy/CMP0004.rst @@ -12,14 +12,15 @@ whitespace from libraries linked with code like This could lead to subtle errors in user projects. -The OLD behavior for this policy is to silently remove leading and -trailing whitespace. The NEW behavior for this policy is to diagnose +The ``OLD`` behavior for this policy is to silently remove leading and +trailing whitespace. The ``NEW`` behavior for this policy is to diagnose the existence of such whitespace as an error. The setting for this policy used when checking the library names is that in effect when the -target is created by an add_executable or add_library command. +target is created by an :command:`add_executable` or :command:`add_library` +command. This policy was introduced in CMake version 2.6.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0005.rst b/Help/policy/CMP0005.rst index 66d125f..59567d5 100644 --- a/Help/policy/CMP0005.rst +++ b/Help/policy/CMP0005.rst @@ -12,15 +12,15 @@ CMake versions 2.6 and above support escaping of most values, but cannot assume the user has not added escapes already in an attempt to work around limitations in earlier versions. -The OLD behavior for this policy is to place definition values given +The ``OLD`` behavior for this policy is to place definition values given to add_definitions directly in the generated build rules without -attempting to escape anything. The NEW behavior for this policy is to +attempting to escape anything. The ``NEW`` behavior for this policy is to generate correct escapes for all native build tools automatically. -See documentation of the COMPILE_DEFINITIONS target property for +See documentation of the ``COMPILE_DEFINITIONS`` target property for limitations of the escaping implementation. This policy was introduced in CMake version 2.6.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0006.rst b/Help/policy/CMP0006.rst index d1b9ece..181958b 100644 --- a/Help/policy/CMP0006.rst +++ b/Help/policy/CMP0006.rst @@ -1,24 +1,24 @@ CMP0006 ------- -Installing MACOSX_BUNDLE targets requires a BUNDLE DESTINATION. +Installing :prop_tgt:`MACOSX_BUNDLE` targets requires a ``BUNDLE DESTINATION``. -This policy determines whether the install(TARGETS) command must be -given a BUNDLE DESTINATION when asked to install a target with the -MACOSX_BUNDLE property set. CMake 2.4 and below did not distinguish +This policy determines whether the :command:`install(TARGETS)` command must be +given a ``BUNDLE DESTINATION`` when asked to install a target with the +:prop_tgt:`MACOSX_BUNDLE` property set. CMake 2.4 and below did not distinguish application bundles from normal executables when installing targets. -CMake 2.6 provides a BUNDLE option to the install(TARGETS) command -that specifies rules specific to application bundles on the Mac. +CMake 2.6 provides a ``BUNDLE`` option to the :command:`install(TARGETS)` +command that specifies rules specific to application bundles on the Mac. Projects should use this option when installing a target with the -MACOSX_BUNDLE property set. +:prop_tgt:`MACOSX_BUNDLE` property set. -The OLD behavior for this policy is to fall back to the RUNTIME -DESTINATION if a BUNDLE DESTINATION is not given. The NEW behavior -for this policy is to produce an error if a bundle target is installed -without a BUNDLE DESTINATION. +The ``OLD`` behavior for this policy is to fall back to the +``RUNTIME DESTINATION`` if a ``BUNDLE DESTINATION`` is not given. The ``NEW`` +behavior for this policy is to produce an error if a bundle target is installed +without a ``BUNDLE DESTINATION``. This policy was introduced in CMake version 2.6.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0007.rst b/Help/policy/CMP0007.rst index 3927645..1006ed3 100644 --- a/Help/policy/CMP0007.rst +++ b/Help/policy/CMP0007.rst @@ -5,13 +5,13 @@ list command no longer ignores empty elements. This policy determines whether the list command will ignore empty elements in the list. CMake 2.4 and below list commands ignored all -empty elements in the list. For example, a;b;;c would have length 3 -and not 4. The OLD behavior for this policy is to ignore empty list -elements. The NEW behavior for this policy is to correctly count +empty elements in the list. For example, ``a;b;;c`` would have length 3 +and not 4. The ``OLD`` behavior for this policy is to ignore empty list +elements. The ``NEW`` behavior for this policy is to correctly count empty elements in a list. This policy was introduced in CMake version 2.6.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0008.rst b/Help/policy/CMP0008.rst index f1e2ddd..18ede82 100644 --- a/Help/policy/CMP0008.rst +++ b/Help/policy/CMP0008.rst @@ -9,26 +9,27 @@ In CMake 2.4 and below it is possible to write code like target_link_libraries(myexe /full/path/to/somelib) -where "somelib" is supposed to be a valid library file name such as -"libsomelib.a" or "somelib.lib". For Makefile generators this +where ``somelib`` is supposed to be a valid library file name such as +``libsomelib.a`` or ``somelib.lib``. For Makefile generators this produces an error at build time because the dependency on the full -path cannot be found. For VS IDE and Xcode generators this used to +path cannot be found. For :ref:`Visual Studio Generators` IDE +and :generator:`Xcode` generators this used to work by accident because CMake would always split off the library directory and ask the linker to search for the library by name -(-lsomelib or somelib.lib). Despite the failure with Makefiles, some -projects have code like this and build only with VS and/or Xcode. +(``-lsomelib`` or ``somelib.lib``). Despite the failure with Makefiles, some +projects have code like this and build only with Visual Studio and/or Xcode. This version of CMake prefers to pass the full path directly to the native build tool, which will fail in this case because it does not name a valid library file. This policy determines what to do with full paths that do not appear -to name a valid library file. The OLD behavior for this policy is to +to name a valid library file. The ``OLD`` behavior for this policy is to split the library name from the path and ask the linker to search for -it. The NEW behavior for this policy is to trust the given path and +it. The ``NEW`` behavior for this policy is to trust the given path and pass it directly to the native build tool unchanged. This policy was introduced in CMake version 2.6.1. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0009.rst b/Help/policy/CMP0009.rst index 44baeb4..27cfde0 100644 --- a/Help/policy/CMP0009.rst +++ b/Help/policy/CMP0009.rst @@ -3,19 +3,19 @@ CMP0009 FILE GLOB_RECURSE calls should not follow symlinks by default. -In CMake 2.6.1 and below, FILE GLOB_RECURSE calls would follow through -symlinks, sometimes coming up with unexpectedly large result sets +In CMake 2.6.1 and below, :command:`file(GLOB_RECURSE)` calls would follow +through symlinks, sometimes coming up with unexpectedly large result sets because of symlinks to top level directories that contain hundreds of thousands of files. This policy determines whether or not to follow symlinks encountered -during a FILE GLOB_RECURSE call. The OLD behavior for this policy is -to follow the symlinks. The NEW behavior for this policy is not to -follow the symlinks by default, but only if FOLLOW_SYMLINKS is given -as an additional argument to the FILE command. +during a :command:`file(GLOB_RECURSE)` call. The ``OLD`` behavior for this +policy is to follow the symlinks. The ``NEW`` behavior for this policy is not +to follow the symlinks by default, but only if ``FOLLOW_SYMLINKS`` is given +as an additional argument to the ``FILE`` command. This policy was introduced in CMake version 2.6.2. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0010.rst b/Help/policy/CMP0010.rst index 344d704..cfae498 100644 --- a/Help/policy/CMP0010.rst +++ b/Help/policy/CMP0010.rst @@ -4,17 +4,17 @@ CMP0010 Bad variable reference syntax is an error. In CMake 2.6.2 and below, incorrect variable reference syntax such as -a missing close-brace ("${FOO") was reported but did not stop +a missing close-brace (``${FOO``) was reported but did not stop processing of CMake code. This policy determines whether a bad -variable reference is an error. The OLD behavior for this policy is +variable reference is an error. The ``OLD`` behavior for this policy is to warn about the error, leave the string untouched, and continue. -The NEW behavior for this policy is to report an error. +The ``NEW`` behavior for this policy is to report an error. If :policy:`CMP0053` is set to ``NEW``, this policy has no effect and is treated as always being ``NEW``. This policy was introduced in CMake version 2.6.3. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0011.rst b/Help/policy/CMP0011.rst index d281e0e..257415c 100644 --- a/Help/policy/CMP0011.rst +++ b/Help/policy/CMP0011.rst @@ -1,24 +1,25 @@ CMP0011 ------- -Included scripts do automatic cmake_policy PUSH and POP. +Included scripts do automatic :command:`cmake_policy` PUSH and POP. In CMake 2.6.2 and below, CMake Policy settings in scripts loaded by -the include() and find_package() commands would affect the includer. -Explicit invocations of cmake_policy(PUSH) and cmake_policy(POP) were -required to isolate policy changes and protect the includer. While -some scripts intend to affect the policies of their includer, most do -not. In CMake 2.6.3 and above, include() and find_package() by -default PUSH and POP an entry on the policy stack around an included -script, but provide a NO_POLICY_SCOPE option to disable it. This -policy determines whether or not to imply NO_POLICY_SCOPE for -compatibility. The OLD behavior for this policy is to imply -NO_POLICY_SCOPE for include() and find_package() commands. The NEW -behavior for this policy is to allow the commands to do their default -cmake_policy PUSH and POP. +the :command:`include` and :command:`find_package` commands would affect +the includer. Explicit invocations of ``cmake_policy(PUSH)`` and +``cmake_policy(POP)`` were required to isolate policy changes and protect +the includer. While some scripts intend to affect the policies of their +includer, most do not. In CMake 2.6.3 and above, :command:`include` and +:command:`find_package` by default ``PUSH`` and ``POP`` an entry on +the policy stack around an included +script, but provide a ``NO_POLICY_SCOPE`` option to disable it. This +policy determines whether or not to imply ``NO_POLICY_SCOPE`` for +compatibility. The ``OLD`` behavior for this policy is to imply +``NO_POLICY_SCOPE`` for :command:`include` and :command:`find_package` commands. +The ``NEW`` behavior for this policy is to allow the commands to do +their default cmake_policy ``PUSH`` and ``POP``. This policy was introduced in CMake version 2.6.3. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0012.rst b/Help/policy/CMP0012.rst index 85d64f4..17ec8d3 100644 --- a/Help/policy/CMP0012.rst +++ b/Help/policy/CMP0012.rst @@ -1,27 +1,28 @@ CMP0012 ------- -if() recognizes numbers and boolean constants. +:command:`if` recognizes numbers and boolean constants. -In CMake versions 2.6.4 and lower the if() command implicitly +In CMake versions 2.6.4 and lower the :command:`if` command implicitly dereferenced arguments corresponding to variables, even those named -like numbers or boolean constants, except for 0 and 1. Numbers and -boolean constants such as true, false, yes, no, on, off, y, n, -notfound, ignore (all case insensitive) were recognized in some cases -but not all. For example, the code "if(TRUE)" might have evaluated as -false. Numbers such as 2 were recognized only in boolean expressions -like "if(NOT 2)" (leading to false) but not as a single-argument like -"if(2)" (also leading to false). Later versions of CMake prefer to +like numbers or boolean constants, except for ``0`` and ``1``. Numbers and +boolean constants such as ``true``, ``false``, ``yes``, ``no``, ``on``, +``off``, ``y``, ``n``, ``notfound``, ``ignore`` (all case insensitive) +were recognized in some cases but not all. For example, the code ``if(TRUE)`` +might have evaluated as ``false``. +Numbers such as 2 were recognized only in boolean expressions +like ``if(NOT 2)`` (leading to ``false``) but not as a single-argument like +``if(2)`` (also leading to ``false``). Later versions of CMake prefer to treat numbers and boolean constants literally, so they should not be used as variable names. -The OLD behavior for this policy is to implicitly dereference -variables named like numbers and boolean constants. The NEW behavior +The ``OLD`` behavior for this policy is to implicitly dereference +variables named like numbers and boolean constants. The ``NEW`` behavior for this policy is to recognize numbers and boolean constants without dereferencing variables with such names. This policy was introduced in CMake version 2.8.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0013.rst b/Help/policy/CMP0013.rst index 2fabb89..dbd67a1 100644 --- a/Help/policy/CMP0013.rst +++ b/Help/policy/CMP0013.rst @@ -9,13 +9,13 @@ generation files would be written and then overwritten in the build tree and could lead to strange behavior. CMake 2.6.4 and above explicitly detect duplicate binary directories. CMake 2.6.4 always considers this case an error. In CMake 2.8.0 and above this policy -determines whether or not the case is an error. The OLD behavior for +determines whether or not the case is an error. The ``OLD`` behavior for this policy is to allow duplicate binary directories. The NEW behavior for this policy is to disallow duplicate binary directories with an error. This policy was introduced in CMake version 2.8.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0014.rst b/Help/policy/CMP0014.rst index f1f7b77..331dde5 100644 --- a/Help/policy/CMP0014.rst +++ b/Help/policy/CMP0014.rst @@ -1,17 +1,17 @@ CMP0014 ------- -Input directories must have CMakeLists.txt. +Input directories must have ``CMakeLists.txt``. -CMake versions before 2.8 silently ignored missing CMakeLists.txt -files in directories referenced by add_subdirectory() or subdirs(), +CMake versions before 2.8 silently ignored missing ``CMakeLists.txt`` +files in directories referenced by :command:`add_subdirectory` or :command:`subdirs`, treating them as if present but empty. In CMake 2.8.0 and above this -policy determines whether or not the case is an error. The OLD -behavior for this policy is to silently ignore the problem. The NEW -behavior for this policy is to report an error. +:command:`cmake_policy` determines whether or not the case is an error. +The ``OLD`` behavior for this policy is to silently ignore the problem. +The ``NEW`` behavior for this policy is to report an error. This policy was introduced in CMake version 2.8.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0015.rst b/Help/policy/CMP0015.rst index 9a48e3d..90d5203 100644 --- a/Help/policy/CMP0015.rst +++ b/Help/policy/CMP0015.rst @@ -1,19 +1,19 @@ CMP0015 ------- -link_directories() treats paths relative to the source dir. + :command:`link_directories` treats paths relative to the source dir. -In CMake 2.8.0 and lower the link_directories() command passed +In CMake 2.8.0 and lower the :command:`link_directories` command passed relative paths unchanged to the linker. In CMake 2.8.1 and above the -link_directories() command prefers to interpret relative paths with -respect to CMAKE_CURRENT_SOURCE_DIR, which is consistent with -include_directories() and other commands. The OLD behavior for this -policy is to use relative paths verbatim in the linker command. The -NEW behavior for this policy is to convert relative paths to absolute -paths by appending the relative path to CMAKE_CURRENT_SOURCE_DIR. +:command:`link_directories` command prefers to interpret relative paths with +respect to ``CMAKE_CURRENT_SOURCE_DIR``, which is consistent with +:command:`include_directories` and other commands. The ``OLD`` behavior for +this policy is to use relative paths verbatim in the linker command. The +``NEW`` behavior for this policy is to convert relative paths to absolute +paths by appending the relative path to ``CMAKE_CURRENT_SOURCE_DIR``. This policy was introduced in CMake version 2.8.1. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0016.rst b/Help/policy/CMP0016.rst index cc898c8..026d02a 100644 --- a/Help/policy/CMP0016.rst +++ b/Help/policy/CMP0016.rst @@ -1,15 +1,16 @@ CMP0016 ------- -target_link_libraries() reports error if its only argument is not a target. +:command:`target_link_libraries` reports error if its only argument +is not a target. -In CMake 2.8.2 and lower the target_link_libraries() command silently +In CMake 2.8.2 and lower the :command:`target_link_libraries` command silently ignored if it was called with only one argument, and this argument wasn't a valid target. In CMake 2.8.3 and above it reports an error in this case. This policy was introduced in CMake version 2.8.3. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0017.rst b/Help/policy/CMP0017.rst index 9f0f038..ca4664e 100644 --- a/Help/policy/CMP0017.rst +++ b/Help/policy/CMP0017.rst @@ -4,18 +4,18 @@ CMP0017 Prefer files from the CMake module directory when including from there. Starting with CMake 2.8.4, if a cmake-module shipped with CMake (i.e. -located in the CMake module directory) calls include() or -find_package(), the files located in the CMake module directory are -preferred over the files in CMAKE_MODULE_PATH. This makes sure that -the modules belonging to CMake always get those files included which +located in the CMake module directory) calls :command:`include` or +:command:`find_package`, the files located in the CMake module directory are +preferred over the files in :variable:`CMAKE_MODULE_PATH`. This makes sure +that the modules belonging to CMake always get those files included which they expect, and against which they were developed and tested. In all -other cases, the files found in CMAKE_MODULE_PATH still take -precedence over the ones in the CMake module directory. The OLD +other cases, the files found in :variable:`CMAKE_MODULE_PATH` still take +precedence over the ones in the CMake module directory. The ``OLD`` behavior is to always prefer files from CMAKE_MODULE_PATH over files from the CMake modules directory. This policy was introduced in CMake version 2.8.4. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0018.rst b/Help/policy/CMP0018.rst index a3a7a12..6248406 100644 --- a/Help/policy/CMP0018.rst +++ b/Help/policy/CMP0018.rst @@ -1,34 +1,35 @@ CMP0018 ------- -Ignore CMAKE_SHARED_LIBRARY_<Lang>_FLAGS variable. +Ignore ``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS`` variable. -CMake 2.8.8 and lower compiled sources in SHARED and MODULE libraries -using the value of the undocumented CMAKE_SHARED_LIBRARY_<Lang>_FLAGS +CMake 2.8.8 and lower compiled sources in ``SHARED`` and ``MODULE`` libraries +using the value of the undocumented ``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS`` platform variable. The variable contained platform-specific flags needed to compile objects for shared libraries. Typically it included -a flag such as -fPIC for position independent code but also included +a flag such as ``-fPIC`` for position independent code but also included other flags needed on certain platforms. CMake 2.8.9 and higher -prefer instead to use the POSITION_INDEPENDENT_CODE target property to -determine what targets should be position independent, and new +prefer instead to use the :prop_tgt:`POSITION_INDEPENDENT_CODE` target +property to determine what targets should be position independent, and new undocumented platform variables to select flags while ignoring -CMAKE_SHARED_LIBRARY_<Lang>_FLAGS completely. +``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS`` completely. The default for either approach produces identical compilation flags, -but if a project modifies CMAKE_SHARED_LIBRARY_<Lang>_FLAGS from its +but if a project modifies ``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS`` from its original value this policy determines which approach to use. -The OLD behavior for this policy is to ignore the -POSITION_INDEPENDENT_CODE property for all targets and use the -modified value of CMAKE_SHARED_LIBRARY_<Lang>_FLAGS for SHARED and -MODULE libraries. +The ``OLD`` behavior for this policy is to ignore the +:prop_tgt:`POSITION_INDEPENDENT_CODE` property for all targets and use the +modified value of ``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS`` for ``SHARED`` and +``MODULE`` libraries. -The NEW behavior for this policy is to ignore -CMAKE_SHARED_LIBRARY_<Lang>_FLAGS whether it is modified or not and -honor the POSITION_INDEPENDENT_CODE target property. +The ``NEW`` behavior for this policy is to ignore +``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS`` whether it is modified or not and +honor the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property. This policy was introduced in CMake version 2.8.9. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0019.rst b/Help/policy/CMP0019.rst index 2e3557d..682dcdf 100644 --- a/Help/policy/CMP0019.rst +++ b/Help/policy/CMP0019.rst @@ -11,12 +11,12 @@ CMake versions because all variable references are now normally evaluated during CMake language processing. CMake 2.8.11 and higher prefer to skip the extra evaluation. -The OLD behavior for this policy is to re-evaluate the values for -strict compatibility. The NEW behavior for this policy is to leave +The ``OLD`` behavior for this policy is to re-evaluate the values for +strict compatibility. The ``NEW`` behavior for this policy is to leave the values untouched. This policy was introduced in CMake version 2.8.11. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0020.rst b/Help/policy/CMP0020.rst index 75ca9de..6d27684 100644 --- a/Help/policy/CMP0020.rst +++ b/Help/policy/CMP0020.rst @@ -1,27 +1,27 @@ CMP0020 ------- -Automatically link Qt executables to qtmain target on Windows. +Automatically link Qt executables to ``qtmain`` target on Windows. CMake 2.8.10 and lower required users of Qt to always specify a link -dependency to the qtmain.lib static library manually on Windows. +dependency to the ``qtmain.lib`` static library manually on Windows. CMake 2.8.11 gained the ability to evaluate generator expressions -while determining the link dependencies from IMPORTED targets. This +while determining the link dependencies from ``IMPORTED`` targets. This allows CMake itself to automatically link executables which link to Qt -to the qtmain.lib library when using IMPORTED Qt targets. For -applications already linking to qtmain.lib, this should have little +to the ``qtmain.lib`` library when using ``IMPORTED`` Qt targets. For +applications already linking to ``qtmain.lib``, this should have little impact. For applications which supply their own alternative WinMain implementation and for applications which use the QAxServer library, this automatic linking will need to be disabled as per the documentation. -The OLD behavior for this policy is not to link executables to -qtmain.lib automatically when they link to the QtCore IMPORTED target. -The NEW behavior for this policy is to link executables to qtmain.lib -automatically when they link to QtCore IMPORTED target. +The ``OLD`` behavior for this policy is not to link executables to +``qtmain.lib`` automatically when they link to the QtCore ``IMPORTED`` target. +The ``NEW`` behavior for this policy is to link executables to ``qtmain.lib`` +automatically when they link to QtCore ``IMPORTED`` target. This policy was introduced in CMake version 2.8.11. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0021.rst b/Help/policy/CMP0021.rst index 3a792ca..937b106 100644 --- a/Help/policy/CMP0021.rst +++ b/Help/policy/CMP0021.rst @@ -1,20 +1,21 @@ CMP0021 ------- -Fatal error on relative paths in INCLUDE_DIRECTORIES target property. +Fatal error on relative paths in :prop_tgt:`INCLUDE_DIRECTORIES` target +property. -CMake 2.8.10.2 and lower allowed the INCLUDE_DIRECTORIES target +CMake 2.8.10.2 and lower allowed the :prop_tgt:`INCLUDE_DIRECTORIES` target property to contain relative paths. The base path for such relative -entries is not well defined. CMake 2.8.12 issues a FATAL_ERROR if the -INCLUDE_DIRECTORIES property contains a relative path. +entries is not well defined. CMake 2.8.12 issues a ``FATAL_ERROR`` if the +:prop_tgt:`INCLUDE_DIRECTORIES` property contains a relative path. -The OLD behavior for this policy is not to warn about relative paths -in the INCLUDE_DIRECTORIES target property. The NEW behavior for this -policy is to issue a FATAL_ERROR if INCLUDE_DIRECTORIES contains a +The ``OLD`` behavior for this policy is not to warn about relative paths +in the ``INCLUDE_DIRECTORIES`` target property. The ``NEW`` behavior for this +policy is to issue a ``FATAL_ERROR`` if ``INCLUDE_DIRECTORIES`` contains a relative path. This policy was introduced in CMake version 2.8.12. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0022.rst b/Help/policy/CMP0022.rst index 579d09a..be60e37 100644 --- a/Help/policy/CMP0022.rst +++ b/Help/policy/CMP0022.rst @@ -1,39 +1,39 @@ CMP0022 ------- -INTERFACE_LINK_LIBRARIES defines the link interface. +:prop_tgt:`INTERFACE_LINK_LIBRARIES` defines the link interface. CMake 2.8.11 constructed the 'link interface' of a target from properties matching ``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?``. The modern way to specify config-sensitive content is to use generator expressions and the ``IMPORTED_`` prefix makes uniform processing of the link interface with generator expressions impossible. The -INTERFACE_LINK_LIBRARIES target property was introduced as a +:prop_tgt:`INTERFACE_LINK_LIBRARIES` target property was introduced as a replacement in CMake 2.8.12. This new property is named consistently -with the INTERFACE_COMPILE_DEFINITIONS, INTERFACE_INCLUDE_DIRECTORIES -and INTERFACE_COMPILE_OPTIONS properties. For in-build targets, CMake +with the ``INTERFACE_COMPILE_DEFINITIONS``, ``INTERFACE_INCLUDE_DIRECTORIES`` +and ``INTERFACE_COMPILE_OPTIONS`` properties. For in-build targets, CMake will use the INTERFACE_LINK_LIBRARIES property as the source of the -link interface only if policy CMP0022 is NEW. When exporting a target -which has this policy set to NEW, only the INTERFACE_LINK_LIBRARIES -property will be processed and generated for the IMPORTED target by -default. A new option to the install(EXPORT) and export commands +link interface only if policy ``CMP0022`` is ``NEW``. When exporting a target +which has this policy set to ``NEW``, only the :prop_tgt:`INTERFACE_LINK_LIBRARIES` +property will be processed and generated for the ``IMPORTED`` target by +default. A new option to the :command:`install(EXPORT)` and export commands allows export of the old-style properties for compatibility with downstream users of CMake versions older than 2.8.12. The -target_link_libraries command will no longer populate the properties -matching LINK_INTERFACE_LIBRARIES(_<CONFIG>)? if this policy is NEW. +:command:`target_link_libraries` command will no longer populate the properties +matching ``LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` if this policy is ``NEW``. Warning-free future-compatible code which works with CMake 2.8.7 onwards can be written by using the ``LINK_PRIVATE`` and ``LINK_PUBLIC`` keywords of :command:`target_link_libraries`. -The OLD behavior for this policy is to ignore the -INTERFACE_LINK_LIBRARIES property for in-build targets. The NEW -behavior for this policy is to use the INTERFACE_LINK_LIBRARIES +The ``OLD`` behavior for this policy is to ignore the +:prop_tgt:`INTERFACE_LINK_LIBRARIES` property for in-build targets. +The ``NEW`` behavior for this policy is to use the ``INTERFACE_LINK_LIBRARIES`` property for in-build targets, and ignore the old properties matching ``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?``. This policy was introduced in CMake version 2.8.12. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0023.rst b/Help/policy/CMP0023.rst index 76a4900..3c72c81 100644 --- a/Help/policy/CMP0023.rst +++ b/Help/policy/CMP0023.rst @@ -1,15 +1,15 @@ CMP0023 ------- -Plain and keyword target_link_libraries signatures cannot be mixed. +Plain and keyword :command:`target_link_libraries` signatures cannot be mixed. -CMake 2.8.12 introduced the target_link_libraries signature using the -PUBLIC, PRIVATE, and INTERFACE keywords to generalize the LINK_PUBLIC -and LINK_PRIVATE keywords introduced in CMake 2.8.7. Use of -signatures with any of these keywords sets the link interface of a +CMake 2.8.12 introduced the :command:`target_link_libraries` signature using +the ``PUBLIC``, ``PRIVATE``, and ``INTERFACE`` keywords to generalize the +``LINK_PUBLIC`` and ``LINK_PRIVATE`` keywords introduced in CMake 2.8.7. +Use of signatures with any of these keywords sets the link interface of a target explicitly, even if empty. This produces confusing behavior when used in combination with the historical behavior of the plain -target_link_libraries signature. For example, consider the code: +:command:`target_link_libraries` signature. For example, consider the code: :: @@ -20,16 +20,16 @@ After the first line the link interface has not been set explicitly so CMake would use the link implementation, A, as the link interface. However, the second line sets the link interface to empty. In order to avoid this subtle behavior CMake now prefers to disallow mixing the -plain and keyword signatures of target_link_libraries for a single +plain and keyword signatures of :command:`target_link_libraries` for a single target. -The OLD behavior for this policy is to allow keyword and plain -target_link_libraries signatures to be mixed. The NEW behavior for +The ``OLD`` behavior for this policy is to allow keyword and plain +:command:`target_link_libraries` signatures to be mixed. The ``NEW`` behavior for this policy is to not to allow mixing of the keyword and plain signatures. This policy was introduced in CMake version 2.8.12. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0024.rst b/Help/policy/CMP0024.rst index 272a56c..6e24b04 100644 --- a/Help/policy/CMP0024.rst +++ b/Help/policy/CMP0024.rst @@ -3,22 +3,23 @@ CMP0024 Disallow include export result. -CMake 2.8.12 and lower allowed use of the include() command with the -result of the export() command. This relies on the assumption that -the export() command has an immediate effect at configure-time during +CMake 2.8.12 and lower allowed use of the :command:`include` command with the +result of the :command:`export` command. This relies on the assumption that +the :command:`export` command has an immediate effect at configure-time during a cmake run. Certain properties of targets are not fully determined until later at generate-time, such as the link language and complete list of link libraries. Future refactoring will change the effect of -the export() command to be executed at generate-time. Use ALIAS +the :command:`export` command to be executed at generate-time. Use ``ALIAS`` targets instead in cases where the goal is to refer to targets by another name. -The OLD behavior for this policy is to allow including the result of -an export() command. The NEW behavior for this policy is not to -allow including the result of an export() command. +The ``OLD`` behavior for this policy is to allow including the result of +an :command:`export` command. The ``NEW`` behavior for this policy is not to +allow including the result of an :command:`export` command. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0025.rst b/Help/policy/CMP0025.rst index 62dd509..ba5e1e9 100644 --- a/Help/policy/CMP0025.rst +++ b/Help/policy/CMP0025.rst @@ -15,13 +15,13 @@ language ``<LANG>`` is enabled by the :command:`project` or :command:`enable_language` command. The policy must be set prior to the invocation of either command. -The OLD behavior for this policy is to use compiler id ``Clang``. The -NEW behavior for this policy is to use compiler id ``AppleClang``. +The ``OLD`` behavior for this policy is to use compiler id ``Clang``. The +``NEW`` behavior for this policy is to use compiler id ``AppleClang``. This policy was introduced in CMake version 3.0. Use the -:command:`cmake_policy` command to set this policy to OLD or NEW explicitly. -Unlike most policies, CMake version |release| does *not* warn -by default when this policy is not set and simply uses OLD behavior. +:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` +explicitly. Unlike most policies, CMake version |release| does *not* warn +by default when this policy is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0025 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0026.rst b/Help/policy/CMP0026.rst index 3fe1374..3401d4a 100644 --- a/Help/policy/CMP0026.rst +++ b/Help/policy/CMP0026.rst @@ -3,26 +3,27 @@ CMP0026 Disallow use of the LOCATION property for build targets. -CMake 2.8.12 and lower allowed reading the LOCATION target +CMake 2.8.12 and lower allowed reading the :prop_tgt:`LOCATION` target property (and configuration-specific variants) to determine the eventual location of build targets. This relies on the assumption that all necessary information is available at configure-time to determine the final location and filename of the target. However, this property is not fully determined until later at -generate-time. At generate time, the $<TARGET_FILE> generator -expression can be used to determine the eventual LOCATION of a target +generate-time. At generate time, the ``$<TARGET_FILE>`` generator +expression can be used to determine the eventual :prop_tgt:`LOCATION` of a target output. -Code which reads the LOCATION target property can be ported to use the -$<TARGET_FILE> generator expression together with the file(GENERATE) -subcommand to generate a file containing the target location. +Code which reads the :prop_tgt:`LOCATION` target property can be ported to +use the ``$<TARGET_FILE>`` generator expression together with the +:command:`file(GENERATE)` subcommand to generate a file containing +the target location. -The OLD behavior for this policy is to allow reading the LOCATION -properties from build-targets. The NEW behavior for this policy is to -not to allow reading the LOCATION properties from build-targets. +The ``OLD`` behavior for this policy is to allow reading the :prop_tgt:`LOCATION` +properties from build-targets. The ``NEW`` behavior for this policy is to +not to allow reading the :prop_tgt:`LOCATION` properties from build-targets. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0027.rst b/Help/policy/CMP0027.rst index 28913ce..bf7b6a9 100644 --- a/Help/policy/CMP0027.rst +++ b/Help/policy/CMP0027.rst @@ -4,24 +4,24 @@ CMP0027 Conditionally linked imported targets with missing include directories. CMake 2.8.11 introduced introduced the concept of -INTERFACE_INCLUDE_DIRECTORIES, and a check at cmake time that the -entries in the INTERFACE_INCLUDE_DIRECTORIES of an IMPORTED target -actually exist. CMake 2.8.11 also introduced generator expression -support in the target_link_libraries command. However, if an imported -target is linked as a result of a generator expression evaluation, the -entries in the INTERFACE_INCLUDE_DIRECTORIES of that target were not +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, and a check at cmake time that the +entries in the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of an ``IMPORTED`` +target actually exist. CMake 2.8.11 also introduced generator expression +support in the :command:`target_link_libraries` command. However, if an +imported target is linked as a result of a generator expression evaluation, the +entries in the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of that target were not checked for existence as they should be. -The OLD behavior of this policy is to report a warning if an entry in -the INTERFACE_INCLUDE_DIRECTORIES of a generator-expression -conditionally linked IMPORTED target does not exist. +The ``OLD`` behavior of this policy is to report a warning if an entry in +the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of a generator-expression +conditionally linked ``IMPORTED`` target does not exist. -The NEW behavior of this policy is to report an error if an entry in -the INTERFACE_INCLUDE_DIRECTORIES of a generator-expression -conditionally linked IMPORTED target does not exist. +The ``NEW`` behavior of this policy is to report an error if an entry in +the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of a generator-expression +conditionally linked ``IMPORTED`` target does not exist. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0028.rst b/Help/policy/CMP0028.rst index be57125..ab38229 100644 --- a/Help/policy/CMP0028.rst +++ b/Help/policy/CMP0028.rst @@ -1,25 +1,25 @@ CMP0028 ------- -Double colon in target name means ALIAS or IMPORTED target. +Double colon in target name means ``ALIAS`` or ``IMPORTED`` target. CMake 2.8.12 and lower allowed the use of targets and files with double -colons in target_link_libraries, with some buildsystem generators. +colons in :command:`target_link_libraries`, with some buildsystem generators. -The use of double-colons is a common pattern used to namespace IMPORTED -targets and ALIAS targets. When computing the link dependencies of a target, -the name of each dependency could either be a target, or a file on disk. -Previously, if a target was not found with a matching name, the name was -considered to refer to a file on disk. This can lead to confusing error +The use of double-colons is a common pattern used to namespace ``IMPORTED`` +targets and ``ALIAS`` targets. When computing the link dependencies of +a target, the name of each dependency could either be a target, or a file +on disk. Previously, if a target was not found with a matching name, the name +was considered to refer to a file on disk. This can lead to confusing error messages if there is a typo in what should be a target name. -The OLD behavior for this policy is to search for targets, then files on disk, -even if the search term contains double-colons. The NEW behavior for this -policy is to issue a FATAL_ERROR if a link dependency contains -double-colons but is not an IMPORTED target or an ALIAS target. +The ``OLD`` behavior for this policy is to search for targets, then files on +disk, even if the search term contains double-colons. The ``NEW`` behavior +for this policy is to issue a ``FATAL_ERROR`` if a link dependency contains +double-colons but is not an ``IMPORTED`` target or an ``ALIAS`` target. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0037.rst b/Help/policy/CMP0037.rst index d1afeb7..9895fb0 100644 --- a/Help/policy/CMP0037.rst +++ b/Help/policy/CMP0037.rst @@ -10,24 +10,25 @@ as :manual:`cmake-generator-expressions(7)` and some diagnostics expect target names to match a restricted pattern. Target names may contain upper and lower case letters, numbers, the underscore -character (_), dot(.), plus(+) and minus(-). As a special case, ALIAS -targets and IMPORTED targets may contain two consecutive colons. +character (``_``), dot(``.``), plus(``+``) and minus(``-``). +As a special case, ``ALIAS`` and ``IMPORTED`` targets may contain +two consecutive colons. Target names reserved by one or more CMake generators are not allowed. -Among others these include "all", "clean", "help", and "install". +Among others these include ``all``, ``clean``, ``help``, and ``install``. -Target names associated with optional features, such as "test" and "package", -may also be reserved. CMake 3.10 and below always reserve them. CMake 3.11 -and above reserve them only when the corresponding feature is enabled -(e.g. by including the :module:`CTest` or :module:`CPack` modules). +Target names associated with optional features, such as ``test`` and +``package``, may also be reserved. CMake 3.10 and below always reserve them. +CMake 3.11 and above reserve them only when the corresponding feature is +enabled (e.g. by including the :module:`CTest` or :module:`CPack` modules). -The OLD behavior for this policy is to allow creating targets with +The ``OLD`` behavior for this policy is to allow creating targets with reserved names or which do not match the validity pattern. -The NEW behavior for this policy is to report an error +The ``NEW`` behavior for this policy is to report an error if an add_* command is used with an invalid target name. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0038.rst b/Help/policy/CMP0038.rst index a306d90..7fb2209 100644 --- a/Help/policy/CMP0038.rst +++ b/Help/policy/CMP0038.rst @@ -7,12 +7,12 @@ CMake 2.8.12 and lower allowed a build target to link to itself directly with a :command:`target_link_libraries` call. This is an indicator of a bug in user code. -The OLD behavior for this policy is to ignore targets which list themselves -in their own link implementation. The NEW behavior for this policy is to +The ``OLD`` behavior for this policy is to ignore targets which list themselves +in their own link implementation. The ``NEW`` behavior for this policy is to report an error if a target attempts to link to itself. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0039.rst b/Help/policy/CMP0039.rst index 97d78ae..4b14e21 100644 --- a/Help/policy/CMP0039.rst +++ b/Help/policy/CMP0039.rst @@ -7,13 +7,13 @@ CMake 2.8.12 and lower allowed using utility targets in the left hand side position of the :command:`target_link_libraries` command. This is an indicator of a bug in user code. -The OLD behavior for this policy is to ignore attempts to set the link -libraries of utility targets. The NEW behavior for this policy is to +The ``OLD`` behavior for this policy is to ignore attempts to set the link +libraries of utility targets. The ``NEW`` behavior for this policy is to report an error if an attempt is made to set the link libraries of a utility target. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0041.rst b/Help/policy/CMP0041.rst index f027d5d..3b4df36 100644 --- a/Help/policy/CMP0041.rst +++ b/Help/policy/CMP0041.rst @@ -15,13 +15,13 @@ As an additional diagnostic, the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` gener on an :prop_tgt:`IMPORTED` target for the install location should not contain paths in the source directory or the build directory. -The OLD behavior for this policy is to ignore relative path entries if they -contain a generator expression. The NEW behavior for this policy is to report +The ``OLD`` behavior for this policy is to ignore relative path entries if they +contain a generator expression. The ``NEW`` behavior for this policy is to report an error if a generator expression appears in another location and the path is relative. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0042.rst b/Help/policy/CMP0042.rst index 31314b2..0877564 100644 --- a/Help/policy/CMP0042.rst +++ b/Help/policy/CMP0042.rst @@ -15,7 +15,7 @@ the :prop_tgt:`INSTALL_NAME_DIR` and :variable:`CMAKE_INSTALL_NAME_DIR` variables. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0043.rst b/Help/policy/CMP0043.rst index 9e427c3..05210ac 100644 --- a/Help/policy/CMP0043.rst +++ b/Help/policy/CMP0043.rst @@ -35,13 +35,13 @@ or via :command:`target_compile_definitions`: COMPILE_DEFINITIONS $<$<CONFIG:Debug>:DIR_DEBUG_MODE> ) -The OLD behavior for this policy is to consume the content of the suffixed +The ``OLD`` behavior for this policy is to consume the content of the suffixed :prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` target property when generating the -compilation command. The NEW behavior for this policy is to ignore the content +compilation command. The ``NEW`` behavior for this policy is to ignore the content of the :prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` target property . This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0044.rst b/Help/policy/CMP0044.rst index 02afa9f..6a4d040 100644 --- a/Help/policy/CMP0044.rst +++ b/Help/policy/CMP0044.rst @@ -9,13 +9,13 @@ comparison of the :variable:`CMAKE_<LANG>_COMPILER_ID` with a test value. The possible valid values are lowercase, but the comparison with the test value was performed case-insensitively. -The OLD behavior for this policy is to perform a case-insensitive comparison -with the value in the ``<LANG>_COMPILER_ID`` expression. The NEW behavior +The ``OLD`` behavior for this policy is to perform a case-insensitive comparison +with the value in the ``<LANG>_COMPILER_ID`` expression. The ``NEW`` behavior for this policy is to perform a case-sensitive comparison with the value in the ``<LANG>_COMPILER_ID`` expression. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0045.rst b/Help/policy/CMP0045.rst index c7e1a90f6..80e217b 100644 --- a/Help/policy/CMP0045.rst +++ b/Help/policy/CMP0045.rst @@ -7,13 +7,13 @@ In CMake 2.8.12 and lower, the :command:`get_target_property` command accepted a non-existent target argument without issuing any error or warning. The result variable is set to a ``-NOTFOUND`` value. -The OLD behavior for this policy is to issue no warning and set the result -variable to a ``-NOTFOUND`` value. The NEW behavior +The ``OLD`` behavior for this policy is to issue no warning and set the result +variable to a ``-NOTFOUND`` value. The ``NEW`` behavior for this policy is to issue a ``FATAL_ERROR`` if the command is called with a non-existent target. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0046.rst b/Help/policy/CMP0046.rst index 576d1b1..bf78584 100644 --- a/Help/policy/CMP0046.rst +++ b/Help/policy/CMP0046.rst @@ -6,14 +6,14 @@ Error on non-existent dependency in add_dependencies. CMake 2.8.12 and lower silently ignored non-existent dependencies listed in the :command:`add_dependencies` command. -The OLD behavior for this policy is to silently ignore non-existent -dependencies. The NEW behavior for this policy is to report an error +The ``OLD`` behavior for this policy is to silently ignore non-existent +dependencies. The ``NEW`` behavior for this policy is to report an error if non-existent dependencies are listed in the :command:`add_dependencies` command. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses -OLD behavior. Use the cmake_policy command to set it to OLD or -NEW explicitly. +``OLD`` behavior. Use the :command:`cmake_policy` command to set it +to ``OLD`` or ``NEW`` explicitly. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0047.rst b/Help/policy/CMP0047.rst index 882dd78..9588edd 100644 --- a/Help/policy/CMP0047.rst +++ b/Help/policy/CMP0047.rst @@ -15,14 +15,14 @@ language ``<LANG>`` is enabled by the :command:`project` or :command:`enable_language` command. The policy must be set prior to the invocation of either command. -The OLD behavior for this policy is to use the ``GNU`` compiler id -for the qcc and QCC compiler drivers. The NEW behavior for this policy +The ``OLD`` behavior for this policy is to use the ``GNU`` compiler id +for the qcc and QCC compiler drivers. The ``NEW`` behavior for this policy is to use the ``QCC`` compiler id for those drivers. This policy was introduced in CMake version 3.0. Use the -:command:`cmake_policy` command to set this policy to OLD or NEW explicitly. -Unlike most policies, CMake version |release| does *not* warn -by default when this policy is not set and simply uses OLD behavior. +:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` +explicitly. Unlike most policies, CMake version |release| does *not* warn +by default when this policy is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0047 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0048.rst b/Help/policy/CMP0048.rst index 0e7e606..e63ec01 100644 --- a/Help/policy/CMP0048.rst +++ b/Help/policy/CMP0048.rst @@ -1,24 +1,24 @@ CMP0048 ------- -The :command:`project` command manages VERSION variables. +The :command:`project` command manages ``VERSION`` variables. CMake version 3.0 introduced the ``VERSION`` option of the :command:`project` command to specify a project version as well as the name. In order to keep :variable:`PROJECT_VERSION` and related variables consistent with variable -:variable:`PROJECT_NAME` it is necessary to set the VERSION variables +:variable:`PROJECT_NAME` it is necessary to set the ``VERSION`` variables to the empty string when no ``VERSION`` is given to :command:`project`. -However, this can change behavior for existing projects that set VERSION +However, this can change behavior for existing projects that set ``VERSION`` variables themselves since :command:`project` may now clear them. This policy controls the behavior for compatibility with such projects. -The OLD behavior for this policy is to leave VERSION variables untouched. -The NEW behavior for this policy is to set VERSION as documented by the +The ``OLD`` behavior for this policy is to leave ``VERSION`` variables untouched. +The ``NEW`` behavior for this policy is to set ``VERSION`` as documented by the :command:`project` command. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses -OLD behavior. Use the cmake_policy command to set it to OLD or -NEW explicitly. +``OLD`` behavior. Use the :command:`cmake_policy` command to set +it to ``OLD`` or ``NEW`` explicitly. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0049.rst b/Help/policy/CMP0049.rst index 291bf57..49b20be 100644 --- a/Help/policy/CMP0049.rst +++ b/Help/policy/CMP0049.rst @@ -13,13 +13,13 @@ when evaluating source file names:: This was undocumented behavior. -The OLD behavior for this policy is to expand such variables when processing -the target sources. The NEW behavior for this policy is to issue an error +The ``OLD`` behavior for this policy is to expand such variables when processing +the target sources. The ``NEW`` behavior for this policy is to issue an error if such variables need to be expanded. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses -OLD behavior. Use the cmake_policy command to set it to OLD or -NEW explicitly. +``OLD`` behavior. Use the :command:`cmake_policy` command to set +it to ``OLD`` or ``NEW`` explicitly. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0050.rst b/Help/policy/CMP0050.rst index 39e40b6..27e7b1d 100644 --- a/Help/policy/CMP0050.rst +++ b/Help/policy/CMP0050.rst @@ -8,13 +8,13 @@ which specified an input to a command. This was undocumented behavior. Modern use of CMake associates custom commands with their output, rather than their input. -The OLD behavior for this policy is to allow the use of -:command:`add_custom_command` SOURCE signatures. The NEW behavior for this +The ``OLD`` behavior for this policy is to allow the use of +:command:`add_custom_command` SOURCE signatures. The ``NEW`` behavior for this policy is to issue an error if such a signature is used. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses -OLD behavior. Use the cmake_policy command to set it to OLD or -NEW explicitly. +``OLD`` behavior. Use the :command:`cmake_policy` command to set it to ``OLD`` or +``NEW`` explicitly. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0052.rst b/Help/policy/CMP0052.rst index 0ea5ace..ee2e6e8 100644 --- a/Help/policy/CMP0052.rst +++ b/Help/policy/CMP0052.rst @@ -1,7 +1,8 @@ CMP0052 ------- -Reject source and build dirs in installed INTERFACE_INCLUDE_DIRECTORIES. +Reject source and build dirs in installed +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`. CMake 3.0 and lower allowed subdirectories of the source directory or build directory to be in the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of @@ -13,9 +14,9 @@ broken if either are removed after installation. See :ref:`Include Directories and Usage Requirements` for more on specifying include directories for targets. -The OLD behavior for this policy is to export the content of the +The ``OLD`` behavior for this policy is to export the content of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` with the source or binary -directory. The NEW behavior for this +directory. The ``NEW`` behavior for this policy is to issue an error if such a directory is used. This policy was introduced in CMake version 3.1. diff --git a/Help/policy/CMP0055.rst b/Help/policy/CMP0055.rst index b3df758..bc5ad08 100644 --- a/Help/policy/CMP0055.rst +++ b/Help/policy/CMP0055.rst @@ -7,13 +7,13 @@ CMake 3.1 and lower allowed calls to the :command:`break` command outside of a loop context and also ignored any given arguments. This was undefined behavior. -The OLD behavior for this policy is to allow :command:`break` to be placed -outside of loop contexts and ignores any arguments. The NEW behavior for this +The ``OLD`` behavior for this policy is to allow :command:`break` to be placed +outside of loop contexts and ignores any arguments. The ``NEW`` behavior for this policy is to issue an error if a misplaced break or any arguments are found. This policy was introduced in CMake version 3.2. CMake version |release| warns when the policy is not set and uses -OLD behavior. Use the cmake_policy command to set it to OLD or -NEW explicitly. +``OLD`` behavior. Use the :command:`cmake_policy` command to set it to ``OLD`` or +``NEW`` explicitly. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0056.rst b/Help/policy/CMP0056.rst index 3ba89d5..834da84 100644 --- a/Help/policy/CMP0056.rst +++ b/Help/policy/CMP0056.rst @@ -14,9 +14,9 @@ the generated project. CMake 3.2 and above prefer to set it so that linker flags are honored as well as compiler flags. This policy provides compatibility with the pre-3.2 behavior. -The OLD behavior for this policy is to not set the value of the +The ``OLD`` behavior for this policy is to not set the value of the :variable:`CMAKE_EXE_LINKER_FLAGS` variable in the generated test -project. The NEW behavior for this policy is to set the value of +project. The ``NEW`` behavior for this policy is to set the value of the :variable:`CMAKE_EXE_LINKER_FLAGS` variable in the test project to the same as it is in the calling project. @@ -27,7 +27,7 @@ variable in the cache. This policy was introduced in CMake version 3.2. Unlike most policies, CMake version |release| does *not* warn by default when this policy -is not set and simply uses OLD behavior. See documentation of the +is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0056 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0060.rst b/Help/policy/CMP0060.rst index 8611aff..98ac2cf 100644 --- a/Help/policy/CMP0060.rst +++ b/Help/policy/CMP0060.rst @@ -51,14 +51,14 @@ and link libraries by full path even when they are in implicit link directories. Policy ``CMP0060`` provides compatibility for existing projects. -The OLD behavior for this policy is to ask the linker to search for +The ``OLD`` behavior for this policy is to ask the linker to search for libraries whose full paths are known to be in implicit link directories. -The NEW behavior for this policy is to link libraries by full path even +The ``NEW`` behavior for this policy is to link libraries by full path even if they are in implicit link directories. This policy was introduced in CMake version 3.3. Unlike most policies, CMake version |release| does *not* warn by default when this policy -is not set and simply uses OLD behavior. See documentation of the +is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0060 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0061.rst b/Help/policy/CMP0061.rst index cb2ac28..57e4161 100644 --- a/Help/policy/CMP0061.rst +++ b/Help/policy/CMP0061.rst @@ -21,6 +21,6 @@ add ``-i``. This policy was introduced in CMake version 3.3. Unlike most policies, CMake version |release| does *not* warn when this policy is not set and -simply uses OLD behavior. +simply uses ``OLD`` behavior. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0062.rst b/Help/policy/CMP0062.rst index 9047fff..0db7aaf 100644 --- a/Help/policy/CMP0062.rst +++ b/Help/policy/CMP0062.rst @@ -1,7 +1,7 @@ CMP0062 ------- -Disallow install() of export() result. +Disallow :command:`install` of :command:`export` result. The :command:`export()` command generates a file containing :ref:`Imported Targets`, which is suitable for use from the build diff --git a/Help/policy/CMP0065.rst b/Help/policy/CMP0065.rst index 2ed775d..b820aad 100644 --- a/Help/policy/CMP0065.rst +++ b/Help/policy/CMP0065.rst @@ -20,7 +20,7 @@ property is set to ``True``. This policy was introduced in CMake version 3.4. Unlike most policies, CMake version |release| does *not* warn by default when this policy -is not set and simply uses OLD behavior. See documentation of the +is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0065 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0066.rst b/Help/policy/CMP0066.rst index d1dcb0e..e110ae1 100644 --- a/Help/policy/CMP0066.rst +++ b/Help/policy/CMP0066.rst @@ -20,7 +20,7 @@ variabldes like :variable:`CMAKE_<LANG>_FLAGS_DEBUG`. This policy was introduced in CMake version 3.7. Unlike most policies, CMake version |release| does *not* warn by default when this policy -is not set and simply uses OLD behavior. See documentation of the +is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0066 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0067.rst b/Help/policy/CMP0067.rst index e6dda80..f802787 100644 --- a/Help/policy/CMP0067.rst +++ b/Help/policy/CMP0067.rst @@ -30,7 +30,7 @@ setting variables. This policy was introduced in CMake version 3.8. Unlike most policies, CMake version |release| does *not* warn by default when this policy -is not set and simply uses OLD behavior. See documentation of the +is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0067 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0071.rst b/Help/policy/CMP0071.rst index ee33aa1..855ecf0 100644 --- a/Help/policy/CMP0071.rst +++ b/Help/policy/CMP0071.rst @@ -21,7 +21,7 @@ source files. .. note:: - To silence the CMP0071 warning source files can be excluded from + To silence the ``CMP0071`` warning source files can be excluded from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` processing by setting the source file properties :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC` or :prop_sf:`SKIP_AUTOGEN`. diff --git a/Help/policy/CMP0082.rst b/Help/policy/CMP0082.rst index 8256444..d887616 100644 --- a/Help/policy/CMP0082.rst +++ b/Help/policy/CMP0082.rst @@ -19,7 +19,7 @@ declared. This policy was introduced in CMake version 3.14. Unlike most policies, CMake version |release| does *not* warn by default when this policy -is not set and simply uses OLD behavior. See documentation of the +is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0082 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0089.rst b/Help/policy/CMP0089.rst index e549e0c..029de55 100644 --- a/Help/policy/CMP0089.rst +++ b/Help/policy/CMP0089.rst @@ -16,13 +16,13 @@ variable after language ``<LANG>`` is enabled by the :command:`project` or :command:`enable_language` command. The policy must be set prior to the invocation of either command. -The OLD behavior for this policy is to use compiler id ``XL``. The -NEW behavior for this policy is to use compiler id ``XLClang``. +The ``OLD`` behavior for this policy is to use compiler id ``XL``. The +``NEW`` behavior for this policy is to use compiler id ``XLClang``. This policy was introduced in CMake version 3.15. Use the -:command:`cmake_policy` command to set this policy to OLD or NEW explicitly. +:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` explicitly. Unlike most policies, CMake version |release| does *not* warn -by default when this policy is not set and simply uses OLD behavior. +by default when this policy is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0089 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/DISALLOWED_COMMAND.txt b/Help/policy/DISALLOWED_COMMAND.txt index 36280d2..6500bb0 100644 --- a/Help/policy/DISALLOWED_COMMAND.txt +++ b/Help/policy/DISALLOWED_COMMAND.txt @@ -1,9 +1,9 @@ CMake >= |disallowed_version| prefer that this command never be called. -The OLD behavior for this policy is to allow the command to be called. -The NEW behavior for this policy is to issue a FATAL_ERROR when the +The ``OLD`` behavior for this policy is to allow the command to be called. +The ``NEW`` behavior for this policy is to issue a ``FATAL_ERROR`` when the command is called. This policy was introduced in CMake version |disallowed_version|. CMake version |release| warns when the policy is not set and uses -OLD behavior. Use the cmake_policy command to set it to OLD or -NEW explicitly. +``OLD`` behavior. Use the :command:`cmake_policy` command to set it to ``OLD`` or +``NEW`` explicitly. diff --git a/Help/prop_cache/ADVANCED.rst b/Help/prop_cache/ADVANCED.rst index a0a4f73..ec4de9d 100644 --- a/Help/prop_cache/ADVANCED.rst +++ b/Help/prop_cache/ADVANCED.rst @@ -4,5 +4,5 @@ ADVANCED True if entry should be hidden by default in GUIs. This is a boolean value indicating whether the entry is considered -interesting only for advanced configuration. The mark_as_advanced() +interesting only for advanced configuration. The :command:`mark_as_advanced` command modifies this property. diff --git a/Help/prop_cache/STRINGS.rst b/Help/prop_cache/STRINGS.rst index 2f8e32e..0e3c326 100644 --- a/Help/prop_cache/STRINGS.rst +++ b/Help/prop_cache/STRINGS.rst @@ -1,9 +1,9 @@ STRINGS ------- -Enumerate possible STRING entry values for GUI selection. +Enumerate possible ``STRING`` entry values for GUI selection. -For cache entries with type STRING, this enumerates a set of values. +For cache entries with type ``STRING``, this enumerates a set of values. CMake GUIs may use this to provide a selection widget instead of a generic string entry field. This is for convenience only. CMake does not enforce that the value matches one of those listed. diff --git a/Help/prop_cache/TYPE.rst b/Help/prop_cache/TYPE.rst index eb75c2a..7ca859f 100644 --- a/Help/prop_cache/TYPE.rst +++ b/Help/prop_cache/TYPE.rst @@ -5,7 +5,7 @@ Widget type for entry in GUIs. Cache entry values are always strings, but CMake GUIs present widgets to help users set values. The GUIs use this property as a hint to -determine the widget type. Valid TYPE values are: +determine the widget type. Valid ``TYPE`` values are: :: @@ -17,5 +17,5 @@ determine the widget type. Valid TYPE values are: STATIC = Value managed by CMake, do not change. UNINITIALIZED = Type not yet specified. -Generally the TYPE of a cache entry should be set by the command which -creates it (set, option, find_library, etc.). +Generally the ``TYPE`` of a cache entry should be set by the command which +creates it ( :command:`set`, :command:`option`, :command:`find_library`, etc.). diff --git a/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst b/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst index e32eed3..986ea5b 100644 --- a/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst +++ b/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst @@ -3,5 +3,5 @@ ADDITIONAL_MAKE_CLEAN_FILES Additional files to clean during the make clean stage. -A list of files that will be cleaned as a part of the "make clean" +A list of files that will be cleaned as a part of the ``make clean`` stage. diff --git a/Help/prop_dir/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM.rst b/Help/prop_dir/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM.rst index 993f620..f534976 100644 --- a/Help/prop_dir/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM.rst +++ b/Help/prop_dir/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM.rst @@ -1,15 +1,15 @@ IMPLICIT_DEPENDS_INCLUDE_TRANSFORM ---------------------------------- -Specify #include line transforms for dependencies in a directory. +Specify ``#include`` line transforms for dependencies in a directory. -This property specifies rules to transform macro-like #include lines +This property specifies rules to transform macro-like ``#include`` lines during implicit dependency scanning of C and C++ source files. The list of rules must be semicolon-separated with each entry of the form -"A_MACRO(%)=value-with-%" (the % must be literal). During dependency -scanning occurrences of A_MACRO(...) on #include lines will be +``A_MACRO(%)=value-with-%`` (the ``%`` must be literal). During dependency +scanning occurrences of ``A_MACRO(...)`` on ``#include`` lines will be replaced by the value given with the macro argument substituted for -'%'. For example, the entry +``%``. For example, the entry :: diff --git a/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst b/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst index 32520865..840a1db 100644 --- a/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst +++ b/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst @@ -3,6 +3,6 @@ INTERPROCEDURAL_OPTIMIZATION_<CONFIG> Per-configuration interprocedural optimization for a directory. -This is a per-configuration version of INTERPROCEDURAL_OPTIMIZATION. +This is a per-configuration version of ``INTERPROCEDURAL_OPTIMIZATION``. If set, this property overrides the generic property for the named configuration. diff --git a/Help/prop_dir/MACROS.rst b/Help/prop_dir/MACROS.rst index e4feada..245cc1b 100644 --- a/Help/prop_dir/MACROS.rst +++ b/Help/prop_dir/MACROS.rst @@ -4,5 +4,5 @@ MACROS List of macro commands available in the current directory. This read-only property specifies the list of CMake macros currently -defined. It is intended for debugging purposes. See the macro +defined. It is intended for debugging purposes. See the :command:`macro` command. diff --git a/Help/prop_dir/TESTS.rst b/Help/prop_dir/TESTS.rst index 56e230e..1c9f6e5 100644 --- a/Help/prop_dir/TESTS.rst +++ b/Help/prop_dir/TESTS.rst @@ -3,5 +3,6 @@ TESTS List of tests. -This read-only property holds a :ref:`semicolon-separated list <CMake Language Lists>` of tests +This read-only property holds a +:ref:`semicolon-separated list <CMake Language Lists>` of tests defined so far, in the current directory, by the :command:`add_test` command. diff --git a/Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst b/Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst index 814bd5f..b65db99 100644 --- a/Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst +++ b/Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst @@ -12,20 +12,20 @@ in the solution file: <contents based on property value> EndGlobalSection -The property must be set to a semicolon-separated list of key=value +The property must be set to a semicolon-separated list of ``key=value`` pairs. Each such pair will be transformed into an entry in the solution global section. Whitespace around key and value is ignored. List elements which do not contain an equal sign are skipped. This property only works for Visual Studio 9 and above; it is ignored on other generators. The property only applies when set on a -directory whose CMakeLists.txt contains a project() command. +directory whose ``CMakeLists.txt`` contains a :command:`project` command. -Note that CMake generates postSolution sections ExtensibilityGlobals -and ExtensibilityAddIns by default. If you set the corresponding +Note that CMake generates postSolution sections ``ExtensibilityGlobals`` +and ``ExtensibilityAddIns`` by default. If you set the corresponding property, it will override the default section. For example, setting -VS_GLOBAL_SECTION_POST_ExtensibilityGlobals will override the default -contents of the ExtensibilityGlobals section, while keeping +``VS_GLOBAL_SECTION_POST_ExtensibilityGlobals`` will override the default +contents of the ``ExtensibilityGlobals`` section, while keeping ExtensibilityAddIns on its default. However, CMake will always add a ``SolutionGuid`` to the ``ExtensibilityGlobals`` section if it is not specified explicitly. diff --git a/Help/prop_dir/VS_GLOBAL_SECTION_PRE_section.rst b/Help/prop_dir/VS_GLOBAL_SECTION_PRE_section.rst index f70e9f1..7f8bf61 100644 --- a/Help/prop_dir/VS_GLOBAL_SECTION_PRE_section.rst +++ b/Help/prop_dir/VS_GLOBAL_SECTION_PRE_section.rst @@ -12,11 +12,11 @@ in the solution file: <contents based on property value> EndGlobalSection -The property must be set to a semicolon-separated list of key=value +The property must be set to a semicolon-separated list of ``key=value`` pairs. Each such pair will be transformed into an entry in the solution global section. Whitespace around key and value is ignored. List elements which do not contain an equal sign are skipped. This property only works for Visual Studio 9 and above; it is ignored on other generators. The property only applies when set on a -directory whose CMakeLists.txt contains a project() command. +directory whose ``CMakeLists.txt`` contains a :command:`project` command. diff --git a/Help/prop_dir/VS_STARTUP_PROJECT.rst b/Help/prop_dir/VS_STARTUP_PROJECT.rst index 04441b6..2680dfa 100644 --- a/Help/prop_dir/VS_STARTUP_PROJECT.rst +++ b/Help/prop_dir/VS_STARTUP_PROJECT.rst @@ -7,7 +7,7 @@ The :ref:`Visual Studio Generators` create a ``.sln`` file for each directory whose ``CMakeLists.txt`` file calls the :command:`project` command. Set this property in the same directory as a :command:`project` command call (e.g. in the top-level ``CMakeLists.txt`` file) to specify the default startup project -for the correpsonding solution file. +for the corresponding solution file. The property must be set to the name of an existing target. This will cause that project to be listed first in the generated solution diff --git a/Help/prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS.rst b/Help/prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS.rst index 8fab503..19775ff 100644 --- a/Help/prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS.rst +++ b/Help/prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS.rst @@ -4,16 +4,18 @@ ALLOW_DUPLICATE_CUSTOM_TARGETS Allow duplicate custom targets to be created. Normally CMake requires that all targets built in a project have -globally unique logical names (see policy CMP0002). This is necessary -to generate meaningful project file names in Xcode and VS IDE +globally unique logical names (see policy :policy:`CMP0002`). +This is necessary to generate meaningful project file names in +:generator:`Xcode` and :ref:`Visual Studio Generators` IDE generators. It also allows the target names to be referenced unambiguously. -Makefile generators are capable of supporting duplicate custom target -names. For projects that care only about Makefile generators and do -not wish to support Xcode or VS IDE generators, one may set this -property to true to allow duplicate custom targets. The property -allows multiple add_custom_target command calls in different +Makefile generators are capable of supporting duplicate :command:`add_custom_target` +names. For projects that care only about :ref:`Makefile Generators` and do +not wish to support :generator:`Xcode` or :ref:`Visual Studio Generators` IDE +generators, one may set this property to ``True`` +to allow duplicate custom targets. The property +allows multiple :command:`add_custom_target` command calls in different directories to specify the same target name. However, setting this property will cause non-Makefile generators to produce an error and refuse to generate the project. diff --git a/Help/prop_gbl/DISABLED_FEATURES.rst b/Help/prop_gbl/DISABLED_FEATURES.rst index 111cdf6..882bbfa 100644 --- a/Help/prop_gbl/DISABLED_FEATURES.rst +++ b/Help/prop_gbl/DISABLED_FEATURES.rst @@ -5,7 +5,7 @@ List of features which are disabled during the CMake run. List of features which are disabled during the CMake run. By default it contains the names of all packages which were not found. This is -determined using the <NAME>_FOUND variables. Packages which are -searched QUIET are not listed. A project can add its own features to +determined using the ``<NAME>_FOUND`` variables. Packages which are +searched ``QUIET`` are not listed. A project can add its own features to this list. This property is used by the macros in -FeatureSummary.cmake. +``FeatureSummary.cmake``. diff --git a/Help/prop_gbl/ENABLED_FEATURES.rst b/Help/prop_gbl/ENABLED_FEATURES.rst index b03da5a..acbb3d0 100644 --- a/Help/prop_gbl/ENABLED_FEATURES.rst +++ b/Help/prop_gbl/ENABLED_FEATURES.rst @@ -5,7 +5,7 @@ List of features which are enabled during the CMake run. List of features which are enabled during the CMake run. By default it contains the names of all packages which were found. This is -determined using the <NAME>_FOUND variables. Packages which are -searched QUIET are not listed. A project can add its own features to +determined using the ``<NAME>_FOUND`` variables. Packages which are +searched ``QUIET`` are not listed. A project can add its own features to this list. This property is used by the macros in -FeatureSummary.cmake. +``FeatureSummary.cmake``. diff --git a/Help/prop_gbl/USE_FOLDERS.rst b/Help/prop_gbl/USE_FOLDERS.rst index a1b4ccb..5919723 100644 --- a/Help/prop_gbl/USE_FOLDERS.rst +++ b/Help/prop_gbl/USE_FOLDERS.rst @@ -4,7 +4,7 @@ USE_FOLDERS Use the :prop_tgt:`FOLDER` target property to organize targets into folders. -If not set, CMake treats this property as OFF by default. CMake +If not set, CMake treats this property as ``OFF`` by default. CMake generators that are capable of organizing into a hierarchy of folders use the values of the :prop_tgt:`FOLDER` target property to name those -folders. See also the documentation for the FOLDER target property. +folders. See also the documentation for the :prop_tgt:`FOLDER` target property. diff --git a/Help/prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.rst b/Help/prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.rst index 9a6086e..9500443 100644 --- a/Help/prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.rst +++ b/Help/prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.rst @@ -1,14 +1,15 @@ XCODE_EMIT_EFFECTIVE_PLATFORM_NAME ---------------------------------- -Control emission of ``EFFECTIVE_PLATFORM_NAME`` by the Xcode generator. +Control emission of ``EFFECTIVE_PLATFORM_NAME`` by the :generator:`Xcode` +generator. It is required for building the same target with multiple SDKs. A common use case is the parallel use of ``iphoneos`` and ``iphonesimulator`` SDKs. -Three different states possible that control when the Xcode generator -emits the ``EFFECTIVE_PLATFORM_NAME`` variable: +Three different states possible that control when the :generator:`Xcode` +generator emits the ``EFFECTIVE_PLATFORM_NAME`` variable: - If set to ``ON`` it will always be emitted - If set to ``OFF`` it will never be emitted diff --git a/Help/prop_inst/CPACK_DESKTOP_SHORTCUTS.rst b/Help/prop_inst/CPACK_DESKTOP_SHORTCUTS.rst index 11f2c03..729ab60 100644 --- a/Help/prop_inst/CPACK_DESKTOP_SHORTCUTS.rst +++ b/Help/prop_inst/CPACK_DESKTOP_SHORTCUTS.rst @@ -1,7 +1,7 @@ CPACK_DESKTOP_SHORTCUTS ----------------------- -Species a list of shortcut names that should be created on the Desktop +Species a list of shortcut names that should be created on the `Desktop` for this file. -The property is currently only supported by the WIX generator. +The property is currently only supported by the :cpack_gen:`CPack WIX Generator`. diff --git a/Help/prop_inst/CPACK_NEVER_OVERWRITE.rst b/Help/prop_inst/CPACK_NEVER_OVERWRITE.rst index 11f44d0..4789e25 100644 --- a/Help/prop_inst/CPACK_NEVER_OVERWRITE.rst +++ b/Help/prop_inst/CPACK_NEVER_OVERWRITE.rst @@ -3,4 +3,4 @@ CPACK_NEVER_OVERWRITE Request that this file not be overwritten on install or reinstall. -The property is currently only supported by the WIX generator. +The property is currently only supported by the :cpack_gen:`CPack WIX Generator`. diff --git a/Help/prop_inst/CPACK_PERMANENT.rst b/Help/prop_inst/CPACK_PERMANENT.rst index 5e191d0..985de0d 100644 --- a/Help/prop_inst/CPACK_PERMANENT.rst +++ b/Help/prop_inst/CPACK_PERMANENT.rst @@ -3,4 +3,4 @@ CPACK_PERMANENT Request that this file not be removed on uninstall. -The property is currently only supported by the WIX generator. +The property is currently only supported by the :cpack_gen:`CPack WIX Generator`. diff --git a/Help/prop_inst/CPACK_STARTUP_SHORTCUTS.rst b/Help/prop_inst/CPACK_STARTUP_SHORTCUTS.rst index 8a16022..d9208b9 100644 --- a/Help/prop_inst/CPACK_STARTUP_SHORTCUTS.rst +++ b/Help/prop_inst/CPACK_STARTUP_SHORTCUTS.rst @@ -1,7 +1,7 @@ CPACK_STARTUP_SHORTCUTS ----------------------- -Species a list of shortcut names that should be created in the Startup folder +Species a list of shortcut names that should be created in the `Startup` folder for this file. -The property is currently only supported by the WIX generator. +The property is currently only supported by the :cpack_gen:`CPack WIX Generator`. diff --git a/Help/prop_inst/CPACK_START_MENU_SHORTCUTS.rst b/Help/prop_inst/CPACK_START_MENU_SHORTCUTS.rst index d30ea39..092334a 100644 --- a/Help/prop_inst/CPACK_START_MENU_SHORTCUTS.rst +++ b/Help/prop_inst/CPACK_START_MENU_SHORTCUTS.rst @@ -1,7 +1,7 @@ CPACK_START_MENU_SHORTCUTS -------------------------- -Species a list of shortcut names that should be created in the Start Menu +Species a list of shortcut names that should be created in the `Start Menu` for this file. -The property is currently only supported by the WIX generator. +The property is currently only supported by the :cpack_gen:`CPack WIX Generator`. diff --git a/Help/prop_inst/CPACK_WIX_ACL.rst b/Help/prop_inst/CPACK_WIX_ACL.rst index 4e13ec4..c88f426 100644 --- a/Help/prop_inst/CPACK_WIX_ACL.rst +++ b/Help/prop_inst/CPACK_WIX_ACL.rst @@ -17,3 +17,5 @@ each of which has to match the following format. ``<permission>`` is any of the YesNoType attributes listed here:: http://wixtoolset.org/documentation/manual/v3/xsd/wix/permission.html + +The property is currently only supported by the :cpack_gen:`CPack WIX Generator`. diff --git a/Help/prop_sf/COMPILE_DEFINITIONS.rst b/Help/prop_sf/COMPILE_DEFINITIONS.rst index 8d2108c..6317690 100644 --- a/Help/prop_sf/COMPILE_DEFINITIONS.rst +++ b/Help/prop_sf/COMPILE_DEFINITIONS.rst @@ -3,14 +3,14 @@ COMPILE_DEFINITIONS Preprocessor definitions for compiling a source file. -The COMPILE_DEFINITIONS property may be set to a semicolon-separated -list of preprocessor definitions using the syntax VAR or VAR=value. +The ``COMPILE_DEFINITIONS`` property may be set to a semicolon-separated +list of preprocessor definitions using the syntax ``VAR`` or ``VAR=value``. Function-style definitions are not supported. CMake will automatically escape the value correctly for the native build system (note that CMake language syntax may require escapes to specify some values). This property may be set on a per-configuration basis using -the name COMPILE_DEFINITIONS_<CONFIG> where <CONFIG> is an upper-case -name (ex. "COMPILE_DEFINITIONS_DEBUG"). +the name ``COMPILE_DEFINITIONS_<CONFIG>`` where ``<CONFIG>`` is an upper-case +name (ex. ``COMPILE_DEFINITIONS_DEBUG``). CMake will automatically drop some definitions that are not supported by the native build tool. Xcode does not support per-configuration @@ -18,7 +18,7 @@ definitions on source files. .. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.txt -Contents of ``COMPILE_DEFINITIONS`` may use "generator expressions" +Contents of ``COMPILE_DEFINITIONS`` may use :manual:`cmake-generator-expressions(7)` with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. However, :generator:`Xcode` does not support per-config per-source settings, so expressions diff --git a/Help/prop_sf/COMPILE_DEFINITIONS_CONFIG.rst b/Help/prop_sf/COMPILE_DEFINITIONS_CONFIG.rst index 8487076..ec867b6 100644 --- a/Help/prop_sf/COMPILE_DEFINITIONS_CONFIG.rst +++ b/Help/prop_sf/COMPILE_DEFINITIONS_CONFIG.rst @@ -5,6 +5,6 @@ Ignored. See CMake Policy :policy:`CMP0043`. Per-configuration preprocessor definitions on a source file. -This is the configuration-specific version of COMPILE_DEFINITIONS. -Note that Xcode does not support per-configuration source file flags -so this property will be ignored by the Xcode generator. +This is the configuration-specific version of :prop_tgt:`COMPILE_DEFINITIONS`. +Note that :generator:`Xcode` does not support per-configuration source +file flags so this property will be ignored by the :generator:`Xcode` generator. diff --git a/Help/prop_sf/EXTERNAL_OBJECT.rst b/Help/prop_sf/EXTERNAL_OBJECT.rst index efa0e9b..351c04d 100644 --- a/Help/prop_sf/EXTERNAL_OBJECT.rst +++ b/Help/prop_sf/EXTERNAL_OBJECT.rst @@ -3,6 +3,6 @@ EXTERNAL_OBJECT If set to true then this is an object file. -If this property is set to true then the source file is really an +If this property is set to ``True`` then the source file is really an object file and should not be compiled. It will still be linked into the target though. diff --git a/Help/prop_sf/Fortran_FORMAT.rst b/Help/prop_sf/Fortran_FORMAT.rst index 69e34aa..1cbbf48 100644 --- a/Help/prop_sf/Fortran_FORMAT.rst +++ b/Help/prop_sf/Fortran_FORMAT.rst @@ -1,9 +1,10 @@ Fortran_FORMAT -------------- -Set to FIXED or FREE to indicate the Fortran source layout. +Set to ``FIXED`` or ``FREE`` to indicate the Fortran source layout. This property tells CMake whether a given Fortran source file uses fixed-format or free-format. CMake will pass the corresponding format -flag to the compiler. Consider using the target-wide Fortran_FORMAT -property if all source files in a target share the same format. +flag to the compiler. Consider using the target-wide +:prop_tgt:`Fortran_FORMAT` property if all source files in a target +share the same format. diff --git a/Help/prop_sf/KEEP_EXTENSION.rst b/Help/prop_sf/KEEP_EXTENSION.rst index d6167e5..a32f968 100644 --- a/Help/prop_sf/KEEP_EXTENSION.rst +++ b/Help/prop_sf/KEEP_EXTENSION.rst @@ -6,4 +6,4 @@ Make the output file have the same extension as the source file. If this property is set then the file extension of the output file will be the same as that of the source file. Normally the output file extension is computed based on the language of the source file, for -example .cxx will go to a .o extension. +example ``.cxx`` will go to a ``.o`` extension. diff --git a/Help/prop_sf/LABELS.rst b/Help/prop_sf/LABELS.rst index e1c1069..d0d2a0a 100644 --- a/Help/prop_sf/LABELS.rst +++ b/Help/prop_sf/LABELS.rst @@ -4,5 +4,5 @@ LABELS Specify a list of text labels associated with a source file. This property has meaning only when the source file is listed in a -target whose LABELS property is also set. No other semantics are +target whose ``LABELS`` property is also set. No other semantics are currently specified. diff --git a/Help/prop_sf/LANGUAGE.rst b/Help/prop_sf/LANGUAGE.rst index 97bfa20..88d438e 100644 --- a/Help/prop_sf/LANGUAGE.rst +++ b/Help/prop_sf/LANGUAGE.rst @@ -5,6 +5,7 @@ What programming language is the file. A property that can be set to indicate what programming language the source file is. If it is not set the language is determined based on -the file extension. Typical values are CXX C etc. Setting this +the file extension. Typical values are ``CXX`` (i.e. C++), ``C``, +``CSharp``, ``CUDA``, ``Fortran``, and ``ASM``. Setting this property for a file means this file will be compiled. Do not set this for headers or files that should not be compiled. diff --git a/Help/prop_sf/OBJECT_OUTPUTS.rst b/Help/prop_sf/OBJECT_OUTPUTS.rst index 1ce4866..e7e880b 100644 --- a/Help/prop_sf/OBJECT_OUTPUTS.rst +++ b/Help/prop_sf/OBJECT_OUTPUTS.rst @@ -1,9 +1,9 @@ OBJECT_OUTPUTS -------------- -Additional outputs for a Ninja or Makefile rule. +Additional outputs for a :generator:`Ninja` or :ref:`Makefile Generators` rule. Additional outputs created by compilation of this source file. If any of these outputs is missing the object will be recompiled. This is -supported only on the Ninja and Makefile generators and will be ignored on -other generators. +supported only on the :generator:`Ninja` and :ref:`Makefile Generators` +and will be ignored on other generators. diff --git a/Help/prop_sf/SYMBOLIC.rst b/Help/prop_sf/SYMBOLIC.rst index c7d0b26..8bebe30 100644 --- a/Help/prop_sf/SYMBOLIC.rst +++ b/Help/prop_sf/SYMBOLIC.rst @@ -3,6 +3,6 @@ SYMBOLIC Is this just a name for a rule. -If SYMBOLIC (boolean) is set to true the build system will be informed +If ``SYMBOLIC`` (boolean) is set to ``True`` the build system will be informed that the source file is not actually created on disk but instead used as a symbolic name for a build rule. diff --git a/Help/prop_sf/VS_CSHARP_tagname.rst b/Help/prop_sf/VS_CSHARP_tagname.rst index d42159f..91c4a06 100644 --- a/Help/prop_sf/VS_CSHARP_tagname.rst +++ b/Help/prop_sf/VS_CSHARP_tagname.rst @@ -3,8 +3,9 @@ VS_CSHARP_<tagname> Visual Studio and CSharp source-file-specific configuration. -Tell the Visual Studio generator to set the source file tag -``<tagname>`` to a given value in the generated Visual Studio CSharp +Tell the :manual:`Visual Studio generators <cmake-generators(7)>` +to set the source file tag ``<tagname>`` +to a given value in the generated Visual Studio CSharp project. Ignored on other generators and languages. This property can be used to define dependencies between source files or set any other Visual Studio specific parameters. diff --git a/Help/prop_sf/VS_DEPLOYMENT_CONTENT.rst b/Help/prop_sf/VS_DEPLOYMENT_CONTENT.rst index 9fb3ba3..6a38478 100644 --- a/Help/prop_sf/VS_DEPLOYMENT_CONTENT.rst +++ b/Help/prop_sf/VS_DEPLOYMENT_CONTENT.rst @@ -2,7 +2,8 @@ VS_DEPLOYMENT_CONTENT --------------------- Mark a source file as content for deployment with a Windows Phone or -Windows Store application when built with a Visual Studio generator. +Windows Store application when built with a +:manual:`Visual Studio generators <cmake-generators(7)>`. The value must evaluate to either ``1`` or ``0`` and may use :manual:`generator expressions <cmake-generator-expressions(7)>` to make the choice based on the build configuration. diff --git a/Help/prop_sf/VS_DEPLOYMENT_LOCATION.rst b/Help/prop_sf/VS_DEPLOYMENT_LOCATION.rst index 303db95..2ce22fc 100644 --- a/Help/prop_sf/VS_DEPLOYMENT_LOCATION.rst +++ b/Help/prop_sf/VS_DEPLOYMENT_LOCATION.rst @@ -2,7 +2,8 @@ VS_DEPLOYMENT_LOCATION ---------------------- Specifies the deployment location for a content source file with a Windows -Phone or Windows Store application when built with a Visual Studio generator. +Phone or Windows Store application when built +with a :manual:`Visual Studio generators <cmake-generators(7)>`. This property is only applicable when using :prop_sf:`VS_DEPLOYMENT_CONTENT`. The value represent the path relative to the app package and applies to all configurations. diff --git a/Help/prop_sf/VS_INCLUDE_IN_VSIX.rst b/Help/prop_sf/VS_INCLUDE_IN_VSIX.rst index 30f471d..db470ef 100644 --- a/Help/prop_sf/VS_INCLUDE_IN_VSIX.rst +++ b/Help/prop_sf/VS_INCLUDE_IN_VSIX.rst @@ -1,6 +1,6 @@ VS_INCLUDE_IN_VSIX ------------------ -Boolean property to specify if the file should be included within a VSIX -extension package. This is needed for development of Visual Studio -extensions. +Boolean property to specify if the file should be included within a +VSIX (Visual Studio Integration Extension) extension package. +This is needed for development of Visual Studio extensions. diff --git a/Help/prop_sf/VS_SHADER_FLAGS.rst b/Help/prop_sf/VS_SHADER_FLAGS.rst index 0901123..0a53afd 100644 --- a/Help/prop_sf/VS_SHADER_FLAGS.rst +++ b/Help/prop_sf/VS_SHADER_FLAGS.rst @@ -1,4 +1,4 @@ VS_SHADER_FLAGS --------------- -Set additional VS shader flags of a ``.hlsl`` source file. +Set additional Visual Studio shader flags of a ``.hlsl`` source file. diff --git a/Help/prop_sf/VS_SHADER_TYPE.rst b/Help/prop_sf/VS_SHADER_TYPE.rst index 6880256..f104837 100644 --- a/Help/prop_sf/VS_SHADER_TYPE.rst +++ b/Help/prop_sf/VS_SHADER_TYPE.rst @@ -1,4 +1,4 @@ VS_SHADER_TYPE -------------- -Set the VS shader type of a ``.hlsl`` source file. +Set the Visual Studio shader type of a ``.hlsl`` source file. diff --git a/Help/prop_sf/VS_XAML_TYPE.rst b/Help/prop_sf/VS_XAML_TYPE.rst index e92191d..1a274ba 100644 --- a/Help/prop_sf/VS_XAML_TYPE.rst +++ b/Help/prop_sf/VS_XAML_TYPE.rst @@ -1,6 +1,7 @@ VS_XAML_TYPE ------------ -Mark a XAML source file as a different type than the default ``Page``. -The most common usage would be to set the default App.xaml file as -ApplicationDefinition. +Mark a Extensible Application Markup Language (XAML) source file +as a different type than the default ``Page``. +The most common usage would be to set the default ``App.xaml`` file as +``ApplicationDefinition``. diff --git a/Help/prop_sf/WRAP_EXCLUDE.rst b/Help/prop_sf/WRAP_EXCLUDE.rst index 2c79f72..638ff03 100644 --- a/Help/prop_sf/WRAP_EXCLUDE.rst +++ b/Help/prop_sf/WRAP_EXCLUDE.rst @@ -4,7 +4,8 @@ WRAP_EXCLUDE Exclude this source file from any code wrapping techniques. Some packages can wrap source files into alternate languages to -provide additional functionality. For example, C++ code can be -wrapped into Java or Python etc using SWIG etc. If WRAP_EXCLUDE is -set to true (1 etc) that indicates that this source file should not be -wrapped. +provide additional functionality. + +For example, C++ code can be wrapped into Java or Python, using SWIG. +If ``WRAP_EXCLUDE`` is set to ``True``, that indicates that this +source file should not be wrapped. diff --git a/Help/prop_sf/XCODE_EXPLICIT_FILE_TYPE.rst b/Help/prop_sf/XCODE_EXPLICIT_FILE_TYPE.rst index 1b24701..b8cf946 100644 --- a/Help/prop_sf/XCODE_EXPLICIT_FILE_TYPE.rst +++ b/Help/prop_sf/XCODE_EXPLICIT_FILE_TYPE.rst @@ -1,7 +1,7 @@ XCODE_EXPLICIT_FILE_TYPE ------------------------ -Set the Xcode ``explicitFileType`` attribute on its reference to a +Set the :generator:`Xcode` ``explicitFileType`` attribute on its reference to a source file. CMake computes a default based on file extension but can be told explicitly with this property. diff --git a/Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst b/Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst index 39e6966..4c93f44 100644 --- a/Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst +++ b/Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst @@ -1,9 +1,9 @@ XCODE_FILE_ATTRIBUTES --------------------- -Add values to the Xcode ``ATTRIBUTES`` setting on its reference to a +Add values to the :generator:`Xcode` ``ATTRIBUTES`` setting on its reference to a source file. Among other things, this can be used to set the role on -a mig file:: +a ``.mig`` file:: set_source_files_properties(defs.mig PROPERTIES diff --git a/Help/prop_sf/XCODE_LAST_KNOWN_FILE_TYPE.rst b/Help/prop_sf/XCODE_LAST_KNOWN_FILE_TYPE.rst index 42e3757..b21891f 100644 --- a/Help/prop_sf/XCODE_LAST_KNOWN_FILE_TYPE.rst +++ b/Help/prop_sf/XCODE_LAST_KNOWN_FILE_TYPE.rst @@ -1,8 +1,8 @@ XCODE_LAST_KNOWN_FILE_TYPE -------------------------- -Set the Xcode ``lastKnownFileType`` attribute on its reference to a -source file. CMake computes a default based on file extension but +Set the :generator:`Xcode` ``lastKnownFileType`` attribute on its reference to +a source file. CMake computes a default based on file extension but can be told explicitly with this property. See also :prop_sf:`XCODE_EXPLICIT_FILE_TYPE`, which is preferred diff --git a/Help/prop_test/COST.rst b/Help/prop_test/COST.rst index 3236a02..0c0fca7 100644 --- a/Help/prop_test/COST.rst +++ b/Help/prop_test/COST.rst @@ -1,7 +1,8 @@ COST ---- -Set this to a floating point value. Tests in a test set will be run in descending order of cost. +Set this to a floating point value. Tests in a test set will be run +in descending order of cost. This property describes the cost of a test. You can explicitly set -this value; tests with higher COST values will run first. +this value; tests with higher ``COST`` values will run first. diff --git a/Help/prop_test/DISABLED.rst b/Help/prop_test/DISABLED.rst index c18ae7f..1d469e8 100644 --- a/Help/prop_test/DISABLED.rst +++ b/Help/prop_test/DISABLED.rst @@ -1,15 +1,15 @@ DISABLED -------- -If set to true, the test will be skipped and its status will be 'Not Run'. A -DISABLED test will not be counted in the total number of tests and its -completion status will be reported to CDash as 'Disabled'. +If set to ``True``, the test will be skipped and its status will be 'Not Run'. A +``DISABLED`` test will not be counted in the total number of tests and its +completion status will be reported to CDash as ``Disabled``. -A DISABLED test does not participate in test fixture dependency resolution. -If a DISABLED test has fixture requirements defined in its +A ``DISABLED`` test does not participate in test fixture dependency resolution. +If a ``DISABLED`` test has fixture requirements defined in its :prop_test:`FIXTURES_REQUIRED` property, it will not cause setup or cleanup tests for those fixtures to be added to the test set. -If a test with the :prop_test:`FIXTURES_SETUP` property set is DISABLED, the -fixture behavior will be as though that setup test was passing and any test +If a test with the :prop_test:`FIXTURES_SETUP` property set is ``DISABLED``, +the fixture behavior will be as though that setup test was passing and any test case requiring that fixture will still run. diff --git a/Help/prop_test/ENVIRONMENT.rst b/Help/prop_test/ENVIRONMENT.rst index df9bc9e..102c792 100644 --- a/Help/prop_test/ENVIRONMENT.rst +++ b/Help/prop_test/ENVIRONMENT.rst @@ -4,6 +4,6 @@ ENVIRONMENT Specify environment variables that should be defined for running a test. If set to a list of environment variables and values of the form -MYVAR=value those environment variables will be defined while running +``MYVAR=value`` those environment variables will be defined while running the test. The environment is restored to its previous state after the test is done. diff --git a/Help/prop_test/MEASUREMENT.rst b/Help/prop_test/MEASUREMENT.rst index bc4936e..de459ed 100644 --- a/Help/prop_test/MEASUREMENT.rst +++ b/Help/prop_test/MEASUREMENT.rst @@ -1,8 +1,8 @@ MEASUREMENT ----------- -Specify a CDASH measurement and value to be reported for a test. +Specify a ``CDASH`` measurement and value to be reported for a test. -If set to a name then that name will be reported to CDASH as a named -measurement with a value of 1. You may also specify a value by -setting MEASUREMENT to "measurement=value". +If set to a name then that name will be reported to ``CDASH`` as a named +measurement with a value of ``1``. You may also specify a value by +setting ``MEASUREMENT`` to ``measurement=value``. diff --git a/Help/prop_test/RUN_SERIAL.rst b/Help/prop_test/RUN_SERIAL.rst index 8f65ae1..ab4c542 100644 --- a/Help/prop_test/RUN_SERIAL.rst +++ b/Help/prop_test/RUN_SERIAL.rst @@ -3,6 +3,6 @@ RUN_SERIAL Do not run this test in parallel with any other test. -Use this option in conjunction with the ctest_test PARALLEL_LEVEL +Use this option in conjunction with the ctest_test ``PARALLEL_LEVEL`` option to specify that this test should not be run in parallel with any other tests. diff --git a/Help/prop_test/SKIP_RETURN_CODE.rst b/Help/prop_test/SKIP_RETURN_CODE.rst index c61273c..a05fbf3 100644 --- a/Help/prop_test/SKIP_RETURN_CODE.rst +++ b/Help/prop_test/SKIP_RETURN_CODE.rst @@ -6,4 +6,4 @@ Return code to mark a test as skipped. Sometimes only a test itself can determine if all requirements for the test are met. If such a situation should not be considered a hard failure a return code of the process can be specified that will mark the test as -"Not Run" if it is encountered. +``Not Run`` if it is encountered. diff --git a/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst index 52ef013..f261756 100644 --- a/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -6,7 +6,7 @@ generated by the compiler while building source files. This is a per-configuration version of :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY`, -but multi-configuration generators (VS, Xcode) do NOT append a +but multi-configuration generators (Visual Studio, Xcode) do NOT append a per-configuration subdirectory to the specified directory. This property is initialized by the value of the :variable:`CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>` variable diff --git a/Help/prop_tgt/DEBUG_POSTFIX.rst b/Help/prop_tgt/DEBUG_POSTFIX.rst index 1487656..04e312e 100644 --- a/Help/prop_tgt/DEBUG_POSTFIX.rst +++ b/Help/prop_tgt/DEBUG_POSTFIX.rst @@ -1,7 +1,7 @@ DEBUG_POSTFIX ------------- -See target property <CONFIG>_POSTFIX. +See target property ``<CONFIG>_POSTFIX``. -This property is a special case of the more-general <CONFIG>_POSTFIX -property for the DEBUG configuration. +This property is a special case of the more-general ``<CONFIG>_POSTFIX`` +property for the ``DEBUG`` configuration. diff --git a/Help/prop_tgt/DEFINE_SYMBOL.rst b/Help/prop_tgt/DEFINE_SYMBOL.rst index f47f135..eb7f937 100644 --- a/Help/prop_tgt/DEFINE_SYMBOL.rst +++ b/Help/prop_tgt/DEFINE_SYMBOL.rst @@ -3,9 +3,9 @@ DEFINE_SYMBOL Define a symbol when compiling this target's sources. -DEFINE_SYMBOL sets the name of the preprocessor symbol defined when +``DEFINE_SYMBOL`` sets the name of the preprocessor symbol defined when compiling sources in a shared library. If not set here then it is set -to target_EXPORTS by default (with some substitutions if the target is +to ``target_EXPORTS`` by default (with some substitutions if the target is not a valid C identifier). This is useful for headers to know whether they are being included from inside their library or outside to properly setup dllexport/dllimport decorations. diff --git a/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION.rst b/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION.rst index a2f7d7d..c100326 100644 --- a/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION.rst +++ b/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION.rst @@ -4,7 +4,7 @@ DOTNET_TARGET_FRAMEWORK_VERSION Specify the .NET target framework version. Used to specify the .NET target framework version for C++/CLI. For -example, "v4.5". +example: ``v4.5``. This property is only evaluated for :ref:`Visual Studio Generators` VS 2010 and above. diff --git a/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD.rst b/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD.rst index a14e48c..664704b 100644 --- a/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD.rst +++ b/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD.rst @@ -1,8 +1,8 @@ EXCLUDE_FROM_DEFAULT_BUILD -------------------------- -Exclude target from "Build Solution". +Exclude target from ``Build Solution``. This property is only used by Visual Studio generators. -When set to TRUE, the target will not be built when you press "Build -Solution". +When set to ``TRUE``, the target will not be built when you press +``Build Solution``. diff --git a/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG.rst b/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG.rst index 655a9de..ad1021a 100644 --- a/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG.rst +++ b/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG.rst @@ -1,9 +1,10 @@ EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG> ----------------------------------- -Per-configuration version of target exclusion from "Build Solution". +Per-configuration version of target exclusion from ``Build Solution``. This is the configuration-specific version of -EXCLUDE_FROM_DEFAULT_BUILD. If the generic EXCLUDE_FROM_DEFAULT_BUILD -is also set on a target, EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG> takes +:prop_tgt:`EXCLUDE_FROM_DEFAULT_BUILD`. If the generic +:prop_tgt:`EXCLUDE_FROM_DEFAULT_BUILD` is also set on a target, +``EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>`` takes precedence in configurations for which it has a value. diff --git a/Help/prop_tgt/EXPORT_NAME.rst b/Help/prop_tgt/EXPORT_NAME.rst index 043c57a..0e021d0 100644 --- a/Help/prop_tgt/EXPORT_NAME.rst +++ b/Help/prop_tgt/EXPORT_NAME.rst @@ -3,6 +3,6 @@ EXPORT_NAME Exported name for target files. -This sets the name for the IMPORTED target generated by the +This sets the name for the ``IMPORTED`` target generated by the :command:`install(EXPORT)` and :command:`export` commands. If not set, the logical target name is used by default. diff --git a/Help/prop_tgt/EchoString.rst b/Help/prop_tgt/EchoString.rst index 32ae2aa..352d062 100644 --- a/Help/prop_tgt/EchoString.rst +++ b/Help/prop_tgt/EchoString.rst @@ -3,5 +3,5 @@ EchoString A message to be displayed when the target is built. -A message to display on some generators (such as makefiles) when the -target is built. +A message to display on some generators (such as :ref:`Makefile Generators`) +when the target is built. diff --git a/Help/prop_tgt/FOLDER.rst b/Help/prop_tgt/FOLDER.rst index 0121125..f6be9e6 100644 --- a/Help/prop_tgt/FOLDER.rst +++ b/Help/prop_tgt/FOLDER.rst @@ -3,10 +3,10 @@ FOLDER Set the folder name. Use to organize targets in an IDE. -Targets with no FOLDER property will appear as top level entities in -IDEs like Visual Studio. Targets with the same FOLDER property value +Targets with no ``FOLDER`` property will appear as top level entities in +IDEs like Visual Studio. Targets with the same ``FOLDER`` property value will appear next to each other in a folder of that name. To nest -folders, use FOLDER values such as 'GUI/Dialogs' with '/' characters +folders, use ``FOLDER`` values such as 'GUI/Dialogs' with '/' characters separating folder levels. This property is initialized by the value of the variable diff --git a/Help/prop_tgt/Fortran_FORMAT.rst b/Help/prop_tgt/Fortran_FORMAT.rst index 0a11d91..8704e5f 100644 --- a/Help/prop_tgt/Fortran_FORMAT.rst +++ b/Help/prop_tgt/Fortran_FORMAT.rst @@ -1,11 +1,11 @@ Fortran_FORMAT -------------- -Set to FIXED or FREE to indicate the Fortran source layout. +Set to ``FIXED`` or ``FREE`` to indicate the Fortran source layout. This property tells CMake whether the Fortran source files in a target use fixed-format or free-format. CMake will pass the corresponding -format flag to the compiler. Use the source-specific Fortran_FORMAT +format flag to the compiler. Use the source-specific ``Fortran_FORMAT`` property to change the format of a specific source file. If the -variable CMAKE_Fortran_FORMAT is set when a target is created its +variable :variable:`CMAKE_Fortran_FORMAT` is set when a target is created its value is used to initialize this property. diff --git a/Help/prop_tgt/Fortran_MODULE_DIRECTORY.rst b/Help/prop_tgt/Fortran_MODULE_DIRECTORY.rst index 9c86437..e061863 100644 --- a/Help/prop_tgt/Fortran_MODULE_DIRECTORY.rst +++ b/Help/prop_tgt/Fortran_MODULE_DIRECTORY.rst @@ -8,10 +8,10 @@ the compiler supports a module output directory this specifies the directory in which the modules will be placed. When this property is not set the modules will be placed in the build directory corresponding to the target's source directory. If the variable -CMAKE_Fortran_MODULE_DIRECTORY is set when a target is created its +:variable:`CMAKE_Fortran_MODULE_DIRECTORY` is set when a target is created its value is used to initialize this property. Note that some compilers will automatically search the module output directory for modules USEd during compilation but others will not. If your sources USE modules their location must be specified by -INCLUDE_DIRECTORIES regardless of this property. +:prop_tgt:`INCLUDE_DIRECTORIES` regardless of this property. diff --git a/Help/prop_tgt/GENERATOR_FILE_NAME.rst b/Help/prop_tgt/GENERATOR_FILE_NAME.rst index 032b22a..a486105 100644 --- a/Help/prop_tgt/GENERATOR_FILE_NAME.rst +++ b/Help/prop_tgt/GENERATOR_FILE_NAME.rst @@ -6,4 +6,4 @@ Generator's file for this target. An internal property used by some generators to record the name of the project or dsp file associated with this target. Note that at configure time, this property is only set for targets created by -include_external_msproject(). +:command:`include_external_msproject`. diff --git a/Help/prop_tgt/GHS_INTEGRITY_APP.rst b/Help/prop_tgt/GHS_INTEGRITY_APP.rst index 7643038..b669781 100644 --- a/Help/prop_tgt/GHS_INTEGRITY_APP.rst +++ b/Help/prop_tgt/GHS_INTEGRITY_APP.rst @@ -4,7 +4,7 @@ GHS_INTEGRITY_APP ``ON`` / ``OFF`` boolean to determine if an executable target should be treated as an `Integrity Application`. -If no value is set and if a `.int` file is added as a source file to the +If no value is set and if a ``.int`` file is added as a source file to the executable target it will be treated as an `Integrity Application`. Supported on :generator:`Green Hills MULTI`. diff --git a/Help/prop_tgt/GNUtoMS.rst b/Help/prop_tgt/GNUtoMS.rst index cf34da9..a09ebbf 100644 --- a/Help/prop_tgt/GNUtoMS.rst +++ b/Help/prop_tgt/GNUtoMS.rst @@ -1,17 +1,17 @@ GNUtoMS ------- -Convert GNU import library (.dll.a) to MS format (.lib). +Convert GNU import library (``.dll.a``) to MS format (``.lib``). When linking a shared library or executable that exports symbols using GNU tools on Windows (MinGW/MSYS) with Visual Studio installed convert -the import library (.dll.a) from GNU to MS format (.lib). Both import -libraries will be installed by install(TARGETS) and exported by -install(EXPORT) and export() to be linked by applications with either -GNU- or MS-compatible tools. +the import library (``.dll.a``) from GNU to MS format (``.lib``). Both import +libraries will be installed by :command:`install(TARGETS)` and exported by +:command:`install(EXPORT)` and :command:`export` to be linked +by applications with either GNU- or MS-compatible tools. -If the variable CMAKE_GNUtoMS is set when a target is created its +If the variable ``CMAKE_GNUtoMS`` is set when a target is created its value is used to initialize this property. The variable must be set -prior to the first command that enables a language such as project() -or enable_language(). CMake provides the variable as an option to the +prior to the first command that enables a language such as :command:`project` +or :command:`enable_language`. CMake provides the variable as an option to the user automatically when configuring on Windows with GNU tools. diff --git a/Help/prop_tgt/HAS_CXX.rst b/Help/prop_tgt/HAS_CXX.rst index 7790932..15199b1 100644 --- a/Help/prop_tgt/HAS_CXX.rst +++ b/Help/prop_tgt/HAS_CXX.rst @@ -3,5 +3,5 @@ HAS_CXX Link the target using the C++ linker tool (obsolete). -This is equivalent to setting the LINKER_LANGUAGE property to CXX. -See that property's documentation for details. +This is equivalent to setting the :prop_tgt:`LINKER_LANGUAGE` +property to ``CXX``. diff --git a/Help/prop_tgt/IMPORTED.rst b/Help/prop_tgt/IMPORTED.rst index 605c1ce..22d28aa 100644 --- a/Help/prop_tgt/IMPORTED.rst +++ b/Help/prop_tgt/IMPORTED.rst @@ -1,8 +1,8 @@ IMPORTED -------- -Read-only indication of whether a target is IMPORTED. +Read-only indication of whether a target is ``IMPORTED``. The boolean value of this property is ``True`` for targets created with -the IMPORTED option to :command:`add_executable` or :command:`add_library`. +the ``IMPORTED`` option to :command:`add_executable` or :command:`add_library`. It is ``False`` for targets built within the project. diff --git a/Help/prop_tgt/IMPORTED_IMPLIB.rst b/Help/prop_tgt/IMPORTED_IMPLIB.rst index acf4b32..77fb552 100644 --- a/Help/prop_tgt/IMPORTED_IMPLIB.rst +++ b/Help/prop_tgt/IMPORTED_IMPLIB.rst @@ -1,7 +1,7 @@ IMPORTED_IMPLIB --------------- -Full path to the import library for an IMPORTED target. +Full path to the import library for an ``IMPORTED`` target. -Set this to the location of the ".lib" part of a windows DLL. Ignored +Set this to the location of the ``.lib`` part of a Windows DLL. Ignored for non-imported targets. diff --git a/Help/prop_tgt/IMPORTED_IMPLIB_CONFIG.rst b/Help/prop_tgt/IMPORTED_IMPLIB_CONFIG.rst index b4b3f02..5debabc 100644 --- a/Help/prop_tgt/IMPORTED_IMPLIB_CONFIG.rst +++ b/Help/prop_tgt/IMPORTED_IMPLIB_CONFIG.rst @@ -1,7 +1,7 @@ IMPORTED_IMPLIB_<CONFIG> ------------------------ -<CONFIG>-specific version of IMPORTED_IMPLIB property. +<CONFIG>-specific version of :prop_tgt:`IMPORTED_IMPLIB` property. Configuration names correspond to those provided by the project from which the target is imported. diff --git a/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES.rst b/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES.rst index 2db2b0e..f7e2165 100644 --- a/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES.rst +++ b/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES.rst @@ -8,7 +8,7 @@ their implementation. On some platforms the linker searches for the dependent libraries of shared libraries they are including in the link. Set this property to the list of dependent shared libraries of an imported library. The list should be disjoint from the list of -interface libraries in the INTERFACE_LINK_LIBRARIES property. On +interface libraries in the :prop_tgt:`INTERFACE_LINK_LIBRARIES` property. On platforms requiring dependent shared libraries to be found at link time CMake uses this list to add appropriate files or paths to the link command line. Ignored for non-imported targets. diff --git a/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG.rst b/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG.rst index ee243c7..5b9c513 100644 --- a/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG.rst +++ b/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG.rst @@ -1,7 +1,7 @@ IMPORTED_LINK_DEPENDENT_LIBRARIES_<CONFIG> ------------------------------------------ -<CONFIG>-specific version of IMPORTED_LINK_DEPENDENT_LIBRARIES. +<CONFIG>-specific version of :prop_tgt:`IMPORTED_LINK_DEPENDENT_LIBRARIES`. Configuration names correspond to those provided by the project from which the target is imported. If set, this property completely diff --git a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES.rst b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES.rst index 5ca9c8b..4ed4281 100644 --- a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES.rst +++ b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES.rst @@ -1,14 +1,14 @@ IMPORTED_LINK_INTERFACE_LANGUAGES --------------------------------- -Languages compiled into an IMPORTED static library. +Languages compiled into an ``IMPORTED`` static library. Set this to the list of languages of source files compiled to produce -a STATIC IMPORTED library (such as "C" or "CXX"). CMake accounts for +a ``STATIC IMPORTED`` library (such as ``C`` or ``CXX``). CMake accounts for these languages when computing how to link a target to the imported library. For example, when a C executable links to an imported C++ static library CMake chooses the C++ linker to satisfy language runtime dependencies of the static library. -This property is ignored for targets that are not STATIC libraries. +This property is ignored for targets that are not ``STATIC`` libraries. This property is ignored for non-imported targets. diff --git a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES_CONFIG.rst b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES_CONFIG.rst index d4a10fb..40fcf7f 100644 --- a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES_CONFIG.rst +++ b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES_CONFIG.rst @@ -1,7 +1,7 @@ IMPORTED_LINK_INTERFACE_LANGUAGES_<CONFIG> ------------------------------------------ -<CONFIG>-specific version of IMPORTED_LINK_INTERFACE_LANGUAGES. +<CONFIG>-specific version of :prop_tgt:`IMPORTED_LINK_INTERFACE_LANGUAGES`. Configuration names correspond to those provided by the project from which the target is imported. If set, this property completely diff --git a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES.rst b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES.rst index 61134a4..527cf2e 100644 --- a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES.rst +++ b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES.rst @@ -1,16 +1,16 @@ IMPORTED_LINK_INTERFACE_LIBRARIES --------------------------------- -Transitive link interface of an IMPORTED target. +Transitive link interface of an ``IMPORTED`` target. Set this to the list of libraries whose interface is included when an -IMPORTED library target is linked to another target. The libraries +``IMPORTED`` library target is linked to another target. The libraries will be included on the link line for the target. Unlike the -LINK_INTERFACE_LIBRARIES property, this property applies to all -imported target types, including STATIC libraries. This property is +:prop_tgt:`LINK_INTERFACE_LIBRARIES` property, this property applies to all +imported target types, including ``STATIC`` libraries. This property is ignored for non-imported targets. This property is ignored if the target also has a non-empty -INTERFACE_LINK_LIBRARIES property. +:prop_tgt:`INTERFACE_LINK_LIBRARIES` property. -This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead. +This property is deprecated. Use :prop_tgt:`INTERFACE_LINK_LIBRARIES` instead. diff --git a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES_CONFIG.rst b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES_CONFIG.rst index 13b93ba..050fb1d 100644 --- a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES_CONFIG.rst +++ b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES_CONFIG.rst @@ -1,13 +1,13 @@ IMPORTED_LINK_INTERFACE_LIBRARIES_<CONFIG> ------------------------------------------ -<CONFIG>-specific version of IMPORTED_LINK_INTERFACE_LIBRARIES. +<CONFIG>-specific version of :prop_tgt:`IMPORTED_LINK_INTERFACE_LIBRARIES`. Configuration names correspond to those provided by the project from which the target is imported. If set, this property completely overrides the generic property for the named configuration. This property is ignored if the target also has a non-empty -INTERFACE_LINK_LIBRARIES property. +:prop_tgt:`INTERFACE_LINK_LIBRARIES` property. -This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead. +This property is deprecated. Use :prop_tgt:`INTERFACE_LINK_LIBRARIES` instead. diff --git a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY.rst b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY.rst index 3a86b99..7a92d96 100644 --- a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY.rst +++ b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY.rst @@ -1,6 +1,6 @@ IMPORTED_LINK_INTERFACE_MULTIPLICITY ------------------------------------ -Repetition count for cycles of IMPORTED static libraries. +Repetition count for cycles of ``IMPORTED`` static libraries. -This is LINK_INTERFACE_MULTIPLICITY for IMPORTED targets. +This is :prop_tgt:`LINK_INTERFACE_MULTIPLICITY` for ``IMPORTED`` targets. diff --git a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY_CONFIG.rst b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY_CONFIG.rst index 33b9b84..758237b 100644 --- a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY_CONFIG.rst +++ b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY_CONFIG.rst @@ -1,7 +1,7 @@ IMPORTED_LINK_INTERFACE_MULTIPLICITY_<CONFIG> --------------------------------------------- -<CONFIG>-specific version of IMPORTED_LINK_INTERFACE_MULTIPLICITY. +<CONFIG>-specific version of :prop_tgt:`IMPORTED_LINK_INTERFACE_MULTIPLICITY`. If set, this property completely overrides the generic property for the named configuration. diff --git a/Help/prop_tgt/IMPORTED_LOCATION.rst b/Help/prop_tgt/IMPORTED_LOCATION.rst index 2d07aad..d674f29 100644 --- a/Help/prop_tgt/IMPORTED_LOCATION.rst +++ b/Help/prop_tgt/IMPORTED_LOCATION.rst @@ -1,21 +1,21 @@ IMPORTED_LOCATION ----------------- -Full path to the main file on disk for an IMPORTED target. +Full path to the main file on disk for an ``IMPORTED`` target. -Set this to the location of an IMPORTED target file on disk. For +Set this to the location of an ``IMPORTED`` target file on disk. For executables this is the location of the executable file. For bundles on macOS this is the location of the executable file inside -Contents/MacOS under the application bundle folder. For static +``Contents/MacOS`` under the application bundle folder. For ``STATIC`` libraries and modules this is the location of the library or module. -For shared libraries on non-DLL platforms this is the location of the +For ``SHARED`` libraries on non-DLL platforms this is the location of the shared library. For frameworks on macOS this is the location of the library file symlink just inside the framework folder. For DLLs this -is the location of the ".dll" part of the library. For UNKNOWN +is the location of the ``.dll`` part of the library. For ``UNKNOWN`` libraries this is the location of the file to be linked. Ignored for non-imported targets. -Projects may skip IMPORTED_LOCATION if the configuration-specific -property IMPORTED_LOCATION_<CONFIG> is set. To get the location of an -imported target read one of the LOCATION or LOCATION_<CONFIG> -properties. +Projects may skip ``IMPORTED_LOCATION`` if the configuration-specific +property :prop_tgt:`IMPORTED_LOCATION_<CONFIG>` is set. To get the location +of an imported target read one of the :prop_tgt:`LOCATION` or +``LOCATION_<CONFIG>`` properties. diff --git a/Help/prop_tgt/IMPORTED_LOCATION_CONFIG.rst b/Help/prop_tgt/IMPORTED_LOCATION_CONFIG.rst index f85bb19..c5f5f04 100644 --- a/Help/prop_tgt/IMPORTED_LOCATION_CONFIG.rst +++ b/Help/prop_tgt/IMPORTED_LOCATION_CONFIG.rst @@ -1,7 +1,7 @@ IMPORTED_LOCATION_<CONFIG> -------------------------- -<CONFIG>-specific version of IMPORTED_LOCATION property. +<CONFIG>-specific version of :prop_tgt:`IMPORTED_LOCATION` property. Configuration names correspond to those provided by the project from which the target is imported. diff --git a/Help/prop_tgt/IMPORTED_NO_SONAME.rst b/Help/prop_tgt/IMPORTED_NO_SONAME.rst index 4a1bb44..cbb7642 100644 --- a/Help/prop_tgt/IMPORTED_NO_SONAME.rst +++ b/Help/prop_tgt/IMPORTED_NO_SONAME.rst @@ -1,9 +1,9 @@ IMPORTED_NO_SONAME ------------------ -Specifies that an IMPORTED shared library target has no "soname". +Specifies that an ``IMPORTED`` shared library target has no ``soname``. Set this property to true for an imported shared library file that has -no "soname" field. CMake may adjust generated link commands for some +no ``soname`` field. CMake may adjust generated link commands for some platforms to prevent the linker from using the path to the library in -place of its missing soname. Ignored for non-imported targets. +place of its missing ``soname``. Ignored for non-imported targets. diff --git a/Help/prop_tgt/IMPORTED_NO_SONAME_CONFIG.rst b/Help/prop_tgt/IMPORTED_NO_SONAME_CONFIG.rst index 22d6822..76fe471 100644 --- a/Help/prop_tgt/IMPORTED_NO_SONAME_CONFIG.rst +++ b/Help/prop_tgt/IMPORTED_NO_SONAME_CONFIG.rst @@ -1,7 +1,7 @@ IMPORTED_NO_SONAME_<CONFIG> --------------------------- -<CONFIG>-specific version of IMPORTED_NO_SONAME property. +<CONFIG>-specific version of :prop_tgt:`IMPORTED_NO_SONAME` property. Configuration names correspond to those provided by the project from which the target is imported. diff --git a/Help/prop_tgt/IMPORTED_SONAME.rst b/Help/prop_tgt/IMPORTED_SONAME.rst index d80907e..bf0c3cb 100644 --- a/Help/prop_tgt/IMPORTED_SONAME.rst +++ b/Help/prop_tgt/IMPORTED_SONAME.rst @@ -1,8 +1,8 @@ IMPORTED_SONAME --------------- -The "soname" of an IMPORTED target of shared library type. +The ``soname`` of an ``IMPORTED`` target of shared library type. -Set this to the "soname" embedded in an imported shared library. This +Set this to the ``soname`` embedded in an imported shared library. This is meaningful only on platforms supporting the feature. Ignored for non-imported targets. diff --git a/Help/prop_tgt/IMPORTED_SONAME_CONFIG.rst b/Help/prop_tgt/IMPORTED_SONAME_CONFIG.rst index 6ec9af3..59a9d1a 100644 --- a/Help/prop_tgt/IMPORTED_SONAME_CONFIG.rst +++ b/Help/prop_tgt/IMPORTED_SONAME_CONFIG.rst @@ -1,7 +1,7 @@ IMPORTED_SONAME_<CONFIG> ------------------------ -<CONFIG>-specific version of IMPORTED_SONAME property. +<CONFIG>-specific version of :prop_tgt:`IMPORTED_SONAME` property. Configuration names correspond to those provided by the project from which the target is imported. diff --git a/Help/prop_tgt/IMPORT_PREFIX.rst b/Help/prop_tgt/IMPORT_PREFIX.rst index deede97..17e381b 100644 --- a/Help/prop_tgt/IMPORT_PREFIX.rst +++ b/Help/prop_tgt/IMPORT_PREFIX.rst @@ -3,7 +3,7 @@ IMPORT_PREFIX What comes before the import library name. -Similar to the target property PREFIX, but used for import libraries -(typically corresponding to a DLL) instead of regular libraries. A -target property that can be set to override the prefix (such as "lib") +Similar to the target property :prop_tgt:`PREFIX`, but used for import libraries +(typically corresponding to a ``DLL``) instead of regular libraries. A +target property that can be set to override the prefix (such as ``lib``) on an import library name. diff --git a/Help/prop_tgt/IMPORT_SUFFIX.rst b/Help/prop_tgt/IMPORT_SUFFIX.rst index bd01250..9307115 100644 --- a/Help/prop_tgt/IMPORT_SUFFIX.rst +++ b/Help/prop_tgt/IMPORT_SUFFIX.rst @@ -3,7 +3,7 @@ IMPORT_SUFFIX What comes after the import library name. -Similar to the target property SUFFIX, but used for import libraries -(typically corresponding to a DLL) instead of regular libraries. A -target property that can be set to override the suffix (such as -".lib") on an import library name. +Similar to the target property :prop_tgt:`SUFFIX`, but used +for import libraries (typically corresponding to a ``DLL``) instead of +regular libraries. A target property that can be set to override +the suffix (such as ``.lib``) on an import library name. diff --git a/Help/prop_tgt/INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INCLUDE_DIRECTORIES.rst index 8b40d9c..b381d1d 100644 --- a/Help/prop_tgt/INCLUDE_DIRECTORIES.rst +++ b/Help/prop_tgt/INCLUDE_DIRECTORIES.rst @@ -18,7 +18,7 @@ paths for the compiler. Relative paths should not be added to this property directly. Use one of the commands above instead to handle relative paths. -Contents of ``INCLUDE_DIRECTORIES`` may use "generator expressions" with +Contents of ``INCLUDE_DIRECTORIES`` may use :manual:`cmake-generator-expressions(7)` with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. diff --git a/Help/prop_tgt/INSTALL_NAME_DIR.rst b/Help/prop_tgt/INSTALL_NAME_DIR.rst index 34348bb..2216072 100644 --- a/Help/prop_tgt/INSTALL_NAME_DIR.rst +++ b/Help/prop_tgt/INSTALL_NAME_DIR.rst @@ -1,10 +1,10 @@ INSTALL_NAME_DIR ---------------- -Mac OSX directory name for installed targets. +macOS directory name for installed targets. -INSTALL_NAME_DIR is a string specifying the directory portion of the -"install_name" field of shared libraries on Mac OSX to use in the +``INSTALL_NAME_DIR`` is a string specifying the directory portion of the +"install_name" field of shared libraries on macOS to use in the installed targets. This property is initialized by the value of the variable diff --git a/Help/prop_tgt/INSTALL_RPATH.rst b/Help/prop_tgt/INSTALL_RPATH.rst index 6206b68..6403f4c 100644 --- a/Help/prop_tgt/INSTALL_RPATH.rst +++ b/Help/prop_tgt/INSTALL_RPATH.rst @@ -5,5 +5,5 @@ The rpath to use for installed targets. A semicolon-separated list specifying the rpath to use in installed targets (for platforms that support it). This property is initialized -by the value of the variable CMAKE_INSTALL_RPATH if it is set when a -target is created. +by the value of the variable :variable:`CMAKE_INSTALL_RPATH` if it is set when +a target is created. diff --git a/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst b/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst index f0006f8..d8be954 100644 --- a/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst +++ b/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst @@ -3,8 +3,8 @@ INSTALL_RPATH_USE_LINK_PATH Add paths to linker search and installed rpath. -INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to true will +``INSTALL_RPATH_USE_LINK_PATH`` is a boolean that if set to ``True`` will append directories in the linker search path and outside the project -to the INSTALL_RPATH. This property is initialized by the value of -the variable CMAKE_INSTALL_RPATH_USE_LINK_PATH if it is set when a +to the :prop_tgt:`INSTALL_RPATH`. This property is initialized by the value of +the variable ``CMAKE_INSTALL_RPATH_USE_LINK_PATH`` if it is set when a target is created. diff --git a/Help/prop_tgt/INTERFACE_LINK_DEPENDS.rst b/Help/prop_tgt/INTERFACE_LINK_DEPENDS.rst index d07f8ea..790554d 100644 --- a/Help/prop_tgt/INTERFACE_LINK_DEPENDS.rst +++ b/Help/prop_tgt/INTERFACE_LINK_DEPENDS.rst @@ -3,9 +3,10 @@ INTERFACE_LINK_DEPENDS Additional public interface files on which a target binary depends for linking. -This property is supported only by Makefile and Ninja generators. It is -intended to specify dependencies on "linker scripts" for custom Makefile link -rules. +This property is supported only by :generator:`Ninja` and +:ref:`Makefile Generators`. +It is intended to specify dependencies on "linker scripts" for +custom Makefile link rules. When target dependencies are specified using :command:`target_link_libraries`, CMake will read this property from all target dependencies to determine the diff --git a/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst index 782b0f0..79d4604 100644 --- a/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst +++ b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst @@ -3,7 +3,7 @@ INTERPROCEDURAL_OPTIMIZATION_<CONFIG> Per-configuration interprocedural optimization for a target. -This is a per-configuration version of INTERPROCEDURAL_OPTIMIZATION. +This is a per-configuration version of :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION`. If set, this property overrides the generic property for the named configuration. diff --git a/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst index 28dd404..5cefc38 100644 --- a/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst @@ -6,7 +6,8 @@ Per-configuration output directory for This is a per-configuration version of the :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` target property, but -multi-configuration generators (VS, Xcode) do NOT append a +multi-configuration generators (:ref:`Visual Studio Generators`, +:generator:`Xcode`) do NOT append a per-configuration subdirectory to the specified directory. This property is initialized by the value of the :variable:`CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG>` variable if diff --git a/Help/prop_tgt/LINKER_LANGUAGE.rst b/Help/prop_tgt/LINKER_LANGUAGE.rst index b1ca867..b0a572b 100644 --- a/Help/prop_tgt/LINKER_LANGUAGE.rst +++ b/Help/prop_tgt/LINKER_LANGUAGE.rst @@ -8,7 +8,7 @@ whose compiler is used to link the target (such as "C" or "CXX"). A typical value for an executable is the language of the source file providing the program entry point (main). If not set, the language with the highest linker preference value is the default. See -documentation of CMAKE_<LANG>_LINKER_PREFERENCE variables. +documentation of :variable:`CMAKE_<LANG>_LINKER_PREFERENCE` variables. If this property is not set by the user, it will be calculated at generate-time by CMake. diff --git a/Help/prop_tgt/LINK_DEPENDS.rst b/Help/prop_tgt/LINK_DEPENDS.rst index 3ab8658..e59d4c0 100644 --- a/Help/prop_tgt/LINK_DEPENDS.rst +++ b/Help/prop_tgt/LINK_DEPENDS.rst @@ -7,7 +7,8 @@ Specifies a semicolon-separated list of full-paths to files on which the link rule for this target depends. The target binary will be linked if any of the named files is newer than it. -This property is supported only by Makefile and Ninja generators. It is +This property is supported only by :generator:`Ninja` and +:ref:`Makefile Generators`. It is intended to specify dependencies on "linker scripts" for custom Makefile link rules. diff --git a/Help/prop_tgt/LINK_FLAGS_CONFIG.rst b/Help/prop_tgt/LINK_FLAGS_CONFIG.rst index e3918ca..68c3129 100644 --- a/Help/prop_tgt/LINK_FLAGS_CONFIG.rst +++ b/Help/prop_tgt/LINK_FLAGS_CONFIG.rst @@ -1,8 +1,8 @@ LINK_FLAGS_<CONFIG> ------------------- -Per-configuration linker flags for a shared library, module or executable -target. +Per-configuration linker flags for a ``SHARED`` library, ``MODULE`` or +``EXECUTABLE`` target. This is the configuration-specific version of :prop_tgt:`LINK_FLAGS`. diff --git a/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY.rst b/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY.rst index 4e26388..b798af9 100644 --- a/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY.rst +++ b/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY.rst @@ -1,9 +1,9 @@ LINK_INTERFACE_MULTIPLICITY --------------------------- -Repetition count for STATIC libraries with cyclic dependencies. +Repetition count for ``STATIC`` libraries with cyclic dependencies. -When linking to a STATIC library target with cyclic dependencies the +When linking to a ``STATIC`` library target with cyclic dependencies the linker may need to scan more than once through the archives in the strongly connected component of the dependency graph. CMake by default constructs the link line so that the linker will scan through diff --git a/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG.rst b/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG.rst index 5ea4a45..7c9461f 100644 --- a/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG.rst +++ b/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG.rst @@ -1,8 +1,8 @@ LINK_INTERFACE_MULTIPLICITY_<CONFIG> ------------------------------------ -Per-configuration repetition count for cycles of STATIC libraries. +Per-configuration repetition count for cycles of ``STATIC`` libraries. This is the configuration-specific version of -LINK_INTERFACE_MULTIPLICITY. If set, this property completely +:prop_tgt:`LINK_INTERFACE_MULTIPLICITY`. If set, this property completely overrides the generic property for the named configuration. diff --git a/Help/prop_tgt/LINK_SEARCH_END_STATIC.rst b/Help/prop_tgt/LINK_SEARCH_END_STATIC.rst index cf9c871..fecbb14 100644 --- a/Help/prop_tgt/LINK_SEARCH_END_STATIC.rst +++ b/Help/prop_tgt/LINK_SEARCH_END_STATIC.rst @@ -3,16 +3,17 @@ LINK_SEARCH_END_STATIC End a link line such that static system libraries are used. -Some linkers support switches such as -Bstatic and -Bdynamic to -determine whether to use static or shared libraries for -lXXX options. +Some linkers support switches such as ``-Bstatic`` and ``-Bdynamic`` to +determine whether to use static or shared libraries for ``-lXXX`` options. CMake uses these options to set the link type for libraries whose full paths are not known or (in some cases) are in implicit link directories for the platform. By default CMake adds an option at the end of the library list (if necessary) to set the linker search type back to its starting type. This property switches the final linker -search type to -Bstatic regardless of how it started. +search type to ``-Bstatic`` regardless of how it started. This property is initialized by the value of the variable -CMAKE_LINK_SEARCH_END_STATIC if it is set when a target is created. +:variable:`CMAKE_LINK_SEARCH_END_STATIC` if it is set +when a target is created. -See also LINK_SEARCH_START_STATIC. +See also :prop_tgt:`LINK_SEARCH_START_STATIC`. diff --git a/Help/prop_tgt/LINK_SEARCH_START_STATIC.rst b/Help/prop_tgt/LINK_SEARCH_START_STATIC.rst index 2e0f9bd..83cf231 100644 --- a/Help/prop_tgt/LINK_SEARCH_START_STATIC.rst +++ b/Help/prop_tgt/LINK_SEARCH_START_STATIC.rst @@ -3,17 +3,18 @@ LINK_SEARCH_START_STATIC Assume the linker looks for static libraries by default. -Some linkers support switches such as -Bstatic and -Bdynamic to -determine whether to use static or shared libraries for -lXXX options. +Some linkers support switches such as ``-Bstatic`` and ``-Bdynamic`` to +determine whether to use static or shared libraries for ``-lXXX`` options. CMake uses these options to set the link type for libraries whose full paths are not known or (in some cases) are in implicit link directories for the platform. By default the linker search type is -assumed to be -Bdynamic at the beginning of the library list. This -property switches the assumption to -Bstatic. It is intended for use -when linking an executable statically (e.g. with the GNU -static +assumed to be ``-Bdynamic`` at the beginning of the library list. This +property switches the assumption to ``-Bstatic``. It is intended for use +when linking an executable statically (e.g. with the GNU ``-static`` option). This property is initialized by the value of the variable -CMAKE_LINK_SEARCH_START_STATIC if it is set when a target is created. + :variable:`CMAKE_LINK_SEARCH_START_STATIC` if it is set + when a target is created. -See also LINK_SEARCH_END_STATIC. +See also :prop_tgt:`LINK_SEARCH_END_STATIC`. diff --git a/Help/prop_tgt/LOCATION.rst b/Help/prop_tgt/LOCATION.rst index 16d5696..d058064 100644 --- a/Help/prop_tgt/LOCATION.rst +++ b/Help/prop_tgt/LOCATION.rst @@ -4,24 +4,25 @@ LOCATION Read-only location of a target on disk. For an imported target, this read-only property returns the value of -the LOCATION_<CONFIG> property for an unspecified configuration -<CONFIG> provided by the target. +the ``LOCATION_<CONFIG>`` property for an unspecified configuration +``<CONFIG>`` provided by the target. For a non-imported target, this property is provided for compatibility with CMake 2.4 and below. It was meant to get the location of an -executable target's output file for use in add_custom_command. The +executable target's output file for use in :command:`add_custom_command`. The path may contain a build-system-specific portion that is replaced at build time with the configuration getting built (such as -"$(ConfigurationName)" in VS). In CMake 2.6 and above -add_custom_command automatically recognizes a target name in its -COMMAND and DEPENDS options and computes the target location. In -CMake 2.8.4 and above add_custom_command recognizes generator -expressions to refer to target locations anywhere in the command. +``$(ConfigurationName)`` in VS). In CMake 2.6 and above +:command:`add_custom_command` automatically recognizes a target name in its +``COMMAND`` and ``DEPENDS`` options and computes the target location. In +CMake 2.8.4 and above :command:`add_custom_command` recognizes +:manual:`generator expressions <cmake-generator-expressions(7)>` +to refer to target locations anywhere in the command. Therefore this property is not needed for creating custom commands. Do not set properties that affect the location of a target after reading this property. These include properties whose names match -"(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?", +``(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?``, ``(IMPLIB_)?(PREFIX|SUFFIX)``, or "LINKER_LANGUAGE". Failure to follow this rule is not diagnosed and leaves the location of the target undefined. diff --git a/Help/prop_tgt/LOCATION_CONFIG.rst b/Help/prop_tgt/LOCATION_CONFIG.rst index ac6bdb7..67de8ed 100644 --- a/Help/prop_tgt/LOCATION_CONFIG.rst +++ b/Help/prop_tgt/LOCATION_CONFIG.rst @@ -4,17 +4,17 @@ LOCATION_<CONFIG> Read-only property providing a target location on disk. A read-only property that indicates where a target's main file is -located on disk for the configuration <CONFIG>. The property is +located on disk for the configuration ``<CONFIG>``. The property is defined only for library and executable targets. An imported target may provide a set of configurations different from that of the importing project. By default CMake looks for an exact-match but otherwise uses an arbitrary available configuration. Use the -MAP_IMPORTED_CONFIG_<CONFIG> property to map imported configurations -explicitly. +:prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` property to map imported +configurations explicitly. Do not set properties that affect the location of a target after reading this property. These include properties whose names match -"(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?", -``(IMPLIB_)?(PREFIX|SUFFIX)``, or "LINKER_LANGUAGE". Failure to follow -this rule is not diagnosed and leaves the location of the target -undefined. +``(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?``, +``(IMPLIB_)?(PREFIX|SUFFIX)``, or :prop_tgt:`LINKER_LANGUAGE`. +Failure to follow this rule is not diagnosed and leaves +the location of the target undefined. diff --git a/Help/prop_tgt/NO_SONAME.rst b/Help/prop_tgt/NO_SONAME.rst index ee45ed8..d381a9c 100644 --- a/Help/prop_tgt/NO_SONAME.rst +++ b/Help/prop_tgt/NO_SONAME.rst @@ -1,10 +1,10 @@ NO_SONAME --------- -Whether to set "soname" when linking a shared library. +Whether to set ``soname`` when linking a shared library. -Enable this boolean property if a generated shared library -should not have "soname" set. Default is to set "soname" on all +Enable this boolean property if a generated ``SHARED`` library +should not have ``soname`` set. Default is to set ``soname`` on all shared libraries as long as the platform supports it. Generally, use this property only for leaf private libraries or plugins. If you use it on normal shared libraries which other targets diff --git a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst index 77fda90..6c55083 100644 --- a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -5,7 +5,8 @@ Per-configuration output directory for the MS debug symbol ``.pdb`` file generated by the linker for an executable or shared library target. This is a per-configuration version of :prop_tgt:`PDB_OUTPUT_DIRECTORY`, -but multi-configuration generators (VS, Xcode) do NOT append a +but multi-configuration generators (:ref:`Visual Studio Generators`, +:generator:`Xcode`) do NOT append a per-configuration subdirectory to the specified directory. This property is initialized by the value of the :variable:`CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG>` variable if it is diff --git a/Help/prop_tgt/POST_INSTALL_SCRIPT.rst b/Help/prop_tgt/POST_INSTALL_SCRIPT.rst index f1adb40..23935bc 100644 --- a/Help/prop_tgt/POST_INSTALL_SCRIPT.rst +++ b/Help/prop_tgt/POST_INSTALL_SCRIPT.rst @@ -3,7 +3,7 @@ POST_INSTALL_SCRIPT Deprecated install support. -The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are the old -way to specify CMake scripts to run before and after installing a -target. They are used only when the old INSTALL_TARGETS command is -used to install the target. Use the INSTALL command instead. +The :prop_tgt:`PRE_INSTALL_SCRIPT` and ``POST_INSTALL_SCRIPT`` properties are +the old way to specify CMake scripts to run before and after installing a +target. They are used only when the old ``INSTALL_TARGETS`` command is +used to install the target. Use the :command:`install` command instead. diff --git a/Help/prop_tgt/PREFIX.rst b/Help/prop_tgt/PREFIX.rst index a165104..a401292 100644 --- a/Help/prop_tgt/PREFIX.rst +++ b/Help/prop_tgt/PREFIX.rst @@ -4,4 +4,4 @@ PREFIX What comes before the library name. A target property that can be set to override the prefix (such as -"lib") on a library name. +``lib``) on a library name. diff --git a/Help/prop_tgt/PRE_INSTALL_SCRIPT.rst b/Help/prop_tgt/PRE_INSTALL_SCRIPT.rst index 113d7c5..43432f4 100644 --- a/Help/prop_tgt/PRE_INSTALL_SCRIPT.rst +++ b/Help/prop_tgt/PRE_INSTALL_SCRIPT.rst @@ -3,7 +3,7 @@ PRE_INSTALL_SCRIPT Deprecated install support. -The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are the old -way to specify CMake scripts to run before and after installing a -target. They are used only when the old INSTALL_TARGETS command is -used to install the target. Use the INSTALL command instead. +The ``PRE_INSTALL_SCRIPT`` and :prop_tgt:`POST_INSTALL_SCRIPT` properties are +the old way to specify CMake scripts to run before and after installing a +target. They are used only when the old ``INSTALL_TARGETS`` command is +used to install the target. Use the :command:`install` command instead. diff --git a/Help/prop_tgt/PRIVATE_HEADER.rst b/Help/prop_tgt/PRIVATE_HEADER.rst index 2bd4079..23e1f8e 100644 --- a/Help/prop_tgt/PRIVATE_HEADER.rst +++ b/Help/prop_tgt/PRIVATE_HEADER.rst @@ -8,4 +8,4 @@ frameworks on macOS, iOS and normal shared libraries on other platforms. This property may be set to a list of header files to be placed in the PrivateHeaders directory inside the framework folder. On non-Apple platforms these headers may be installed using the ``PRIVATE_HEADER`` -option to the ``install(TARGETS)`` command. +option to the :command:`install(TARGETS)` command. diff --git a/Help/prop_tgt/PUBLIC_HEADER.rst b/Help/prop_tgt/PUBLIC_HEADER.rst index 549ac7c..915e39c 100644 --- a/Help/prop_tgt/PUBLIC_HEADER.rst +++ b/Help/prop_tgt/PUBLIC_HEADER.rst @@ -8,4 +8,4 @@ frameworks on macOS, iOS and normal shared libraries on other platforms. This property may be set to a list of header files to be placed in the ``Headers`` directory inside the framework folder. On non-Apple platforms these headers may be installed using the ``PUBLIC_HEADER`` option to the -``install(TARGETS)`` command. +:command:`install(TARGETS)` command. diff --git a/Help/prop_tgt/RESOURCE.rst b/Help/prop_tgt/RESOURCE.rst index 55ae774..e5a1cb6 100644 --- a/Help/prop_tgt/RESOURCE.rst +++ b/Help/prop_tgt/RESOURCE.rst @@ -9,7 +9,7 @@ or normal shared libraries on other platforms. This property may be set to a list of files to be placed in the corresponding directory (eg. ``Resources`` directory for macOS) inside the bundle. On non-Apple platforms these files may be installed using the ``RESOURCE`` -option to the ``install(TARGETS)`` command. +option to the :command:`install(TARGETS)` command. Following example of Application Bundle: @@ -18,21 +18,18 @@ Following example of Application Bundle: add_executable(ExecutableTarget addDemo.c resourcefile.txt - appresourcedir/appres.txt - ) + appresourcedir/appres.txt) target_link_libraries(ExecutableTarget heymath mul) set(RESOURCE_FILES resourcefile.txt - appresourcedir/appres.txt - ) + appresourcedir/appres.txt) set_target_properties(ExecutableTarget PROPERTIES MACOSX_BUNDLE TRUE MACOSX_FRAMEWORK_IDENTIFIER org.cmake.ExecutableTarget - RESOURCE "${RESOURCE_FILES}" - ) + RESOURCE "${RESOURCE_FILES}") will produce flat structure for iOS systems:: @@ -53,7 +50,7 @@ For macOS systems it will produce following directory structure:: appres.txt resourcefile.txt -For Linux, such cmake script produce following files:: +For Linux, such CMake script produce following files:: ExecutableTarget Resources diff --git a/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst index 94fb277..6727754 100644 --- a/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst @@ -6,7 +6,8 @@ Per-configuration output directory for This is a per-configuration version of the :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target property, but -multi-configuration generators (VS, Xcode) do NOT append a +multi-configuration generators (:ref:`Visual Studio Generators`, +:generator:`Xcode`) do NOT append a per-configuration subdirectory to the specified directory. This property is initialized by the value of the :variable:`CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG>` variable if diff --git a/Help/prop_tgt/SKIP_BUILD_RPATH.rst b/Help/prop_tgt/SKIP_BUILD_RPATH.rst index a91fa9c..7086b1b 100644 --- a/Help/prop_tgt/SKIP_BUILD_RPATH.rst +++ b/Help/prop_tgt/SKIP_BUILD_RPATH.rst @@ -3,7 +3,7 @@ SKIP_BUILD_RPATH Should rpaths be used for the build tree. -SKIP_BUILD_RPATH is a boolean specifying whether to skip automatic +``SKIP_BUILD_RPATH`` is a boolean specifying whether to skip automatic generation of an rpath allowing the target to run from the build tree. This property is initialized by the value of the variable -CMAKE_SKIP_BUILD_RPATH if it is set when a target is created. +:variable:`CMAKE_SKIP_BUILD_RPATH` if it is set when a target is created. diff --git a/Help/prop_tgt/SUFFIX.rst b/Help/prop_tgt/SUFFIX.rst index 70844be..32ec429 100644 --- a/Help/prop_tgt/SUFFIX.rst +++ b/Help/prop_tgt/SUFFIX.rst @@ -4,4 +4,4 @@ SUFFIX What comes after the target name. A target property that can be set to override the suffix (such as -".so" or ".exe") on the name of a library, module or executable. +``.so`` or ``.exe``) on the name of a library, module or executable. diff --git a/Help/prop_tgt/TYPE.rst b/Help/prop_tgt/TYPE.rst index 1cd9db4..3136d11 100644 --- a/Help/prop_tgt/TYPE.rst +++ b/Help/prop_tgt/TYPE.rst @@ -4,6 +4,6 @@ TYPE The type of the target. This read-only property can be used to test the type of the given -target. It will be one of STATIC_LIBRARY, MODULE_LIBRARY, -SHARED_LIBRARY, OBJECT_LIBRARY, INTERFACE_LIBRARY, EXECUTABLE or one -of the internal target types. +target. It will be one of ``STATIC_LIBRARY``, ``MODULE_LIBRARY``, +``SHARED_LIBRARY``, ``OBJECT_LIBRARY``, ``INTERFACE_LIBRARY``, ``EXECUTABLE`` +or one of the internal target types. diff --git a/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst b/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst index 7e00ac4..71858c5 100644 --- a/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst +++ b/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst @@ -3,8 +3,8 @@ XCODE_ATTRIBUTE_<an-attribute> Set Xcode target attributes directly. -Tell the Xcode generator to set '<an-attribute>' to a given value in -the generated Xcode project. Ignored on other generators. +Tell the :generator:`Xcode` generator to set '<an-attribute>' to a given +value in the generated Xcode project. Ignored on other generators. See the :variable:`CMAKE_XCODE_ATTRIBUTE_<an-attribute>` variable to set attributes on all targets in a directory tree. diff --git a/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst b/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst index a56a210..0adb5db 100644 --- a/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst +++ b/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst @@ -1,7 +1,7 @@ XCODE_GENERATE_SCHEME --------------------- -If enabled, the Xcode generator will generate schema files. These +If enabled, the :generator:`Xcode` generator will generate schema files. These are useful to invoke analyze, archive, build-for-testing and test actions from the command line. diff --git a/Help/release/3.14.rst b/Help/release/3.14.rst index 5038a75..f2a91c6 100644 --- a/Help/release/3.14.rst +++ b/Help/release/3.14.rst @@ -377,3 +377,17 @@ Other Changes * 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. + +Updates +======= + +Changes made since CMake 3.14.0 include the following. + +3.14.1 +------ + +* The :module:`FindFontconfig` module added by 3.14.0 accidentally + used uppercase ``FONTCONFIG_*`` variable names that do not match + our conventions. 3.14.1 revises the module to use ``Fontconfig_*`` + variable names. This is incompatible with 3.14.0 but since the + module is new in the 3.14 series usage should not yet be widespread. diff --git a/Help/release/3.9.rst b/Help/release/3.9.rst index ffa95aa..89da627 100644 --- a/Help/release/3.9.rst +++ b/Help/release/3.9.rst @@ -150,7 +150,7 @@ Modules * The :module:`CMakeFindDependencyMacro` module ``find_dependency`` macro now forwards all arguments to the underlying :command:`find_package` call. Existing uses will continue to function as before, but callers can - now access the full suite of arguments that ``find_package`` accepts. + now access the full suite of arguments that :command:`find_package` accepts. * The :module:`FeatureSummary` module :command:`feature_summary` command now accepts the new ``DEFAULT_DESCRIPTION`` option that will print the default diff --git a/Help/release/dev/FindPython-virtual-env.rst b/Help/release/dev/FindPython-virtual-env.rst new file mode 100644 index 0000000..5489dc2 --- /dev/null +++ b/Help/release/dev/FindPython-virtual-env.rst @@ -0,0 +1,5 @@ +FindPython-virtual-env +---------------------- + +* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` + gain capability to control how virtual environments are handled. diff --git a/Help/release/dev/allow-aliasing-unkown-import-targets.rst b/Help/release/dev/allow-aliasing-unkown-import-targets.rst new file mode 100644 index 0000000..aa5da0c --- /dev/null +++ b/Help/release/dev/allow-aliasing-unkown-import-targets.rst @@ -0,0 +1,5 @@ +allow-aliasing-unkown-import-targets +------------------------------------ + +* :command:`add_library` command ``ALIAS`` option learned to support + import libraries of the ``UNKNOWN`` type. diff --git a/Help/release/dev/ctest_submit_get_buildid.rst b/Help/release/dev/ctest_submit_get_buildid.rst new file mode 100644 index 0000000..39a0010 --- /dev/null +++ b/Help/release/dev/ctest_submit_get_buildid.rst @@ -0,0 +1,6 @@ +ctest_submit_get_buildid +-------------------------- + +* The :command:`ctest_submit` command learned a new option: ``BUILD_ID``. + This can be used to store the ID assigned to this build by CDash to a + variable. diff --git a/Help/release/dev/genex-TARGET_FILE_BASE_NAME.rst b/Help/release/dev/genex-TARGET_FILE_BASE_NAME.rst new file mode 100644 index 0000000..d8b2b21 --- /dev/null +++ b/Help/release/dev/genex-TARGET_FILE_BASE_NAME.rst @@ -0,0 +1,7 @@ +genex-TARGET_FILE_BASE_NAME +--------------------------- + +* New ``$<TARGET_FILE_BASE_NAME:...>``, ``$<TARGET_LINKER_FILE_BASE_NAME:...>`` + and ``$<TARGET_PDB_FILE_BASE_NAME:...>`` + :manual:`generator expressions <cmake-generator-expressions(7)>` have been + added to retrieve the base name of various artifacts. diff --git a/Help/release/dev/genex-TARGET_FILE_PREFIX.rst b/Help/release/dev/genex-TARGET_FILE_PREFIX.rst new file mode 100644 index 0000000..3e480bb --- /dev/null +++ b/Help/release/dev/genex-TARGET_FILE_PREFIX.rst @@ -0,0 +1,7 @@ +genex-TARGET_FILE_PREFIX +------------------------ + +* New ``$<TARGET_FILE_PREFIX:...>``, ``$<TARGET_LINKER_FILE_PREFIX:...>``, + ``$<TARGET_FILE_SUFFIX:...>`` and ``$<TARGET_LINKER_FILE_SUFFIX:...>`` + :manual:`generator expressions <cmake-generator-expressions(7)>` have been + added to retrieve the prefix and suffix of various artifacts. diff --git a/Help/release/dev/genex_filter.rst b/Help/release/dev/genex_filter.rst new file mode 100644 index 0000000..ad23134 --- /dev/null +++ b/Help/release/dev/genex_filter.rst @@ -0,0 +1,6 @@ +genex_filter +------------ + +* A new ``$<FILTER:list,INCLUDE|EXCLUDE,regex>`` + :manual:`generator expression <cmake-generator-expressions(7)>` + has been added. diff --git a/Help/release/dev/ghs-custom-commands.rst b/Help/release/dev/ghs-custom-commands.rst new file mode 100644 index 0000000..a29ef88 --- /dev/null +++ b/Help/release/dev/ghs-custom-commands.rst @@ -0,0 +1,5 @@ +ghs_custom_commands +------------------- + +* The :generator:`Green Hills MULTI` generator now supports + :command:`add_custom_command` and :command:`add_custom_target` diff --git a/Help/release/dev/iface-headers.rst b/Help/release/dev/iface-headers.rst new file mode 100644 index 0000000..2e1de5e --- /dev/null +++ b/Help/release/dev/iface-headers.rst @@ -0,0 +1,7 @@ +iface-headers +------------- + +* ``INTERFACE`` library can now have :prop_tgt:`PUBLIC_HEADER` and + :prop_tgt:`PRIVATE_HEADER` properties set. The headers specified by those + properties can be installed using the :command:`install(TARGETS)` command by + passing the ``PUBLIC_HEADER`` and ``PRIVATE_HEADER`` arguments respectively. diff --git a/Help/release/dev/project-include-before.rst b/Help/release/dev/project-include-before.rst new file mode 100644 index 0000000..3f16cd7 --- /dev/null +++ b/Help/release/dev/project-include-before.rst @@ -0,0 +1,5 @@ +cmake_project_include_before +---------------------------- + +* A variable :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` was added to allow + injection of custom code into the project. diff --git a/Help/release/dev/project-include.rst b/Help/release/dev/project-include.rst new file mode 100644 index 0000000..659e933 --- /dev/null +++ b/Help/release/dev/project-include.rst @@ -0,0 +1,5 @@ +cmake_project_include +--------------------- + +* A variable :variable:`CMAKE_PROJECT_INCLUDE` was added to allow injection + of custom code into the project without knowing the project name a priori. diff --git a/Help/release/dev/remove_duplicates.rst b/Help/release/dev/remove_duplicates.rst new file mode 100644 index 0000000..f6a7fff --- /dev/null +++ b/Help/release/dev/remove_duplicates.rst @@ -0,0 +1,6 @@ +remove_duplicates +----------------- + +* A new ``$<REMOVE_DUPLICATES:list>`` + :manual:`generator expression <cmake-generator-expressions(7)>` + has been added. diff --git a/Help/release/dev/string-repeat.rst b/Help/release/dev/string-repeat.rst new file mode 100644 index 0000000..4be0d5c --- /dev/null +++ b/Help/release/dev/string-repeat.rst @@ -0,0 +1,4 @@ +string-repeat +-------------- + +* The :command:`string` learned a new sub-command ``REPEAT``. diff --git a/Help/variable/CMAKE_CROSSCOMPILING.rst b/Help/variable/CMAKE_CROSSCOMPILING.rst index 9e96769..7e6ec33 100644 --- a/Help/variable/CMAKE_CROSSCOMPILING.rst +++ b/Help/variable/CMAKE_CROSSCOMPILING.rst @@ -19,8 +19,9 @@ macOS are handled differently to other cross compiling scenarios. Rather than relying on :variable:`CMAKE_SYSTEM_NAME` to select the target platform, Apple device builds use :variable:`CMAKE_OSX_SYSROOT` to select the appropriate SDK, which indirectly determines the target platform. Furthermore, when using the -Xcode generator, developers can switch between device and simulator builds at -build time rather than having a single choice at configure time, so the concept +:generator:`Xcode` generator, developers can switch between device and +simulator builds at build time rather than having a single +choice at configure time, so the concept of whether the build is cross compiling or not is more complex. Therefore, the use of ``CMAKE_CROSSCOMPILING`` is not recommended for projects targeting Apple devices. diff --git a/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst b/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst index 95d2c7f..e7774f2 100644 --- a/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst +++ b/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst @@ -6,7 +6,7 @@ should point to a command on the host system that can run executable built for the target system. The command will be used to run :command:`try_run` generated executables, -which avoids manual population of the TryRunResults.cmake file. +which avoids manual population of the ``TryRunResults.cmake`` file. It is also used as the default value for the :prop_tgt:`CROSSCOMPILING_EMULATOR` target property of executables. diff --git a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst index 72e8e66..eea2c4f 100644 --- a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst +++ b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst @@ -2,6 +2,6 @@ CMAKE_CUDA_HOST_COMPILER ------------------------ Executable to use when compiling host code when compiling ``CUDA`` language -files. Maps to the nvcc -ccbin option. Will only be used by CMake on the first +files. Maps to the ``nvcc -ccbin`` option. Will only be used by CMake on the first configuration to determine a valid host compiler for ``CUDA``. After a valid host compiler has been found, this value is read-only. diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE.rst new file mode 100644 index 0000000..7de767a --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_INCLUDE.rst @@ -0,0 +1,6 @@ +CMAKE_PROJECT_INCLUDE +--------------------- + +A CMake language file or module to be included by the :command:`project` +command. This is intended for injecting custom code into project +builds without modifying their source. diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst new file mode 100644 index 0000000..12a5263 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst @@ -0,0 +1,6 @@ +CMAKE_PROJECT_INCLUDE_BEFORE +---------------------------- + +A CMake language file or module to be included before processing the +:command:`project` command. This is intended for injecting custom code into +project builds without modifying their source. diff --git a/Help/variable/CMAKE_SKIP_INSTALL_RULES.rst b/Help/variable/CMAKE_SKIP_INSTALL_RULES.rst index 44966f3..b77bb68 100644 --- a/Help/variable/CMAKE_SKIP_INSTALL_RULES.rst +++ b/Help/variable/CMAKE_SKIP_INSTALL_RULES.rst @@ -3,6 +3,6 @@ CMAKE_SKIP_INSTALL_RULES Whether to disable generation of installation rules. -If ``TRUE``, cmake will neither generate installaton rules nor +If ``TRUE``, CMake will neither generate installation rules nor will it generate ``cmake_install.cmake`` files. This variable is ``FALSE`` by default. diff --git a/Help/variable/CMAKE_SOURCE_DIR.rst b/Help/variable/CMAKE_SOURCE_DIR.rst index 416fbe1..d1f1798 100644 --- a/Help/variable/CMAKE_SOURCE_DIR.rst +++ b/Help/variable/CMAKE_SOURCE_DIR.rst @@ -7,7 +7,7 @@ This is the full path to the top level of the current CMake source tree. For an in-source build, this would be the same as :variable:`CMAKE_BINARY_DIR`. -When run in -P script mode, CMake sets the variables +When run in ``-P`` script mode, CMake sets the variables :variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`, :variable:`CMAKE_CURRENT_BINARY_DIR` and :variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. diff --git a/Help/variable/CMAKE_STAGING_PREFIX.rst b/Help/variable/CMAKE_STAGING_PREFIX.rst index 1310e94..bdb97fa 100644 --- a/Help/variable/CMAKE_STAGING_PREFIX.rst +++ b/Help/variable/CMAKE_STAGING_PREFIX.rst @@ -5,10 +5,10 @@ This variable may be set to a path to install to when cross-compiling. This can be useful if the path in :variable:`CMAKE_SYSROOT` is read-only, or otherwise should remain pristine. -The ``CMAKE_STAGING_PREFIX`` location is also used as a search prefix by the -``find_*`` commands. This can be controlled by setting the +The :variable:`CMAKE_STAGING_PREFIX` location is also used as a search prefix +by the ``find_*`` commands. This can be controlled by setting the :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` variable. -If any RPATH/RUNPATH entries passed to the linker contain the -``CMAKE_STAGING_PREFIX``, the matching path fragments are replaced with the -:variable:`CMAKE_INSTALL_PREFIX`. +If any ``RPATH``/``RUNPATH`` entries passed to the linker contain the +:variable:`CMAKE_STAGING_PREFIX`, the matching path fragments are replaced +with the :variable:`CMAKE_INSTALL_PREFIX`. diff --git a/Help/variable/CMAKE_SUPPRESS_REGENERATION.rst b/Help/variable/CMAKE_SUPPRESS_REGENERATION.rst index ed47e1a..96184dd 100644 --- a/Help/variable/CMAKE_SUPPRESS_REGENERATION.rst +++ b/Help/variable/CMAKE_SUPPRESS_REGENERATION.rst @@ -1,10 +1,10 @@ CMAKE_SUPPRESS_REGENERATION --------------------------- -If CMAKE_SUPPRESS_REGENERATION is ``OFF``, which is default, then CMake adds a -special target on which all other targets depend that checks the build system -and optionally re-runs CMake to regenerate the build system when the target -specification source changes. +If ``CMAKE_SUPPRESS_REGENERATION`` is ``OFF``, which is default, then CMake +adds a special target on which all other targets depend that checks the build +system and optionally re-runs CMake to regenerate the build system when +the target specification source changes. If this variable evaluates to ``ON`` at the end of the top-level ``CMakeLists.txt`` file, CMake will not add the regeneration target to the diff --git a/Help/variable/CMAKE_SYSROOT.rst b/Help/variable/CMAKE_SYSROOT.rst index 64f81bb..35b944f 100644 --- a/Help/variable/CMAKE_SYSROOT.rst +++ b/Help/variable/CMAKE_SYSROOT.rst @@ -4,8 +4,8 @@ CMAKE_SYSROOT Path to pass to the compiler in the ``--sysroot`` flag. The ``CMAKE_SYSROOT`` content is passed to the compiler in the ``--sysroot`` -flag, if supported. The path is also stripped from the RPATH/RUNPATH if -necessary on installation. The ``CMAKE_SYSROOT`` is also used to prefix +flag, if supported. The path is also stripped from the ``RPATH``/``RUNPATH`` +if necessary on installation. The ``CMAKE_SYSROOT`` is also used to prefix paths searched by the ``find_*`` commands. This variable may only be set in a toolchain file specified by diff --git a/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst b/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst index 1fb84d7..5b1a003 100644 --- a/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst +++ b/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst @@ -1,7 +1,7 @@ CMAKE_XCODE_GENERATE_SCHEME --------------------------- -If enabled, the Xcode generator will generate schema files. These +If enabled, the :generator:`Xcode` generator will generate schema files. These are useful to invoke analyze, archive, build-for-testing and test actions from the command line. diff --git a/Help/variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst b/Help/variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst index 5dad6bd..30ae236 100644 --- a/Help/variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst +++ b/Help/variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst @@ -5,7 +5,7 @@ Ask CPack to error out as soon as a file with absolute ``INSTALL DESTINATION`` is encountered. The fatal error is emitted before the installation of the offending -file takes place. Some CPack generators, like NSIS, enforce this +file takes place. Some CPack generators, like ``NSIS``, enforce this internally. This variable triggers the definition of :variable:`CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION` when CPack runs. diff --git a/Help/variable/PackageName_ROOT.rst b/Help/variable/PackageName_ROOT.rst index c5b07ae..1c2fd34 100644 --- a/Help/variable/PackageName_ROOT.rst +++ b/Help/variable/PackageName_ROOT.rst @@ -3,7 +3,7 @@ Calls to :command:`find_package(<PackageName>)` will search in prefixes specified by the ``<PackageName>_ROOT`` CMake variable, where -``<PackageName>`` is the name given to the ``find_package`` call +``<PackageName>`` is the name given to the :command:`find_package` call and ``_ROOT`` is literal. For example, ``find_package(Foo)`` will search prefixes specified in the ``Foo_ROOT`` CMake variable (if set). See policy :policy:`CMP0074`. diff --git a/Help/variable/XCODE_VERSION.rst b/Help/variable/XCODE_VERSION.rst index b85d41e..9caf19a 100644 --- a/Help/variable/XCODE_VERSION.rst +++ b/Help/variable/XCODE_VERSION.rst @@ -3,5 +3,5 @@ XCODE_VERSION Version of Xcode (:generator:`Xcode` generator only). -Under the Xcode generator, this is the version of Xcode as specified -in ``Xcode.app/Contents/version.plist`` (such as ``3.1.2``). +Under the :generator:`Xcode` generator, this is the version of Xcode +as specified in ``Xcode.app/Contents/version.plist`` (such as ``3.1.2``). |