diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/FIND_XXX.txt | 5 | ||||
| -rw-r--r-- | Help/command/add_library.rst | 9 | ||||
| -rw-r--r-- | Help/command/find_package.rst | 5 | ||||
| -rw-r--r-- | Help/command/if.rst | 3 | ||||
| -rw-r--r-- | Help/command/install.rst | 23 | ||||
| -rw-r--r-- | Help/command/string.rst | 52 | ||||
| -rw-r--r-- | Help/manual/cmake-buildsystem.7.rst | 12 | ||||
| -rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 4 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 1 | ||||
| -rw-r--r-- | Help/prop_tgt/IMPORTED_OBJECTS.rst | 11 | ||||
| -rw-r--r-- | Help/prop_tgt/IMPORTED_OBJECTS_CONFIG.rst | 7 | ||||
| -rw-r--r-- | Help/release/dev/FindMPI-add-imported-targets.rst | 4 | ||||
| -rw-r--r-- | Help/release/dev/add_custom_command-TARGET_OBJECTS.rst | 6 | ||||
| -rw-r--r-- | Help/release/dev/add_library-TARGET_OBJECTS.rst | 5 | ||||
| -rw-r--r-- | Help/release/dev/file-GENERATE-TARGET_OBJECTS.rst | 6 | ||||
| -rw-r--r-- | Help/release/dev/install-TARGET_OBJECTS.rst | 8 | ||||
| -rw-r--r-- | Help/variable/CMAKE_MATCH_COUNT.rst | 7 | ||||
| -rw-r--r-- | Help/variable/CMAKE_MATCH_n.rst | 10 |
19 files changed, 132 insertions, 48 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index bd4d295..2f27764 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -73,6 +73,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: 1. Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a ``-DVAR=value``. + The values are interpreted as :ref:`;-lists <CMake Language Lists>`. This can be skipped if ``NO_CMAKE_PATH`` is passed. * |CMAKE_PREFIX_PATH_XXX| @@ -80,7 +81,9 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: * |CMAKE_XXX_MAC_PATH| 2. Search paths specified in cmake-specific environment variables. - These are intended to be set in the user's shell configuration. + These are intended to be set in the user's shell configuration, + and therefore use the host's native path separator + (``;`` on Windows and ``:`` on UNIX). This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed. * |CMAKE_PREFIX_PATH_XXX| diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index af75a39..3a76040 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -64,7 +64,7 @@ Imported Libraries :: - add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED + add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED [GLOBAL]) An :ref:`IMPORTED library target <Imported Targets>` references a library @@ -106,10 +106,9 @@ may contain only sources that compile, header files, and other files that would not affect linking of a normal library (e.g. ``.txt``). They may contain custom commands generating such sources, but not ``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands. Object libraries -cannot be imported, exported, installed, or linked. Some native build -systems may not like targets that have only object files, so consider -adding at least one real source file to any target that references -``$<TARGET_OBJECTS:objlib>``. +cannot be linked. Some native build systems may not like targets that +have only object files, so consider adding at least one real source file +to any target that references ``$<TARGET_OBJECTS:objlib>``. Alias Libraries ^^^^^^^^^^^^^^^ diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 2cb1e5f..60a77b8 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -251,6 +251,7 @@ enabled. 1. Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a ``-DVAR=value``. + The values are interpreted as :ref:`;-lists <CMake Language Lists>`. This can be skipped if ``NO_CMAKE_PATH`` is passed:: CMAKE_PREFIX_PATH @@ -258,7 +259,9 @@ enabled. CMAKE_APPBUNDLE_PATH 2. Search paths specified in cmake-specific environment variables. - These are intended to be set in the user's shell configuration. + These are intended to be set in the user's shell configuration, + and therefore use the host's native path separator + (``;`` on Windows and ``:`` on UNIX). This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed:: <package>_DIR diff --git a/Help/command/if.rst b/Help/command/if.rst index 2a087d0..edd343d 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -103,7 +103,8 @@ Possible expressions are: ``if(<variable|string> MATCHES regex)`` True if the given string or variable's value matches the given regular - expression. + expression. See :ref:`Regex Specification` for regex format. + ``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables. ``if(<variable|string> LESS <variable|string>)`` True if the given string or variable's value is a valid number and less diff --git a/Help/command/install.rst b/Help/command/install.rst index 70087a4..58438b7 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -73,7 +73,7 @@ Installing Targets :: install(TARGETS targets... [EXPORT <export-name>] - [[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE| + [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE| PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE] [DESTINATION <dir>] [PERMISSIONS permissions...] @@ -86,10 +86,10 @@ Installing Targets ) The ``TARGETS`` form specifies rules for installing targets from a -project. There are five kinds of target files that may be installed: -``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``FRAMEWORK``, and ``BUNDLE``. -Executables are treated as ``RUNTIME`` targets, except that those -marked with the ``MACOSX_BUNDLE`` property are treated as ``BUNDLE`` +project. There are six kinds of target files that may be installed: +``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``OBJECTS``, ``FRAMEWORK``, and +``BUNDLE``. Executables are treated as ``RUNTIME`` targets, except that +those marked with the ``MACOSX_BUNDLE`` property are treated as ``BUNDLE`` targets on OS X. Static libraries are treated as ``ARCHIVE`` targets, except that those marked with the ``FRAMEWORK`` property are treated as ``FRAMEWORK`` targets on OS X. @@ -99,10 +99,11 @@ targets, except that those marked with the ``FRAMEWORK`` property are treated as ``FRAMEWORK`` targets on OS X. For DLL platforms the DLL part of a shared library is treated as a ``RUNTIME`` target and the corresponding import library is treated as an ``ARCHIVE`` target. -All Windows-based systems including Cygwin are DLL platforms. -The ``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, and ``FRAMEWORK`` arguments -change the type of target to which the subsequent properties apply. -If none is given the installation properties apply to all target +All Windows-based systems including Cygwin are DLL platforms. Object +libraries are always treated as ``OBJECTS`` targets. +The ``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``OBJECTS``, and ``FRAMEWORK`` +arguments change the type of target to which the subsequent properties +apply. If none is given the installation properties apply to all target types. If only one is given then only targets of that type will be installed (which can be used to install just a DLL or just an import library). @@ -165,8 +166,8 @@ the ``mySharedLib`` DLL will be installed to ``<prefix>/bin`` and The ``EXPORT`` option associates the installed target files with an export called ``<export-name>``. It must appear before any ``RUNTIME``, -``LIBRARY``, or ``ARCHIVE`` options. To actually install the export -file itself, call ``install(EXPORT)``, documented below. +``LIBRARY``, ``ARCHIVE``, or ``OBJECTS`` options. To actually install the +export file itself, call ``install(EXPORT)``, documented below. Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property set to ``TRUE`` has undefined behavior. diff --git a/Help/command/string.rst b/Help/command/string.rst index 698a91d..4f0c45c 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -77,31 +77,43 @@ The replace expression may refer to paren-delimited subexpressions of the match using ``\1``, ``\2``, ..., ``\9``. Note that two backslashes (``\\1``) are required in CMake code to get a backslash through argument parsing. +.. _`Regex Specification`: + Regex Specification """"""""""""""""""" The following characters have special meaning in regular expressions: -:: - - ^ Matches at beginning of input - $ Matches at end of input - . Matches any single character - [ ] Matches any character(s) inside the brackets - [^ ] Matches any character(s) not inside the brackets - - Inside brackets, specifies an inclusive range between - characters on either side e.g. [a-f] is [abcdef] - To match a literal - using brackets, make it the first - or the last character e.g. [+*/-] matches basic - mathematical operators. - * Matches preceding pattern zero or more times - + Matches preceding pattern one or more times - ? Matches preceding pattern zero or once only - | Matches a pattern on either side of the | - () Saves a matched subexpression, which can be referenced - in the REGEX REPLACE operation. Additionally it is saved - by all regular expression-related commands, including - e.g. if( MATCHES ), in the variables CMAKE_MATCH_(0..9). +``^`` + Matches at beginning of input +``$`` + Matches at end of input +``.`` + Matches any single character +``[ ]`` + Matches any character(s) inside the brackets +``[^ ]`` + Matches any character(s) not inside the brackets +``-`` + Inside brackets, specifies an inclusive range between + characters on either side e.g. ``[a-f]`` is ``[abcdef]`` + To match a literal ``-`` using brackets, make it the first + or the last character e.g. ``[+*/-]`` matches basic + mathematical operators. +``*`` + Matches preceding pattern zero or more times +``+`` + Matches preceding pattern one or more times +``?`` + Matches preceding pattern zero or once only +``|`` + Matches a pattern on either side of the ``|`` +``()`` + Saves a matched subexpression, which can be referenced + in the ``REGEX REPLACE`` operation. Additionally it is saved + by all regular expression-related commands, including + e.g. :command:`if(MATCHES)`, in the variables + :variable:`CMAKE_MATCH_<n>` for ``<n>`` 0..9. ``*``, ``+`` and ``?`` have higher precedence than concatenation. ``|`` has lower precedence than concatenation. This means that the regular diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 2e6a803..95f5b87 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -125,10 +125,10 @@ The object files collection can be used as source inputs to other targets: add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp) -``OBJECT`` libraries may only be used locally as sources in a buildsystem -- -they may not be installed, exported, or used in the right hand side of +``OBJECT`` libraries may not be used in the right hand side of :command:`target_link_libraries`. They also may not be used as the ``TARGET`` -in a use of the :command:`add_custom_command(TARGET)` command signature. +in a use of the :command:`add_custom_command(TARGET)` command signature. They +may be installed, and will be exported as an INTERFACE library. Although object libraries may not be named directly in calls to the :command:`target_link_libraries` command, they can be "linked" @@ -136,6 +136,12 @@ indirectly by using an :ref:`Interface Library <Interface Libraries>` whose :prop_tgt:`INTERFACE_SOURCES` target property is set to name ``$<TARGET_OBJECTS:objlib>``. +Although object libraries may not be used as the ``TARGET`` +in a use of the :command:`add_custom_command(TARGET)` command signature, +the list of objects can be used by :command:`add_custom_command(OUTPUT)` or +:command:`file(GENERATE)` by using ``$<TARGET_OBJECTS:objlib>``. + + Build Specification and Usage Requirements ========================================== diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 3eac45f..bddb174 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -290,9 +290,7 @@ Available output expressions are: Content of ``...`` converted to a C identifier. ``$<TARGET_OBJECTS:objLib>`` List of objects resulting from build of ``objLib``. ``objLib`` must be an - object of type ``OBJECT_LIBRARY``. This expression may only be used in - the sources of :command:`add_library` and :command:`add_executable` - commands. + object of type ``OBJECT_LIBRARY``. ``$<SHELL_PATH:...>`` Content of ``...`` converted to shell path style. For example, slashes are converted to backslashes in Windows shells and drive letters are converted diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 27c75dc..31b2389 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -194,6 +194,8 @@ Properties on Targets /prop_tgt/IMPORTED_LOCATION /prop_tgt/IMPORTED_NO_SONAME_CONFIG /prop_tgt/IMPORTED_NO_SONAME + /prop_tgt/IMPORTED_OBJECTS_CONFIG + /prop_tgt/IMPORTED_OBJECTS /prop_tgt/IMPORTED /prop_tgt/IMPORTED_SONAME_CONFIG /prop_tgt/IMPORTED_SONAME diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 7347bcc..4317f67 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -56,6 +56,7 @@ Variables that Provide Information /variable/CMAKE_MAJOR_VERSION /variable/CMAKE_MAKE_PROGRAM /variable/CMAKE_MATCH_COUNT + /variable/CMAKE_MATCH_n /variable/CMAKE_MINIMUM_REQUIRED_VERSION /variable/CMAKE_MINOR_VERSION /variable/CMAKE_PARENT_LIST_FILE diff --git a/Help/prop_tgt/IMPORTED_OBJECTS.rst b/Help/prop_tgt/IMPORTED_OBJECTS.rst new file mode 100644 index 0000000..222e6cc --- /dev/null +++ b/Help/prop_tgt/IMPORTED_OBJECTS.rst @@ -0,0 +1,11 @@ +IMPORTED_OBJECTS +---------------- + +:ref:`;-list <CMake Language Lists>` of absolute paths to the object +files on disk for an :ref:`imported <Imported targets>` +:ref:`object library <object libraries>`. + +Ignored for non-imported targets. + +Projects may skip ``IMPORTED_OBJECTS`` if the configuration-specific +property :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>` is set instead. diff --git a/Help/prop_tgt/IMPORTED_OBJECTS_CONFIG.rst b/Help/prop_tgt/IMPORTED_OBJECTS_CONFIG.rst new file mode 100644 index 0000000..4419ed1 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_OBJECTS_CONFIG.rst @@ -0,0 +1,7 @@ +IMPORTED_OBJECTS_<CONFIG> +------------------------- + +<CONFIG>-specific version of :prop_tgt:`IMPORTED_OBJECTS` property. + +Configuration names correspond to those provided by the project from +which the target is imported. diff --git a/Help/release/dev/FindMPI-add-imported-targets.rst b/Help/release/dev/FindMPI-add-imported-targets.rst new file mode 100644 index 0000000..c0a7bfc --- /dev/null +++ b/Help/release/dev/FindMPI-add-imported-targets.rst @@ -0,0 +1,4 @@ +FindMPI-add-imported-targets +------------------------------ + +* The :module:`FindMPI` module now provides imported targets. diff --git a/Help/release/dev/add_custom_command-TARGET_OBJECTS.rst b/Help/release/dev/add_custom_command-TARGET_OBJECTS.rst new file mode 100644 index 0000000..c4a9ee8 --- /dev/null +++ b/Help/release/dev/add_custom_command-TARGET_OBJECTS.rst @@ -0,0 +1,6 @@ +add_custom_command-TARGET_OBJECTS +--------------------------------- + +* The :command:`add_custom_command` command learned to evaluate the + ``TARGET_OBJECTS`` + :manual:`generator expression <cmake-generator-expressions(7)>`. diff --git a/Help/release/dev/add_library-TARGET_OBJECTS.rst b/Help/release/dev/add_library-TARGET_OBJECTS.rst new file mode 100644 index 0000000..964064e --- /dev/null +++ b/Help/release/dev/add_library-TARGET_OBJECTS.rst @@ -0,0 +1,5 @@ +add_library-TARGET_OBJECTS +-------------------------- + +* The :command:`add_library` command ``IMPORTED`` option learned to support + :ref:`Object Libraries`. diff --git a/Help/release/dev/file-GENERATE-TARGET_OBJECTS.rst b/Help/release/dev/file-GENERATE-TARGET_OBJECTS.rst new file mode 100644 index 0000000..853a803 --- /dev/null +++ b/Help/release/dev/file-GENERATE-TARGET_OBJECTS.rst @@ -0,0 +1,6 @@ +file-GENERATE-TARGET_OBJECTS +---------------------------- + +* The :command:`file(GENERATE)` subcommand learned to evaluate the + ``TARGET_OBJECTS`` + :manual:`generator expression <cmake-generator-expressions(7)>`. diff --git a/Help/release/dev/install-TARGET_OBJECTS.rst b/Help/release/dev/install-TARGET_OBJECTS.rst new file mode 100644 index 0000000..dbcf635 --- /dev/null +++ b/Help/release/dev/install-TARGET_OBJECTS.rst @@ -0,0 +1,8 @@ +install-TARGET_OBJECTS +---------------------- + +* The :command:`install(TARGETS)` command learned a new ``OBJECTS`` option to + specify where to install :ref:`Object Libraries`. + +* The :command:`install(EXPORT)` command learned how to export + :ref:`Object Libraries`. diff --git a/Help/variable/CMAKE_MATCH_COUNT.rst b/Help/variable/CMAKE_MATCH_COUNT.rst index 8b1c036..355e834 100644 --- a/Help/variable/CMAKE_MATCH_COUNT.rst +++ b/Help/variable/CMAKE_MATCH_COUNT.rst @@ -3,6 +3,7 @@ CMAKE_MATCH_COUNT The number of matches with the last regular expression. -When a regular expression match is used, CMake fills in ``CMAKE_MATCH_<n>`` -variables with the match contents. The ``CMAKE_MATCH_COUNT`` variable holds -the number of match expressions when these are filled. +When a regular expression match is used, CMake fills in +:variable:`CMAKE_MATCH_<n>` variables with the match contents. +The ``CMAKE_MATCH_COUNT`` variable holds the number of match +expressions when these are filled. diff --git a/Help/variable/CMAKE_MATCH_n.rst b/Help/variable/CMAKE_MATCH_n.rst new file mode 100644 index 0000000..c7dd623 --- /dev/null +++ b/Help/variable/CMAKE_MATCH_n.rst @@ -0,0 +1,10 @@ +CMAKE_MATCH_<n> +--------------- + +Capture group ``<n>`` matched by the last regular expression, for groups +0 through 9. Group 0 is the entire match. Groups 1 through 9 are the +subexpressions captured by ``()`` syntax. + +When a regular expression match is used, CMake fills in ``CMAKE_MATCH_<n>`` +variables with the match contents. The :variable:`CMAKE_MATCH_COUNT` +variable holds the number of match expressions when these are filled. |