diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/FIND_XXX.txt | 9 | ||||
| -rw-r--r-- | Help/command/file.rst | 40 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 2 | ||||
| -rw-r--r-- | Help/release/3.17.rst | 37 | ||||
| -rw-r--r-- | Help/release/dev/file_configure.rst | 6 | ||||
| -rw-r--r-- | Help/release/dev/required_find_commands.rst | 6 |
7 files changed, 81 insertions, 21 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/file.rst b/Help/command/file.rst index 5877d43..5a479d9 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>...]) @@ -484,6 +485,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 ^^^^^^^^^^ diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 15f0cfc..5197bb6 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -391,7 +391,6 @@ Properties on Targets /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN /prop_tgt/XCODE_SCHEME_ARGUMENTS - /prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY /prop_tgt/XCODE_SCHEME_DEBUG_AS_ROOT /prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER @@ -408,6 +407,7 @@ Properties on Targets /prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP + /prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY /prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS /prop_tgt/XCTEST diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 7696fd9..c271024 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -247,7 +247,6 @@ Variables that Change Behavior /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN - /variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY /variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING /variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS @@ -262,6 +261,7 @@ Variables that Change Behavior /variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP + /variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY /variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS /variable/PackageName_ROOT diff --git a/Help/release/3.17.rst b/Help/release/3.17.rst index 23dec84..f2c4d85 100644 --- a/Help/release/3.17.rst +++ b/Help/release/3.17.rst @@ -47,12 +47,12 @@ Command-Line ------------ * :manual:`cmake(1)` gained a ``--debug-find`` command-line option to - enable additional human-readable output on where find commands search. + enable additional human-readable output on where ``find_*`` commands search. * :manual:`cmake(1)` gained a ``--trace-format`` command-line option that can be used to set the ``--trace`` output format. Currently, the old human readable and the new JSON format are supported. The new JSON format - is easier to parse automatically, than the existing format. + is easier to parse automatically than the existing format. * :manual:`cmake(1)` gained a ``-E rm`` command-line tool that can be used to remove directories and files. This supersedes the existing @@ -65,7 +65,7 @@ Commands ``DEPENDS`` arguments that are specified relative to the current binary directory. -* The :command:`foreach` learned a new option ``ZIP_LISTS`` to iterate +* The :command:`foreach` command learned a new ``ZIP_LISTS`` option to iterate over multiple lists simultaneously. * The :command:`load_cache(READ_WITH_PREFIX)` command mode is now allowed @@ -79,7 +79,7 @@ Commands * The :command:`message` command gained new keywords ``CHECK_START``, ``CHECK_PASS`` and ``CHECK_FAIL``. -* :command:`target_compile_options` command now honors the ``BEFORE`` +* The :command:`target_compile_options` command now honors the ``BEFORE`` keyword more consistently. See policy :policy:`CMP0101`. Variables @@ -102,7 +102,7 @@ Variables use CUDA. * The :variable:`CMAKE_FIND_DEBUG_MODE` variable was introduced to - print extra find call information during the cmake run to standard + print extra ``find_*`` call information during the cmake run to standard error. Output is designed for human consumption and not for parsing. * The :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable now takes its @@ -117,17 +117,20 @@ Variables to persist a log level between CMake runs, unlike the ``--log-level`` command line option which only applies to that particular run. -* The :variable:`CMAKE_XCODE_SCHEME_ENVIRONMENT` variable and - :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` target property were added to - tell the :generator:`Xcode` generator to set the value of the - ``Custom Working Directory`` schema option. +* The :variable:`CMAKE_XCODE_SCHEME_ENVIRONMENT` variable was added + to initialize the :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` target property. + +* The :variable:`CMAKE_XCODE_SCHEME_WORKING_DIRECTORY` variable and + associated :prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY` target property + were added to tell the :generator:`Xcode` generator to set the value of + the ``Custom Working Directory`` schema option. Properties ---------- * The :prop_tgt:`AIX_EXPORT_ALL_SYMBOLS` target property and associated :variable:`CMAKE_AIX_EXPORT_ALL_SYMBOLS` variable were created to - optionally explicitly disbale automatic export of symbols from shared + optionally explicitly disable automatic export of symbols from shared libraries on AIX. * The :prop_tgt:`DEPRECATION` target property was added to mark @@ -180,11 +183,11 @@ Modules * The :module:`FindPython3` and :module:`FindPython` modules gained, respectively, variable ``Python3_SOABI`` and ``Python_SOABI`` giving the standard extension suffix for modules. Moreover, commands - ``Python3_add_library`` and ``Python_add_library`` gained the option + ``Python3_add_library()`` and ``Python_add_library()`` gained the option ``WITH_SOABI`` to prefix the library suffix with the value of ``SOABI``. * The :module:`FindLibXml2` module now provides an imported target for the - ``xmllint`` executable + ``xmllint`` executable. Autogen ------- @@ -198,7 +201,7 @@ CTest * The :variable:`CTEST_CONFIGURATION_TYPE` variable is now set from the command line when :manual:`ctest(1)` is invoked with ``-C <cfg>``. -* The :manual:`ctest(1)` gained support for Dr. Memory to run +* The :manual:`ctest(1)` tool gained support for Dr. Memory to run memcheck runs. * The :manual:`ctest(1)` tool gained a ``--no-tests=<[error|ignore]>`` option @@ -246,9 +249,9 @@ CPack :variable:`CPACK_NSIS_FINISH_TITLE_3LINES`. These can be used to specify the finish page title and display it in 3 lines. -* The :cpack_gen:`CPack productbuild Generator` gained option - :variable:`CPACK_PRODUCTBUILD_BACKGROUND` to specify a background image - for the macOS installer. +* The :cpack_gen:`CPack productbuild Generator` gained support for a + :variable:`CPACK_PRODUCTBUILD_BACKGROUND` variable to specify a background + image for the macOS installer. Other ----- @@ -293,7 +296,7 @@ Other Changes See policy :policy:`CMP0099`. * When using MinGW tools, the :command:`find_library` command no longer - finds ``.dll`` files by default. Instead it expects ``.dll.a`` import + finds ``.dll`` files by default. Instead, it expects ``.dll.a`` import libraries to be available. * The :generator:`MinGW Makefiles` generator no longer issues an error if diff --git a/Help/release/dev/file_configure.rst b/Help/release/dev/file_configure.rst new file mode 100644 index 0000000..35e99c4 --- /dev/null +++ b/Help/release/dev/file_configure.rst @@ -0,0 +1,6 @@ +file_configure +-------------- + +* The :command:`file(CONFIGURE)` subcommand was created in order replicate the + :command:`configure_file` functionality without resorting to a pre-existing + file on disk as input. The content is instead passed as a string. diff --git a/Help/release/dev/required_find_commands.rst b/Help/release/dev/required_find_commands.rst new file mode 100644 index 0000000..cc2bf02 --- /dev/null +++ b/Help/release/dev/required_find_commands.rst @@ -0,0 +1,6 @@ +required_find_commands +---------------------- + +* The :command:`find_program`, :command:`find_library`, :command:`find_path` + and :command:`find_file` commands gained a new ``REQUIRED`` option that will + stop processing with an error message if nothing is found. |