diff options
Diffstat (limited to 'Help/command')
| -rw-r--r-- | Help/command/FIND_XXX.txt | 9 | ||||
| -rw-r--r-- | Help/command/cmake_command.rst | 90 | ||||
| -rw-r--r-- | Help/command/execute_process.rst | 13 | ||||
| -rw-r--r-- | Help/command/file.rst | 107 | ||||
| -rw-r--r-- | Help/command/function.rst | 4 | ||||
| -rw-r--r-- | Help/command/install.rst | 54 | ||||
| -rw-r--r-- | Help/command/macro.rst | 4 | ||||
| -rw-r--r-- | Help/command/string.rst | 21 |
8 files changed, 274 insertions, 28 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 42bf52b..cebe051 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -15,6 +15,7 @@ The general signature is: [PATHS path1 [path2 ... ENV var]] [PATH_SUFFIXES suffix1 [suffix2 ...]] [DOC "cache documentation string"] + [REQUIRED] [NO_DEFAULT_PATH] [NO_PACKAGE_ROOT_PATH] [NO_CMAKE_PATH] @@ -31,8 +32,9 @@ A cache entry named by ``<VAR>`` is created to store the result of this command. If the |SEARCH_XXX| is found the result is stored in the variable and the search will not be repeated unless the variable is cleared. -If nothing is found, the result will be -``<VAR>-NOTFOUND``, and the search will be attempted again the +If nothing is found, the result will be ``<VAR>-NOTFOUND``. +The ``REQUIRED`` option stops processing with an error message if nothing +is found, otherwise the search will be attempted again the next time |FIND_XXX| is invoked with the same variable. Options include: @@ -57,6 +59,9 @@ Options include: ``DOC`` Specify the documentation string for the ``<VAR>`` cache entry. +``REQUIRED`` + Stop processing with an error message if nothing is found. + If ``NO_DEFAULT_PATH`` is specified, then no additional paths are added to the search. If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: diff --git a/Help/command/cmake_command.rst b/Help/command/cmake_command.rst new file mode 100644 index 0000000..08b7832 --- /dev/null +++ b/Help/command/cmake_command.rst @@ -0,0 +1,90 @@ +cmake_command +------------- + +Call meta-operations on CMake commands. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + cmake_command(`INVOKE`_ <command> [<args>...]) + cmake_command(`EVAL`_ CODE <code>...) + +Introduction +^^^^^^^^^^^^ + +This command will call meta-operations on built-in CMake commands or +those created via the :command:`macro` or :command:`function` commands. + +``cmake_command`` does not introduce a new variable or policy scope. + +Invoking Commands +^^^^^^^^^^^^^^^^^ + +.. _INVOKE: + +.. code-block:: cmake + + cmake_command(INVOKE <command> [<args>...]) + +Invokes the named ``<command>`` with the given arguments (if any). +For example, the code: + +.. code-block:: cmake + + set(message_command "message") + cmake_command(INVOKE ${message_command} STATUS "Hello World!") + +is equivalent to + +.. code-block:: cmake + + message(STATUS "Hello World!") + +Evaluating Code +^^^^^^^^^^^^^^^ + +.. _EVAL: + +.. code-block:: cmake + + cmake_command(EVAL CODE <code>...) + +Evaluates the ``<code>...`` as CMake code. + +For example, the code: + +.. code-block:: cmake + + set(A TRUE) + set(B TRUE) + set(C TRUE) + set(condition "(A AND B) OR C") + + cmake_command(EVAL CODE " + if (${condition}) + message(STATUS TRUE) + else() + message(STATUS FALSE) + endif()" + ) + +is equivalent to + +.. code-block:: cmake + + set(A TRUE) + set(B TRUE) + set(C TRUE) + set(condition "(A AND B) OR C") + + file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake " + if (${condition}) + message(STATUS TRUE) + else() + message(STATUS FALSE) + endif()" + ) + + include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake) diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index 14f879d..b32025f 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -21,7 +21,9 @@ Execute one or more child processes. [COMMAND_ECHO <where>] [OUTPUT_STRIP_TRAILING_WHITESPACE] [ERROR_STRIP_TRAILING_WHITESPACE] - [ENCODING <name>]) + [ENCODING <name>] + [ECHO_OUTPUT_VARIABLE] + [ECHO_ERROR_VARIABLE]) Runs the given sequence of one or more commands. @@ -105,6 +107,15 @@ Options: for this encoding. In CMake 3.11.0, ``UTF-8`` was added for consistency with the `UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention. +``ECHO_OUTPUT_VARIABLE``, ``ECHO_ERROR_VARIABLE`` + The standard output or standard error will not be exclusively redirected to + the configured variables. + + The output will be duplicated, it will be sent into the configured variables + and also on standard output or standard error. + + This is analogous to the ``tee`` Unix command. + If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the same pipe the precedence is not specified. If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will diff --git a/Help/command/file.rst b/Help/command/file.rst index df7d8ba..92cb2ed 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -19,6 +19,7 @@ Synopsis file({`WRITE`_ | `APPEND`_} <filename> <content>...) file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...]) file(`GENERATE`_ OUTPUT <output-file> [...]) + file(`CONFIGURE`_ OUTPUT <output-file> CONTENT <content> [...]) `Filesystem`_ file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...]) @@ -41,6 +42,10 @@ Synopsis `Locking`_ file(`LOCK`_ <path> [...]) + `Archiving`_ + file(`ARCHIVE_CREATE`_ OUTPUT <archive> FILES <files> [...]) + file(`ARCHIVE_EXTRACT`_ INPUT <archive> DESTINATION <dir> [...]) + Reading ^^^^^^^ @@ -54,7 +59,9 @@ Reading Read content from a file called ``<filename>`` and store it in a ``<variable>``. Optionally start from the given ``<offset>`` and read at most ``<max-in>`` bytes. The ``HEX`` option causes data to -be converted to a hexadecimal representation (useful for binary data). +be converted to a hexadecimal representation (useful for binary data). If the +``HEX`` option is specified, letters in the output (``a`` through ``f``) are in +lowercase. .. _STRINGS: @@ -482,6 +489,45 @@ generation phase. The output file will not yet have been written when the ``file(GENERATE)`` command returns, it is written only after processing all of a project's ``CMakeLists.txt`` files. +.. _CONFIGURE: + +.. code-block:: cmake + + file(CONFIGURE OUTPUT output-file + CONTENT content + [ESCAPE_QUOTES] [@ONLY] + [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) + +Generate an output file using the input given by ``CONTENT`` and substitute +variable values referenced as ``@VAR@`` or ``${VAR}`` contained therein. The +substitution rules behave the same as the :command:`configure_file` command. +In order to match :command:`configure_file`'s behavior, generator expressions +are not supported for both ``OUTPUT`` and ``CONTENT``. + +The arguments are: + +``OUTPUT <output-file>`` + Specify the output file name to generate. A relative path is treated with + respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. See policy + :policy:`CMP0070`. + ``<output-file>`` does not support generator expressions. + +``CONTENT <content>`` + Use the content given explicitly as input. + ``<content>`` does not support generator expressions. + +``ESCAPE_QUOTES`` + Escape any substituted quotes with backslashes (C-style). + +``@ONLY`` + Restrict variable replacement to references of the form ``@VAR@``. + This is useful for configuring scripts that use ``${VAR}`` syntax. + +``NEWLINE_STYLE <style>`` + Specify the newline style for the output file. Specify + ``UNIX`` or ``LF`` for ``\n`` newlines, or specify + ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines. + Filesystem ^^^^^^^^^^ @@ -846,3 +892,62 @@ child directory or file. Trying to lock file twice is not allowed. Any intermediate directories and file itself will be created if they not exist. ``GUARD`` and ``TIMEOUT`` options ignored on ``RELEASE`` operation. + +Archiving +^^^^^^^^^ + +.. _ARCHIVE_CREATE: + +.. code-block:: cmake + + file(ARCHIVE_CREATE OUTPUT <archive> + [FILES <files>] + [DIRECTORY <dirs>] + [FORMAT <format>] + [TYPE <type>] + [MTIME <mtime>] + [VERBOSE]) + +Creates an archive specifed by ``OUTPUT`` with the content of ``FILES`` and +``DIRECTORY``. + +To specify the format of the archive set the ``FORMAT`` option. +Supported formats are: ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw``, +(restricted pax, default), and ``zip``. + +To specify the type of compression set the ``TYPE`` option. +Supported compression types are: ``None``, ``BZip2``, ``GZip``, ``XZ``, +and ``Zstd``. + +.. note:: + With ``FORMAT`` set to ``raw`` only one file will be compressed with the + compression type specified by ``TYPE``. + +With ``VERBOSE`` the command will produce verbose output. + +To specify the modification time recorded in tarball entries use +the ``MTIME`` option. + +.. _ARCHIVE_EXTRACT: + +.. code-block:: cmake + + file(ARCHIVE_EXTRACT INPUT <archive> + [FILES <files>] + [DIRECTORY <dirs>] + [DESTINATION <dir>] + [LIST_ONLY] + [VERBOSE]) + +Extracts or lists the content of an archive specified by ``INPUT``. + +The directory where the content of the archive will be extracted can +be specified via ``DESTINATION``. If the directory does not exit, it +will be created. + +To select which files and directories will be extracted or listed +use ``FILES`` and ``DIRECTORY`` options. + +``LIST_ONLY`` will only list the files in the archive. + +With ``VERBOSE`` the command will produce verbose output. diff --git a/Help/command/function.rst b/Help/command/function.rst index 53ba754..30938b3 100644 --- a/Help/command/function.rst +++ b/Help/command/function.rst @@ -44,11 +44,15 @@ can be invoked through any of foo() Foo() FOO() + cmake_command(INVOKE foo) and so on. However, it is strongly recommended to stay with the case chosen in the function definition. Typically functions use all-lowercase names. +The :command:`cmake_command(INVOKE ...)` command can also be used to invoke the +function. + Arguments ^^^^^^^^^ diff --git a/Help/command/install.rst b/Help/command/install.rst index 5affc5b..abf6b17 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -30,13 +30,20 @@ signatures that specify them. The common options are: ``DESTINATION`` Specify the directory on disk to which a file will be installed. - If a full path (with a leading slash or drive letter) is given - it is used directly. If a relative path is given it is interpreted - relative to the value of the :variable:`CMAKE_INSTALL_PREFIX` variable. + Arguments can be relative or absolute paths. + + If a relative path is given it is interpreted relative to the value + of the :variable:`CMAKE_INSTALL_PREFIX` variable. The prefix can be relocated at install time using the ``DESTDIR`` mechanism explained in the :variable:`CMAKE_INSTALL_PREFIX` variable documentation. + If an absolute path (with a leading slash or drive letter) is given + it is used verbatim. + + As absolute paths are not supported by :manual:`cpack <cpack(1)>` installer + generators, it is preferable to use relative paths throughout. + ``PERMISSIONS`` Specify permissions for installed files. Valid permissions are ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``, @@ -119,31 +126,38 @@ Installing Targets ) The ``TARGETS`` form specifies rules for installing targets from a -project. There are several kinds of target files that may be installed: +project. There are several kinds of target :ref:`Output Artifacts` +that may be installed: ``ARCHIVE`` - Static libraries are treated as ``ARCHIVE`` targets, except those - 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. - On AIX, the linker import file created for executables with - :prop_tgt:`ENABLE_EXPORTS` is treated as an ``ARCHIVE`` target. + Target artifacts of this kind include: + + * *Static libraries* + (except on macOS when marked as ``FRAMEWORK``, see below); + * *DLL import libraries* + (on all Windows-based systems including Cygwin; they have extension + ``.lib``, in contrast to the ``.dll`` libraries that go to ``RUNTIME``); + * On AIX, the *linker import file* created for executables with + :prop_tgt:`ENABLE_EXPORTS` enabled. ``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 macOS (see - ``FRAMEWORK`` below.) + Target artifacts of this kind include: + + * *Shared libraries*, except + + - DLLs (these go to ``RUNTIME``, see below), + - on macOS when marked as ``FRAMEWORK`` (see below). ``RUNTIME`` - Executables are treated as ``RUNTIME`` objects, except those marked - 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. + Target artifacts of this kind include: + + * *Executables* + (except on macOS when marked as ``MACOSX_BUNDLE``, see ``BUNDLE`` below); + * DLLs (on all Windows-based systems including Cygwin; note that the + accompanying import libraries are of kind ``ARCHIVE``). ``OBJECTS`` - Object libraries (a simple group of object files) are always treated - as ``OBJECTS`` targets. + Object files associated with *object libraries*. ``FRAMEWORK`` Both static and shared libraries marked with the ``FRAMEWORK`` diff --git a/Help/command/macro.rst b/Help/command/macro.rst index 3f6f2f9..ee955cb 100644 --- a/Help/command/macro.rst +++ b/Help/command/macro.rst @@ -42,11 +42,15 @@ can be invoked through any of foo() Foo() FOO() + cmake_command(INVOKE foo) and so on. However, it is strongly recommended to stay with the case chosen in the macro definition. Typically macros use all-lowercase names. +The :command:`cmake_command(INVOKE ...)` command can also be used to invoke the +macro. + Arguments ^^^^^^^^^ diff --git a/Help/command/string.rst b/Help/command/string.rst index 81a2061..cfcf914 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -11,8 +11,6 @@ Synopsis `Search and Replace`_ string(`FIND`_ <string> <substring> <out-var> [...]) string(`REPLACE`_ <match-string> <replace-string> <out-var> <input>...) - - `Regular Expressions`_ string(`REGEX MATCH`_ <match-regex> <out-var> <input>...) string(`REGEX MATCHALL`_ <match-regex> <out-var> <input>...) string(`REGEX REPLACE`_ <match-regex> <replace-expr> <out-var> <input>...) @@ -38,6 +36,7 @@ Synopsis `Generation`_ string(`ASCII`_ <number>... <out-var>) + string(`HEX`_ <string> <out-var>) string(`CONFIGURE`_ <string> <out-var> [...]) string(`MAKE_C_IDENTIFIER`_ <string> <out-var>) string(`RANDOM`_ [<option>...] <out-var>) @@ -47,6 +46,9 @@ Synopsis Search and Replace ^^^^^^^^^^^^^^^^^^ +Search and Replace With Plain Strings +""""""""""""""""""""""""""""""""""""" + .. _FIND: .. code-block:: cmake @@ -74,8 +76,8 @@ so strings containing multi-byte characters may lead to unexpected results. Replace all occurrences of ``<match_string>`` in the ``<input>`` with ``<replace_string>`` and store the result in the ``<output_variable>``. -Regular Expressions -^^^^^^^^^^^^^^^^^^^ +Search and Replace With Regular Expressions +""""""""""""""""""""""""""""""""""""""""""" .. _`REGEX MATCH`: @@ -87,6 +89,7 @@ Regular Expressions Match the ``<regular_expression>`` once and store the match in the ``<output_variable>``. All ``<input>`` arguments are concatenated before matching. +Regular expressions are specified in the subsection just below. .. _`REGEX MATCHALL`: @@ -353,6 +356,16 @@ Generation Convert all numbers into corresponding ASCII characters. +.. _HEX: + +.. code-block:: cmake + + string(HEX <string> <output_variable>) + +Convert each byte in the input ``<string>`` to its hexadecimal representation +and store the concatenated hex digits in the ``<output_variable>``. Letters in +the output (``a`` through ``f``) are in lowercase. + .. _CONFIGURE: .. code-block:: cmake |