diff options
Diffstat (limited to 'Help/command')
28 files changed, 425 insertions, 125 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 38c231a..73dbd57 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -137,7 +137,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: .. |FIND_ARGS_XXX| replace:: <VAR> NAMES name -On OS X the :variable:`CMAKE_FIND_FRAMEWORK` and +On macOS the :variable:`CMAKE_FIND_FRAMEWORK` and :variable:`CMAKE_FIND_APPBUNDLE` variables determine the order of preference between Apple-style and unix-style package components. diff --git a/Help/command/LINK_OPTIONS_LINKER.txt b/Help/command/LINK_OPTIONS_LINKER.txt new file mode 100644 index 0000000..76927be --- /dev/null +++ b/Help/command/LINK_OPTIONS_LINKER.txt @@ -0,0 +1,10 @@ +To pass options to the linker tool, each compiler driver has is own syntax. +The ``LINKER:`` prefix can be used to specify, in a portable way, options +to pass to the linker tool. The ``LINKER:`` prefix is replaced by the required +driver option and the rest of the option string defines linker arguments using +``,`` as separator. These arguments will be formatted according to the +:variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG` and +:variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP` variables. + +For example, ``"LINKER:-z,defs"`` becomes ``-Xlinker -z -Xlinker defs`` for +``Clang`` and ``-Wl,-z,defs`` for ``GNU GCC``. diff --git a/Help/command/COMPILE_OPTIONS_SHELL.txt b/Help/command/OPTIONS_SHELL.txt index a1316c8..530c012 100644 --- a/Help/command/COMPILE_OPTIONS_SHELL.txt +++ b/Help/command/OPTIONS_SHELL.txt @@ -1,4 +1,4 @@ -The final set of compile options used for a target is constructed by +The final set of compile or link options used for a target is constructed by accumulating options from the current target and the usage requirements of it dependencies. The set of options is de-duplicated to avoid repetition. While beneficial for individual options, the de-duplication step can break diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst index c445608..350a1c0 100644 --- a/Help/command/add_compile_options.rst +++ b/Help/command/add_compile_options.rst @@ -22,4 +22,4 @@ 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. -.. include:: COMPILE_OPTIONS_SHELL.txt +.. include:: OPTIONS_SHELL.txt diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 5f74c54..71fe494 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -182,6 +182,9 @@ The options are: If it is a relative path it will be interpreted relative to the build tree directory corresponding to the current source directory. + Arguments to ``WORKING_DIRECTORY`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + ``DEPFILE`` Specify a ``.d`` depfile for the :generator:`Ninja` generator. A ``.d`` file holds dependencies usually emitted by the custom diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index bd61c8b..a6b2f77 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -121,3 +121,6 @@ The options are: Execute the command with the given current working directory. If it is a relative path it will be interpreted relative to the build tree directory corresponding to the current source directory. + + Arguments to ``WORKING_DIRECTORY`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index f20b274..c4c512c 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -35,7 +35,7 @@ variable :variable:`BUILD_SHARED_LIBS` is ``ON``. For ``SHARED`` and ``MODULE`` libraries the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property is set to ``ON`` automatically. A ``SHARED`` or ``STATIC`` library may be marked with the :prop_tgt:`FRAMEWORK` -target property to create an OS X Framework. +target property to create an macOS Framework. If a library does not export any symbols, it must not be declared as a ``SHARED`` library. For example, a Windows resource DLL or a managed C++/CLI @@ -153,6 +153,7 @@ the interface target using the commands: * :command:`set_property`, * :command:`target_link_libraries(INTERFACE)`, +* :command:`target_link_options(INTERFACE)`, * :command:`target_include_directories(INTERFACE)`, * :command:`target_compile_options(INTERFACE)`, * :command:`target_compile_definitions(INTERFACE)`, and diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst new file mode 100644 index 0000000..551d440 --- /dev/null +++ b/Help/command/add_link_options.rst @@ -0,0 +1,26 @@ +add_link_options +---------------- + +Adds options to the link of shared library, module and executable targets. + +:: + + add_link_options(<option> ...) + +Adds options to the link step for targets in the current directory and below +that are added after this command is invoked. See documentation of the +:prop_dir:`directory <LINK_OPTIONS>` and +:prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties. + +This command can be used to add any options, but alternative commands +exist to add libraries (:command:`target_link_libraries` or +:command:`link_libraries`). + +Arguments to ``add_link_options`` may use "generator expressions" 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. + +.. include:: LINK_OPTIONS_LINKER.txt + +.. include:: OPTIONS_SHELL.txt diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst index 9893151..2dee93a 100644 --- a/Help/command/cmake_host_system_information.rst +++ b/Help/command/cmake_host_system_information.rst @@ -20,10 +20,10 @@ Key Description ``NUMBER_OF_PHYSICAL_CORES`` Number of physical cores ``HOSTNAME`` Hostname ``FQDN`` Fully qualified domain name -``TOTAL_VIRTUAL_MEMORY`` Total virtual memory in megabytes -``AVAILABLE_VIRTUAL_MEMORY`` Available virtual memory in megabytes -``TOTAL_PHYSICAL_MEMORY`` Total physical memory in megabytes -``AVAILABLE_PHYSICAL_MEMORY`` Available physical memory in megabytes +``TOTAL_VIRTUAL_MEMORY`` Total virtual memory in MiB [#mebibytes]_ +``AVAILABLE_VIRTUAL_MEMORY`` Available virtual memory in MiB [#mebibytes]_ +``TOTAL_PHYSICAL_MEMORY`` Total physical memory in MiB [#mebibytes]_ +``AVAILABLE_PHYSICAL_MEMORY`` Available physical memory in MiB [#mebibytes]_ ``IS_64BIT`` One if processor is 64Bit ``HAS_FPU`` One if processor has floating point unit ``HAS_MMX`` One if processor supports MMX instructions @@ -44,3 +44,7 @@ Key Description ``OS_VERSION`` The OS build ID ``OS_PLATFORM`` See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` ============================= ================================================ + +.. rubric:: Footnotes + +.. [#mebibytes] One MiB (mebibyte) is equal to 1024x1024 bytes. diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index cc9612b..2ba6bef 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -10,6 +10,7 @@ Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`. [RETRY_COUNT <count>] [RETRY_DELAY <delay>] [RETURN_VALUE <result-var>] + [CAPTURE_CMAKE_ERROR <result-var>] [QUIET] ) @@ -52,6 +53,10 @@ The options are: Store in the ``<result-var>`` variable ``0`` for success and non-zero on failure. +``CAPTURE_CMAKE_ERROR <result-var>`` + Store in the ``<result-var>`` variable -1 if there are any errors running + the command and prevent ctest from returning non-zero if an error occurs. + ``QUIET`` Suppress all non-error messages that would have otherwise been printed to the console. @@ -65,6 +70,7 @@ Submit to CDash Upload API [HTTPHEADER <header>] [RETRY_COUNT <count>] [RETRY_DELAY <delay>] + [RETURN_VALUE <result-var>] [QUIET]) This second signature is used to upload files to CDash via the CDash @@ -73,5 +79,5 @@ 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 ``HTTPHEADER``, ``RETRY_COUNT``, ``RETRY_DELAY``, and -``QUIET`` options as described above. +This signature accepts the ``HTTPHEADER``, ``RETRY_COUNT``, ``RETRY_DELAY``, +``RETURN_VALUE`` and ``QUIET`` options as described above. diff --git a/Help/command/ctest_update.rst b/Help/command/ctest_update.rst index b205bca..df1a4e5 100644 --- a/Help/command/ctest_update.rst +++ b/Help/command/ctest_update.rst @@ -5,7 +5,10 @@ Perform the :ref:`CTest Update Step` as a :ref:`Dashboard Client`. :: - ctest_update([SOURCE <source-dir>] [RETURN_VALUE <result-var>] [QUIET]) + ctest_update([SOURCE <source-dir>] + [RETURN_VALUE <result-var>] + [CAPTURE_CMAKE_ERROR <result-var>] + [QUIET]) Update the source tree from version control and record results in ``Update.xml`` for submission with the :command:`ctest_submit` command. @@ -20,6 +23,10 @@ The options are: Store in the ``<result-var>`` variable the number of files updated or ``-1`` on error. +``CAPTURE_CMAKE_ERROR <result-var>`` + Store in the ``<result-var>`` variable -1 if there are any errors running + the command and prevent ctest from returning non-zero if an error occurs. + ``QUIET`` Tell CTest to suppress most non-error messages that it would have otherwise printed to the console. CTest will still report diff --git a/Help/command/export.rst b/Help/command/export.rst index 0c676c6..8c49328 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -51,15 +51,15 @@ unspecified. :: - export(PACKAGE <name>) + export(PACKAGE <PackageName>) Store the current build directory in the CMake user package registry -for package ``<name>``. The find_package command may consider the -directory while searching for package ``<name>``. This helps dependent +for package ``<PackageName>``. The 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 registry that this command creates works only in conjunction with a -package configuration file (``<name>Config.cmake``) that works with the +package configuration file (``<PackageName>Config.cmake``) that works with the build tree. In some cases, for example for packaging and for system wide installations, it is not desirable to write the user package registry. If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index a4416ab..3ad571c 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -1,21 +1,29 @@ find_package ------------ -Load settings for an external project. +.. only:: html + + .. contents:: + +Find an external project, and load its settings. + +.. _`basic signature`: + +Basic Signature and Module Mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: - find_package(<package> [version] [EXACT] [QUIET] [MODULE] + find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE] [REQUIRED] [[COMPONENTS] [components...]] [OPTIONAL_COMPONENTS components...] [NO_POLICY_SCOPE]) -Finds and loads settings from an external project. ``<package>_FOUND`` +Finds and loads settings from an external project. ``<PackageName>_FOUND`` will be set to indicate whether the package was found. When the package is found package-specific information is provided through variables and :ref:`Imported Targets` documented by the package itself. The ``QUIET`` option disables messages if the package cannot be found. The -``MODULE`` option disables the second signature documented below. The ``REQUIRED`` option stops processing with an error message if the package cannot be found. @@ -33,28 +41,35 @@ should be compatible (format is ``major[.minor[.patch[.tweak]]]``). The inside a find-module, the corresponding arguments are forwarded automatically from the outer call (including the ``EXACT`` flag for ``[version]``). Version support is currently provided only on a -package-by-package basis (details below). +package-by-package basis (see the `Version Selection`_ section below). -User code should generally look for packages using the above simple -signature. The remainder of this command documentation specifies the +See the :command:`cmake_policy` command documentation for discussion +of the ``NO_POLICY_SCOPE`` option. + +The command has two modes by which it searches for packages: "Module" +mode and "Config" mode. The above signature selects Module mode. +If no module is found the command falls back to Config mode, described +below. This fall back is disabled if the ``MODULE`` option is given. + +In Module mode, CMake searches for a file called ``Find<PackageName>.cmake`` +in the :variable:`CMAKE_MODULE_PATH` followed by the CMake installation. +If the file is found, it is read and processed by CMake. It is responsible +for finding the package, checking the version, and producing any needed +messages. Some find-modules provide limited or no support for versioning; +check the module documentation. + +Full Signature and Config Mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +User code should generally look for packages using the above `basic +signature`_. The remainder of this command documentation specifies the full command signature and details of the search process. Project maintainers wishing to provide a package to be found by this command are encouraged to read on. -The command has two modes by which it searches for packages: "Module" -mode and "Config" mode. Module mode is available when the command is -invoked with the above reduced signature. CMake searches for a file -called ``Find<package>.cmake`` in the :variable:`CMAKE_MODULE_PATH` -followed by the CMake installation. If the file is found, it is read -and processed by CMake. It is responsible for finding the package, -checking the version, and producing any needed messages. Many -find-modules provide limited or no support for versioning; check -the module documentation. If no module is found and the ``MODULE`` -option is not given the command proceeds to Config mode. - The complete Config mode command signature is:: - find_package(<package> [version] [EXACT] [QUIET] + find_package(<PackageName> [version] [EXACT] [QUIET] [REQUIRED] [[COMPONENTS] [components...]] [CONFIG|NO_MODULE] [NO_POLICY_SCOPE] @@ -76,37 +91,44 @@ The complete Config mode command signature is:: ONLY_CMAKE_FIND_ROOT_PATH | NO_CMAKE_FIND_ROOT_PATH]) -The ``CONFIG`` option may be used to skip Module mode explicitly and -switch to Config mode. It is synonymous to using ``NO_MODULE``. Config -mode is also implied by use of options not specified in the reduced -signature. +The ``CONFIG`` option, the synonymous ``NO_MODULE`` option, or the use +of options not specified in the `basic signature`_ all enforce pure Config +mode. In pure Config mode, the command skips Module mode search and +proceeds at once with Config mode search. -Config mode attempts to locate a configuration file provided by the -package to be found. A cache entry called ``<package>_DIR`` is created to +Config mode search attempts to locate a configuration file provided by the +package to be found. A cache entry called ``<PackageName>_DIR`` is created to hold the directory containing the file. By default the command -searches for a package with the name ``<package>``. If the ``NAMES`` option -is given the names following it are used instead of ``<package>``. The -command searches for a file called ``<name>Config.cmake`` or -``<lower-case-name>-config.cmake`` for each name specified. A -replacement set of possible configuration file names may be given +searches for a package with the name ``<PackageName>``. If the ``NAMES`` option +is given the names following it are used instead of ``<PackageName>``. +The command searches for a file called ``<PackageName>Config.cmake`` or +``<lower-case-package-name>-config.cmake`` for each name specified. +A replacement set of possible configuration file names may be given using the ``CONFIGS`` option. The search procedure is specified below. Once found, the configuration file is read and processed by CMake. Since the file is provided by the package it already knows the location of package contents. The full path to the configuration file -is stored in the cmake variable ``<package>_CONFIG``. +is stored in the cmake variable ``<PackageName>_CONFIG``. All configuration files which have been considered by CMake while searching for an installation of the package with an appropriate -version are stored in the cmake variable ``<package>_CONSIDERED_CONFIGS``, -the associated versions in ``<package>_CONSIDERED_VERSIONS``. +version are stored in the cmake variable ``<PackageName>_CONSIDERED_CONFIGS``, +the associated versions in ``<PackageName>_CONSIDERED_VERSIONS``. If the package configuration file cannot be found CMake will generate an error describing the problem unless the ``QUIET`` argument is specified. If ``REQUIRED`` is specified and the package is not found a fatal error is generated and the configure step stops executing. If -``<package>_DIR`` has been set to a directory not containing a +``<PackageName>_DIR`` has been set to a directory not containing a configuration file CMake will ignore it and search from scratch. +Package maintainers providing CMake package configuration files are +encouraged to name and install them such that the `Search Procedure`_ +outlined below will find them without requiring use of additional options. + +Version Selection +^^^^^^^^^^^^^^^^^ + When the ``[version]`` argument is given Config mode will only find a version of the package that claims compatibility with the requested version (format is ``major[.minor[.patch[.tweak]]]``). If the ``EXACT`` @@ -127,7 +149,7 @@ version file is loaded in a nested scope in which the following variables have been defined: ``PACKAGE_FIND_NAME`` - the ``<package>`` name + the ``<PackageName>`` ``PACKAGE_FIND_VERSION`` full requested version string ``PACKAGE_FIND_VERSION_MAJOR`` @@ -158,17 +180,17 @@ whether the configuration file provides an acceptable version. They are not available after the find_package call returns. If the version is acceptable the following variables are set: -``<package>_VERSION`` +``<PackageName>_VERSION`` full provided version string -``<package>_VERSION_MAJOR`` +``<PackageName>_VERSION_MAJOR`` major version if provided, else 0 -``<package>_VERSION_MINOR`` +``<PackageName>_VERSION_MINOR`` minor version if provided, else 0 -``<package>_VERSION_PATCH`` +``<PackageName>_VERSION_PATCH`` patch version if provided, else 0 -``<package>_VERSION_TWEAK`` +``<PackageName>_VERSION_TWEAK`` tweak version if provided, else 0 -``<package>_VERSION_COUNT`` +``<PackageName>_VERSION_COUNT`` number of version components, 0 to 4 and the corresponding package configuration file is loaded. @@ -187,17 +209,8 @@ For instance in order to select the highest version one can set:: before calling ``find_package``. -Config mode provides an elaborate interface and search procedure. -Much of the interface is provided for completeness and for use -internally by find-modules loaded by Module mode. Most user code -should simply call:: - - find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET]) - -in order to find a package. Package maintainers providing CMake -package configuration files are encouraged to name and install them -such that the procedure outlined below will find them without -requiring use of additional options. +Search Procedure +^^^^^^^^^^^^^^^^ CMake constructs a set of possible installation prefixes for the package. Under each prefix several directories are searched for a @@ -216,7 +229,7 @@ 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 OS X Frameworks and Application Bundles the +On systems supporting macOS Frameworks and Application Bundles the following directories are searched for frameworks or bundles containing a configuration file:: @@ -228,7 +241,7 @@ containing a configuration file:: <prefix>/<name>.app/Contents/Resources/CMake/ (A) In all cases the ``<name>`` is treated as case-insensitive and corresponds -to any of the names specified (``<package>`` or names given by ``NAMES``). +to any of the names specified (``<PackageName>`` or names given by ``NAMES``). Paths with ``lib/<arch>`` are enabled if the :variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. ``lib*`` includes one @@ -286,7 +299,7 @@ enabled. (``;`` on Windows and ``:`` on UNIX). This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed:: - <package>_DIR + <PackageName>_DIR CMAKE_PREFIX_PATH CMAKE_FRAMEWORK_PATH CMAKE_APPBUNDLE_PATH @@ -329,7 +342,7 @@ enabled. hard-coded guesses. .. |FIND_XXX| replace:: find_package -.. |FIND_ARGS_XXX| replace:: <package> +.. |FIND_ARGS_XXX| replace:: <PackageName> .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: :variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE` @@ -339,33 +352,36 @@ enabled. Every non-REQUIRED ``find_package`` call can be disabled by setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``. +Package File Interface Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + When loading a find module or package configuration file ``find_package`` defines variables to provide information about the call arguments (and restores their original state before returning): ``CMAKE_FIND_PACKAGE_NAME`` - the ``<package>`` name which is searched for -``<package>_FIND_REQUIRED`` + the ``<PackageName>`` which is searched for +``<PackageName>_FIND_REQUIRED`` true if ``REQUIRED`` option was given -``<package>_FIND_QUIETLY`` +``<PackageName>_FIND_QUIETLY`` true if ``QUIET`` option was given -``<package>_FIND_VERSION`` +``<PackageName>_FIND_VERSION`` full requested version string -``<package>_FIND_VERSION_MAJOR`` +``<PackageName>_FIND_VERSION_MAJOR`` major version if requested, else 0 -``<package>_FIND_VERSION_MINOR`` +``<PackageName>_FIND_VERSION_MINOR`` minor version if requested, else 0 -``<package>_FIND_VERSION_PATCH`` +``<PackageName>_FIND_VERSION_PATCH`` patch version if requested, else 0 -``<package>_FIND_VERSION_TWEAK`` +``<PackageName>_FIND_VERSION_TWEAK`` tweak version if requested, else 0 -``<package>_FIND_VERSION_COUNT`` +``<PackageName>_FIND_VERSION_COUNT`` number of version components, 0 to 4 -``<package>_FIND_VERSION_EXACT`` +``<PackageName>_FIND_VERSION_EXACT`` true if ``EXACT`` option was given -``<package>_FIND_COMPONENTS`` +``<PackageName>_FIND_COMPONENTS`` list of requested components -``<package>_FIND_REQUIRED_<c>`` +``<PackageName>_FIND_REQUIRED_<c>`` true if component ``<c>`` is required, false if component ``<c>`` is optional @@ -375,8 +391,5 @@ In Config mode ``find_package`` handles ``REQUIRED``, ``QUIET``, and ``[version]`` options automatically but leaves it to the package configuration file to handle components in a way that makes sense for the package. The package configuration file may set -``<package>_FOUND`` to false to tell ``find_package`` that component +``<PackageName>_FOUND`` to false to tell ``find_package`` that component requirements are not satisfied. - -See the :command:`cmake_policy` command documentation for discussion -of the ``NO_POLICY_SCOPE`` option. diff --git a/Help/command/if.rst b/Help/command/if.rst index f04f233..5294ce8 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -148,23 +148,33 @@ Possible expressions are: ``if(<variable|string> VERSION_LESS <variable|string>)`` Component-wise integer version number comparison (version format is - ``major[.minor[.patch[.tweak]]]``). + ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). + Any non-integer version component or non-integer trailing part of a version + component effectively truncates the string at that point. ``if(<variable|string> VERSION_GREATER <variable|string>)`` Component-wise integer version number comparison (version format is - ``major[.minor[.patch[.tweak]]]``). + ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). + Any non-integer version component or non-integer trailing part of a version + component effectively truncates the string at that point. ``if(<variable|string> VERSION_EQUAL <variable|string>)`` Component-wise integer version number comparison (version format is - ``major[.minor[.patch[.tweak]]]``). + ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). + Any non-integer version component or non-integer trailing part of a version + component effectively truncates the string at that point. ``if(<variable|string> VERSION_LESS_EQUAL <variable|string>)`` Component-wise integer version number comparison (version format is - ``major[.minor[.patch[.tweak]]]``). + ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). + Any non-integer version component or non-integer trailing part of a version + component effectively truncates the string at that point. ``if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)`` Component-wise integer version number comparison (version format is - ``major[.minor[.patch[.tweak]]]``). + ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). + Any non-integer version component or non-integer trailing part of a version + component effectively truncates the string at that point. ``if(<variable|string> IN_LIST <variable>)`` True if the given element is contained in the named list variable. diff --git a/Help/command/include_directories.rst b/Help/command/include_directories.rst index f694934..e797b5d 100644 --- a/Help/command/include_directories.rst +++ b/Help/command/include_directories.rst @@ -33,3 +33,9 @@ Arguments to ``include_directories`` may use "generator expressions" 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. + +.. note:: + + Prefer the :command:`target_include_directories` command to add include + directories to individual targets and optionally propagate/export them + to dependents. diff --git a/Help/command/install.rst b/Help/command/install.rst index 6cea996..08c5718 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -89,6 +89,13 @@ Command signatures that install files may print messages during installation. Use the :variable:`CMAKE_INSTALL_MESSAGE` variable to control which messages are printed. +Many of the ``install()`` variants implicitly create the directories +containing the installed files. If +:variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` is set, these +directories will be created with the permissions specified. Otherwise, +they will be created according to the uname rules on Unix-like platforms. +Windows platforms are unaffected. + Installing Targets ^^^^^^^^^^^^^^^^^^ @@ -115,19 +122,19 @@ project. There are several kinds of target files that may be installed: ``ARCHIVE`` Static libraries are treated as ``ARCHIVE`` targets, except those - marked with the ``FRAMEWORK`` property on OS X (see ``FRAMEWORK`` + marked with the ``FRAMEWORK`` property on macOS (see ``FRAMEWORK`` below.) For DLL platforms (all Windows-based systems including Cygwin), the DLL import library is treated as an ``ARCHIVE`` target. ``LIBRARY`` Module libraries are always treated as ``LIBRARY`` targets. For non- DLL platforms shared libraries are treated as ``LIBRARY`` targets, - except those marked with the ``FRAMEWORK`` property on OS X (see + except those marked with the ``FRAMEWORK`` property on macOS (see ``FRAMEWORK`` below.) ``RUNTIME`` Executables are treated as ``RUNTIME`` objects, except those marked - with the ``MACOSX_BUNDLE`` property on OS X (see ``BUNDLE`` below.) + with the ``MACOSX_BUNDLE`` property on macOS (see ``BUNDLE`` below.) For DLL platforms (all Windows-based systems including Cygwin), the DLL part of a shared library is treated as a ``RUNTIME`` target. @@ -137,11 +144,11 @@ project. There are several kinds of target files that may be installed: ``FRAMEWORK`` Both static and shared libraries marked with the ``FRAMEWORK`` - property are treated as ``FRAMEWORK`` targets on OS X. + property are treated as ``FRAMEWORK`` targets on macOS. ``BUNDLE`` Executables marked with the ``MACOSX_BUNDLE`` property are treated as - ``BUNDLE`` targets on OS X. + ``BUNDLE`` targets on macOS. ``PUBLIC_HEADER`` Any ``PUBLIC_HEADER`` files associated with a library are installed in @@ -280,6 +287,14 @@ targets that link to the object libraries in their implementation. Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property set to ``TRUE`` has undefined behavior. +:command:`install(TARGETS)` can install targets that were created in +other directories. When using such cross-directory install rules, running +``make install`` (or similar) from a subdirectory will not guarantee that +targets from other directories are up-to-date. You can use +:command:`target_link_libraries` or :command:`add_dependencies` +to ensure that such out-of-directory targets are built before the +subdirectory-specific install rules are run. + The install destination given to the target install ``DESTINATION`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. @@ -427,6 +442,10 @@ example, the code will print a message during installation. +The contents of ``SCRIPT`` or ``CODE`` may use "generator expressions" with +the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. + Installing Exports ^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/link_directories.rst b/Help/command/link_directories.rst index 5c64bc6..1dce9a0 100644 --- a/Help/command/link_directories.rst +++ b/Help/command/link_directories.rst @@ -1,19 +1,51 @@ link_directories ---------------- -Specify directories in which the linker will look for libraries. +Add directories in which the linker will look for libraries. :: - link_directories(directory1 directory2 ...) + link_directories([AFTER|BEFORE] directory1 [directory2 ...]) -Specify the paths in which the linker should search for libraries. -The command will apply only to targets created after it is called. +Add the paths in which the linker should search for libraries. Relative paths given to this command are interpreted as relative to the current source directory, see :policy:`CMP0015`. -Note that this command is rarely necessary. Library locations -returned by :command:`find_package` and :command:`find_library` are -absolute paths. Pass these absolute library file paths directly to the -:command:`target_link_libraries` command. CMake will ensure the linker finds -them. +The directories are added to the :prop_dir:`LINK_DIRECTORIES` directory +property for the current ``CMakeLists.txt`` file, converting relative +paths to absolute as needed. +The command will apply only to targets created after it is called. + +By default the directories specified are appended onto the current list of +directories. This default behavior can be changed by setting +:variable:`CMAKE_LINK_DIRECTORIES_BEFORE` to ``ON``. By using +``AFTER`` or ``BEFORE`` explicitly, you can select between appending and +prepending, independent of the default. + +Arguments to ``link_directories`` may use "generator expressions" 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. + +.. note:: + + This command is rarely necessary and should be avoided where there are + other choices. Prefer to pass full absolute paths to libraries where + possible, since this ensures the correct library will always be linked. + The :command:`find_library` command provides the full path, which can + generally be used directly in calls to :command:`target_link_libraries`. + Situations where a library search path may be needed include: + + - Project generators like Xcode where the user can switch target + architecture at build time, but a full path to a library cannot + be used because it only provides one architecture (i.e. it is not + a universal binary). + - Libraries may themselves have other private library dependencies + that expect to be found via ``RPATH`` mechanisms, but some linkers + are not able to fully decode those paths (e.g. due to the presence + of things like ``$ORIGIN``). + + If a library search path must be provided, prefer to localize the effect + where possible by using the :command:`target_link_directories` command + rather than ``link_directories()``. The target-specific command can also + control how the search directories propagate to other dependent targets. diff --git a/Help/command/list.rst b/Help/command/list.rst index 589e572..ad2c428 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -28,7 +28,7 @@ Synopsis `Ordering`_ list(`REVERSE`_ <list>) - list(`SORT`_ <list>) + list(`SORT`_ <list> [...]) Introduction ^^^^^^^^^^^^ @@ -253,7 +253,23 @@ Reverses the contents of the list in-place. :: - list(SORT <list>) - + list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>]) Sorts the list in-place alphabetically. +Use the option ``<compare>`` to select the compare type for sorting. +The ``<compare>`` option may be one of: + +* ``STRING``: Sorts a list of strings alphabetically. +* ``FILE_BASENAME``: Sort a list of pathnames of files by their basenames. + +Use the option ``<case>`` to select a case sensitive or case insensitive sort mode. +The ``<case>`` option may be one of: + +* ``SENSITIVE``: Sorts the list alphabetically. +* ``INSENSITIVE``: Sorts the list alphabetically in descending order. + +Use the option ``<order>`` to select a case sensitive or case insensitive sort mode. +The ``<order>`` option may be one of: + +* ``ASCENDING``: Sorts the list in ascending order. +* ``DESCENDING``: Sorts the list in descending order. diff --git a/Help/command/math.rst b/Help/command/math.rst index f99dc3d..63af931 100644 --- a/Help/command/math.rst +++ b/Help/command/math.rst @@ -5,10 +5,26 @@ Mathematical expressions. :: - math(EXPR <output-variable> <math-expression>) + math(EXPR <output-variable> <math-expression> [OUTPUT_FORMAT <format>]) ``EXPR`` evaluates mathematical expression and returns result in the output variable. Example mathematical expression is ``5 * (10 + 13)``. Supported operators are ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``, ``^``, ``~``, ``<<``, ``>>``, and ``(...)``. They have the same meaning as they do in C code. + +Numeric constants are evaluated in decimal or hexadecimal representation. + +The result is formatted according to the option "OUTPUT_FORMAT" , +where ``<format>`` is one of: +:: + + HEXADECIMAL = Result in output variable will be formatted in C code + Hexadecimal notation. + DECIMAL = Result in output variable will be formatted in decimal notation. + + +For example:: + + math(EXPR value "100 * 0xA" DECIMAL) results in value is set to "1000" + math(EXPR value "100 * 0xA" HEXADECIMAL) results in value is set to "0x3e8" diff --git a/Help/command/option.rst b/Help/command/option.rst index 91cd0a7..4fabb87 100644 --- a/Help/command/option.rst +++ b/Help/command/option.rst @@ -9,7 +9,9 @@ Provides an option that the user can optionally select. [initial value]) Provide an option for the user to select as ``ON`` or ``OFF``. If no -initial value is provided, ``OFF`` is used. +initial value is provided, ``OFF`` is used. If the option is already +set as a normal variable then the command does nothing +(see policy :policy:`CMP0077`). If you have options that depend on the values of other options, see the module help for :module:`CMakeDependentOption`. diff --git a/Help/command/set_directory_properties.rst b/Help/command/set_directory_properties.rst index e485fce..42e7fd7 100644 --- a/Help/command/set_directory_properties.rst +++ b/Help/command/set_directory_properties.rst @@ -1,12 +1,11 @@ set_directory_properties ------------------------ -Set a property of the directory. +Set properties of the current directory and subdirectories in key-value pairs. :: set_directory_properties(PROPERTIES prop1 value1 prop2 value2) -Set a property for the current directory and subdirectories. See -:ref:`Directory Properties` for the list of properties known -to CMake. +See :ref:`Directory Properties` for the list of properties known to CMake +and their individual documentation for the behavior of each property. diff --git a/Help/command/string.rst b/Help/command/string.rst index efa923b..29a153a 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -151,6 +151,20 @@ has lower precedence than concatenation. This means that the regular expression ``^ab+d$`` matches ``abbd`` but not ``ababd``, and the regular expression ``^(ab|cd)$`` matches ``ab`` but not ``abd``. +Backslash (``\``) characters in regular expressions are interpreted +literally and do not escape anything or represent placeholders. +However, CMake language :ref:`Escape Sequences` such as ``\t``, +``\r``, ``\n``, and ``\\`` may be used to construct literal tabs, +carriage returns, newlines, and backslashes (respectively) to pass +in a regex. For example: + +* The quoted argument ``"[ \t\r\n]"`` specifies a regex that matches + any single whitespace character. +* The quoted argument ``"[/\\]"`` specifies a regex that matches + a single forward slash ``/`` or backslash ``\``. +* The quoted argument ``"[A-Za-z0-9_]"`` specifies a regex that matches + any single "word" character in the C locale. + Manipulation ^^^^^^^^^^^^ diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index 194d008..88b7f15 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst @@ -39,4 +39,4 @@ 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. -.. include:: COMPILE_OPTIONS_SHELL.txt +.. include:: OPTIONS_SHELL.txt diff --git a/Help/command/target_link_directories.rst b/Help/command/target_link_directories.rst new file mode 100644 index 0000000..b46aac0 --- /dev/null +++ b/Help/command/target_link_directories.rst @@ -0,0 +1,55 @@ +target_link_directories +----------------------- + +Add link directories to a target. + +:: + + target_link_directories(<target> [BEFORE] + <INTERFACE|PUBLIC|PRIVATE> [items1...] + [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + +Specify the paths in which the linker should search for libraries when +linking a given target. Each item can be an absolute or relative path, +with the latter being interpreted as relative to the current source +directory. These items will be added to the link command. + +The named ``<target>`` must have been created by a command such as +:command:`add_executable` or :command:`add_library` and must not be an +:ref:`ALIAS target <Alias Targets>`. + +The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to +specify the scope of the items that follow them. ``PRIVATE`` and +``PUBLIC`` items will populate the :prop_tgt:`LINK_DIRECTORIES` property +of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_LINK_DIRECTORIES` property of ``<target>`` +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items). +Each item specifies a link directory and will be converted to an absolute +path if necessary before adding it to the relevant property. Repeated +calls for the same ``<target>`` append items in the order called. + +If ``BEFORE`` is specified, the content will be prepended to the relevant +property instead of being appended. + +Arguments to ``target_link_directories`` may use "generator expressions" +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. + +.. note:: + + This command is rarely necessary and should be avoided where there are + other choices. Prefer to pass full absolute paths to libraries where + possible, since this ensures the correct library will always be linked. + The :command:`find_library` command provides the full path, which can + generally be used directly in calls to :command:`target_link_libraries`. + Situations where a library search path may be needed include: + + - Project generators like Xcode where the user can switch target + architecture at build time, but a full path to a library cannot + be used because it only provides one architecture (i.e. it is not + a universal binary). + - Libraries may themselves have other private library dependencies + that expect to be found via ``RPATH`` mechanisms, but some linkers + are not able to fully decode those paths (e.g. due to the presence + of things like ``$ORIGIN``). diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index fcc2c07..e1c374e 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -18,10 +18,13 @@ All of them have the general form:: target_link_libraries(<target> ... <item>... ...) -The named ``<target>`` must have been created in the current directory by -a command such as :command:`add_executable` or :command:`add_library` and -must not be an :ref:`ALIAS target <Alias Targets>`. -Repeated calls for the same ``<target>`` append items in the order called. +The named ``<target>`` must have been created by a command such as +:command:`add_executable` or :command:`add_library` and must not be an +:ref:`ALIAS target <Alias Targets>`. If policy :policy:`CMP0079` is not +set to ``NEW`` then the target must have been created in the current +directory. Repeated calls for the same ``<target>`` append items in +the order called. + Each ``<item>`` may be: * **A library target name**: The generated link line will have the @@ -70,7 +73,8 @@ Each ``<item>`` may be: Link flags specified here are inserted into the link command in the same place as the link libraries. This might not be correct, depending on - the linker. Use the :prop_tgt:`LINK_FLAGS` target property to add link + the linker. Use the :prop_tgt:`LINK_OPTIONS` target property or + :command:`target_link_options` command to add link flags explicitly. The flags will then be placed at the toolchain-defined flag position in the link command. diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst new file mode 100644 index 0000000..8f47180 --- /dev/null +++ b/Help/command/target_link_options.rst @@ -0,0 +1,42 @@ +target_link_options +------------------- + +Add link options to a target. + +:: + + target_link_options(<target> [BEFORE] + <INTERFACE|PUBLIC|PRIVATE> [items1...] + [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + +Specify link options to use when linking a given target. The +named ``<target>`` must have been created by a command such as +:command:`add_executable` or :command:`add_library` and must not be an +:ref:`ALIAS target <Alias Targets>`. + +If ``BEFORE`` is specified, the content will be prepended to the property +instead of being appended. + +This command can be used to add any options, but +alternative commands exist to add libraries +(:command:`target_link_libraries` and :command:`link_libraries`). +See documentation of the :prop_dir:`directory <LINK_OPTIONS>` and +:prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties. + +The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to +specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` +items will populate the :prop_tgt:`LINK_OPTIONS` property of +``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_LINK_OPTIONS` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify link options. Repeated calls for the same +``<target>`` append items in the order called. + +Arguments to ``target_link_options`` may use "generator expressions" +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. + +.. include:: LINK_OPTIONS_LINKER.txt + +.. include:: OPTIONS_SHELL.txt diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index a4f5196..5dd8d86 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -9,7 +9,9 @@ Add sources to a target. <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specify sources to use when compiling a given target. The +Specify sources to use when compiling a given target. Relative +source file paths are interpreted as being relative to the current +source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an :ref:`ALIAS target <Alias Targets>`. @@ -27,3 +29,6 @@ Arguments to ``target_sources`` may use "generator expressions" 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. + +See also the :policy:`CMP0076` policy for older behavior related to the +handling of relative source file paths. diff --git a/Help/command/unset.rst b/Help/command/unset.rst index a1fc95c..c19dd31 100644 --- a/Help/command/unset.rst +++ b/Help/command/unset.rst @@ -7,9 +7,16 @@ Unset a variable, cache variable, or environment variable. unset(<variable> [CACHE | PARENT_SCOPE]) -Removes the specified variable causing it to become undefined. If -``CACHE`` is present then the variable is removed from the cache instead -of the current scope. +Removes a normal variable from the current scope, causing it +to become undefined. If ``CACHE`` is present, then a cache variable +is removed instead of a normal variable. Note that when evaluating +:ref:`Variable References` of the form ``${VAR}``, CMake first searches +for a normal variable with that name. If no such normal variable exists, +CMake will then search for a cache entry with that name. Because of this +unsetting a normal variable can expose a cache variable that was previously +hidden. To force a variable reference of the form ``${VAR}`` to return an +empty string, use ``set(<variable> "")``, which clears the normal variable +but leaves it defined. If ``PARENT_SCOPE`` is present then the variable is removed from the scope above the current scope. See the same option in the :command:`set` command |