diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/list.rst | 30 | ||||
| -rw-r--r-- | Help/cpack_gen/innosetup.rst | 420 | ||||
| -rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 264 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-presets.7.rst | 9 | ||||
| -rw-r--r-- | Help/manual/cpack-generators.7.rst | 1 | ||||
| -rw-r--r-- | Help/policy/CMP0105.rst | 5 | ||||
| -rw-r--r-- | Help/policy/CMP0150.rst | 39 | ||||
| -rw-r--r-- | Help/release/dev/ExternalProject-FetchContent-relative-git-remotes.rst | 7 | ||||
| -rw-r--r-- | Help/release/dev/FindDoxygen-custom-config-file.rst | 5 | ||||
| -rw-r--r-- | Help/release/dev/GenEx-LIST.rst | 4 | ||||
| -rw-r--r-- | Help/release/dev/cpack-innosetup.rst | 12 | ||||
| -rw-r--r-- | Help/release/dev/preset-includes-macro-expansion.rst | 7 |
13 files changed, 785 insertions, 19 deletions
diff --git a/Help/command/list.rst b/Help/command/list.rst index 191003a700..0c7a562872 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -188,7 +188,7 @@ For more information on regular expressions look under .. versionadded:: 3.12 - Transforms the list by applying an action to all or, by specifying a + Transforms the list by applying an ``<ACTION>`` to all or, by specifying a ``<SELECTOR>``, to the selected elements of the list, storing the result in-place or in the specified output variable. @@ -205,42 +205,42 @@ For more information on regular expressions look under :command:`APPEND <string(APPEND)>`, :command:`PREPEND <string(PREPEND)>` Append, prepend specified value to each element of the list. - .. code-block:: cmake - - list(TRANSFORM <list> <APPEND|PREPEND> <value> ...) + .. signature:: + list(TRANSFORM <list> (APPEND|PREPEND) <value> ...) + :target: TRANSFORM_APPEND - :command:`TOUPPER <string(TOUPPER)>`, :command:`TOLOWER <string(TOLOWER)>` - Convert each element of the list to upper, lower characters. + :command:`TOLOWER <string(TOLOWER)>`, :command:`TOUPPER <string(TOUPPER)>` + Convert each element of the list to lower, upper characters. - .. code-block:: cmake - - list(TRANSFORM <list> <TOLOWER|TOUPPER> ...) + .. signature:: + list(TRANSFORM <list> (TOLOWER|TOUPPER) ...) + :target: TRANSFORM_TOLOWER :command:`STRIP <string(STRIP)>` Remove leading and trailing spaces from each element of the list. - .. code-block:: cmake - + .. signature:: list(TRANSFORM <list> STRIP ...) + :target: TRANSFORM_STRIP :command:`GENEX_STRIP <string(GENEX_STRIP)>` Strip any :manual:`generator expressions <cmake-generator-expressions(7)>` from each element of the list. - .. code-block:: cmake - + .. signature:: list(TRANSFORM <list> GENEX_STRIP ...) + :target: TRANSFORM_GENEX_STRIP :command:`REPLACE <string(REGEX REPLACE)>`: Match the regular expression as many times as possible and substitute the replacement expression for the match for each element of the list (same semantic as :command:`string(REGEX REPLACE)`). - .. code-block:: cmake - + .. signature:: list(TRANSFORM <list> REPLACE <regular_expression> <replace_expression> ...) + :target: TRANSFORM_REPLACE ``<SELECTOR>`` determines which elements of the list will be transformed. Only one type of selector can be specified at a time. diff --git a/Help/cpack_gen/innosetup.rst b/Help/cpack_gen/innosetup.rst new file mode 100644 index 0000000000..f48e7f56c6 --- /dev/null +++ b/Help/cpack_gen/innosetup.rst @@ -0,0 +1,420 @@ +CPack Inno Setup Generator +-------------------------- + +.. versionadded:: 3.27 + +Inno Setup is a free installer for Windows programs by Jordan Russell and +Martijn Laan (https://jrsoftware.org/isinfo.php). + +This documentation explains Inno Setup generator specific options. + +The generator provides a lot of options like components. Unfortunately, not +all features (e.g. component dependencies) are currently supported by +Inno Setup and they're ignored by the generator for now. + +CPack requires Inno Setup 6 or greater and only works on Windows. + +Variables specific to CPack Inno Setup generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can use the following variables to change the behavior of the CPack +``INNOSETUP`` generator: + + +General +""""""" + +None of the following variables is required to be set for the Inno Setup +generator to work. If a variable is marked as mandatory below but not set, +its default value is taken. + +The variables can also contain Inno Setup constants like ``{app}``. Please +refer to the documentation of Inno Setup for more information. + +If you're asked to provide the path to any file, you can always give an +absolute path or in most cases the relative path from the top-level directory +where all files being installed by an :command:`install` instruction reside. + +CPack tries to escape quotes and other special characters for you. However, +using special characters could cause problems. + +The following variable simplifies the usage of Inno Setup in CMake: + +.. variable:: CPACK_INNOSETUP_USE_CMAKE_BOOL_FORMAT + + Inno Setup only uses ``yes`` or ``no`` as boolean formats meanwhile CMake + uses a lot of alternative formats like ``ON`` or ``OFF``. Having this option + turned on enables an automatic conversion. + + Consider the following example: + + .. code-block:: cmake + + set(CMAKE_INNOSETUP_SETUP_AllowNoIcons OFF) + + If this option is turned on, the following line will be created in the output + script: ``AllowNoIcons=no``. + Else, the following erroneous line will be created: ``AllowNoIcons=OFF`` + + The conversion is enabled in every Inno Setup specific variable. + + :Mandatory: Yes + :Default: ``ON`` + + +Setup Specific Variables +"""""""""""""""""""""""" + +.. variable:: CPACK_INNOSETUP_ARCHITECTURE + + One of ``x86``, ``x64``, ``arm64`` or ``ia64``. This variable specifies the + target architecture of the installer. This also affects the Program Files + folder or registry keys being used. + + CPack tries to determine the correct value with a try compile (see + :variable:`CMAKE_SIZEOF_VOID_P`), but this option can be manually specified + too (especially when using ``ia64`` or cross-platform compilation). + + :Mandatory: Yes + :Default: Either ``x86`` or ``x64`` depending on the results of the try-compile + +.. variable:: CPACK_INNOSETUP_INSTALL_ROOT + + If you don't want the installer to create the installation directory under + Program Files, you've to specify the installation root here. + + The full directory of the installation will be: + ``${CPACK_INNOSETUP_INSTALL_ROOT}/${CPACK_PACKAGE_INSTALL_DIRECTORY}``. + + :Mandatory: Yes + :Default: ``{autopf}`` + +.. variable:: CPACK_INNOSETUP_ALLOW_CUSTOM_DIRECTORY + + If turned on, the installer allows the user to change the installation + directory providing an extra wizard page. + + :Mandatory: Yes + :Default: ``ON`` + +.. variable:: CPACK_INNOSETUP_PROGRAM_MENU_FOLDER + + The initial name of the start menu folder being created. + + If this variable is set to ``.``, then no separate folder is created, + application shortcuts will appear in the top-level start menu folder. + + :Mandatory: Yes + :Default: The value of :variable:`CPACK_PACKAGE_NAME` + +.. variable:: CPACK_INNOSETUP_LANGUAGES + + A :ref:`semicolon-separated list <CMake Language Lists>` of languages you want + Inno Setup to include. + + Currently available: ``armenian``, ``brazilianPortuguese``, ``bulgarian``, + ``catalan``, ``corsican``, ``czech``, ``danish``, ``dutch``, ``english``, + ``finnish``, ``french``, ``german``, ``hebrew``, ``icelandic``, ``italian``, + ``japanese``, ``norwegian``, ``polish``, ``portuguese``, ``russian``, + ``slovak``, ``slovenian``, ``spanish``, ``turkish`` and ``ukrainian``. + This list might differ depending on the version of Inno Setup. + + :Mandatory: Yes + :Default: ``english`` + +.. variable:: CPACK_INNOSETUP_IGNORE_LICENSE_PAGE + + If you don't specify a license file using + :variable:`CPACK_RESOURCE_FILE_LICENSE`, CPack uses a file for demonstration + purposes. If you want the installer to ignore license files at all, you can + enable this option. + + :Mandatory: Yes + :Default: ``OFF`` + +.. variable:: CPACK_INNOSETUP_IGNORE_README_PAGE + + If you don't specify a readme file using + :variable:`CPACK_RESOURCE_FILE_README`, CPack uses a file for demonstration + purposes. If you want the installer to ignore readme files at all, you can + enable this option. Make sure the option is disabled when using + a custom readme file. + + :Mandatory: Yes + :Default: ``ON`` + +.. variable:: CPACK_INNOSETUP_PASSWORD + + Enables password protection and file encryption with the given password. + + :Mandatory: No + +.. variable:: CPACK_INNOSETUP_USE_MODERN_WIZARD + + Enables the modern look and feel provided by Inno Setup. If this option is + turned off, the classic style is used instead. Images and icon files are + also affected. + + :Mandatory: Yes + :Default: ``OFF`` because of compatibility reasons + +.. variable:: CPACK_INNOSETUP_ICON_FILE + + The path to a custom installer ``.ico`` file. + + Use :variable:`CPACK_PACKAGE_ICON` to customize the bitmap file being shown + in the wizard. + + :Mandatory: No + +.. variable:: CPACK_INNOSETUP_SETUP_<directive> + + This group allows adapting any of the ``[Setup]`` section directives provided + by Inno Setup where ``directive`` is its name. + + Here are some examples: + + .. code-block:: cmake + + set(CPACK_INNOSETUP_SETUP_WizardSmallImageFile "my_bitmap.bmp") + set(CPACK_INNOSETUP_SETUP_AllowNoIcons OFF) # This requires CPACK_INNOSETUP_USE_CMAKE_BOOL_FORMAT to be on + + All of these variables have higher priority than the others. + Consider the following example: + + .. code-block:: cmake + + set(CPACK_INNOSETUP_SETUP_Password "admin") + set(CPACK_INNOSETUP_PASSWORD "secret") + + The password will be ``admin`` at the end because ``CPACK_INNOSETUP_PASSWORD`` + has less priority than ``CPACK_INNOSETUP_SETUP_Password``. + + :Mandatory: No + + +File Specific Variables +""""""""""""""""""""""" + +Although all files being installed by an :command:`install` instruction are +automatically processed and added to the installer, there are some variables +to customize the installation process. + +Before using executables (only ``.exe`` or ``.com``) in shortcuts +(e.g. :variable:`CPACK_CREATE_DESKTOP_LINKS`) or ``[Run]`` entries, you've to +add the raw file name (without path and extension) to +:variable:`CPACK_PACKAGE_EXECUTABLES` and create a start menu shortcut +for them. + +If you have two files with the same raw name (e.g. ``a/executable.exe`` and +``b/executable.com``), an entry in the section is created twice. This will +result in undefined behavior and is not recommended. + +.. variable:: CPACK_INNOSETUP_CUSTOM_INSTALL_INSTRUCTIONS + + This variable should contain a + :ref:`semicolon-separated list <CMake Language Lists>` of pairs ``path``, + ``instruction`` and can be used to customize the install command being + automatically created for each file or directory. + + CPack creates the following Inno Setup instruction for every file... + + .. code-block:: + + Source: "absolute\path\to\my_file.txt"; DestDir: "{app}"; Flags: ignoreversion + + ...and the following line for every directory: + + .. code-block:: + + Name: "{app}\my_folder" + + You might want to change the destination directory or the flags of + ``my_file.txt``. Since we can also provide a relative path, the line you'd + like to have, is the following: + + .. code-block:: + + Source: "my_file.txt"; DestDir: "{userdocs}"; Flags: ignoreversion uninsneveruninstall + + You would do this by using ``my_file.txt`` as ``path`` and + ``Source: "my_file.txt"; DestDir: "{userdocs}"; Flags: ignoreversion uninsneveruninstall`` + as ``instruction``. + + You've to take care of the `escaping problem <https://cmake.org/cmake/help/book/mastering-cmake/chapter/Packaging%20With%20CPack.html#adding-custom-cpack-options>`_. + So the CMake command would be: + + .. code-block:: cmake + + set(CPACK_INNOSETUP_CUSTOM_INSTALL_INSTRUCTIONS "my_file.txt;Source: \\\"my_file.txt\\\"\\; DestDir: \\\"{userdocs}\\\"\\; Flags: ignoreversion uninsneveruninstall") + + To improve readability, you should go around the escaping problem by using + :variable:`CPACK_VERBATIM_VARIABLES` or by placing the instruction into a + separate CPack project config file. + + If you customize the install instruction of a specific file, you lose the + connection to its component. To go around, manually add + ``Components: <component>``. You also need to add its shortcuts and ``[Run]`` + entries by yourself in a custom section, since the executable won't be found + anymore by :variable:`CPACK_PACKAGE_EXECUTABLES`. + + Here's another example (Note: You've to go around the escaping problem for + the example to work): + + .. code-block:: cmake + + set(CPACK_INNOSETUP_CUSTOM_INSTALL_INSTRUCTIONS + "component1/my_folder" "Name: \"{userdocs}\\my_folder\"\; Components: component1" + "component2/my_folder2/my_file.txt" "Source: \"component2\\my_folder2\\my_file.txt\"\; DestDir: \"{app}\\my_folder2\\my_file.txt\"\; Flags: ignoreversion uninsneveruninstall\; Components: component2") + + :Mandatory: No + +.. variable:: CPACK_INNOSETUP_MENU_LINKS + + This variable should contain a + :ref:`semicolon-separated list <CMake Language Lists>` of pairs ``link``, + ``link name`` and can be used to add shortcuts into the start menu folder + beside those of the executables (see :variable:`CPACK_PACKAGE_EXECUTABLES`). + While ``link name`` is the label, ``link`` can be a URL or a path relative to + the installation directory. + + Here's an example: + + .. code-block:: cmake + + set(CPACK_INNOSETUP_MENU_LINKS + "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/cmake.html" + "CMake Help" "https://cmake.org" "CMake Web Site") + + :Mandatory: No + +.. variable:: CPACK_INNOSETUP_CREATE_UNINSTALL_LINK + + If this option is turned on, a shortcut to the application's uninstaller is + automatically added to the start menu folder. + + :Mandatory: Yes + :Default: ``OFF`` + +.. variable:: CPACK_INNOSETUP_RUN_EXECUTABLES + + A :ref:`semicolon-separated list <CMake Language Lists>` of executables being + specified in :variable:`CPACK_PACKAGE_EXECUTABLES` which the user can run + when the installer finishes. + + They're internally added to the ``[Run]`` section. + + :Mandatory: No + + +Components Specific Variables +""""""""""""""""""""""""""""" + +The generator supports components and also downloaded components. However, +there are some features of components that aren't supported yet (especially +component dependencies). These variables are ignored for now. + +CPack will change a component's name in Inno Setup if it has a parent group +for technical reasons. Consider using ``group\component`` as component name in +Inno Setup scripts if you have the component ``component`` and its parent +group ``group``. + +Here are some additional variables for components: + +.. variable:: CPACK_INNOSETUP_<compName>_INSTALL_DIRECTORY + + If you don't want the component ``compName`` to be installed under ``{app}``, + you've to specify its installation directory here. + + :Mandatory: No + +.. variable:: CPACK_INNOSETUP_VERIFY_DOWNLOADS + + This option only affects downloaded components. + + If this option is turned on, the hashes of the downloaded archives are + calculated during compile and + download time. The installer will only proceed if they match. + + :Mandatory: Yes + :Default: ``ON`` + + +Compilation and Scripting Specific Variables +"""""""""""""""""""""""""""""""""""""""""""" + +.. variable:: CPACK_INNOSETUP_EXECUTABLE + + The filename of the Inno Setup Script Compiler command. + + :Mandatory: Yes + :Default: ``ISCC`` + +.. variable:: CPACK_INNOSETUP_EXECUTABLE_ARGUMENTS + + A :ref:`semicolon-separated list <CMake Language Lists>` of extra + command-line options for the Inno Setup Script Compiler command. + + For example: ``/Qp;/Smysigntool=$p`` + + Take care of the `escaping problem <https://cmake.org/cmake/help/book/mastering-cmake/chapter/Packaging%20With%20CPack.html#adding-custom-cpack-options>`_. + + :Mandatory: No + +.. variable:: CPACK_INNOSETUP_DEFINE_<macro> + + This group allows to add custom define directives as command-line options to + the Inno Setup Preprocessor command. Each entry emulates a + ``#define public <macro>`` directive. Its macro is accessible from anywhere + (``public``), so it can also be used in extra script files. + + Macro names must not contain any special characters. Refer to the Inno Setup + Preprocessor documentation for the detailed rules. + + Consider the following example: + + .. code-block:: cmake + + # The following line emulates: #define public MyMacro "Hello, World!" + set(CPACK_INNOSETUP_DEFINE_MyMacro "Hello, World!") + + At this point, you can use ``MyMacro`` anywhere. For example in the following + extra script: + + .. code-block:: + + AppComments={#emit "'My Macro' has the value: " + MyMacro} + + Take care of the `escaping problem <https://cmake.org/cmake/help/book/mastering-cmake/chapter/Packaging%20With%20CPack.html#adding-custom-cpack-options>`_. + + :Mandatory: No + +.. variable:: CPACK_INNOSETUP_EXTRA_SCRIPTS + + A :ref:`semicolon-separated list <CMake Language Lists>` of paths to + additional ``.iss`` script files to be processed. + + They're internally included at the top of the output script file using a + ``#include`` directive. + + You can add any section in your file to extend the installer (e.g. adding + additional tasks or registry keys). Prefer using + :variable:`CPACK_INNOSETUP_SETUP_<directive>` when extending the + ``[Setup]`` section. + + :Mandatory: No + +.. variable:: CPACK_INNOSETUP_CODE_FILES + + A :ref:`semicolon-separated list <CMake Language Lists>` of paths to + additional Pascal files to be processed. + + This variable is actually the same as + :variable:`CPACK_INNOSETUP_EXTRA_SCRIPTS`, except you don't have to + add ``[Code]`` at the top of your file. Never change the current section in + a code file. This will result in undefined behavior! Treat them as normal + Pascal scripts instead. + + Code files are included at the very bottom of the output script. + + :Mandatory: No diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 9da37999b1..9d29dc38e3 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -104,6 +104,17 @@ improved further like so: VERBATIM ) +Finally, the above example can be expressed in a more simple and robust way +using an alternate generator expression: + +.. code-block:: cmake + + add_custom_target(run_some_tool + COMMAND some_tool "$<LIST:TRANSFORM,$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>,PREPEND,-I>" + COMMAND_EXPAND_LISTS + VERBATIM + ) + A common mistake is to try to split a generator expression across multiple lines with indenting: @@ -318,6 +329,15 @@ String Transformations List Expressions ---------------- +Most of the expressions in this section are closely associated with the +:command:`list` command, providing the same capabilities, but in +the form of a generator expression. + +.. _GenEx List Comparisons: + +List Comparisons +^^^^^^^^^^^^^^^^ + .. genex:: $<IN_LIST:string,list> .. versionadded:: 3.12 @@ -325,9 +345,186 @@ List Expressions ``1`` if ``string`` is an item in the semicolon-separated ``list``, else ``0``. It uses case-sensitive comparisons. -.. genex:: $<JOIN:list,string> +.. _GenEx List Queries: + +List Queries +^^^^^^^^^^^^ + +.. genex:: $<LIST:LENGTH,list> + + .. versionadded:: 3.27 + + Returns the list's length. + +.. genex:: $<LIST:GET,list,index,...> + + .. versionadded:: 3.27 + + Returns the list of elements specified by indices from the list. + +.. genex:: $<LIST:SUBLIST,list,begin,length> + + .. versionadded:: 3.27 + + Returns a sublist of the given list. If <length> is 0, an empty list will be + returned. If <length> is -1 or the list is smaller than <begin>+<length> then + the remaining elements of the list starting at <begin> will be returned. + +.. genex:: $<LIST:FIND,list,value> + + .. versionadded:: 3.27 + + Returns the index of the element specified in the list or -1 if it wasn't + found. + +.. _GenEx List Transformations: + +List Transformations +^^^^^^^^^^^^^^^^^^^^ + +.. genex:: $<LIST:JOIN,list,glue> + + .. versionadded:: 3.27 + + Returns a string which joins the list with the content of the ``glue`` string + inserted between each item. + +.. genex:: $<LIST:APPEND,list,element,...> + + .. versionadded:: 3.27 + + Returns a list with the elements appended. + +.. genex:: $<LIST:PREPEND,list,element,...> + + .. versionadded:: 3.27 + + Returns a list with the elements inserted at the beginning of the list. + +.. genex:: $<LIST:INSERT,list,index,element,...> + + .. versionadded:: 3.27 + + Returns a list with the elements inserted at the specified index. It is an + error to specify an out-of-range index. Valid indexes are 0 to N where N is + the length of the list, inclusive. An empty list has length 0. + +.. genex:: $<LIST:POP_BACK,list> + + .. versionadded:: 3.27 + + Returns a list with the last element was removed. + +.. genex:: $<LIST:POP_FRONT,list> + + .. versionadded:: 3.27 + + Returns a list with the first element was removed. + +.. genex:: $<LIST:REMOVE_ITEM,list,value,...> + + .. versionadded:: 3.27 + + Returns a list with all instances of the given values were removed. + +.. genex:: $<LIST:REMOVE_AT,list,index,...> + + .. versionadded:: 3.27 - Joins the list with the content of ``string`` inserted between each item. + Returns a list with all values at given indices were removed. + +.. genex:: $<LIST:REMOVE_DUPLICATES,list> + + .. versionadded:: 3.27 + + Returns a list where duplicated items were removed. The relative order of + items is preserved, but if duplicates are encountered, only the first + instance is preserved. + +.. genex:: $<LIST:FILTER,list,INCLUDE|EXCLUDE,regex> + + .. versionadded:: 3.27 + + Returns a list with the items that match the regular expression ``regex`` + were included or removed. + +.. genex:: $<LIST:TRANSFORM,list,ACTION[,SELECTOR]> + + .. versionadded:: 3.27 + + Returns the list transformed by applying an ``ACTION`` to all or, by + specifying a ``SELECTOR``, to the selected elements of the list. + + .. note:: + + The ``TRANSFORM`` sub-command does not change the number of elements in the + list. If a ``SELECTOR`` is specified, only some elements will be changed, + the other ones will remain the same as before the transformation. + + ``ACTION`` specifies the action to apply to the elements of the list. + The actions have exactly the same semantics as of the + :command:`list(TRANSFORM)` command. ``ACTION`` must be one of the following: + + :command:`APPEND <list(TRANSFORM_APPEND)>`, :command:`PREPEND <list(TRANSFORM_APPEND)>` + Append, prepend specified value to each element of the list. + + .. code-block:: cmake + + $<LIST:TRANSFORM,list,(APPEND|PREPEND),value[,SELECTOR]> + + :command:`TOLOWER <list(TRANSFORM_TOLOWER)>`, :command:`TOUPPER <list(TRANSFORM_TOLOWER)>` + Convert each element of the list to lower, upper characters. + + .. code-block:: cmake + + $<LIST:TRANSFORM,list,(TOLOWER|TOUPPER)[,SELECTOR]> + + :command:`STRIP <list(TRANSFORM_STRIP)>` + Remove leading and trailing spaces from each element of the list. + + .. code-block:: cmake + + $<LIST:TRANSFORM,list,STRIP[,SELECTOR]> + + :command:`REPLACE <list(TRANSFORM_REPLACE)>`: + Match the regular expression as many times as possible and substitute + the replacement expression for the match for each element of the list. + + .. code-block:: cmake + + $<LIST:TRANSFORM,list,REPLACE,regular_expression,replace_expression[,SELECTOR]> + + ``SELECTOR`` determines which elements of the list will be transformed. + Only one type of selector can be specified at a time. When given, + ``SELECTOR`` must be one of the following: + + ``AT`` + Specify a list of indexes. + + .. code-block:: cmake + + $<LIST:TRANSFORM,list,ACTION,AT,index[,index...]> + + ``FOR`` + Specify a range with, optionally, an increment used to iterate over the + range. + + .. code-block:: cmake + + $<LIST:TRANSFORM,list,ACTION,FOR,start,stop[,step]> + + ``REGEX`` + Specify a regular expression. + Only elements matching the regular expression will be transformed. + + .. code-block:: cmake + + $<LIST:TRANSFORM,list,ACTION,REGEX,regular_expression> + +.. genex:: $<JOIN:list,glue> + + Joins the list with the content of the ``glue`` string inserted between each + item. .. genex:: $<REMOVE_DUPLICATES:list> @@ -344,6 +541,69 @@ List Expressions Includes or removes items from ``list`` that match the regular expression ``regex``. +.. _GenEx List Ordering: + +List Ordering +^^^^^^^^^^^^^ + +.. genex:: $<LIST:REVERSE,list> + + .. versionadded:: 3.27 + + Returns the list with the elements in reverse order. + +.. genex:: $<LIST:SORT,list[,(COMPARE:option|CASE:option|ORDER:option)]...> + + .. versionadded:: 3.27 + + Returns the list sorted according the specified options. + + Use one of the ``COMPARE`` options to select the comparison method + for sorting: + + ``STRING`` + Sorts a list of strings alphabetically. + This is the default behavior if the ``COMPARE`` option is not given. + + ``FILE_BASENAME`` + Sorts a list of pathnames of files by their basenames. + + ``NATURAL`` + Sorts a list of strings using natural order + (see ``strverscmp(3)`` manual), i.e. such that contiguous digits + are compared as whole numbers. + For example: the following list `10.0 1.1 2.1 8.0 2.0 3.1` + will be sorted as `1.1 2.0 2.1 3.1 8.0 10.0` if the ``NATURAL`` + comparison is selected where it will be sorted as + `1.1 10.0 2.0 2.1 3.1 8.0` with the ``STRING`` comparison. + + Use one of the ``CASE`` options to select a case sensitive or case + insensitive sort mode: + + ``SENSITIVE`` + List items are sorted in a case-sensitive manner. + This is the default behavior if the ``CASE`` option is not given. + + ``INSENSITIVE`` + List items are sorted case insensitively. The order of + items which differ only by upper/lowercase is not specified. + + To control the sort order, one of the ``ORDER`` options can be given: + + ``ASCENDING`` + Sorts the list in ascending order. + This is the default behavior when the ``ORDER`` option is not given. + + ``DESCENDING`` + Sorts the list in descending order. + + This is an error to specify multiple times the same option. Various options + can be specified in any order: + + .. code-block:: cmake + + $<LIST:SORT,list,CASE:SENSITIVE,COMPARE:STRING,ORDER:DESCENDING> + Path Expressions ---------------- diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 8c7189a72b..ff573906b2 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -57,6 +57,7 @@ Policies Introduced by CMake 3.27 .. toctree:: :maxdepth: 1 + CMP0150: ExternalProject_Add and FetchContent_Declare treat relative git repository paths as being relative to parent project's remote. </policy/CMP0150> CMP0149: Visual Studio generators select latest Windows SDK by default. </policy/CMP0149> CMP0148: The FindPythonInterp and FindPythonLibs modules are removed. </policy/CMP0148> CMP0147: Visual Studio generators build custom commands in parallel. </policy/CMP0147> diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index 7794e45ce5..e2366da0ac 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -133,6 +133,9 @@ Files directly or indirectly included from ``CMakePresets.json`` should be guaranteed to be provided by the project. ``CMakeUserPresets.json`` may include files from anywhere. +Starting from version ``7``, the ``include`` field supports +`macro expansion`_, but only ``$penv{}`` macro expansion. + Configure Preset ^^^^^^^^^^^^^^^^ @@ -1057,6 +1060,12 @@ fields: a workflow preset may have the same name as a configure, build, test, or package preset. +``vendor`` + An optional map containing vendor-specific information. CMake does not + interpret the contents of this field except to verify that it is a map + if it does exist. However, it should follow the same conventions as the + root-level ``vendor`` field. + ``displayName`` An optional string with a human-friendly name of the preset. diff --git a/Help/manual/cpack-generators.7.rst b/Help/manual/cpack-generators.7.rst index ade9149c18..abb291b46e 100644 --- a/Help/manual/cpack-generators.7.rst +++ b/Help/manual/cpack-generators.7.rst @@ -20,6 +20,7 @@ Generators /cpack_gen/dmg /cpack_gen/external /cpack_gen/freebsd + /cpack_gen/innosetup /cpack_gen/ifw /cpack_gen/nsis /cpack_gen/nuget diff --git a/Help/policy/CMP0105.rst b/Help/policy/CMP0105.rst index 097a59abb8..aadc8d6ee6 100644 --- a/Help/policy/CMP0105.rst +++ b/Help/policy/CMP0105.rst @@ -8,12 +8,13 @@ properties are now used for the device link step. In CMake 3.17 and below, link options are not used by the device link step. -The ``OLD`` behavior for this policy is to ignore the link options. +The ``OLD`` behavior for this policy is to ignore the link options during the +device link step. The ``NEW`` behavior of this policy is to use the link options during the device link step. -This policy was introduced in CMake version 3.17. Use the +This policy was introduced in CMake version 3.18. Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. Unlike many policies, CMake version |release| does *not* warn when this policy is not set and simply uses ``OLD`` behavior. diff --git a/Help/policy/CMP0150.rst b/Help/policy/CMP0150.rst new file mode 100644 index 0000000000..fe646d98f4 --- /dev/null +++ b/Help/policy/CMP0150.rst @@ -0,0 +1,39 @@ +CMP0150 +------- + +.. versionadded:: 3.27 + +:command:`ExternalProject_Add` and :command:`FetchContent_Declare` commands +treat relative ``GIT_REPOSITORY`` paths as being relative to the parent +project's remote. + +Earlier versions of these commands always treated relative paths in +``GIT_REPOSITORY`` as local paths, but the base directory it was treated +as relative to was both undocumented and unintuitive. The ``OLD`` behavior +for this policy is to interpret relative paths used for ``GIT_REPOSITORY`` +as local paths relative to the following: + +* The parent directory of ``SOURCE_DIR`` for :command:`ExternalProject_Add`. +* ``FETCHCONTENT_BASE_DIR`` for :command:`FetchContent_Declare`. + +The ``NEW`` behavior is to determine the remote from the parent project and +interpret the path relative to that remote. The value of +:variable:`CMAKE_CURRENT_SOURCE_DIR` when :command:`ExternalProject_Add` or +:command:`FetchContent_Declare` is called determines the parent project. +The remote is selected according to the following (the first match is used): + +* If the parent project is checked out on a branch with an upstream remote + defined, use that remote. +* If only one remote is defined, use that remote. +* If multiple remotes are defined and one of them is named ``origin``, use + ``origin``'s remote but also issue a warning. + +If an appropriate remote cannot be determined from the above, a fatal error +will be raised. + +This policy was introduced in CMake version 3.27. CMake version |release| +warns when a relative path is encountered and the policy is not set, +falling back to using ``OLD`` behavior. Use the :command:`cmake_policy` +command to set it to ``OLD`` or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/release/dev/ExternalProject-FetchContent-relative-git-remotes.rst b/Help/release/dev/ExternalProject-FetchContent-relative-git-remotes.rst new file mode 100644 index 0000000000..d467620a39 --- /dev/null +++ b/Help/release/dev/ExternalProject-FetchContent-relative-git-remotes.rst @@ -0,0 +1,7 @@ +ExternalProject-FetchContent-Relative-git-remotes +------------------------------------------------- + +* The :module:`ExternalProject` and :module:`FetchContent` modules + now resolve relative `GIT_REPOSITORY` paths as relative to the + parent project's remote, not as a relative local file system path. + See :policy:`CMP0150`. diff --git a/Help/release/dev/FindDoxygen-custom-config-file.rst b/Help/release/dev/FindDoxygen-custom-config-file.rst new file mode 100644 index 0000000000..badc26e35b --- /dev/null +++ b/Help/release/dev/FindDoxygen-custom-config-file.rst @@ -0,0 +1,5 @@ +FindDoxygen-custom-config-file +------------------------------ + +* The :module:`FindDoxygen` module's ``doxygen_add_docs`` command gained + a ``CONFIG_FILE`` option to specify a custom doxygen configuration file. diff --git a/Help/release/dev/GenEx-LIST.rst b/Help/release/dev/GenEx-LIST.rst new file mode 100644 index 0000000000..f65a092db9 --- /dev/null +++ b/Help/release/dev/GenEx-LIST.rst @@ -0,0 +1,4 @@ +GenEx-LIST +---------- + +* The :genex:`LIST` generator expression was added to manage lists. diff --git a/Help/release/dev/cpack-innosetup.rst b/Help/release/dev/cpack-innosetup.rst new file mode 100644 index 0000000000..a9f8e8e331 --- /dev/null +++ b/Help/release/dev/cpack-innosetup.rst @@ -0,0 +1,12 @@ +cpack-innosetup +--------------- + +* The :cpack_gen:`CPack Inno Setup Generator` was added to package using + Inno Setup. + + The new generator adds: + + * A lot of options to customize the Inno Setup installer (e.g. custom + installation rules) + * Start menu and desktop shortcuts + * Components (and also downloaded components) diff --git a/Help/release/dev/preset-includes-macro-expansion.rst b/Help/release/dev/preset-includes-macro-expansion.rst new file mode 100644 index 0000000000..e1f00302a2 --- /dev/null +++ b/Help/release/dev/preset-includes-macro-expansion.rst @@ -0,0 +1,7 @@ +preset-includes-macro-expansion +------------------------------- + +* :manual:`cmake-presets(7)` files now support schema version ``7``. + +* :manual:`cmake-presets(7)` now supports ``$penv{}`` macro expansion + in ``include`` fields. |