diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/export.rst | 13 | ||||
| -rw-r--r-- | Help/command/file.rst | 68 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 2 | ||||
| -rw-r--r-- | Help/policy/CMP0157.rst | 48 | ||||
| -rw-r--r-- | Help/prop_tgt/AUTOGEN_COMMAND_LINE_LENGTH_MAX.rst | 18 | ||||
| -rw-r--r-- | Help/prop_tgt/AUTOMOC.rst | 4 | ||||
| -rw-r--r-- | Help/prop_tgt/AUTOUIC.rst | 4 | ||||
| -rw-r--r-- | Help/prop_tgt/Swift_COMPILATION_MODE-VALUES.txt | 19 | ||||
| -rw-r--r-- | Help/prop_tgt/Swift_COMPILATION_MODE.rst | 33 | ||||
| -rw-r--r-- | Help/release/3.27.rst | 4 | ||||
| -rw-r--r-- | Help/release/dev/install-export-xcframework.rst | 9 | ||||
| -rw-r--r-- | Help/variable/CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX.rst | 10 | ||||
| -rw-r--r-- | Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst | 10 | ||||
| -rw-r--r-- | Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst | 31 | ||||
| -rw-r--r-- | Help/variable/CMAKE_Swift_COMPILATION_MODE.rst | 32 |
17 files changed, 272 insertions, 36 deletions
diff --git a/Help/command/export.rst b/Help/command/export.rst index 0440c50..f190df7 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -170,6 +170,9 @@ Configuring Exports [ENABLED (<bool-true>|<bool-false>|AUTO)] [EXTRA_ARGS <args>...] ] [...] + [TARGET <target> + [XCFRAMEWORK_LOCATION <location>] + ] [...] ) .. versionadded:: 3.29 @@ -202,3 +205,13 @@ Configure the parameters of an export. The arguments are as follows: ``EXTRA_ARGS <args>`` Specify additional arguments to pass to :command:`find_dependency` after the ``REQUIRED`` argument. + +``TARGET <target>`` + Specify a target to configure in this export. This argument accepts the + following additional arguments: + + ``XCFRAMEWORK_LOCATION`` + Specify the location of an ``.xcframework`` which contains the library from + this target. If specified, the generated code will check to see if the + ``.xcframework`` exists, and if it does, it will use the ``.xcframework`` + as its imported location instead of the installed library. diff --git a/Help/command/file.rst b/Help/command/file.rst index f9d1a79..957b8b5 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -32,14 +32,14 @@ Synopsis `Writing`_ file({`WRITE`_ | `APPEND`_} <filename> <content>...) - file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...]) + 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>...]) - file(`MAKE_DIRECTORY`_ [<dir>...]) - file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...]) + file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] <globbing-expr>...) + file(`MAKE_DIRECTORY`_ <directories>...) + file({`REMOVE`_ | `REMOVE_RECURSE`_ } <files>...) file(`RENAME`_ <oldname> <newname> [...]) file(`COPY_FILE`_ <oldname> <newname> [...]) file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...]) @@ -80,7 +80,7 @@ Reading (``a`` through ``f``) are in lowercase. .. signature:: - file(STRINGS <filename> <variable> [<options>...]) + file(STRINGS <filename> <variable> <options>...) Parse a list of ASCII strings from ``<filename>`` and store it in ``<variable>``. Binary data in the file are ignored. Carriage return @@ -165,17 +165,17 @@ Reading [RESOLVED_DEPENDENCIES_VAR <deps_var>] [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>] [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>] - [EXECUTABLES [<executable_files>...]] - [LIBRARIES [<library_files>...]] - [MODULES [<module_files>...]] - [DIRECTORIES [<directories>...]] + [EXECUTABLES <executable_files>...] + [LIBRARIES <library_files>...] + [MODULES <module_files>...] + [DIRECTORIES <directories>...] [BUNDLE_EXECUTABLE <bundle_executable_file>] - [PRE_INCLUDE_REGEXES [<regexes>...]] - [PRE_EXCLUDE_REGEXES [<regexes>...]] - [POST_INCLUDE_REGEXES [<regexes>...]] - [POST_EXCLUDE_REGEXES [<regexes>...]] - [POST_INCLUDE_FILES [<files>...]] - [POST_EXCLUDE_FILES [<files>...]] + [PRE_INCLUDE_REGEXES <regexes>...] + [PRE_EXCLUDE_REGEXES <regexes>...] + [POST_INCLUDE_REGEXES <regexes>...] + [POST_EXCLUDE_REGEXES <regexes>...] + [POST_INCLUDE_FILES <files>...] + [POST_EXCLUDE_FILES <files>...] ) Please note that this sub-command is not intended to be used in project mode. @@ -210,7 +210,7 @@ Reading of paths that were found for that filename are stored in ``<conflicting_deps_prefix>_<filename>``. - ``EXECUTABLES <executable_files>`` + ``EXECUTABLES <executable_files>...`` List of executable files to read for dependencies. These are executables that are typically created with :command:`add_executable`, but they do not have to be created by CMake. On Apple platforms, the paths to these @@ -218,14 +218,14 @@ Reading resolving the libraries. Specifying any kind of library (``STATIC``, ``MODULE``, or ``SHARED``) here will result in undefined behavior. - ``LIBRARIES <library_files>`` + ``LIBRARIES <library_files>...`` List of library files to read for dependencies. These are libraries that are typically created with :command:`add_library(SHARED)`, but they do not have to be created by CMake. Specifying ``STATIC`` libraries, ``MODULE`` libraries, or executables here will result in undefined behavior. - ``MODULES <module_files>`` + ``MODULES <module_files>...`` List of loadable module files to read for dependencies. These are modules that are typically created with :command:`add_library(MODULE)`, but they do not have to be created by CMake. They are typically used by calling @@ -233,7 +233,7 @@ Reading Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables here will result in undefined behavior. - ``DIRECTORIES <directories>`` + ``DIRECTORIES <directories>...`` List of additional directories to search for dependencies. On Linux platforms, these directories are searched if the dependency is not found in any of the other usual paths. If it is found in such a directory, a @@ -256,30 +256,30 @@ Reading The following arguments specify filters for including or excluding libraries to be resolved. See below for a full description of how they work. - ``PRE_INCLUDE_REGEXES <regexes>`` + ``PRE_INCLUDE_REGEXES <regexes>...`` List of pre-include regexes through which to filter the names of not-yet-resolved dependencies. - ``PRE_EXCLUDE_REGEXES <regexes>`` + ``PRE_EXCLUDE_REGEXES <regexes>...`` List of pre-exclude regexes through which to filter the names of not-yet-resolved dependencies. - ``POST_INCLUDE_REGEXES <regexes>`` + ``POST_INCLUDE_REGEXES <regexes>...`` List of post-include regexes through which to filter the names of resolved dependencies. - ``POST_EXCLUDE_REGEXES <regexes>`` + ``POST_EXCLUDE_REGEXES <regexes>...`` List of post-exclude regexes through which to filter the names of resolved dependencies. - ``POST_INCLUDE_FILES <files>`` + ``POST_INCLUDE_FILES <files>...`` .. versionadded:: 3.21 List of post-include filenames through which to filter the names of resolved dependencies. Symlinks are resolved when attempting to match these filenames. - ``POST_EXCLUDE_FILES <files>`` + ``POST_EXCLUDE_FILES <files>...`` .. versionadded:: 3.21 List of post-exclude filenames through which to filter the names of @@ -486,8 +486,8 @@ Writing to update the file only when its content changes. .. signature:: - file(TOUCH [<files>...]) - file(TOUCH_NOCREATE [<files>...]) + file(TOUCH <files>...) + file(TOUCH_NOCREATE <files>...) .. versionadded:: 3.12 @@ -638,10 +638,10 @@ Filesystem .. signature:: file(GLOB <variable> [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] - [<globbing-expressions>...]) + <globbing-expressions>...) file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS] [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] - [<globbing-expressions>...]) + <globbing-expressions>...) Generate a list of files that match the ``<globbing-expressions>`` and store it into the ``<variable>``. Globbing expressions are similar to @@ -703,13 +703,13 @@ Filesystem ============== ====================================================== .. signature:: - file(MAKE_DIRECTORY [<directories>...]) + file(MAKE_DIRECTORY <directories>...) Create the given directories and their parents as needed. .. signature:: - file(REMOVE [<files>...]) - file(REMOVE_RECURSE [<files>...]) + file(REMOVE <files>...) + file(REMOVE_RECURSE <files>...) Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given files and directories, including non-empty directories. No error is emitted @@ -1012,8 +1012,8 @@ Transfer ^^^^^^^^ .. signature:: - file(DOWNLOAD <url> [<file>] [<options>...]) - file(UPLOAD <file> <url> [<options>...]) + file(DOWNLOAD <url> [<file>] <options>...) + file(UPLOAD <file> <url> <options>...) The ``DOWNLOAD`` subcommand downloads the given ``<url>`` to a local ``<file>``. The ``UPLOAD`` mode uploads a local ``<file>`` to a given diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 5b1939e..ddde877 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -57,6 +57,7 @@ Policies Introduced by CMake 3.29 .. toctree:: :maxdepth: 1 + CMP0157: Swift compilation mode is selected by an abstraction. </policy/CMP0157> CMP0156: De-duplicate libraries on link lines based on linker capabilities. </policy/CMP0156> Policies Introduced by CMake 3.28 diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 276cb13..0adfdfb 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -130,6 +130,7 @@ Properties on Targets /prop_tgt/ARCHIVE_OUTPUT_NAME /prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG /prop_tgt/AUTOGEN_BUILD_DIR + /prop_tgt/AUTOGEN_COMMAND_LINE_LENGTH_MAX /prop_tgt/AUTOGEN_ORIGIN_DEPENDS /prop_tgt/AUTOGEN_PARALLEL /prop_tgt/AUTOGEN_TARGET_DEPENDS @@ -393,6 +394,7 @@ Properties on Targets /prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG /prop_tgt/STATIC_LIBRARY_OPTIONS /prop_tgt/SUFFIX + /prop_tgt/Swift_COMPILATION_MODE /prop_tgt/Swift_DEPENDENCIES_FILE /prop_tgt/Swift_LANGUAGE_VERSION /prop_tgt/Swift_MODULE_DIRECTORY diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index a73494e..35b57a5 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -115,6 +115,7 @@ Variables that Provide Information /variable/CMAKE_SOURCE_DIR /variable/CMAKE_STATIC_LIBRARY_PREFIX /variable/CMAKE_STATIC_LIBRARY_SUFFIX + /variable/CMAKE_Swift_COMPILATION_MODE /variable/CMAKE_Swift_MODULE_DIRECTORY /variable/CMAKE_Swift_NUM_THREADS /variable/CMAKE_TOOLCHAIN_FILE @@ -400,6 +401,7 @@ Variables that Control the Build /variable/CMAKE_APPLE_SILICON_PROCESSOR /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX /variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS /variable/CMAKE_AUTOGEN_PARALLEL /variable/CMAKE_AUTOGEN_USE_SYSTEM_INCLUDE diff --git a/Help/policy/CMP0157.rst b/Help/policy/CMP0157.rst new file mode 100644 index 0000000..a8f8210 --- /dev/null +++ b/Help/policy/CMP0157.rst @@ -0,0 +1,48 @@ +CMP0157 +------- + +.. versionadded:: 3.29 + +Swift compilation mode is selected by an abstraction. + +The Swift compiler can compile modules in different modes. The desired build +mode depends whether the developer is iterating and wants to incrementally make +changes, or if they are building a release for distribution and want more +optimizations applied to the resulting binary. + +CMake versions 3.26 through 3.28 build Swift binaries with whole-module +optimizations enabled when configured in a non-debug build type. +For CMake versions earlier than 3.26, the developer needs to specify +the necessary flag manually for the :ref:`Ninja Generators`, and cannot +not specify whole-module optimizations to the :generator:`Xcode` generator. + +CMake versions 3.29 and above prefer to set the compilation mode using +the :prop_tgt:`Swift_COMPILATION_MODE` target property, which can be +initialized by the :variable:`CMAKE_Swift_COMPILATION_MODE` variable. + +This policy provides compatibility for projects that have not been updated. +The policy setting takes effect as of the first :command:`project` or +:command:`enable_language` command that enables the ``Swift`` language. + +.. note:: + + Once the policy has taken effect at the top of a project, that choice + must be used throughout the tree. In projects that have nested projects + in subdirectories, be sure to convert everything together. + +The ``OLD`` behavior for this policy builds all Swift targets in +``wholemodule`` mode for non-debug configurations. :ref:`Ninja Generators` +prepend the ``-wmo`` flag to the default set of Swift flags. +The :generator:`Xcode` generator sets the ``SWIFT_COMPILATION_MODE`` +attribute to ``wholemodule`` in the generated Xcode project file. + +The ``NEW`` behavior for this policy is to apply the compilation mode specified +in the :prop_tgt:`Swift_COMPILATION_MODE` target property, initialized as each +target is created by the :variable:`CMAKE_Swift_COMPILATION_MODE` variable. + +This policy was introduced in CMake version 3.29. 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. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_tgt/AUTOGEN_COMMAND_LINE_LENGTH_MAX.rst b/Help/prop_tgt/AUTOGEN_COMMAND_LINE_LENGTH_MAX.rst new file mode 100644 index 0000000..f1e51a7 --- /dev/null +++ b/Help/prop_tgt/AUTOGEN_COMMAND_LINE_LENGTH_MAX.rst @@ -0,0 +1,18 @@ +AUTOGEN_COMMAND_LINE_LENGTH_MAX +------------------------------- + +.. versionadded:: 3.29 + +Command line length limit for autogen targets, i.e. ``moc`` or ``uic``, +that triggers the use of response files on Windows instead of passing all +arguments to the command line. + +- An empty (or unset) value sets the limit to 32000 +- A positive non zero integer value sets the exact command line length + limit. + +By default ``AUTOGEN_COMMAND_LINE_LENGTH_MAX`` is initialized from +:variable:`CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX`. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index 0feb2e8..6f58afb 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst @@ -247,5 +247,9 @@ will be generated when this variable is ``ON``. This target property controls the number of ``moc`` or ``uic`` processes to start in parallel during builds. +:prop_tgt:`AUTOGEN_COMMAND_LINE_LENGTH_MAX`: +This target property controls the limit when to use response files for +``moc`` or ``uic`` processes on Windows. + See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. diff --git a/Help/prop_tgt/AUTOUIC.rst b/Help/prop_tgt/AUTOUIC.rst index dc854b2..95366ee 100644 --- a/Help/prop_tgt/AUTOUIC.rst +++ b/Help/prop_tgt/AUTOUIC.rst @@ -81,5 +81,9 @@ will be generated when this variable is ``ON``. This target property controls the number of ``moc`` or ``uic`` processes to start in parallel during builds. +:prop_tgt:`AUTOGEN_COMMAND_LINE_LENGTH_MAX`: +This target property controls the limit when to use response files for +``moc`` or ``uic`` processes on Windows. + See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. diff --git a/Help/prop_tgt/Swift_COMPILATION_MODE-VALUES.txt b/Help/prop_tgt/Swift_COMPILATION_MODE-VALUES.txt new file mode 100644 index 0000000..b94380a --- /dev/null +++ b/Help/prop_tgt/Swift_COMPILATION_MODE-VALUES.txt @@ -0,0 +1,19 @@ +``incremental`` + Compiles each Swift source in the module separately, resulting in better + parallelism in the build. The compiler emits additional information into + the build directory improving rebuild performance when small changes are made + to the source between rebuilds. This is the best option to use while + iterating on changes in a project. + +``wholemodule`` + Whole-module optimizations are slowest to compile, but results in the most + optimized library. The entire context is loaded into once instance of the + compiler, so there is no parallelism across source files in the module. + +``singlefile`` + Compiles each source in a Swift modules separately, resulting in better + parallelism. Unlike the ``incremental`` build mode, no additional information + is emitted by the compiler during the build, so rebuilding after making small + changes to the source file will not run faster. This option should be used + sparingly, preferring ``incremental`` builds, unless working around a compiler + bug. diff --git a/Help/prop_tgt/Swift_COMPILATION_MODE.rst b/Help/prop_tgt/Swift_COMPILATION_MODE.rst new file mode 100644 index 0000000..e26474a --- /dev/null +++ b/Help/prop_tgt/Swift_COMPILATION_MODE.rst @@ -0,0 +1,33 @@ +Swift_COMPILATION_MODE +---------------------- + +.. versionadded:: 3.29 + +Specify how Swift compiles a target. + +The allowed values are: + +.. include:: Swift_COMPILATION_MODE-VALUES.txt + +Use :manual:`generator expressions <cmake-generator-expressions(7)>` to support +per-configuration specification. For example, the code: + +.. code-block:: cmake + + add_library(foo foo.swift) + set_property(TARGET foo PROPERTY + Swift_COMPILATION_MODE "$<IF:$<CONFIG:Release>,wholemodule,incremental>") + +sets the Swift compilation mode to wholemodule mode in the release configuration +and sets the property to incremental mode in other configurations. + +The property is initialized from the value of the +:variable:`CMAKE_Swift_COMPILATION_MODE` variable, if it is set. If the property +is not set or is empty, then CMake uses the default value ``incremental`` to +specify the swift compilation mode. + +.. note:: + + This property only has effect when policy :policy:`CMP0157` is set to ``NEW`` + prior to the first :command:`project` or :command:`enable_language` command + that enables the Swift language. diff --git a/Help/release/3.27.rst b/Help/release/3.27.rst index 2ba0c7d..8a67ebc 100644 --- a/Help/release/3.27.rst +++ b/Help/release/3.27.rst @@ -285,8 +285,8 @@ Changes made since CMake 3.27.0 include the following. to select the Windows 8.1 SDK. In CMake 3.27.[0-1] the ``version=`` field was limited to selecting Windows 10 SDKs. -3.27.3, 3.27.4, 3.27.5, 3.27.6, 3.27.7 --------------------------------------- +3.27.3, 3.27.4, 3.27.5, 3.27.6, 3.27.7, 3.27.8 +---------------------------------------------- * These versions made no changes to documented features or interfaces. Some implementation updates were made to support ecosystem changes diff --git a/Help/release/dev/install-export-xcframework.rst b/Help/release/dev/install-export-xcframework.rst new file mode 100644 index 0000000..513a552 --- /dev/null +++ b/Help/release/dev/install-export-xcframework.rst @@ -0,0 +1,9 @@ +install-export-xcframework +-------------------------- + +* The :command:`export(SETUP)` command gained a new ``XCFRAMEWORK_LOCATION`` + argument, which can be used to specify the location of a ``.xcframework`` + that can be substituted for the installed library. +* The :module:`CMakePackageConfigHelpers` module gained a new + :command:`generate_apple_platform_selection_file` function, which can be + used to generate a file that includes another Apple-platform-specific file. diff --git a/Help/variable/CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX.rst b/Help/variable/CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX.rst new file mode 100644 index 0000000..eabda43 --- /dev/null +++ b/Help/variable/CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX.rst @@ -0,0 +1,10 @@ +CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX +------------------------------------- + +.. versionadded:: 3.29 + +Command line length limit for autogen targets, i.e. ``moc`` or ``uic``, +that triggers the use of response files on Windows instead of passing all +arguments to the command line. + +By default ``CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX`` is unset. diff --git a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst index 58818f4..b375b77 100644 --- a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst +++ b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst @@ -15,4 +15,14 @@ variables which have been stored in the cache will still be there. In that case it is recommended to remove the cache variables for this package from the cache using the cache editor or :option:`cmake -U`. +Note that this variable can lead to inconsistent results within the project. +Consider the case where a dependency is requested via :command:`find_package` +from two different places within the project. If the first call does not +have the ``REQUIRED`` keyword, it will not find the dependency when +``CMAKE_DISABLE_FIND_PACKAGE_<PackageName>`` is set to true for that +dependency. The project will proceed under the assumption that the dependency +isn't available. If the second call elsewhere in the project *does* have the +``REQUIRED`` keyword, it can succeed. Two different parts of the same project +have then seen opposite results for the same dependency. + See also the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable. diff --git a/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst index 893f1ae..52bf30a 100644 --- a/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst +++ b/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst @@ -11,4 +11,35 @@ turned into ``REQUIRED`` by setting the variable This can be used to assert assumptions about build environment and to ensure the build will fail early if they do not hold. +Note that setting this variable to true breaks some commonly used patterns. +Multiple calls to :command:`find_package` are sometimes used to obtain a +different search order to the default. +For example, projects can force checking a known path for a particular +package first before searching any of the other default search paths: + +.. code:: cmake + + find_package(something PATHS /some/local/path NO_DEFAULT_PATH) + find_package(something) + +In the above, the first call looks for the ``something`` package in a specific +directory. If ``CMAKE_REQUIRE_FIND_PACKAGE_something`` is set to true, then +this first call must succeed, otherwise a fatal error occurs. The second call +never gets a chance to provide a fall-back to using the default search +locations. + +A similar pattern is used even by some of CMake's own Find modules to search +for a config package first: + +.. code:: cmake + + find_package(something CONFIG QUIET) + if(NOT something_FOUND) + # Fall back to searching using typical Find module logic... + endif() + +Again, if ``CMAKE_REQUIRE_FIND_PACKAGE_something`` is true, the first call +must succeed. It effectively means a config package must be found for the +dependency, and the Find module logic is never used. + See also the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable. diff --git a/Help/variable/CMAKE_Swift_COMPILATION_MODE.rst b/Help/variable/CMAKE_Swift_COMPILATION_MODE.rst new file mode 100644 index 0000000..5e55d8c --- /dev/null +++ b/Help/variable/CMAKE_Swift_COMPILATION_MODE.rst @@ -0,0 +1,32 @@ +CMAKE_Swift_COMPILATION_MODE +---------------------------- + +.. versionadded:: 3.29 + +Specify how Swift compiles a target. This variable is used to initialize the +:prop_tgt:`Swift_COMPILATION_MODE` property on targets as they are created. + +The allowed values are: + +.. include:: ../prop_tgt/Swift_COMPILATION_MODE-VALUES.txt + +Use :manual:`generator expressions <cmake-generator-expressions(7)>` to support +per-configuration specification. For example, the code: + +.. code-block:: cmake + + set(CMAKE_Swift_COMPILATION_MODE + "$<IF:$<CONFIG:Release>,wholemodule,incremental>") + +sets the default Swift compilation mode to wholemodule mode when building a +release configuration and to incremental mode in other configurations. + +If this variable is not set then the :prop_tgt:`Swift_COMPILATION_MODE` target +property will not be set automatically. If that property is unset then CMake +uses the default value ``incremental`` to build the Swift source files. + +.. note:: + + This property only has effect when policy :policy:`CMP0157` is set to ``NEW`` + prior to the first :command:`project` or :command:`enable_language` command + that enables the Swift language. |