diff options
Diffstat (limited to 'Modules')
33 files changed, 1239 insertions, 938 deletions
diff --git a/Modules/CMakeDetermineCSharpCompiler.cmake b/Modules/CMakeDetermineCSharpCompiler.cmake index fe98469..652eb63 100644 --- a/Modules/CMakeDetermineCSharpCompiler.cmake +++ b/Modules/CMakeDetermineCSharpCompiler.cmake @@ -3,7 +3,7 @@ if(NOT ${CMAKE_GENERATOR} MATCHES "Visual Studio ([^9]|[9][0-9])") message(FATAL_ERROR - "C# is currently only supported for Microsoft Visual Studio 11 2012 and later.") + "C# is currently only supported for Microsoft Visual Studio 12 2013 and later.") endif() include(${CMAKE_ROOT}/Modules/CMakeDetermineCompiler.cmake) diff --git a/Modules/CMakeDetermineCompilerId.cmake b/Modules/CMakeDetermineCompilerId.cmake index 6c49096..4db9aa8 100644 --- a/Modules/CMakeDetermineCompilerId.cmake +++ b/Modules/CMakeDetermineCompilerId.cmake @@ -608,6 +608,7 @@ Id flags: ${testflags} ${CMAKE_${lang}_COMPILER_ID_FLAGS_ALWAYS} if(CMAKE_OSX_SYSROOT) set(id_sdkroot "SDKROOT = \"${CMAKE_OSX_SYSROOT}\";") if(CMAKE_OSX_SYSROOT MATCHES "(^|/)[Ii][Pp][Hh][Oo][Nn][Ee]" OR + CMAKE_OSX_SYSROOT MATCHES "(^|/)[Xx][Rr]" OR CMAKE_OSX_SYSROOT MATCHES "(^|/)[Aa][Pp][Pp][Ll][Ee][Tt][Vv]") set(id_product_type "com.apple.product-type.bundle.unit-test") elseif(CMAKE_OSX_SYSROOT MATCHES "(^|/)[Ww][Aa][Tt][Cc][Hh]") diff --git a/Modules/CMakeDetermineSystem.cmake b/Modules/CMakeDetermineSystem.cmake index 386be73..fff4e9d 100644 --- a/Modules/CMakeDetermineSystem.cmake +++ b/Modules/CMakeDetermineSystem.cmake @@ -47,6 +47,28 @@ if(CMAKE_HOST_UNIX) set(CMAKE_HOST_SYSTEM_VERSION "${_CMAKE_HOST_SYSTEM_MAJOR_VERSION}.${_CMAKE_HOST_SYSTEM_MINOR_VERSION}") unset(_CMAKE_HOST_SYSTEM_MAJOR_VERSION) unset(_CMAKE_HOST_SYSTEM_MINOR_VERSION) + elseif(CMAKE_HOST_SYSTEM_NAME STREQUAL "Android") + execute_process(COMMAND getprop ro.build.version.sdk + OUTPUT_VARIABLE CMAKE_HOST_SYSTEM_VERSION + OUTPUT_STRIP_TRAILING_WHITESPACE + ERROR_QUIET) + + if(NOT DEFINED CMAKE_SYSTEM_VERSION) + set(_ANDROID_API_LEVEL_H $ENV{PREFIX}/include/android/api-level.h) + set(_ANDROID_API_REGEX "#define __ANDROID_API__ ([0-9]+)") + file(READ ${_ANDROID_API_LEVEL_H} _ANDROID_API_LEVEL_H_CONTENT) + string(REGEX MATCH ${_ANDROID_API_REGEX} _ANDROID_API_LINE "${_ANDROID_API_LEVEL_H_CONTENT}") + string(REGEX REPLACE ${_ANDROID_API_REGEX} "\\1" _ANDROID_API "${_ANDROID_API_LINE}") + if(_ANDROID_API) + set(CMAKE_SYSTEM_VERSION "${_ANDROID_API}") + endif() + + unset(_ANDROID_API_LEVEL_H) + unset(_ANDROID_API_LEVEL_H_CONTENT) + unset(_ANDROID_API_REGEX) + unset(_ANDROID_API_LINE) + unset(_ANDROID_API) + endif() else() execute_process(COMMAND ${CMAKE_UNAME} -r OUTPUT_VARIABLE CMAKE_HOST_SYSTEM_VERSION diff --git a/Modules/CMakeSwiftInformation.cmake b/Modules/CMakeSwiftInformation.cmake index 777c680..1c6f0df 100644 --- a/Modules/CMakeSwiftInformation.cmake +++ b/Modules/CMakeSwiftInformation.cmake @@ -21,7 +21,8 @@ set(CMAKE_INCLUDE_FLAG_Swift "-I ") # FIXME: Move compiler- and platform-specific flags to the above-included modules. if(CMAKE_SYSTEM_NAME STREQUAL "Darwin" OR CMAKE_SYSTEM_NAME STREQUAL "iOS" - OR CMAKE_SYSTEM_NAME STREQUAL "tvOS" OR CMAKE_SYSTEM_NAME STREQUAL "watchOS") + OR CMAKE_SYSTEM_NAME STREQUAL "tvOS" OR CMAKE_SYSTEM_NAME STREQUAL "visionOS" + OR CMAKE_SYSTEM_NAME STREQUAL "watchOS") set(CMAKE_SHARED_LIBRARY_SONAME_Swift_FLAG "-Xlinker -install_name -Xlinker ") elseif(NOT CMAKE_SYSTEM_NAME STREQUAL Windows) set(CMAKE_SHARED_LIBRARY_SONAME_Swift_FLAG "-Xlinker -soname -Xlinker ") @@ -30,7 +31,8 @@ if(NOT CMAKE_SYSTEM_NAME STREQUAL Windows) set(CMAKE_EXECUTABLE_RUNTIME_Swift_FLAG "-Xlinker -rpath -Xlinker ") set(CMAKE_SHARED_LIBRARY_RUNTIME_Swift_FLAG "-Xlinker -rpath -Xlinker ") if(CMAKE_SYSTEM_NAME STREQUAL "Darwin" OR CMAKE_SYSTEM_NAME STREQUAL "iOS" - OR CMAKE_SYSTEM_NAME STREQUAL "tvOS" OR CMAKE_SYSTEM_NAME STREQUAL "watchOS") + OR CMAKE_SYSTEM_NAME STREQUAL "tvOS" OR CMAKE_SYSTEM_NAME STREQUAL "visionOS" + OR CMAKE_SYSTEM_NAME STREQUAL "watchOS") set(CMAKE_EXECUTABLE_RUNTIME_Swift_FLAG_SEP "") set(CMAKE_SHARED_LIBRARY_RUNTIME_Swift_FLAG_SEP "") else() diff --git a/Modules/CMakeSystemSpecificInitialize.cmake b/Modules/CMakeSystemSpecificInitialize.cmake index e87d868..ee8cb86 100644 --- a/Modules/CMakeSystemSpecificInitialize.cmake +++ b/Modules/CMakeSystemSpecificInitialize.cmake @@ -25,7 +25,7 @@ unset(LINUX) # It is useful to share the same aforementioned configuration files and # avoids duplicating them in case of tightly related platforms. # -# An example are the platforms supported by Xcode (macOS, iOS, tvOS, +# An example are the platforms supported by Xcode (macOS, iOS, tvOS, visionOS # and watchOS). For all of those the CMAKE_EFFECTIVE_SYSTEM_NAME is # set to Apple which results in using # Platform/Apple-AppleClang-CXX.cmake for the Apple C++ compiler. diff --git a/Modules/CheckLanguage.cmake b/Modules/CheckLanguage.cmake index 69913a3..04e721c 100644 --- a/Modules/CheckLanguage.cmake +++ b/Modules/CheckLanguage.cmake @@ -5,26 +5,45 @@ CheckLanguage ------------- -Check if a language can be enabled +Check whether a language can be enabled by the :command:`enable_language` +or :command:`project` commands: -Usage: +.. command:: check_language -:: + .. code-block:: cmake - check_language(<lang>) + check_language(<lang>) -where ``<lang>`` is a language that may be passed to :command:`enable_language` -such as ``Fortran``. If :variable:`CMAKE_<LANG>_COMPILER` is already defined -the check does nothing. Otherwise it tries enabling the language in a -test project. The result is cached in :variable:`CMAKE_<LANG>_COMPILER` -as the compiler that was found, or ``NOTFOUND`` if the language cannot be -enabled. For CUDA which can have an explicit host compiler, the cache -:variable:`CMAKE_CUDA_HOST_COMPILER` variable will be set if it was required -for compilation (and cleared if it was not). + Try enabling language ``<lang>`` in a test project and record results + in the cache: -Example: + :variable:`CMAKE_<LANG>_COMPILER` + If the language can be enabled, this variable is set to the compiler + that was found. If the language cannot be enabled, this variable is + set to ``NOTFOUND``. -:: + If this variable is already set, either explicitly or cached by + a previous call, the check is skipped. + + :variable:`CMAKE_CUDA_HOST_COMPILER` + This variable is set when ``<lang>`` is ``CUDA``. + + If the check detects an explicit host compiler that is required for + compilation, this variable will be set to that compiler. + If the check detects that no explicit host compiler is needed, + this variable will be cleared. + + If this variable is already set, its value is preserved only if + :variable:`CMAKE_CUDA_COMPILER <CMAKE_<LANG>_COMPILER>` is also set. + Otherwise, the check runs and overwrites + :variable:`CMAKE_CUDA_HOST_COMPILER` with a new result. + Note that :variable:`CMAKE_CUDA_HOST_COMPILER` documents it should + not be set without also setting + :variable:`CMAKE_CUDA_COMPILER <CMAKE_<LANG>_COMPILER>` to a NVCC compiler. + +For example: + +.. code-block:: cmake check_language(Fortran) if(CMAKE_Fortran_COMPILER) diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake index 605908d..bec5c8e 100644 --- a/Modules/ExternalProject.cmake +++ b/Modules/ExternalProject.cmake @@ -11,11 +11,8 @@ ExternalProject .. contents:: -Commands -^^^^^^^^ - External Project Definition -""""""""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. command:: ExternalProject_Add @@ -34,866 +31,900 @@ External Project Definition customized. The function supports a large number of options which can be used to tailor the external project behavior. - **Directory Options:** - Most of the time, the default directory layout is sufficient. It is largely - an implementation detail that the main project usually doesn't need to - change. In some circumstances, however, control over the directory layout - can be useful or necessary. The directory options are potentially more - useful from the point of view that the main build can use the - :command:`ExternalProject_Get_Property` command to retrieve their values, - thereby allowing the main project to refer to build artifacts of the - external project. - - ``PREFIX <dir>`` - Root directory for the external project. Unless otherwise noted below, - all other directories associated with the external project will be - created under here. - - ``TMP_DIR <dir>`` - Directory in which to store temporary files. - - ``STAMP_DIR <dir>`` - Directory in which to store the timestamps of each step. Log files from - individual steps are also created in here unless overridden by LOG_DIR - (see *Logging Options* below). - - ``LOG_DIR <dir>`` - .. versionadded:: 3.14 - - Directory in which to store the logs of each step. - - ``DOWNLOAD_DIR <dir>`` - Directory in which to store downloaded files before unpacking them. This - directory is only used by the URL download method, all other download - methods use ``SOURCE_DIR`` directly instead. - - ``SOURCE_DIR <dir>`` - Source directory into which downloaded contents will be unpacked, or for - non-URL download methods, the directory in which the repository should be - checked out, cloned, etc. If no download method is specified, this must - point to an existing directory where the external project has already - been unpacked or cloned/checked out. - - .. note:: - If a download method is specified, any existing contents of the source - directory may be deleted. Only the URL download method checks whether - this directory is either missing or empty before initiating the - download, stopping with an error if it is not empty. All other - download methods silently discard any previous contents of the source - directory. - - ``BINARY_DIR <dir>`` - Specify the build directory location. This option is ignored if - ``BUILD_IN_SOURCE`` is enabled. - - ``INSTALL_DIR <dir>`` - Installation prefix to be placed in the ``<INSTALL_DIR>`` placeholder. - This does not actually configure the external project to install to - the given prefix. That must be done by passing appropriate arguments - to the external project configuration step, e.g. using ``<INSTALL_DIR>``. - - If any of the above ``..._DIR`` options are not specified, their defaults - are computed as follows. If the ``PREFIX`` option is given or the - ``EP_PREFIX`` directory property is set, then an external project is built - and installed under the specified prefix:: - - TMP_DIR = <prefix>/tmp - STAMP_DIR = <prefix>/src/<name>-stamp - DOWNLOAD_DIR = <prefix>/src - SOURCE_DIR = <prefix>/src/<name> - BINARY_DIR = <prefix>/src/<name>-build - INSTALL_DIR = <prefix> - LOG_DIR = <STAMP_DIR> - - Otherwise, if the ``EP_BASE`` directory property is set then components - of an external project are stored under the specified base:: - - TMP_DIR = <base>/tmp/<name> - STAMP_DIR = <base>/Stamp/<name> - DOWNLOAD_DIR = <base>/Download/<name> - SOURCE_DIR = <base>/Source/<name> - BINARY_DIR = <base>/Build/<name> - INSTALL_DIR = <base>/Install/<name> - LOG_DIR = <STAMP_DIR> - - If no ``PREFIX``, ``EP_PREFIX``, or ``EP_BASE`` is specified, then the - default is to set ``PREFIX`` to ``<name>-prefix``. Relative paths are - interpreted with respect to :variable:`CMAKE_CURRENT_BINARY_DIR` at the - point where ``ExternalProject_Add()`` is called. - - **Download Step Options:** - A download method can be omitted if the ``SOURCE_DIR`` option is used to - point to an existing non-empty directory. Otherwise, one of the download - methods below must be specified (multiple download methods should not be - given) or a custom ``DOWNLOAD_COMMAND`` provided. - - ``DOWNLOAD_COMMAND <cmd>...`` - Overrides the command used for the download step - (:manual:`generator expressions <cmake-generator-expressions(7)>` are - supported). If this option is specified, all other download options will - be ignored. Providing an empty string for ``<cmd>`` effectively disables - the download step. - - *URL Download* - ``URL <url1> [<url2>...]`` - List of paths and/or URL(s) of the external project's source. When more - than one URL is given, they are tried in turn until one succeeds. A URL - may be an ordinary path in the local file system (in which case it - must be the only URL provided) or any downloadable URL supported by the - :command:`file(DOWNLOAD)` command. A local filesystem path may refer to - either an existing directory or to an archive file, whereas a URL is - expected to point to a file which can be treated as an archive. When an - archive is used, it will be unpacked automatically unless the - ``DOWNLOAD_NO_EXTRACT`` option is set to prevent it. The archive type - is determined by inspecting the actual content rather than using logic - based on the file extension. - - .. versionchanged:: 3.7 - Multiple URLs are allowed. - - ``URL_HASH <algo>=<hashValue>`` - Hash of the archive file to be downloaded. The argument should be of - the form ``<algo>=<hashValue>`` where ``algo`` can be any of the hashing - algorithms supported by the :command:`file()` command. Specifying this - option is strongly recommended for URL downloads, as it ensures the - integrity of the downloaded content. It is also used as a check for a - previously downloaded file, allowing connection to the remote location - to be avoided altogether if the local directory already has a file from - an earlier download that matches the specified hash. - - ``URL_MD5 <md5>`` - Equivalent to ``URL_HASH MD5=<md5>``. - - ``DOWNLOAD_NAME <fname>`` - File name to use for the downloaded file. If not given, the end of the - URL is used to determine the file name. This option is rarely needed, - the default name is generally suitable and is not normally used outside - of code internal to the ``ExternalProject`` module. - - ``DOWNLOAD_EXTRACT_TIMESTAMP <bool>`` - .. versionadded:: 3.24 - - When specified with a true value, the timestamps of the extracted - files will match those in the archive. When false, the timestamps of - the extracted files will reflect the time at which the extraction - was performed. If the download URL changes, timestamps based off - those in the archive can result in dependent targets not being rebuilt - when they potentially should have been. Therefore, unless the file - timestamps are significant to the project in some way, use a false - value for this option. If ``DOWNLOAD_EXTRACT_TIMESTAMP`` is not given, - the default is false. See policy :policy:`CMP0135`. - - ``DOWNLOAD_NO_EXTRACT <bool>`` - .. versionadded:: 3.6 - - Allows the extraction part of the download step to be disabled by - passing a boolean true value for this option. If this option is not - given, the downloaded contents will be unpacked automatically if - required. If extraction has been disabled, the full path to the - downloaded file is available as ``<DOWNLOADED_FILE>`` in subsequent - steps or as the property ``DOWNLOADED_FILE`` with the - :command:`ExternalProject_Get_Property` command. - - ``DOWNLOAD_NO_PROGRESS <bool>`` - Can be used to disable logging the download progress. If this option is - not given, download progress messages will be logged. - - ``TIMEOUT <seconds>`` - Maximum time allowed for file download operations. - - ``INACTIVITY_TIMEOUT <seconds>`` - .. versionadded:: 3.19 - - Terminate the operation after a period of inactivity. - - ``HTTP_USERNAME <username>`` - .. versionadded:: 3.7 - - Username for the download operation if authentication is required. - - ``HTTP_PASSWORD <password>`` - .. versionadded:: 3.7 - - Password for the download operation if authentication is required. - - ``HTTP_HEADER <header1> [<header2>...]`` - .. versionadded:: 3.7 - - Provides an arbitrary list of HTTP headers for the download operation. - This can be useful for accessing content in systems like AWS, etc. - - ``TLS_VERIFY <bool>`` - Specifies whether certificate verification should be performed for - https URLs. If this option is not provided, the default behavior is - determined by the :variable:`CMAKE_TLS_VERIFY` variable (see - :command:`file(DOWNLOAD)`). If that is also not set, certificate - verification will not be performed. In situations where ``URL_HASH`` - cannot be provided, this option can be an alternative verification - measure. - - .. versionchanged:: 3.6 - This option also applies to ``git clone`` invocations, although the - default behavior is different. If ``TLS_VERIFY`` is not given and - :variable:`CMAKE_TLS_VERIFY` is not set, the behavior will be - determined by git's defaults. Normally, the ``sslVerify`` git - config setting defaults to true, but the user may have overridden - this at a global level. - - ``TLS_CAINFO <file>`` - Specify a custom certificate authority file to use if ``TLS_VERIFY`` - is enabled. If this option is not specified, the value of the - :variable:`CMAKE_TLS_CAINFO` variable will be used instead (see - :command:`file(DOWNLOAD)`) - - ``NETRC <level>`` - .. versionadded:: 3.11 - - Specify whether the ``.netrc`` file is to be used for operation. - If this option is not specified, the value of the - :variable:`CMAKE_NETRC` variable will be used instead - (see :command:`file(DOWNLOAD)`). Valid levels are: - - ``IGNORED`` - The ``.netrc`` file is ignored. - This is the default. - ``OPTIONAL`` - The ``.netrc`` file is optional, and information in the URL - is preferred. The file will be scanned to find which ever - information is not specified in the URL. - ``REQUIRED`` - The ``.netrc`` file is required, and information in the URL - is ignored. - - ``NETRC_FILE <file>`` - .. versionadded:: 3.11 - - Specify an alternative ``.netrc`` file to the one in your home directory - if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option - is not specified, the value of the :variable:`CMAKE_NETRC_FILE` variable - will be used instead (see :command:`file(DOWNLOAD)`) - - .. versionadded:: 3.1 - Added support for `tbz2`, `.tar.xz`, `.txz`, and `.7z` extensions. - - *Git* - NOTE: A git version of 1.6.5 or later is required if this download method - is used. - - ``GIT_REPOSITORY <url>`` - URL of the git repository. Any URL understood by the ``git`` command - may be used. - - .. versionchanged:: 3.27 - A relative URL will be resolved based on the parent project's - remote, subject to :policy:`CMP0150`. See the policy documentation - for how the remote is selected, including conditions where the - remote selection can fail. Local filesystem remotes should - always use absolute paths. - - ``GIT_TAG <tag>`` - Git branch name, tag or commit hash. Note that branch names and tags - should generally be specified as remote names (i.e. ``origin/myBranch`` - rather than simply ``myBranch``). This ensures that if the remote end - has its tag moved or branch rebased or history rewritten, the local - clone will still be updated correctly. In general, however, specifying - a commit hash should be preferred for a number of reasons: - - - If the local clone already has the commit corresponding to the hash, - no ``git fetch`` needs to be performed to check for changes each time - CMake is re-run. This can result in a significant speed up if many - external projects are being used. - - Using a specific git hash ensures that the main project's own history - is fully traceable to a specific point in the external project's - evolution. If a branch or tag name is used instead, then checking out - a specific commit of the main project doesn't necessarily pin the - whole build to a specific point in the life of the external project. - The lack of such deterministic behavior makes the main project lose - traceability and repeatability. - - If ``GIT_SHALLOW`` is enabled then ``GIT_TAG`` works only with - branch names and tags. A commit hash is not allowed. - - Note that if not provided, ``GIT_TAG`` defaults to ``master``, not the - default Git branch name. - - ``GIT_REMOTE_NAME <name>`` - The optional name of the remote. If this option is not specified, it - defaults to ``origin``. - - ``GIT_SUBMODULES <module>...`` - Specific git submodules that should also be updated. If this option is - not provided, all git submodules will be updated. - - .. versionchanged:: 3.16 - When :policy:`CMP0097` is set to ``NEW``, if this value is set - to an empty string then no submodules are initialized or updated. - - ``GIT_SUBMODULES_RECURSE <bool>`` - .. versionadded:: 3.17 - - Specify whether git submodules (if any) should update recursively by - passing the ``--recursive`` flag to ``git submodule update``. - If not specified, the default is on. - - ``GIT_SHALLOW <bool>`` - .. versionadded:: 3.6 - - When this option is enabled, the ``git clone`` operation will be given - the ``--depth 1`` option. This performs a shallow clone, which avoids - downloading the whole history and instead retrieves just the commit - denoted by the ``GIT_TAG`` option. - - ``GIT_PROGRESS <bool>`` - .. versionadded:: 3.8 - - When enabled, this option instructs the ``git clone`` operation to - report its progress by passing it the ``--progress`` option. Without - this option, the clone step for large projects may appear to make the - build stall, since nothing will be logged until the clone operation - finishes. While this option can be used to provide progress to prevent - the appearance of the build having stalled, it may also make the build - overly noisy if lots of external projects are used. - - ``GIT_CONFIG <option1> [<option2>...]`` - .. versionadded:: 3.8 - - Specify a list of config options to pass to ``git clone``. Each option - listed will be transformed into its own ``--config <option>`` on the - ``git clone`` command line, with each option required to be in the - form ``key=value``. - - ``GIT_REMOTE_UPDATE_STRATEGY <strategy>`` - .. versionadded:: 3.18 - - When ``GIT_TAG`` refers to a remote branch, this option can be used to - specify how the update step behaves. The ``<strategy>`` must be one of - the following: - - ``CHECKOUT`` - Ignore the local branch and always checkout the branch specified by - ``GIT_TAG``. - - ``REBASE`` - Try to rebase the current branch to the one specified by ``GIT_TAG``. - If there are local uncommitted changes, they will be stashed first - and popped again after rebasing. If rebasing or popping stashed - changes fail, abort the rebase and halt with an error. - When ``GIT_REMOTE_UPDATE_STRATEGY`` is not present, this is the - default strategy unless the default has been overridden with - ``CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY`` (see below). - Note that if the branch specified in ``GIT_TAG`` is different to - the upstream branch currently being tracked, it is not safe to - perform a rebase. In that situation, ``REBASE`` will silently be - treated as ``CHECKOUT`` instead. - - ``REBASE_CHECKOUT`` - Same as ``REBASE`` except if the rebase fails, an annotated tag will - be created at the original ``HEAD`` position from before the rebase - and then checkout ``GIT_TAG`` just like the ``CHECKOUT`` strategy. - The message stored on the annotated tag will give information about - what was attempted and the tag name will include a timestamp so that - each failed run will add a new tag. This strategy ensures no changes - will be lost, but updates should always succeed if ``GIT_TAG`` refers - to a valid ref unless there are uncommitted changes that cannot be - popped successfully. - - The variable ``CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY`` can be set to - override the default strategy. This variable should not be set by a - project, it is intended for the user to set. It is primarily intended - for use in continuous integration scripts to ensure that when history - is rewritten on a remote branch, the build doesn't end up with - unintended changes or failed builds resulting from conflicts during - rebase operations. - - *Subversion* - ``SVN_REPOSITORY <url>`` - URL of the Subversion repository. - - ``SVN_REVISION -r<rev>`` - Revision to checkout from the Subversion repository. - - ``SVN_USERNAME <username>`` - Username for the Subversion checkout and update. - - ``SVN_PASSWORD <password>`` - Password for the Subversion checkout and update. - - ``SVN_TRUST_CERT <bool>`` - Specifies whether to trust the Subversion server site certificate. If - enabled, the ``--trust-server-cert`` option is passed to the ``svn`` - checkout and update commands. - - *Mercurial* - ``HG_REPOSITORY <url>`` - URL of the mercurial repository. - - ``HG_TAG <tag>`` - Mercurial branch name, tag or commit id. - - *CVS* - ``CVS_REPOSITORY <cvsroot>`` - CVSROOT of the CVS repository. - - ``CVS_MODULE <mod>`` - Module to checkout from the CVS repository. - - ``CVS_TAG <tag>`` - Tag to checkout from the CVS repository. - - **Update Step Options:** - Whenever CMake is re-run, by default the external project's sources will be - updated if the download method supports updates (e.g. a git repository - would be checked if the ``GIT_TAG`` does not refer to a specific commit). - - ``UPDATE_COMMAND <cmd>...`` - Overrides the download method's update step with a custom command. - The command may use - :manual:`generator expressions <cmake-generator-expressions(7)>`. - - ``UPDATE_DISCONNECTED <bool>`` - .. versionadded:: 3.2 - - When enabled, this option causes the update step to be skipped (but see - below for changed behavior where this is not the case). It does not - prevent the download step. The update step can still be - added as a step target (see :command:`ExternalProject_Add_StepTargets`) - and called manually. This is useful if you want to allow developers to - build the project when disconnected from the network (the network may - still be needed for the download step though). - - .. versionchanged:: 3.27 - - When ``UPDATE_DISCONNECTED`` is true, the update step will be executed - if any details about the update or download step are changed. - Furthermore, if using the git download/update method, the update - logic will be modified to skip attempts to contact the remote. - If the ``GIT_TAG`` mentions a ref that is not known locally, the - update step will halt with a fatal error. - - When this option is present, it is generally advisable to make the value - a cache variable under the developer's control rather than hard-coding - it. If this option is not present, the default value is taken from the - ``EP_UPDATE_DISCONNECTED`` directory property. If that is also not - defined, updates are performed as normal. The ``EP_UPDATE_DISCONNECTED`` - directory property is intended as a convenience for controlling the - ``UPDATE_DISCONNECTED`` behavior for an entire section of a project's - directory hierarchy and may be a more convenient method of giving - developers control over whether or not to perform updates (assuming the - project also provides a cache variable or some other convenient method - for setting the directory property). - - This may cause a step target to be created automatically for the - ``download`` step. See policy :policy:`CMP0114`. - - **Patch Step Options:** - ``PATCH_COMMAND <cmd>...`` - Specifies a custom command to patch the sources after an update. By - default, no patch command is defined. Note that it can be quite difficult - to define an appropriate patch command that performs robustly, especially - for download methods such as git where changing the ``GIT_TAG`` will not - discard changes from a previous patch, but the patch command will be - called again after updating to the new tag. - - **Configure Step Options:** - The configure step is run after the download and update steps. By default, - the external project is assumed to be a CMake project, but this can be - overridden if required. - - ``CONFIGURE_COMMAND <cmd>...`` - The default configure command runs CMake with a few options based on - the main project. The options added are typically only those needed to - use the same generator as the main project, but the ``CMAKE_GENERATOR`` - option can be given to override this. The project is responsible for - adding any toolchain details, flags or other settings it wants to - re-use from the main project or otherwise specify (see ``CMAKE_ARGS``, - ``CMAKE_CACHE_ARGS`` and ``CMAKE_CACHE_DEFAULT_ARGS`` below). - - For non-CMake external projects, the ``CONFIGURE_COMMAND`` option must - be used to override the default configure command - (:manual:`generator expressions <cmake-generator-expressions(7)>` are - supported). For projects that require no configure step, specify this - option with an empty string as the command to execute. - - ``CMAKE_COMMAND /.../cmake`` - Specify an alternative cmake executable for the configure step (use an - absolute path). This is generally not recommended, since it is - usually desirable to use the same CMake version throughout the whole - build. This option is ignored if a custom configure command has been - specified with ``CONFIGURE_COMMAND``. - - ``CMAKE_GENERATOR <gen>`` - Override the CMake generator used for the configure step. Without this - option, the same generator as the main build will be used. This option is - ignored if a custom configure command has been specified with the - ``CONFIGURE_COMMAND`` option. - - ``CMAKE_GENERATOR_PLATFORM <platform>`` - .. versionadded:: 3.1 - - Pass a generator-specific platform name to the CMake command (see - :variable:`CMAKE_GENERATOR_PLATFORM`). It is an error to provide this - option without the ``CMAKE_GENERATOR`` option. - - ``CMAKE_GENERATOR_TOOLSET <toolset>`` - Pass a generator-specific toolset name to the CMake command (see - :variable:`CMAKE_GENERATOR_TOOLSET`). It is an error to provide this - option without the ``CMAKE_GENERATOR`` option. - - ``CMAKE_GENERATOR_INSTANCE <instance>`` - .. versionadded:: 3.11 - - Pass a generator-specific instance selection to the CMake command (see - :variable:`CMAKE_GENERATOR_INSTANCE`). It is an error to provide this - option without the ``CMAKE_GENERATOR`` option. - - ``CMAKE_ARGS <arg>...`` - The specified arguments are passed to the :program:`cmake` command line. - They can be any argument the :program:`cmake` command understands, not just - cache values defined by ``-D...`` arguments (see also - :manual:`CMake Options <cmake(1)>`). - - .. versionadded:: 3.3 - Arguments may use - :manual:`generator expressions <cmake-generator-expressions(7)>`. - - ``CMAKE_CACHE_ARGS <arg>...`` - This is an alternate way of specifying cache variables where command line - length issues may become a problem. The arguments are expected to be in - the form ``-Dvar:STRING=value``, which are then transformed into - CMake :command:`set` commands with the ``FORCE`` option used. These - ``set()`` commands are written to a pre-load script which is then applied - using the :manual:`cmake -C <cmake(1)>` command line option. - - .. versionadded:: 3.3 - Arguments may use - :manual:`generator expressions <cmake-generator-expressions(7)>`. - - ``CMAKE_CACHE_DEFAULT_ARGS <arg>...`` - .. versionadded:: 3.2 - - This is the same as the ``CMAKE_CACHE_ARGS`` option except the ``set()`` - commands do not include the ``FORCE`` keyword. This means the values act - as initial defaults only and will not override any variables already set - from a previous run. Use this option with care, as it can lead to - different behavior depending on whether the build starts from a fresh - build directory or re-uses previous build contents. - - .. versionadded:: 3.15 - If the CMake generator is the ``Green Hills MULTI`` and not overridden, - the original project's settings for the GHS toolset and target system - customization cache variables are propagated into the external project. - - ``SOURCE_SUBDIR <dir>`` - .. versionadded:: 3.7 - - When no ``CONFIGURE_COMMAND`` option is specified, the configure step - assumes the external project has a ``CMakeLists.txt`` file at the top of - its source tree (i.e. in ``SOURCE_DIR``). The ``SOURCE_SUBDIR`` option - can be used to point to an alternative directory within the source tree - to use as the top of the CMake source tree instead. This must be a - relative path and it will be interpreted as being relative to - ``SOURCE_DIR``. - - .. versionadded:: 3.14 - When ``BUILD_IN_SOURCE`` option is enabled, the ``BUILD_COMMAND`` - is used to point to an alternative directory within the source tree. - - ``CONFIGURE_HANDLED_BY_BUILD <bool>`` - .. versionadded:: 3.20 - - Enabling this option relaxes the dependencies of the configure step on - other external projects to order-only. This means the configure step will - be executed after its external project dependencies are built but it will - not be marked dirty when one of its external project dependencies is - rebuilt. This option can be enabled when the build step is smart enough - to figure out if the configure step needs to be rerun. CMake and Meson are - examples of build systems whose build step is smart enough to know if the - configure step needs to be rerun. - - **Build Step Options:** - If the configure step assumed the external project uses CMake as its build - system, the build step will also. Otherwise, the build step will assume a - Makefile-based build and simply run ``make`` with no arguments as the - default build step. This can be overridden with custom build commands if - required. - - If both the main project and the external project use make as their build - tool, the build step of the external project is invoked as a recursive - make using ``$(MAKE)``. This will communicate some build tool settings - from the main project to the external project. If either the main project - or external project is not using make, no build tool settings will be - passed to the external project other than those established by the - configure step (i.e. running ``ninja -v`` in the main project will not - pass ``-v`` to the external project's build step, even if it also uses - ``ninja`` as its build tool). - - ``BUILD_COMMAND <cmd>...`` - Overrides the default build command - (:manual:`generator expressions <cmake-generator-expressions(7)>` are - supported). If this option is not given, the default build command will - be chosen to integrate with the main build in the most appropriate way - (e.g. using recursive ``make`` for Makefile generators or - :option:`cmake --build` if the project uses a CMake build). This option - can be specified with an empty string as the command to make the build - step do nothing. - - ``BUILD_IN_SOURCE <bool>`` - When this option is enabled, the build will be done directly within the - external project's source tree. This should generally be avoided, the use - of a separate build directory is usually preferred, but it can be useful - when the external project assumes an in-source build. The ``BINARY_DIR`` - option should not be specified if building in-source. - - ``BUILD_ALWAYS <bool>`` - Enabling this option forces the build step to always be run. This can be - the easiest way to robustly ensure that the external project's own build - dependencies are evaluated rather than relying on the default - success timestamp-based method. This option is not normally needed unless - developers are expected to modify something the external project's build - depends on in a way that is not detectable via the step target - dependencies (e.g. ``SOURCE_DIR`` is used without a download method and - developers might modify the sources in ``SOURCE_DIR``). - - ``BUILD_BYPRODUCTS <file>...`` - .. versionadded:: 3.2 - - Specifies files that will be generated by the build command but which - might or might not have their modification time updated by subsequent - builds. This may also be required to explicitly declare dependencies - when using the :generator:`Ninja` generator. - These ultimately get passed through as ``BYPRODUCTS`` to the - build step's own underlying call to :command:`add_custom_command`, which - has additional documentation. - - **Install Step Options:** - If the configure step assumed the external project uses CMake as its build - system, the install step will also. Otherwise, the install step will assume - a Makefile-based build and simply run ``make install`` as the default build - step. This can be overridden with custom install commands if required. - - ``INSTALL_COMMAND <cmd>...`` - The external project's own install step is invoked as part of the main - project's *build*. It is done after the external project's build step - and may be before or after the external project's test step (see the - ``TEST_BEFORE_INSTALL`` option below). The external project's install - rules are not part of the main project's install rules, so if anything - from the external project should be installed as part of the main build, - these need to be specified in the main build as additional - :command:`install` commands. The default install step builds the - ``install`` target of the external project, but this can be overridden - with a custom command using this option - (:manual:`generator expressions <cmake-generator-expressions(7)>` are - supported). Passing an empty string as the ``<cmd>`` makes the install - step do nothing. - - ``INSTALL_BYPRODUCTS <file>...`` - .. versionadded:: 3.26 - - Specifies files that will be generated by the install command but which - might or might not have their modification time updated by subsequent - installs. This may also be required to explicitly declare dependencies - when using the :generator:`Ninja` generator. - These ultimately get passed through as ``BYPRODUCTS`` to the - install step's own underlying call to :command:`add_custom_command`, which - has additional documentation. - - .. note:: - If the :envvar:`CMAKE_INSTALL_MODE` environment variable is set when the - main project is built, it will only have an effect if the following - conditions are met: - - * The main project's configure step assumed the external project uses - CMake as its build system. - * The external project's install command actually runs. Note that due - to the way ``ExternalProject`` may use timestamps internally, if - nothing the install step depends on needs to be re-executed, the - install command might also not need to run. - - Note also that ``ExternalProject`` does not check whether the - :envvar:`CMAKE_INSTALL_MODE` environment variable changes from one run - to another. - - **Test Step Options:** - The test step is only defined if at least one of the following ``TEST_...`` - options are provided. - - ``TEST_COMMAND <cmd>...`` - Overrides the default test command - (:manual:`generator expressions <cmake-generator-expressions(7)>` are - supported). If this option is not given, the default behavior of the test - step is to build the external project's own ``test`` target. This option - can be specified with ``<cmd>`` as an empty string, which allows the test - step to still be defined, but it will do nothing. Do not specify any of - the other ``TEST_...`` options if providing an empty string as the test - command, but prefer to omit all ``TEST_...`` options altogether if the - test step target is not needed. - - ``TEST_BEFORE_INSTALL <bool>`` - When this option is enabled, the test step will be executed before the - install step. The default behavior is for the test step to run after the - install step. - - ``TEST_AFTER_INSTALL <bool>`` - This option is mainly useful as a way to indicate that the test step is - desired but all default behavior is sufficient. Specifying this option - with a boolean true value ensures the test step is defined and that it - comes after the install step. If both ``TEST_BEFORE_INSTALL`` and - ``TEST_AFTER_INSTALL`` are enabled, the latter is silently ignored. - - ``TEST_EXCLUDE_FROM_MAIN <bool>`` - .. versionadded:: 3.2 - - If enabled, the main build's default ALL target will not depend on the - test step. This can be a useful way of ensuring the test step is defined - but only gets invoked when manually requested. - This may cause a step target to be created automatically for either - the ``install`` or ``build`` step. See policy :policy:`CMP0114`. - - **Output Logging Options:** - Each of the following ``LOG_...`` options can be used to wrap the relevant - step in a script to capture its output to files. The log files will be - created in ``LOG_DIR`` if supplied or otherwise the ``STAMP_DIR`` - directory with step-specific file names. - - ``LOG_DOWNLOAD <bool>`` - When enabled, the output of the download step is logged to files. - - ``LOG_UPDATE <bool>`` - When enabled, the output of the update step is logged to files. - - ``LOG_PATCH <bool>`` - .. versionadded:: 3.14 - - When enabled, the output of the patch step is logged to files. - - ``LOG_CONFIGURE <bool>`` - When enabled, the output of the configure step is logged to files. - - ``LOG_BUILD <bool>`` - When enabled, the output of the build step is logged to files. - - ``LOG_INSTALL <bool>`` - When enabled, the output of the install step is logged to files. - - ``LOG_TEST <bool>`` - When enabled, the output of the test step is logged to files. - - ``LOG_MERGED_STDOUTERR <bool>`` - .. versionadded:: 3.14 - - When enabled, stdout and stderr will be merged for any step whose - output is being logged to files. - - ``LOG_OUTPUT_ON_FAILURE <bool>`` - .. versionadded:: 3.14 - - This option only has an effect if at least one of the other ``LOG_<step>`` - options is enabled. If an error occurs for a step which has logging to - file enabled, that step's output will be printed to the console if - ``LOG_OUTPUT_ON_FAILURE`` is set to true. For cases where a large amount - of output is recorded, just the end of that output may be printed to the - console. - - **Terminal Access Options:** - .. versionadded:: 3.4 - - Steps can be given direct access to the terminal in some cases. Giving a - step access to the terminal may allow it to receive terminal input if - required, such as for authentication details not provided by other options. - With the :generator:`Ninja` generator, these options place the steps in the - ``console`` :prop_gbl:`job pool <JOB_POOLS>`. Each step can be given access - to the terminal individually via the following options: - - ``USES_TERMINAL_DOWNLOAD <bool>`` - Give the download step access to the terminal. - - ``USES_TERMINAL_UPDATE <bool>`` - Give the update step access to the terminal. - - ``USES_TERMINAL_PATCH <bool>`` - .. versionadded:: 3.23 - - Give the patch step access to the terminal. - - ``USES_TERMINAL_CONFIGURE <bool>`` - Give the configure step access to the terminal. - - ``USES_TERMINAL_BUILD <bool>`` - Give the build step access to the terminal. - - ``USES_TERMINAL_INSTALL <bool>`` - Give the install step access to the terminal. - - ``USES_TERMINAL_TEST <bool>`` - Give the test step access to the terminal. - - **Target Options:** - ``DEPENDS <targets>...`` - Specify other targets on which the external project depends. The other - targets will be brought up to date before any of the external project's - steps are executed. Because the external project uses additional custom - targets internally for each step, the ``DEPENDS`` option is the most - convenient way to ensure all of those steps depend on the other targets. - Simply doing - :command:`add_dependencies(\<name\> \<targets\>) <add_dependencies>` will - not make any of the steps dependent on ``<targets>``. - - ``EXCLUDE_FROM_ALL <bool>`` - When enabled, this option excludes the external project from the default - ALL target of the main build. - - ``STEP_TARGETS <step-target>...`` - Generate custom targets for the specified steps. This is required if the - steps need to be triggered manually or if they need to be used as - dependencies of other targets. If this option is not specified, the - default value is taken from the ``EP_STEP_TARGETS`` directory property. - See :command:`ExternalProject_Add_StepTargets` below for further - discussion of the effects of this option. - - ``INDEPENDENT_STEP_TARGETS <step-target>...`` - .. deprecated:: 3.19 - This is allowed only if policy :policy:`CMP0114` is not set to ``NEW``. - - Generates custom targets for the specified steps and prevent these targets - from having the usual dependencies applied to them. If this option is not - specified, the default value is taken from the - ``EP_INDEPENDENT_STEP_TARGETS`` directory property. This option is mostly - useful for allowing individual steps to be driven independently, such as - for a CDash setup where each step should be initiated and reported - individually rather than as one whole build. See - :command:`ExternalProject_Add_StepTargets` below for further discussion - of the effects of this option. - - **Miscellaneous Options:** - ``LIST_SEPARATOR <sep>`` - For any of the various ``..._COMMAND`` options, and ``CMAKE_ARGS``, - replace ``;`` with ``<sep>`` in the specified command lines. - This can be useful where list variables may be given in commands where - they should end up as space-separated arguments (``<sep>`` would be a - single space character string in this case). - - ``COMMAND <cmd>...`` - Any of the other ``..._COMMAND`` options can have additional commands - appended to them by following them with as many ``COMMAND ...`` options - as needed - (:manual:`generator expressions <cmake-generator-expressions(7)>` are - supported). For example: - - .. code-block:: cmake - - ExternalProject_Add(example - ... # Download options, etc. - BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build" - COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG> - COMMAND ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete" - ) +Directory Options +""""""""""""""""" + +Most of the time, the default directory layout is sufficient. It is largely +an implementation detail that the main project usually doesn't need to +change. In some circumstances, however, control over the directory layout +can be useful or necessary. The directory options are potentially more +useful from the point of view that the main build can use the +:command:`ExternalProject_Get_Property` command to retrieve their values, +thereby allowing the main project to refer to build artifacts of the +external project. + +``PREFIX <dir>`` + Root directory for the external project. Unless otherwise noted below, + all other directories associated with the external project will be + created under here. + +``TMP_DIR <dir>`` + Directory in which to store temporary files. + +``STAMP_DIR <dir>`` + Directory in which to store the timestamps of each step. Log files from + individual steps are also created in here unless overridden by LOG_DIR + (see *Logging Options* below). + +``LOG_DIR <dir>`` + .. versionadded:: 3.14 + + Directory in which to store the logs of each step. + +``DOWNLOAD_DIR <dir>`` + Directory in which to store downloaded files before unpacking them. This + directory is only used by the URL download method, all other download + methods use ``SOURCE_DIR`` directly instead. + +``SOURCE_DIR <dir>`` + Source directory into which downloaded contents will be unpacked, or for + non-URL download methods, the directory in which the repository should be + checked out, cloned, etc. If no download method is specified, this must + point to an existing directory where the external project has already + been unpacked or cloned/checked out. + + .. note:: + If a download method is specified, any existing contents of the source + directory may be deleted. Only the URL download method checks whether + this directory is either missing or empty before initiating the + download, stopping with an error if it is not empty. All other + download methods silently discard any previous contents of the source + directory. + +``BINARY_DIR <dir>`` + Specify the build directory location. This option is ignored if + ``BUILD_IN_SOURCE`` is enabled. + +``INSTALL_DIR <dir>`` + Installation prefix to be placed in the ``<INSTALL_DIR>`` placeholder. + This does not actually configure the external project to install to + the given prefix. That must be done by passing appropriate arguments + to the external project configuration step, e.g. using ``<INSTALL_DIR>``. + +If any of the above ``..._DIR`` options are not specified, their defaults +are computed as follows. If the ``PREFIX`` option is given or the +``EP_PREFIX`` directory property is set, then an external project is built +and installed under the specified prefix:: + + TMP_DIR = <prefix>/tmp + STAMP_DIR = <prefix>/src/<name>-stamp + DOWNLOAD_DIR = <prefix>/src + SOURCE_DIR = <prefix>/src/<name> + BINARY_DIR = <prefix>/src/<name>-build + INSTALL_DIR = <prefix> + LOG_DIR = <STAMP_DIR> + +Otherwise, if the ``EP_BASE`` directory property is set then components +of an external project are stored under the specified base:: + + TMP_DIR = <base>/tmp/<name> + STAMP_DIR = <base>/Stamp/<name> + DOWNLOAD_DIR = <base>/Download/<name> + SOURCE_DIR = <base>/Source/<name> + BINARY_DIR = <base>/Build/<name> + INSTALL_DIR = <base>/Install/<name> + LOG_DIR = <STAMP_DIR> + +If no ``PREFIX``, ``EP_PREFIX``, or ``EP_BASE`` is specified, then the +default is to set ``PREFIX`` to ``<name>-prefix``. Relative paths are +interpreted with respect to :variable:`CMAKE_CURRENT_BINARY_DIR` at the +point where ``ExternalProject_Add()`` is called. + +Download Step Options +""""""""""""""""""""" + +A download method can be omitted if the ``SOURCE_DIR`` option is used to +point to an existing non-empty directory. Otherwise, one of the download +methods below must be specified (multiple download methods should not be +given) or a custom ``DOWNLOAD_COMMAND`` provided. + +``DOWNLOAD_COMMAND <cmd>...`` + Overrides the command used for the download step + (:manual:`generator expressions <cmake-generator-expressions(7)>` are + supported). If this option is specified, all other download options will + be ignored. Providing an empty string for ``<cmd>`` effectively disables + the download step. + +URL +~~~ + +``URL <url1> [<url2>...]`` + List of paths and/or URL(s) of the external project's source. When more + than one URL is given, they are tried in turn until one succeeds. A URL + may be an ordinary path in the local file system (in which case it + must be the only URL provided) or any downloadable URL supported by the + :command:`file(DOWNLOAD)` command. A local filesystem path may refer to + either an existing directory or to an archive file, whereas a URL is + expected to point to a file which can be treated as an archive. When an + archive is used, it will be unpacked automatically unless the + ``DOWNLOAD_NO_EXTRACT`` option is set to prevent it. The archive type + is determined by inspecting the actual content rather than using logic + based on the file extension. + + .. versionchanged:: 3.7 + Multiple URLs are allowed. + +``URL_HASH <algo>=<hashValue>`` + Hash of the archive file to be downloaded. The argument should be of + the form ``<algo>=<hashValue>`` where ``algo`` can be any of the hashing + algorithms supported by the :command:`file()` command. Specifying this + option is strongly recommended for URL downloads, as it ensures the + integrity of the downloaded content. It is also used as a check for a + previously downloaded file, allowing connection to the remote location + to be avoided altogether if the local directory already has a file from + an earlier download that matches the specified hash. + +``URL_MD5 <md5>`` + Equivalent to ``URL_HASH MD5=<md5>``. + +``DOWNLOAD_NAME <fname>`` + File name to use for the downloaded file. If not given, the end of the + URL is used to determine the file name. This option is rarely needed, + the default name is generally suitable and is not normally used outside + of code internal to the ``ExternalProject`` module. + +``DOWNLOAD_EXTRACT_TIMESTAMP <bool>`` + .. versionadded:: 3.24 + + When specified with a true value, the timestamps of the extracted + files will match those in the archive. When false, the timestamps of + the extracted files will reflect the time at which the extraction + was performed. If the download URL changes, timestamps based off + those in the archive can result in dependent targets not being rebuilt + when they potentially should have been. Therefore, unless the file + timestamps are significant to the project in some way, use a false + value for this option. If ``DOWNLOAD_EXTRACT_TIMESTAMP`` is not given, + the default is false. See policy :policy:`CMP0135`. + +``DOWNLOAD_NO_EXTRACT <bool>`` + .. versionadded:: 3.6 + + Allows the extraction part of the download step to be disabled by + passing a boolean true value for this option. If this option is not + given, the downloaded contents will be unpacked automatically if + required. If extraction has been disabled, the full path to the + downloaded file is available as ``<DOWNLOADED_FILE>`` in subsequent + steps or as the property ``DOWNLOADED_FILE`` with the + :command:`ExternalProject_Get_Property` command. + +``DOWNLOAD_NO_PROGRESS <bool>`` + Can be used to disable logging the download progress. If this option is + not given, download progress messages will be logged. + +``TIMEOUT <seconds>`` + Maximum time allowed for file download operations. + +``INACTIVITY_TIMEOUT <seconds>`` + .. versionadded:: 3.19 + + Terminate the operation after a period of inactivity. + +``HTTP_USERNAME <username>`` + .. versionadded:: 3.7 + + Username for the download operation if authentication is required. + +``HTTP_PASSWORD <password>`` + .. versionadded:: 3.7 + + Password for the download operation if authentication is required. + +``HTTP_HEADER <header1> [<header2>...]`` + .. versionadded:: 3.7 + + Provides an arbitrary list of HTTP headers for the download operation. + This can be useful for accessing content in systems like AWS, etc. + +``TLS_VERIFY <bool>`` + Specifies whether certificate verification should be performed for + https URLs. If this option is not provided, the default behavior is + determined by the :variable:`CMAKE_TLS_VERIFY` variable (see + :command:`file(DOWNLOAD)`). If that is also not set, certificate + verification will not be performed. In situations where ``URL_HASH`` + cannot be provided, this option can be an alternative verification + measure. + + .. versionchanged:: 3.6 + This option also applies to ``git clone`` invocations, although the + default behavior is different. If ``TLS_VERIFY`` is not given and + :variable:`CMAKE_TLS_VERIFY` is not set, the behavior will be + determined by git's defaults. Normally, the ``sslVerify`` git + config setting defaults to true, but the user may have overridden + this at a global level. + +``TLS_CAINFO <file>`` + Specify a custom certificate authority file to use if ``TLS_VERIFY`` + is enabled. If this option is not specified, the value of the + :variable:`CMAKE_TLS_CAINFO` variable will be used instead (see + :command:`file(DOWNLOAD)`) + +``NETRC <level>`` + .. versionadded:: 3.11 + + Specify whether the ``.netrc`` file is to be used for operation. + If this option is not specified, the value of the + :variable:`CMAKE_NETRC` variable will be used instead + (see :command:`file(DOWNLOAD)`). Valid levels are: + + ``IGNORED`` + The ``.netrc`` file is ignored. + This is the default. + ``OPTIONAL`` + The ``.netrc`` file is optional, and information in the URL + is preferred. The file will be scanned to find which ever + information is not specified in the URL. + ``REQUIRED`` + The ``.netrc`` file is required, and information in the URL + is ignored. + +``NETRC_FILE <file>`` + .. versionadded:: 3.11 + + Specify an alternative ``.netrc`` file to the one in your home directory + if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option + is not specified, the value of the :variable:`CMAKE_NETRC_FILE` variable + will be used instead (see :command:`file(DOWNLOAD)`) + +.. versionadded:: 3.1 + Added support for `tbz2`, `.tar.xz`, `.txz`, and `.7z` extensions. + +Git +~~~ + +NOTE: A git version of 1.6.5 or later is required if this download method +is used. + +``GIT_REPOSITORY <url>`` + URL of the git repository. Any URL understood by the ``git`` command + may be used. + + .. versionchanged:: 3.27 + A relative URL will be resolved based on the parent project's + remote, subject to :policy:`CMP0150`. See the policy documentation + for how the remote is selected, including conditions where the + remote selection can fail. Local filesystem remotes should + always use absolute paths. + +``GIT_TAG <tag>`` + Git branch name, tag or commit hash. Note that branch names and tags + should generally be specified as remote names (i.e. ``origin/myBranch`` + rather than simply ``myBranch``). This ensures that if the remote end + has its tag moved or branch rebased or history rewritten, the local + clone will still be updated correctly. In general, however, specifying + a commit hash should be preferred for a number of reasons: + + - If the local clone already has the commit corresponding to the hash, + no ``git fetch`` needs to be performed to check for changes each time + CMake is re-run. This can result in a significant speed up if many + external projects are being used. + - Using a specific git hash ensures that the main project's own history + is fully traceable to a specific point in the external project's + evolution. If a branch or tag name is used instead, then checking out + a specific commit of the main project doesn't necessarily pin the + whole build to a specific point in the life of the external project. + The lack of such deterministic behavior makes the main project lose + traceability and repeatability. + + If ``GIT_SHALLOW`` is enabled then ``GIT_TAG`` works only with + branch names and tags. A commit hash is not allowed. + + Note that if not provided, ``GIT_TAG`` defaults to ``master``, not the + default Git branch name. + +``GIT_REMOTE_NAME <name>`` + The optional name of the remote. If this option is not specified, it + defaults to ``origin``. + +``GIT_SUBMODULES <module>...`` + Specific git submodules that should also be updated. If this option is + not provided, all git submodules will be updated. + + .. versionchanged:: 3.16 + When :policy:`CMP0097` is set to ``NEW``, if this value is set + to an empty string then no submodules are initialized or updated. + +``GIT_SUBMODULES_RECURSE <bool>`` + .. versionadded:: 3.17 + + Specify whether git submodules (if any) should update recursively by + passing the ``--recursive`` flag to ``git submodule update``. + If not specified, the default is on. + +``GIT_SHALLOW <bool>`` + .. versionadded:: 3.6 + + When this option is enabled, the ``git clone`` operation will be given + the ``--depth 1`` option. This performs a shallow clone, which avoids + downloading the whole history and instead retrieves just the commit + denoted by the ``GIT_TAG`` option. + +``GIT_PROGRESS <bool>`` + .. versionadded:: 3.8 + + When enabled, this option instructs the ``git clone`` operation to + report its progress by passing it the ``--progress`` option. Without + this option, the clone step for large projects may appear to make the + build stall, since nothing will be logged until the clone operation + finishes. While this option can be used to provide progress to prevent + the appearance of the build having stalled, it may also make the build + overly noisy if lots of external projects are used. + +``GIT_CONFIG <option1> [<option2>...]`` + .. versionadded:: 3.8 + + Specify a list of config options to pass to ``git clone``. Each option + listed will be transformed into its own ``--config <option>`` on the + ``git clone`` command line, with each option required to be in the + form ``key=value``. + +``GIT_REMOTE_UPDATE_STRATEGY <strategy>`` + .. versionadded:: 3.18 + + When ``GIT_TAG`` refers to a remote branch, this option can be used to + specify how the update step behaves. The ``<strategy>`` must be one of + the following: + + ``CHECKOUT`` + Ignore the local branch and always checkout the branch specified by + ``GIT_TAG``. + + ``REBASE`` + Try to rebase the current branch to the one specified by ``GIT_TAG``. + If there are local uncommitted changes, they will be stashed first + and popped again after rebasing. If rebasing or popping stashed + changes fail, abort the rebase and halt with an error. + When ``GIT_REMOTE_UPDATE_STRATEGY`` is not present, this is the + default strategy unless the default has been overridden with + ``CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY`` (see below). + Note that if the branch specified in ``GIT_TAG`` is different to + the upstream branch currently being tracked, it is not safe to + perform a rebase. In that situation, ``REBASE`` will silently be + treated as ``CHECKOUT`` instead. + + ``REBASE_CHECKOUT`` + Same as ``REBASE`` except if the rebase fails, an annotated tag will + be created at the original ``HEAD`` position from before the rebase + and then checkout ``GIT_TAG`` just like the ``CHECKOUT`` strategy. + The message stored on the annotated tag will give information about + what was attempted and the tag name will include a timestamp so that + each failed run will add a new tag. This strategy ensures no changes + will be lost, but updates should always succeed if ``GIT_TAG`` refers + to a valid ref unless there are uncommitted changes that cannot be + popped successfully. + + The variable ``CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY`` can be set to + override the default strategy. This variable should not be set by a + project, it is intended for the user to set. It is primarily intended + for use in continuous integration scripts to ensure that when history + is rewritten on a remote branch, the build doesn't end up with + unintended changes or failed builds resulting from conflicts during + rebase operations. + +Subversion +~~~~~~~~~~ + +``SVN_REPOSITORY <url>`` + URL of the Subversion repository. + +``SVN_REVISION -r<rev>`` + Revision to checkout from the Subversion repository. + +``SVN_USERNAME <username>`` + Username for the Subversion checkout and update. + +``SVN_PASSWORD <password>`` + Password for the Subversion checkout and update. + +``SVN_TRUST_CERT <bool>`` + Specifies whether to trust the Subversion server site certificate. If + enabled, the ``--trust-server-cert`` option is passed to the ``svn`` + checkout and update commands. + +Mercurial +~~~~~~~~~ + +``HG_REPOSITORY <url>`` + URL of the mercurial repository. + +``HG_TAG <tag>`` + Mercurial branch name, tag or commit id. + +CVS +~~~ + +``CVS_REPOSITORY <cvsroot>`` + CVSROOT of the CVS repository. + +``CVS_MODULE <mod>`` + Module to checkout from the CVS repository. + +``CVS_TAG <tag>`` + Tag to checkout from the CVS repository. + +Update Step Options +""""""""""""""""""" + +Whenever CMake is re-run, by default the external project's sources will be +updated if the download method supports updates (e.g. a git repository +would be checked if the ``GIT_TAG`` does not refer to a specific commit). + +``UPDATE_COMMAND <cmd>...`` + Overrides the download method's update step with a custom command. + The command may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +``UPDATE_DISCONNECTED <bool>`` + .. versionadded:: 3.2 + + When enabled, this option causes the update step to be skipped (but see + below for changed behavior where this is not the case). It does not + prevent the download step. The update step can still be + added as a step target (see :command:`ExternalProject_Add_StepTargets`) + and called manually. This is useful if you want to allow developers to + build the project when disconnected from the network (the network may + still be needed for the download step though). + + .. versionchanged:: 3.27 + + When ``UPDATE_DISCONNECTED`` is true, the update step will be executed + if any details about the update or download step are changed. + Furthermore, if using the git download/update method, the update + logic will be modified to skip attempts to contact the remote. + If the ``GIT_TAG`` mentions a ref that is not known locally, the + update step will halt with a fatal error. + + When this option is present, it is generally advisable to make the value + a cache variable under the developer's control rather than hard-coding + it. If this option is not present, the default value is taken from the + ``EP_UPDATE_DISCONNECTED`` directory property. If that is also not + defined, updates are performed as normal. The ``EP_UPDATE_DISCONNECTED`` + directory property is intended as a convenience for controlling the + ``UPDATE_DISCONNECTED`` behavior for an entire section of a project's + directory hierarchy and may be a more convenient method of giving + developers control over whether or not to perform updates (assuming the + project also provides a cache variable or some other convenient method + for setting the directory property). + + This may cause a step target to be created automatically for the + ``download`` step. See policy :policy:`CMP0114`. + +Patch Step Options +"""""""""""""""""" + +``PATCH_COMMAND <cmd>...`` + Specifies a custom command to patch the sources after an update. By + default, no patch command is defined. Note that it can be quite difficult + to define an appropriate patch command that performs robustly, especially + for download methods such as git where changing the ``GIT_TAG`` will not + discard changes from a previous patch, but the patch command will be + called again after updating to the new tag. + +Configure Step Options +"""""""""""""""""""""" + +The configure step is run after the download and update steps. By default, +the external project is assumed to be a CMake project, but this can be +overridden if required. + +``CONFIGURE_COMMAND <cmd>...`` + The default configure command runs CMake with a few options based on + the main project. The options added are typically only those needed to + use the same generator as the main project, but the ``CMAKE_GENERATOR`` + option can be given to override this. The project is responsible for + adding any toolchain details, flags or other settings it wants to + re-use from the main project or otherwise specify (see ``CMAKE_ARGS``, + ``CMAKE_CACHE_ARGS`` and ``CMAKE_CACHE_DEFAULT_ARGS`` below). + + For non-CMake external projects, the ``CONFIGURE_COMMAND`` option must + be used to override the default configure command + (:manual:`generator expressions <cmake-generator-expressions(7)>` are + supported). For projects that require no configure step, specify this + option with an empty string as the command to execute. + +``CMAKE_COMMAND /.../cmake`` + Specify an alternative cmake executable for the configure step (use an + absolute path). This is generally not recommended, since it is + usually desirable to use the same CMake version throughout the whole + build. This option is ignored if a custom configure command has been + specified with ``CONFIGURE_COMMAND``. + +``CMAKE_GENERATOR <gen>`` + Override the CMake generator used for the configure step. Without this + option, the same generator as the main build will be used. This option is + ignored if a custom configure command has been specified with the + ``CONFIGURE_COMMAND`` option. + +``CMAKE_GENERATOR_PLATFORM <platform>`` + .. versionadded:: 3.1 + + Pass a generator-specific platform name to the CMake command (see + :variable:`CMAKE_GENERATOR_PLATFORM`). It is an error to provide this + option without the ``CMAKE_GENERATOR`` option. + +``CMAKE_GENERATOR_TOOLSET <toolset>`` + Pass a generator-specific toolset name to the CMake command (see + :variable:`CMAKE_GENERATOR_TOOLSET`). It is an error to provide this + option without the ``CMAKE_GENERATOR`` option. + +``CMAKE_GENERATOR_INSTANCE <instance>`` + .. versionadded:: 3.11 + + Pass a generator-specific instance selection to the CMake command (see + :variable:`CMAKE_GENERATOR_INSTANCE`). It is an error to provide this + option without the ``CMAKE_GENERATOR`` option. + +``CMAKE_ARGS <arg>...`` + The specified arguments are passed to the :program:`cmake` command line. + They can be any argument the :program:`cmake` command understands, not just + cache values defined by ``-D...`` arguments (see also + :manual:`CMake Options <cmake(1)>`). + + .. versionadded:: 3.3 + Arguments may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +``CMAKE_CACHE_ARGS <arg>...`` + This is an alternate way of specifying cache variables where command line + length issues may become a problem. The arguments are expected to be in + the form ``-Dvar:STRING=value``, which are then transformed into + CMake :command:`set` commands with the ``FORCE`` option used. These + ``set()`` commands are written to a pre-load script which is then applied + using the :manual:`cmake -C <cmake(1)>` command line option. + + .. versionadded:: 3.3 + Arguments may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +``CMAKE_CACHE_DEFAULT_ARGS <arg>...`` + .. versionadded:: 3.2 + + This is the same as the ``CMAKE_CACHE_ARGS`` option except the ``set()`` + commands do not include the ``FORCE`` keyword. This means the values act + as initial defaults only and will not override any variables already set + from a previous run. Use this option with care, as it can lead to + different behavior depending on whether the build starts from a fresh + build directory or re-uses previous build contents. + + .. versionadded:: 3.15 + If the CMake generator is the ``Green Hills MULTI`` and not overridden, + the original project's settings for the GHS toolset and target system + customization cache variables are propagated into the external project. + +``SOURCE_SUBDIR <dir>`` + .. versionadded:: 3.7 + + When no ``CONFIGURE_COMMAND`` option is specified, the configure step + assumes the external project has a ``CMakeLists.txt`` file at the top of + its source tree (i.e. in ``SOURCE_DIR``). The ``SOURCE_SUBDIR`` option + can be used to point to an alternative directory within the source tree + to use as the top of the CMake source tree instead. This must be a + relative path and it will be interpreted as being relative to + ``SOURCE_DIR``. + + .. versionadded:: 3.14 + When ``BUILD_IN_SOURCE`` option is enabled, the ``BUILD_COMMAND`` + is used to point to an alternative directory within the source tree. + +``CONFIGURE_HANDLED_BY_BUILD <bool>`` + .. versionadded:: 3.20 + + Enabling this option relaxes the dependencies of the configure step on + other external projects to order-only. This means the configure step will + be executed after its external project dependencies are built but it will + not be marked dirty when one of its external project dependencies is + rebuilt. This option can be enabled when the build step is smart enough + to figure out if the configure step needs to be rerun. CMake and Meson are + examples of build systems whose build step is smart enough to know if the + configure step needs to be rerun. + +Build Step Options +"""""""""""""""""" + +If the configure step assumed the external project uses CMake as its build +system, the build step will also. Otherwise, the build step will assume a +Makefile-based build and simply run ``make`` with no arguments as the +default build step. This can be overridden with custom build commands if +required. + +If both the main project and the external project use make as their build +tool, the build step of the external project is invoked as a recursive +make using ``$(MAKE)``. This will communicate some build tool settings +from the main project to the external project. If either the main project +or external project is not using make, no build tool settings will be +passed to the external project other than those established by the +configure step (i.e. running ``ninja -v`` in the main project will not +pass ``-v`` to the external project's build step, even if it also uses +``ninja`` as its build tool). + +``BUILD_COMMAND <cmd>...`` + Overrides the default build command + (:manual:`generator expressions <cmake-generator-expressions(7)>` are + supported). If this option is not given, the default build command will + be chosen to integrate with the main build in the most appropriate way + (e.g. using recursive ``make`` for Makefile generators or + :option:`cmake --build` if the project uses a CMake build). This option + can be specified with an empty string as the command to make the build + step do nothing. + +``BUILD_IN_SOURCE <bool>`` + When this option is enabled, the build will be done directly within the + external project's source tree. This should generally be avoided, the use + of a separate build directory is usually preferred, but it can be useful + when the external project assumes an in-source build. The ``BINARY_DIR`` + option should not be specified if building in-source. + +``BUILD_ALWAYS <bool>`` + Enabling this option forces the build step to always be run. This can be + the easiest way to robustly ensure that the external project's own build + dependencies are evaluated rather than relying on the default + success timestamp-based method. This option is not normally needed unless + developers are expected to modify something the external project's build + depends on in a way that is not detectable via the step target + dependencies (e.g. ``SOURCE_DIR`` is used without a download method and + developers might modify the sources in ``SOURCE_DIR``). + +``BUILD_BYPRODUCTS <file>...`` + .. versionadded:: 3.2 + + Specifies files that will be generated by the build command but which + might or might not have their modification time updated by subsequent + builds. This may also be required to explicitly declare dependencies + when using the :generator:`Ninja` generator. + These ultimately get passed through as ``BYPRODUCTS`` to the + build step's own underlying call to :command:`add_custom_command`, which + has additional documentation. + +Install Step Options +"""""""""""""""""""" + +If the configure step assumed the external project uses CMake as its build +system, the install step will also. Otherwise, the install step will assume +a Makefile-based build and simply run ``make install`` as the default build +step. This can be overridden with custom install commands if required. + +``INSTALL_COMMAND <cmd>...`` + The external project's own install step is invoked as part of the main + project's *build*. It is done after the external project's build step + and may be before or after the external project's test step (see the + ``TEST_BEFORE_INSTALL`` option below). The external project's install + rules are not part of the main project's install rules, so if anything + from the external project should be installed as part of the main build, + these need to be specified in the main build as additional + :command:`install` commands. The default install step builds the + ``install`` target of the external project, but this can be overridden + with a custom command using this option + (:manual:`generator expressions <cmake-generator-expressions(7)>` are + supported). Passing an empty string as the ``<cmd>`` makes the install + step do nothing. + +``INSTALL_BYPRODUCTS <file>...`` + .. versionadded:: 3.26 + + Specifies files that will be generated by the install command but which + might or might not have their modification time updated by subsequent + installs. This may also be required to explicitly declare dependencies + when using the :generator:`Ninja` generator. + These ultimately get passed through as ``BYPRODUCTS`` to the + install step's own underlying call to :command:`add_custom_command`, which + has additional documentation. + +.. note:: + If the :envvar:`CMAKE_INSTALL_MODE` environment variable is set when the + main project is built, it will only have an effect if the following + conditions are met: + + * The main project's configure step assumed the external project uses + CMake as its build system. + * The external project's install command actually runs. Note that due + to the way ``ExternalProject`` may use timestamps internally, if + nothing the install step depends on needs to be re-executed, the + install command might also not need to run. + + Note also that ``ExternalProject`` does not check whether the + :envvar:`CMAKE_INSTALL_MODE` environment variable changes from one run + to another. + +Test Step Options +""""""""""""""""" + +The test step is only defined if at least one of the following ``TEST_...`` +options are provided. + +``TEST_COMMAND <cmd>...`` + Overrides the default test command + (:manual:`generator expressions <cmake-generator-expressions(7)>` are + supported). If this option is not given, the default behavior of the test + step is to build the external project's own ``test`` target. This option + can be specified with ``<cmd>`` as an empty string, which allows the test + step to still be defined, but it will do nothing. Do not specify any of + the other ``TEST_...`` options if providing an empty string as the test + command, but prefer to omit all ``TEST_...`` options altogether if the + test step target is not needed. + +``TEST_BEFORE_INSTALL <bool>`` + When this option is enabled, the test step will be executed before the + install step. The default behavior is for the test step to run after the + install step. + +``TEST_AFTER_INSTALL <bool>`` + This option is mainly useful as a way to indicate that the test step is + desired but all default behavior is sufficient. Specifying this option + with a boolean true value ensures the test step is defined and that it + comes after the install step. If both ``TEST_BEFORE_INSTALL`` and + ``TEST_AFTER_INSTALL`` are enabled, the latter is silently ignored. + +``TEST_EXCLUDE_FROM_MAIN <bool>`` + .. versionadded:: 3.2 + + If enabled, the main build's default ALL target will not depend on the + test step. This can be a useful way of ensuring the test step is defined + but only gets invoked when manually requested. + This may cause a step target to be created automatically for either + the ``install`` or ``build`` step. See policy :policy:`CMP0114`. + +Output Logging Options +"""""""""""""""""""""" + +Each of the following ``LOG_...`` options can be used to wrap the relevant +step in a script to capture its output to files. The log files will be +created in ``LOG_DIR`` if supplied or otherwise the ``STAMP_DIR`` +directory with step-specific file names. + +``LOG_DOWNLOAD <bool>`` + When enabled, the output of the download step is logged to files. + +``LOG_UPDATE <bool>`` + When enabled, the output of the update step is logged to files. + +``LOG_PATCH <bool>`` + .. versionadded:: 3.14 + + When enabled, the output of the patch step is logged to files. + +``LOG_CONFIGURE <bool>`` + When enabled, the output of the configure step is logged to files. + +``LOG_BUILD <bool>`` + When enabled, the output of the build step is logged to files. + +``LOG_INSTALL <bool>`` + When enabled, the output of the install step is logged to files. + +``LOG_TEST <bool>`` + When enabled, the output of the test step is logged to files. + +``LOG_MERGED_STDOUTERR <bool>`` + .. versionadded:: 3.14 + + When enabled, stdout and stderr will be merged for any step whose + output is being logged to files. + +``LOG_OUTPUT_ON_FAILURE <bool>`` + .. versionadded:: 3.14 + + This option only has an effect if at least one of the other ``LOG_<step>`` + options is enabled. If an error occurs for a step which has logging to + file enabled, that step's output will be printed to the console if + ``LOG_OUTPUT_ON_FAILURE`` is set to true. For cases where a large amount + of output is recorded, just the end of that output may be printed to the + console. + +Terminal Access Options +""""""""""""""""""""""" + +.. versionadded:: 3.4 + +Steps can be given direct access to the terminal in some cases. Giving a +step access to the terminal may allow it to receive terminal input if +required, such as for authentication details not provided by other options. +With the :generator:`Ninja` generator, these options place the steps in the +``console`` :prop_gbl:`job pool <JOB_POOLS>`. Each step can be given access +to the terminal individually via the following options: + +``USES_TERMINAL_DOWNLOAD <bool>`` + Give the download step access to the terminal. + +``USES_TERMINAL_UPDATE <bool>`` + Give the update step access to the terminal. + +``USES_TERMINAL_PATCH <bool>`` + .. versionadded:: 3.23 + + Give the patch step access to the terminal. + +``USES_TERMINAL_CONFIGURE <bool>`` + Give the configure step access to the terminal. + +``USES_TERMINAL_BUILD <bool>`` + Give the build step access to the terminal. + +``USES_TERMINAL_INSTALL <bool>`` + Give the install step access to the terminal. + +``USES_TERMINAL_TEST <bool>`` + Give the test step access to the terminal. + +Target Options +"""""""""""""" + +``DEPENDS <targets>...`` + Specify other targets on which the external project depends. The other + targets will be brought up to date before any of the external project's + steps are executed. Because the external project uses additional custom + targets internally for each step, the ``DEPENDS`` option is the most + convenient way to ensure all of those steps depend on the other targets. + Simply doing + :command:`add_dependencies(\<name\> \<targets\>) <add_dependencies>` will + not make any of the steps dependent on ``<targets>``. + +``EXCLUDE_FROM_ALL <bool>`` + When enabled, this option excludes the external project from the default + ALL target of the main build. + +``STEP_TARGETS <step-target>...`` + Generate custom targets for the specified steps. This is required if the + steps need to be triggered manually or if they need to be used as + dependencies of other targets. If this option is not specified, the + default value is taken from the ``EP_STEP_TARGETS`` directory property. + See :command:`ExternalProject_Add_StepTargets` below for further + discussion of the effects of this option. + +``INDEPENDENT_STEP_TARGETS <step-target>...`` + .. deprecated:: 3.19 + This is allowed only if policy :policy:`CMP0114` is not set to ``NEW``. + + Generates custom targets for the specified steps and prevent these targets + from having the usual dependencies applied to them. If this option is not + specified, the default value is taken from the + ``EP_INDEPENDENT_STEP_TARGETS`` directory property. This option is mostly + useful for allowing individual steps to be driven independently, such as + for a CDash setup where each step should be initiated and reported + individually rather than as one whole build. See + :command:`ExternalProject_Add_StepTargets` below for further discussion + of the effects of this option. + +Miscellaneous Options +""""""""""""""""""""" + +``LIST_SEPARATOR <sep>`` + For any of the various ``..._COMMAND`` options, and ``CMAKE_ARGS``, + replace ``;`` with ``<sep>`` in the specified command lines. + This can be useful where list variables may be given in commands where + they should end up as space-separated arguments (``<sep>`` would be a + single space character string in this case). + +``COMMAND <cmd>...`` + Any of the other ``..._COMMAND`` options can have additional commands + appended to them by following them with as many ``COMMAND ...`` options + as needed + (:manual:`generator expressions <cmake-generator-expressions(7)>` are + supported). For example: + + .. code-block:: cmake + + ExternalProject_Add(example + ... # Download options, etc. + BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build" + COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG> + COMMAND ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete" + ) - It should also be noted that each build step is created via a call to - :command:`ExternalProject_Add_Step`. See that command's documentation for the - automatic substitutions that are supported for some options. +It should also be noted that each build step is created via a call to +:command:`ExternalProject_Add_Step`. See that command's documentation for the +automatic substitutions that are supported for some options. Obtaining Project Properties -"""""""""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. command:: ExternalProject_Get_Property @@ -914,7 +945,7 @@ Obtaining Project Properties message("Source dir of myExtProj = ${SOURCE_DIR}") Explicit Step Management -"""""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^^^^ The ``ExternalProject_Add()`` function on its own is often sufficient for incorporating an external project into the main build. Certain scenarios diff --git a/Modules/FindCUDAToolkit.cmake b/Modules/FindCUDAToolkit.cmake index c2627e7..12aca8d 100644 --- a/Modules/FindCUDAToolkit.cmake +++ b/Modules/FindCUDAToolkit.cmake @@ -965,12 +965,15 @@ if(CUDAToolkit_FOUND) # search paths without symlinks if(CUDAToolkit_LIBRARY_DIR MATCHES ".*/cuda/${CUDAToolkit_VERSION_MAJOR}.${CUDAToolkit_VERSION_MINOR}/lib64$") # Search location for math_libs/ - file(REAL_PATH "${CUDAToolkit_LIBRARY_DIR}/../../../" _cmake_search_dir) - list(APPEND CUDAToolkit_LIBRARY_SEARCH_DIRS "${_cmake_search_dir}") - - # Search location for extras like cupti - file(REAL_PATH "${CUDAToolkit_LIBRARY_DIR}/../" _cmake_search_dir) - list(APPEND CUDAToolkit_LIBRARY_SEARCH_DIRS "${_cmake_search_dir}") + block(SCOPE_FOR POLICIES) + cmake_policy(SET CMP0152 NEW) + file(REAL_PATH "${CUDAToolkit_LIBRARY_DIR}/../../../../../" _cmake_search_dir) + list(APPEND CUDAToolkit_LIBRARY_SEARCH_DIRS "${_cmake_search_dir}") + + # Search location for extras like cupti + file(REAL_PATH "${CUDAToolkit_LIBRARY_DIR}/../../../" _cmake_search_dir) + list(APPEND CUDAToolkit_LIBRARY_SEARCH_DIRS "${_cmake_search_dir}") + endblock() endif() # If no `CUDAToolkit_LIBRARY_ROOT` exists set it based on CUDAToolkit_LIBRARY_DIR @@ -1009,17 +1012,26 @@ if(CUDAToolkit_FOUND) ) # Don't try any stub directories until we have exhausted all other # search locations. - find_library(CUDA_${lib_name}_LIBRARY - NAMES ${search_names} - HINTS ${CUDAToolkit_LIBRARY_SEARCH_DIRS} - ENV CUDA_PATH - PATH_SUFFIXES lib64/stubs lib/x64/stubs lib/stubs stubs - ) + set(CUDA_IMPORT_PROPERTY IMPORTED_LOCATION) + set(CUDA_IMPORT_TYPE UNKNOWN) + if(NOT CUDA_${lib_name}_LIBRARY) + find_library(CUDA_${lib_name}_LIBRARY + NAMES ${search_names} + HINTS ${CUDAToolkit_LIBRARY_SEARCH_DIRS} + ENV CUDA_PATH + PATH_SUFFIXES lib64/stubs lib/x64/stubs lib/stubs stubs + ) + if(CUDA_${lib_name}_LIBRARY AND NOT WIN32) + # Use `IMPORTED_IMPLIB` so that we don't add a `-rpath` entry for stub directories + set(CUDA_IMPORT_PROPERTY IMPORTED_IMPLIB) + set(CUDA_IMPORT_TYPE SHARED) + endif() + endif() mark_as_advanced(CUDA_${lib_name}_LIBRARY) if (NOT TARGET CUDA::${lib_name} AND CUDA_${lib_name}_LIBRARY) - add_library(CUDA::${lib_name} UNKNOWN IMPORTED) + add_library(CUDA::${lib_name} ${CUDA_IMPORT_TYPE} IMPORTED) target_include_directories(CUDA::${lib_name} SYSTEM INTERFACE "${CUDAToolkit_INCLUDE_DIRS}") if(DEFINED CUDAToolkit_MATH_INCLUDE_DIR) string(FIND ${CUDA_${lib_name}_LIBRARY} "math_libs" math_libs) @@ -1027,7 +1039,7 @@ if(CUDAToolkit_FOUND) target_include_directories(CUDA::${lib_name} SYSTEM INTERFACE "${CUDAToolkit_MATH_INCLUDE_DIR}") endif() endif() - set_property(TARGET CUDA::${lib_name} PROPERTY IMPORTED_LOCATION "${CUDA_${lib_name}_LIBRARY}") + set_property(TARGET CUDA::${lib_name} PROPERTY ${CUDA_IMPORT_PROPERTY} "${CUDA_${lib_name}_LIBRARY}") foreach(dep ${arg_DEPS}) if(TARGET CUDA::${dep}) target_link_libraries(CUDA::${lib_name} INTERFACE CUDA::${dep}) diff --git a/Modules/FindCURL.cmake b/Modules/FindCURL.cmake index acb87dc..2f33dac 100644 --- a/Modules/FindCURL.cmake +++ b/Modules/FindCURL.cmake @@ -58,6 +58,18 @@ returns its results with no further action. Set ``CURL_NO_CURL_CMAKE`` to ``ON`` to disable this search. +Hints +^^^^^ + +``CURL_USE_STATIC_LIBS`` + + .. versionadded:: 3.28 + + Set to ``TRUE`` to use static libraries. + + This is meaningful only when CURL is not found via its + CMake Package Configuration file. + #]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/FindPackageHandleStandardArgs.cmake) @@ -193,6 +205,11 @@ if(CURL_FOUND) set_target_properties(CURL::libcurl PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${CURL_INCLUDE_DIRS}") + if(CURL_USE_STATIC_LIBS) + set_property(TARGET CURL::libcurl APPEND PROPERTY + INTERFACE_COMPILE_DEFINITIONS "CURL_STATICLIB") + endif() + if(EXISTS "${CURL_LIBRARY}") set_target_properties(CURL::libcurl PROPERTIES IMPORTED_LINK_INTERFACE_LANGUAGES "C" @@ -212,5 +229,11 @@ if(CURL_FOUND) IMPORTED_LINK_INTERFACE_LANGUAGES "C" IMPORTED_LOCATION_DEBUG "${CURL_LIBRARY_DEBUG}") endif() + + if(CURL_USE_STATIC_LIBS AND MSVC) + set_target_properties(CURL::libcurl PROPERTIES + INTERFACE_LINK_LIBRARIES "normaliz.lib;ws2_32.lib;wldap32.lib") + endif() + endif() endif() diff --git a/Modules/FindEXPAT.cmake b/Modules/FindEXPAT.cmake index 3bedc73..762931e 100644 --- a/Modules/FindEXPAT.cmake +++ b/Modules/FindEXPAT.cmake @@ -30,6 +30,15 @@ This module will set the following variables in your project: ``EXPAT_FOUND`` true if the Expat headers and libraries were found. +Hints +^^^^^ + +``EXPAT_USE_STATIC_LIBS`` + + .. versionadded:: 3.28 + + Set to ``TRUE`` to use static libraries. + #]=======================================================================] find_package(PkgConfig QUIET) @@ -43,8 +52,13 @@ set(EXPAT_NAMES expat expatw) set(EXPAT_NAMES_DEBUG expatd expatwd) if(WIN32) - list(APPEND EXPAT_NAMES expatMT expatMD expatwMT expatwMD) - list(APPEND EXPAT_NAMES_DEBUG expatdMT expatdMD expatwdMT expatwdMD) + if(EXPAT_USE_STATIC_LIBS) + list(APPEND EXPAT_NAMES expatMT expatwMT) + list(APPEND EXPAT_NAMES_DEBUG expatdMT expatwdMT) + else() + list(APPEND EXPAT_NAMES expatMT expatMD expatwMT expatwMD) + list(APPEND EXPAT_NAMES_DEBUG expatdMT expatdMD expatwdMT expatwdMD) + endif() endif() # Allow EXPAT_LIBRARY to be set manually, as the location of the expat library @@ -115,6 +129,11 @@ if(EXPAT_FOUND) IMPORTED_LINK_INTERFACE_LANGUAGES "C" INTERFACE_INCLUDE_DIRECTORIES "${EXPAT_INCLUDE_DIRS}") + if(EXPAT_USE_STATIC_LIBS) + set_property(TARGET EXPAT::EXPAT APPEND PROPERTY + INTERFACE_COMPILE_DEFINITIONS "XML_STATIC") + endif() + if(EXPAT_LIBRARY_RELEASE) set_property(TARGET EXPAT::EXPAT APPEND PROPERTY IMPORTED_CONFIGURATIONS RELEASE) diff --git a/Modules/FindFLTK.cmake b/Modules/FindFLTK.cmake index d54d2f6..a245c6c 100644 --- a/Modules/FindFLTK.cmake +++ b/Modules/FindFLTK.cmake @@ -232,7 +232,7 @@ else() find_program(FLTK_CONFIG_SCRIPT fltk-config PATHS ${FLTK_BIN_DIR}) if(FLTK_CONFIG_SCRIPT) if(NOT FLTK_INCLUDE_DIR) - exec_program(${FLTK_CONFIG_SCRIPT} ARGS --cxxflags OUTPUT_VARIABLE FLTK_CXXFLAGS) + execute_process(COMMAND ${FLTK_CONFIG_SCRIPT} --cxxflags OUTPUT_VARIABLE FLTK_CXXFLAGS) if(FLTK_CXXFLAGS) string(REGEX MATCHALL "-I[^ ]*" _fltk_temp_dirs ${FLTK_CXXFLAGS}) string(REPLACE "-I" "" _fltk_temp_dirs "${_fltk_temp_dirs}") @@ -256,7 +256,7 @@ else() # Try to find FLTK library if(UNIX) if(FLTK_CONFIG_SCRIPT) - exec_program(${FLTK_CONFIG_SCRIPT} ARGS --libs OUTPUT_VARIABLE _FLTK_POSSIBLE_LIBS) + execute_process(COMMAND ${FLTK_CONFIG_SCRIPT} --libs OUTPUT_VARIABLE _FLTK_POSSIBLE_LIBS) if(_FLTK_POSSIBLE_LIBS) get_filename_component(_FLTK_POSSIBLE_LIBRARY_DIR ${_FLTK_POSSIBLE_LIBS} PATH) endif() @@ -292,12 +292,12 @@ else() # Find the extra libraries needed for the fltk_images library. if(UNIX) if(FLTK_CONFIG_SCRIPT) - exec_program(${FLTK_CONFIG_SCRIPT} ARGS --use-images --ldflags + execute_process(COMMAND ${FLTK_CONFIG_SCRIPT} --use-images --ldflags OUTPUT_VARIABLE FLTK_IMAGES_LDFLAGS) set(FLTK_LIBS_EXTRACT_REGEX ".*-lfltk_images (.*) -lfltk.*") if("${FLTK_IMAGES_LDFLAGS}" MATCHES "${FLTK_LIBS_EXTRACT_REGEX}") string(REGEX REPLACE " +" ";" FLTK_IMAGES_LIBS "${CMAKE_MATCH_1}") - # The EXEC_PROGRAM will not be inherited into subdirectories from + # The execute_process() will not be inherited into subdirectories from # the file that originally included this module. Save the answer. set(FLTK_IMAGES_LIBS "${FLTK_IMAGES_LIBS}" CACHE INTERNAL "Extra libraries for fltk_images library.") diff --git a/Modules/FindFLTK2.cmake b/Modules/FindFLTK2.cmake index a43f7a4..2f6e41d 100644 --- a/Modules/FindFLTK2.cmake +++ b/Modules/FindFLTK2.cmake @@ -191,12 +191,12 @@ if(FLTK2_DIR) if(UNIX) find_program(FLTK2_CONFIG_SCRIPT fltk2-config PATHS ${FLTK2_BIN_DIR}) if(FLTK2_CONFIG_SCRIPT) - exec_program(${FLTK2_CONFIG_SCRIPT} ARGS --use-images --ldflags + execute_process(COMMAND ${FLTK2_CONFIG_SCRIPT} --use-images --ldflags OUTPUT_VARIABLE FLTK2_IMAGES_LDFLAGS) set(FLTK2_LIBS_EXTRACT_REGEX ".*-lfltk2_images (.*) -lfltk2.*") if("${FLTK2_IMAGES_LDFLAGS}" MATCHES "${FLTK2_LIBS_EXTRACT_REGEX}") string(REGEX REPLACE " +" ";" FLTK2_IMAGES_LIBS "${CMAKE_MATCH_1}") - # The EXEC_PROGRAM will not be inherited into subdirectories from + # The execute_process() will not be inherited into subdirectories from # the file that originally included this module. Save the answer. set(FLTK2_IMAGES_LIBS "${FLTK2_IMAGES_LIBS}" CACHE INTERNAL "Extra libraries for fltk_images library.") diff --git a/Modules/FindJNI.cmake b/Modules/FindJNI.cmake index 27f9b0e..c6d7b09 100644 --- a/Modules/FindJNI.cmake +++ b/Modules/FindJNI.cmake @@ -383,6 +383,23 @@ foreach(JAVA_PROG "${JAVA_RUNTIME}" "${JAVA_COMPILE}" "${JAVA_ARCHIVE}") endforeach() if(APPLE) + if(DEFINED XCODE_VERSION) + set(_FindJNI_XCODE_VERSION "${XCODE_VERSION}") + else() + # get xcode version + execute_process( + COMMAND xcodebuild -version + OUTPUT_VARIABLE _xcode_version + ) + string(REGEX REPLACE "Xcode ([0-9]+(\\.[0-9]+)*)" "\\1" _FindJNI_XCODE_VERSION ${_xcode_version}) + unset(_xcode_version) + endif() + + if(_FindJNI_XCODE_VERSION VERSION_GREATER 12.1) + set(CMAKE_FIND_FRAMEWORK "NEVER") + endif() + unset(_FindJNI_XCODE_VERSION) + if(CMAKE_FIND_FRAMEWORK STREQUAL "ONLY") set(_JNI_SEARCHES FRAMEWORK) elseif(CMAKE_FIND_FRAMEWORK STREQUAL "NEVER") diff --git a/Modules/FindProtobuf.cmake b/Modules/FindProtobuf.cmake index a92fb52..008b537 100644 --- a/Modules/FindProtobuf.cmake +++ b/Modules/FindProtobuf.cmake @@ -136,15 +136,95 @@ Example: Variable to define with autogenerated Python files ``ARGN`` ``.proto`` files + +.. command:: protobuf_generate + + .. versionadded:: 3.13 + + Automatically generate source files from ``.proto`` schema files at build time:: + + protobuf_generate ( + TARGET <target> + [LANGUAGE <lang>] + [OUT_VAR <out_var>] + [EXPORT_MACRO <macro>] + [PROTOC_OUT_DIR <dir>] + [PLUGIN <plugin>] + [PLUGIN_OPTIONS <plugin_options>] + [DEPENDENCIES <depends] + [PROTOS <protobuf_files>] + [IMPORT_DIRS <dirs>] + [GENERATE_EXTENSIONS <extensions>] + [PROTOC_OPTIONS <protoc_options>] + [APPEND_PATH]) + + ``APPEND_PATH`` + A flag that causes the base path of all proto schema files to be added to + ``IMPORT_DIRS``. + ``LANGUAGE`` + A single value: cpp or python. Determines what kind of source files are + being generated. Defaults to cpp. + ``OUT_VAR`` + Name of a CMake variable that will be filled with the paths to the generated + source files. + ``EXPORT_MACRO`` + Name of a macro that is applied to all generated Protobuf message classes + and extern variables. It can, for example, be used to declare DLL exports. + ``PROTOC_OUT_DIR`` + Output directory of generated source files. Defaults to ``CMAKE_CURRENT_BINARY_DIR``. + ``PLUGIN`` + .. versionadded:: 3.21 + + An optional plugin executable. This could, for example, be the path to + ``grpc_cpp_plugin``. + ``PLUGIN_OPTIONS`` + .. versionadded:: 3.28 + + Additional options provided to the plugin, such as ``generate_mock_code=true`` + for the gRPC cpp plugin. + ``DEPENDENCIES`` + .. versionadded:: 3.28 + + Arguments forwarded to the ``DEPENDS`` of the underlying ``add_custom_command`` + invocation. + ``TARGET`` + CMake target that will have the generated files added as sources. + ``PROTOS`` + List of proto schema files. If omitted, then every source file ending in *proto* of ``TARGET`` will be used. + ``IMPORT_DIRS`` + A common parent directory for the schema files. For example, if the schema file is + ``proto/helloworld/helloworld.proto`` and the import directory ``proto/`` then the + generated files are ``${PROTOC_OUT_DIR}/helloworld/helloworld.pb.h`` and + ``${PROTOC_OUT_DIR}/helloworld/helloworld.pb.cc``. + ``GENERATE_EXTENSIONS`` + If LANGUAGE is omitted then this must be set to the extensions that protoc generates. + ``PROTOC_OPTIONS`` + .. versionadded:: 3.28 + + Additional arguments that are forwarded to protoc. + + Example:: + + find_package(gRPC CONFIG REQUIRED) + find_package(Protobuf REQUIRED) + add_library(ProtoTest Test.proto) + target_link_libraries(ProtoTest PUBLIC gRPC::grpc++) + protobuf_generate(TARGET ProtoTest) + protobuf_generate( + TARGET ProtoTest + LANGUAGE grpc + PLUGIN protoc-gen-grpc=$<TARGET_FILE:gRPC::grpc_cpp_plugin> + PLUGIN_OPTIONS generate_mock_code=true + GENERATE_EXTENSIONS .grpc.pb.h .grpc.pb.cc) #]=======================================================================] function(protobuf_generate) set(_options APPEND_PATH DESCRIPTORS) - set(_singleargs LANGUAGE OUT_VAR EXPORT_MACRO PROTOC_OUT_DIR PLUGIN) + set(_singleargs LANGUAGE OUT_VAR EXPORT_MACRO PROTOC_OUT_DIR PLUGIN PLUGIN_OPTIONS DEPENDENCIES) if(COMMAND target_sources) list(APPEND _singleargs TARGET) endif() - set(_multiargs PROTOS IMPORT_DIRS GENERATE_EXTENSIONS) + set(_multiargs PROTOS IMPORT_DIRS GENERATE_EXTENSIONS PROTOC_OPTIONS) cmake_parse_arguments(protobuf_generate "${_options}" "${_singleargs}" "${_multiargs}" "${ARGN}") @@ -168,9 +248,18 @@ function(protobuf_generate) endif() if(protobuf_generate_EXPORT_MACRO AND protobuf_generate_LANGUAGE STREQUAL cpp) - set(_dll_export_decl "dllexport_decl=${protobuf_generate_EXPORT_MACRO}:") + set(_dll_export_decl "dllexport_decl=${protobuf_generate_EXPORT_MACRO}") endif() + foreach(_option ${_dll_export_decl} ${protobuf_generate_PLUGIN_OPTIONS}) + # append comma - not using CMake lists and string replacement as users + # might have semicolons in options + if(_plugin_options) + set( _plugin_options "${_plugin_options},") + endif() + set(_plugin_options "${_plugin_options}${_option}") + endforeach() + if(protobuf_generate_PLUGIN) set(_plugin "--plugin=${protobuf_generate_PLUGIN}") endif() @@ -204,14 +293,12 @@ function(protobuf_generate) # Create an include path for each file specified foreach(_file ${protobuf_generate_PROTOS}) get_filename_component(_abs_file ${_file} ABSOLUTE) - get_filename_component(_abs_path ${_abs_file} PATH) - list(FIND _protobuf_include_path ${_abs_path} _contains_already) + get_filename_component(_abs_dir ${_abs_file} DIRECTORY) + list(FIND _protobuf_include_path ${_abs_dir} _contains_already) if(${_contains_already} EQUAL -1) - list(APPEND _protobuf_include_path -I ${_abs_path}) + list(APPEND _protobuf_include_path -I ${_abs_dir}) endif() endforeach() - else() - set(_protobuf_include_path -I ${CMAKE_CURRENT_SOURCE_DIR}) endif() foreach(DIR ${protobuf_generate_IMPORT_DIRS}) @@ -222,6 +309,10 @@ function(protobuf_generate) endif() endforeach() + if(NOT _protobuf_include_path) + set(_protobuf_include_path -I ${CMAKE_CURRENT_SOURCE_DIR}) + endif() + set(_generated_srcs_all) foreach(_proto ${protobuf_generate_PROTOS}) get_filename_component(_abs_file ${_proto} ABSOLUTE) @@ -246,12 +337,20 @@ function(protobuf_generate) endif() list(APPEND _generated_srcs_all ${_generated_srcs}) + set(_comment "Running ${protobuf_generate_LANGUAGE} protocol buffer compiler on ${_proto}") + if(protobuf_generate_PROTOC_OPTIONS) + set(_comment "${_comment}, protoc-options: ${protobuf_generate_PROTOC_OPTIONS}") + endif() + if(_plugin_options) + set(_comment "${_comment}, plugin-options: ${_plugin_options}") + endif() + add_custom_command( OUTPUT ${_generated_srcs} - COMMAND protobuf::protoc - ARGS --${protobuf_generate_LANGUAGE}_out ${_dll_export_decl}${protobuf_generate_PROTOC_OUT_DIR} ${_plugin} ${_dll_desc_out} ${_protobuf_include_path} ${_abs_file} - DEPENDS ${_abs_file} protobuf::protoc - COMMENT "Running ${protobuf_generate_LANGUAGE} protocol buffer compiler on ${_proto}" + COMMAND protobuf::protoc + ARGS ${protobuf_generate_PROTOC_OPTIONS} --${protobuf_generate_LANGUAGE}_out ${_plugin_options}:${protobuf_generate_PROTOC_OUT_DIR} ${_plugin} ${_dll_desc_out} ${_protobuf_include_path} ${_abs_file} + DEPENDS ${_abs_file} protobuf::protoc ${protobuf_generate_DEPENDENCIES} + COMMENT ${_comment} VERBATIM ) endforeach() diff --git a/Modules/FindPython/Support.cmake b/Modules/FindPython/Support.cmake index f78433d..65501e3 100644 --- a/Modules/FindPython/Support.cmake +++ b/Modules/FindPython/Support.cmake @@ -981,7 +981,7 @@ function (_PYTHON_VALIDATE_COMPILER) # retrieve python environment version from compiler set (working_dir "${CMAKE_CURRENT_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/PythonCompilerVersion.dir") - file (WRITE "${working_dir}/version.py" "import sys; sys.stdout.write('.'.join([str(x) for x in sys.version_info[:3]]))\n") + file (WRITE "${working_dir}/version.py" "import sys; sys.stdout.write('.'.join([str(x) for x in sys.version_info[:3]])); sys.stdout.flush()\n") execute_process (COMMAND ${launcher} "${_${_PYTHON_PREFIX}_COMPILER}" ${_${_PYTHON_PREFIX}_IRON_PYTHON_COMPILER_ARCH_FLAGS} /target:exe /embed "${working_dir}/version.py" @@ -2520,7 +2520,7 @@ if ("Compiler" IN_LIST ${_PYTHON_PREFIX}_FIND_COMPONENTS) # retrieve python environment version from compiler _python_get_launcher (_${_PYTHON_PREFIX}_COMPILER_LAUNCHER COMPILER) set (_${_PYTHON_PREFIX}_VERSION_DIR "${CMAKE_CURRENT_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/PythonCompilerVersion.dir") - file (WRITE "${_${_PYTHON_PREFIX}_VERSION_DIR}/version.py" "import sys; sys.stdout.write('.'.join([str(x) for x in sys.version_info[:3]]))\n") + file (WRITE "${_${_PYTHON_PREFIX}_VERSION_DIR}/version.py" "import sys; sys.stdout.write('.'.join([str(x) for x in sys.version_info[:3]])); sys.stdout.flush()\n") execute_process (COMMAND ${_${_PYTHON_PREFIX}_COMPILER_LAUNCHER} "${_${_PYTHON_PREFIX}_COMPILER}" ${_${_PYTHON_PREFIX}_IRON_PYTHON_COMPILER_ARCH_FLAGS} /target:exe /embed "${_${_PYTHON_PREFIX}_VERSION_DIR}/version.py" diff --git a/Modules/FindQt.cmake b/Modules/FindQt.cmake index 44a1f41..604f8e3 100644 --- a/Modules/FindQt.cmake +++ b/Modules/FindQt.cmake @@ -91,7 +91,7 @@ endif () # now find qmake find_program(QT_QMAKE_EXECUTABLE_FINDQT NAMES qmake PATHS "${QT_SEARCH_PATH}/bin" "$ENV{QTDIR}/bin") if(QT_QMAKE_EXECUTABLE_FINDQT) - exec_program(${QT_QMAKE_EXECUTABLE_FINDQT} ARGS "-query QT_VERSION" + execute_process(COMMAND ${QT_QMAKE_EXECUTABLE_FINDQT} -query QT_VERSION OUTPUT_VARIABLE QTVERSION) if(QTVERSION MATCHES "4") set(QT_QMAKE_EXECUTABLE ${QT_QMAKE_EXECUTABLE_FINDQT} CACHE PATH "Qt4 qmake program.") @@ -103,8 +103,8 @@ if(QT_QMAKE_EXECUTABLE_FINDQT) endif() if(QT_QMAKE_EXECUTABLE_FINDQT) - exec_program( ${QT_QMAKE_EXECUTABLE_FINDQT} - ARGS "-query QT_INSTALL_HEADERS" + execute_process(COMMAND ${QT_QMAKE_EXECUTABLE_FINDQT} + -query QT_INSTALL_HEADERS OUTPUT_VARIABLE qt_headers ) endif() diff --git a/Modules/FindwxWidgets.cmake b/Modules/FindwxWidgets.cmake index cc76b35..78fa481 100644 --- a/Modules/FindwxWidgets.cmake +++ b/Modules/FindwxWidgets.cmake @@ -848,7 +848,8 @@ if(wxWidgets_FIND_STYLE STREQUAL "unix") DBG_MSG_V("wxWidgets required components : ${_cmp_req}") DBG_MSG_V("wxWidgets optional components : ${_cmp_opt}") if(DEFINED _cmp_opt) - string(REPLACE ";" "," _cmp_opt "--optional-libs ${_cmp_opt}") + string(REPLACE ";" "," _cmp_opt "${_cmp_opt}") + set(_cmp_opt "--optional-libs" ${_cmp_opt}) endif() string(REPLACE ";" "," _cmp_req "${_cmp_req}") execute_process( diff --git a/Modules/FindwxWindows.cmake b/Modules/FindwxWindows.cmake index 6e4be91..d1b25e1 100644 --- a/Modules/FindwxWindows.cmake +++ b/Modules/FindwxWindows.cmake @@ -635,14 +635,14 @@ else() # remember: always link shared to use systems GL etc. libs (no static # linking, just link *against* static .a libs) if(WXWINDOWS_USE_SHARED_LIBS) - set(WX_CONFIG_ARGS_LIBS "--libs") + set(WX_CONFIG_ARGS_LIBS --libs) else() - set(WX_CONFIG_ARGS_LIBS "--static --libs") + set(WX_CONFIG_ARGS_LIBS --static --libs) endif() # do we need additionial wx GL stuff like GLCanvas ? if(WXWINDOWS_USE_GL) - string(APPEND WX_CONFIG_ARGS_LIBS " --gl-libs" ) + list(APPEND WX_CONFIG_ARGS_LIBS --gl-libs) endif() ##message("DBG: WX_CONFIG_ARGS_LIBS=${WX_CONFIG_ARGS_LIBS}===") @@ -662,14 +662,15 @@ else() ##CMAKE_WXWINDOWS_CXX_FLAGS=${CMAKE_WXWINDOWS_CXX_FLAGS}===") # keep the back-quoted string for clarity - set(WXWINDOWS_LIBRARIES "`${CMAKE_WXWINDOWS_WXCONFIG_EXECUTABLE} ${WX_CONFIG_ARGS_LIBS}`") + string(REPLACE ";" " " _wx_config_args_libs "${WX_CONFIG_ARGS_LIBS}") + set(WXWINDOWS_LIBRARIES "`${CMAKE_WXWINDOWS_WXCONFIG_EXECUTABLE} ${_wx_config_args_libs}`") ##message("DBG2: for linking: ##WXWINDOWS_LIBRARIES=${WXWINDOWS_LIBRARIES}===") # evaluate wx-config output to separate linker flags and linkdirs for # rpath: - exec_program(${CMAKE_WXWINDOWS_WXCONFIG_EXECUTABLE} - ARGS ${WX_CONFIG_ARGS_LIBS} + execute_process(COMMAND ${CMAKE_WXWINDOWS_WXCONFIG_EXECUTABLE} + ${WX_CONFIG_ARGS_LIBS} OUTPUT_VARIABLE WX_CONFIG_LIBS ) ## extract linkdirs (-L) for rpath diff --git a/Modules/Internal/FeatureTesting.cmake b/Modules/Internal/FeatureTesting.cmake index 1a8a27e..c2bd14f 100644 --- a/Modules/Internal/FeatureTesting.cmake +++ b/Modules/Internal/FeatureTesting.cmake @@ -37,6 +37,7 @@ macro(_record_compiler_features lang compile_flags feature_list) LINK_LIBRARIES "${compile_flags_for_link}" COPY_FILE "${CMAKE_BINARY_DIR}/CMakeFiles/feature_tests.bin" COPY_FILE_ERROR _copy_error + __CMAKE_INTERNAL FEATURE_TESTING ) if(NOT CMAKE_${lang}_FEATURE_TEST) set(_result 255) diff --git a/Modules/Platform/Apple-Clang.cmake b/Modules/Platform/Apple-Clang.cmake index 0681bfb..4d7546a 100644 --- a/Modules/Platform/Apple-Clang.cmake +++ b/Modules/Platform/Apple-Clang.cmake @@ -22,6 +22,10 @@ macro(__apple_compiler_clang lang) set(CMAKE_${lang}_OSX_DEPLOYMENT_TARGET_FLAG "-mtvos-version-min=") elseif(_CMAKE_OSX_SYSROOT_PATH MATCHES "/AppleTVSimulator") set(CMAKE_${lang}_OSX_DEPLOYMENT_TARGET_FLAG "-mtvos-simulator-version-min=") + elseif(_CMAKE_OSX_SYSROOT_PATH MATCHES "/XROS") + set(CMAKE_${lang}_OSX_DEPLOYMENT_TARGET_FLAG "-mtargetos=xros") + elseif(_CMAKE_OSX_SYSROOT_PATH MATCHES "/XRSimulator") + set(CMAKE_${lang}_OSX_DEPLOYMENT_TARGET_FLAG "-mtargetos=xros") elseif(_CMAKE_OSX_SYSROOT_PATH MATCHES "/WatchOS") set(CMAKE_${lang}_OSX_DEPLOYMENT_TARGET_FLAG "-mwatchos-version-min=") elseif(_CMAKE_OSX_SYSROOT_PATH MATCHES "/WatchSimulator") diff --git a/Modules/Platform/Darwin-Initialize.cmake b/Modules/Platform/Darwin-Initialize.cmake index e253392..8d5bf8c 100644 --- a/Modules/Platform/Darwin-Initialize.cmake +++ b/Modules/Platform/Darwin-Initialize.cmake @@ -43,7 +43,7 @@ if(NOT CMAKE_CROSSCOMPILING AND unset(_sysctl_stdout) endif() -# macOS, iOS, tvOS, and watchOS should lookup compilers from +# macOS, iOS, tvOS, visionOS, and watchOS should lookup compilers from # Platform/Apple-${CMAKE_CXX_COMPILER_ID}-<LANG> set(CMAKE_EFFECTIVE_SYSTEM_NAME "Apple") @@ -76,6 +76,8 @@ elseif(CMAKE_SYSTEM_NAME STREQUAL iOS) set(_CMAKE_OSX_SYSROOT_DEFAULT "iphoneos") elseif(CMAKE_SYSTEM_NAME STREQUAL tvOS) set(_CMAKE_OSX_SYSROOT_DEFAULT "appletvos") +elseif(CMAKE_SYSTEM_NAME STREQUAL visionOS) + set(_CMAKE_OSX_SYSROOT_DEFAULT "xros") elseif(CMAKE_SYSTEM_NAME STREQUAL watchOS) set(_CMAKE_OSX_SYSROOT_DEFAULT "watchos") elseif("${CMAKE_GENERATOR}" MATCHES Xcode diff --git a/Modules/Platform/Darwin.cmake b/Modules/Platform/Darwin.cmake index 48a9065..d614182 100644 --- a/Modules/Platform/Darwin.cmake +++ b/Modules/Platform/Darwin.cmake @@ -1,4 +1,4 @@ -if(CMAKE_SYSTEM_NAME STREQUAL "iOS" OR CMAKE_SYSTEM_NAME STREQUAL "tvOS" OR CMAKE_SYSTEM_NAME STREQUAL "watchOS") +if(CMAKE_SYSTEM_NAME STREQUAL "iOS" OR CMAKE_SYSTEM_NAME STREQUAL "tvOS" OR CMAKE_SYSTEM_NAME STREQUAL "visionOS" OR CMAKE_SYSTEM_NAME STREQUAL "watchOS") if(NOT DEFINED CMAKE_MACOSX_BUNDLE) set(CMAKE_MACOSX_BUNDLE ON) endif() diff --git a/Modules/Platform/Windows-MSVC.cmake b/Modules/Platform/Windows-MSVC.cmake index 8e96bf4..829ab9b 100644 --- a/Modules/Platform/Windows-MSVC.cmake +++ b/Modules/Platform/Windows-MSVC.cmake @@ -28,6 +28,8 @@ endif() if(CMAKE_SYSTEM_NAME STREQUAL "WindowsCE") set(_PLATFORM_LINK_FLAGS " /subsystem:windowsce") +elseif(CMAKE_SYSTEM_NAME STREQUAL "WindowsKernelModeDriver") + set(_PLATFORM_LINK_FLAGS " -subsystem:native -kernel -MANIFEST:NO") else() set(_PLATFORM_LINK_FLAGS "") endif() @@ -223,6 +225,18 @@ elseif(WINDOWS_PHONE OR WINDOWS_STORE) else() set(CMAKE_C_STANDARD_LIBRARIES_INIT "kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib") endif() +elseif(CMAKE_SYSTEM_NAME STREQUAL "WindowsKernelModeDriver") + set(CMAKE_C_STANDARD_LIBRARIES_INIT "") + set(_FLAGS_C " -kernel") + set(_FLAGS_CXX " -kernel") + foreach(t EXE SHARED MODULE) + string(APPEND CMAKE_${t}_LINKER_FLAGS_INIT " -NODEFAULTLIB") + endforeach() + if((_MSVC_C_ARCHITECTURE_FAMILY STREQUAL "x64") OR (_MSVC_CXX_ARCHITECTURE_FAMILY STREQUAL "x64")) + set(_PLATFORM_DEFINES "${_PLATFORM_DEFINES} -D_AMD64_ -DAMD64") + elseif((_MSVC_C_ARCHITECTURE_FAMILY STREQUAL "ARM64") OR (_MSVC_CXX_ARCHITECTURE_FAMILY STREQUAL "ARM64")) + set(_PLATFORM_DEFINES "${_PLATFORM_DEFINES} -D_ARM64_ -DARM64") + endif() else() set(_PLATFORM_DEFINES "/DWIN32") if((_MSVC_C_ARCHITECTURE_FAMILY STREQUAL "ARM64EC") OR (_MSVC_CXX_ARCHITECTURE_FAMILY STREQUAL "ARM64EC")) @@ -294,7 +308,7 @@ endif() # add /debug and /INCREMENTAL:YES to DEBUG and RELWITHDEBINFO also add pdbtype # on versions that support it set( MSVC_INCREMENTAL_YES_FLAG "") -if(NOT WINDOWS_PHONE AND NOT WINDOWS_STORE) +if(NOT WINDOWS_PHONE AND NOT WINDOWS_STORE AND NOT CMAKE_SYSTEM_NAME STREQUAL "WindowsKernelModeDriver") if(NOT MSVC_INCREMENTAL_DEFAULT) set( MSVC_INCREMENTAL_YES_FLAG "/INCREMENTAL:YES") else() @@ -353,8 +367,14 @@ macro(__windows_compiler_msvc lang) set(_CMAKE_VS_LINK_DLL "<CMAKE_COMMAND> -E vs_link_dll --intdir=<OBJECT_DIR> --rc=<CMAKE_RC_COMPILER> --mt=<CMAKE_MT> --manifests <MANIFESTS> -- ") set(_CMAKE_VS_LINK_EXE "<CMAKE_COMMAND> -E vs_link_exe --intdir=<OBJECT_DIR> --rc=<CMAKE_RC_COMPILER> --mt=<CMAKE_MT> --manifests <MANIFESTS> -- ") endif() + if(CMAKE_SYSTEM_NAME STREQUAL "WindowsKernelModeDriver") + set(_DLL_DRIVER "-driver") + else() + set(_DLL_DRIVER "/dll") + endif() set(CMAKE_${lang}_CREATE_SHARED_LIBRARY - "${_CMAKE_VS_LINK_DLL}<CMAKE_LINKER> ${CMAKE_CL_NOLOGO} <OBJECTS> ${CMAKE_START_TEMP_FILE} /out:<TARGET> /implib:<TARGET_IMPLIB> /pdb:<TARGET_PDB> /dll /version:<TARGET_VERSION_MAJOR>.<TARGET_VERSION_MINOR>${_PLATFORM_LINK_FLAGS} <LINK_FLAGS> <LINK_LIBRARIES> ${CMAKE_END_TEMP_FILE}") + "${_CMAKE_VS_LINK_DLL}<CMAKE_LINKER> ${CMAKE_CL_NOLOGO} <OBJECTS> ${CMAKE_START_TEMP_FILE} /out:<TARGET> /implib:<TARGET_IMPLIB> /pdb:<TARGET_PDB> ${_DLL_DRIVER} /version:<TARGET_VERSION_MAJOR>.<TARGET_VERSION_MINOR>${_PLATFORM_LINK_FLAGS} <LINK_FLAGS> <LINK_LIBRARIES> ${CMAKE_END_TEMP_FILE}") + unset(_DLL_DRIVER) set(CMAKE_${lang}_CREATE_SHARED_MODULE ${CMAKE_${lang}_CREATE_SHARED_LIBRARY}) set(CMAKE_${lang}_CREATE_STATIC_LIBRARY "<CMAKE_AR> ${CMAKE_CL_NOLOGO} <LINK_FLAGS> /out:<TARGET> <OBJECTS> ") diff --git a/Modules/Platform/Windows.cmake b/Modules/Platform/Windows.cmake index 8697e7a..1bf39cf 100644 --- a/Modules/Platform/Windows.cmake +++ b/Modules/Platform/Windows.cmake @@ -1,7 +1,11 @@ set(CMAKE_STATIC_LIBRARY_PREFIX "") set(CMAKE_STATIC_LIBRARY_SUFFIX ".lib") set(CMAKE_SHARED_LIBRARY_PREFIX "") # lib -set(CMAKE_SHARED_LIBRARY_SUFFIX ".dll") # .so +if(CMAKE_SYSTEM_NAME STREQUAL "WindowsKernelModeDriver") + set(CMAKE_SHARED_LIBRARY_SUFFIX ".sys") # .so +else() + set(CMAKE_SHARED_LIBRARY_SUFFIX ".dll") # .so +endif() set(CMAKE_IMPORT_LIBRARY_PREFIX "") set(CMAKE_IMPORT_LIBRARY_SUFFIX ".lib") set(CMAKE_EXECUTABLE_SUFFIX ".exe") # .exe diff --git a/Modules/Platform/WindowsKernelModeDriver-Initialize.cmake b/Modules/Platform/WindowsKernelModeDriver-Initialize.cmake new file mode 100644 index 0000000..6f0ef33 --- /dev/null +++ b/Modules/Platform/WindowsKernelModeDriver-Initialize.cmake @@ -0,0 +1,11 @@ +# undocumented, do not use outside of CMake +cmake_language(GET_EXPERIMENTAL_FEATURE_ENABLED "WindowsKernelModeDriver" _cmake_windows_kernel_mode_driver_enabled) +if(NOT _cmake_windows_kernel_mode_driver_enabled) + message(FATAL_ERROR "Windows kernel-mode driver experimental support is not enabled.") +endif() + +if(CMAKE_GENERATOR MATCHES "Visual Studio") + message(FATAL_ERROR "Visual Studio generators do not yet support CMAKE_SYSTEM_NAME=WindowsKernelModeDriver.") +endif() + +set(_CMAKE_FEATURE_DETECTION_TARGET_TYPE STATIC_LIBRARY) diff --git a/Modules/Platform/WindowsKernelModeDriver-MSVC-C.cmake b/Modules/Platform/WindowsKernelModeDriver-MSVC-C.cmake new file mode 100644 index 0000000..ce8060b --- /dev/null +++ b/Modules/Platform/WindowsKernelModeDriver-MSVC-C.cmake @@ -0,0 +1 @@ +include(Platform/Windows-MSVC-C) diff --git a/Modules/Platform/WindowsKernelModeDriver-MSVC-CXX.cmake b/Modules/Platform/WindowsKernelModeDriver-MSVC-CXX.cmake new file mode 100644 index 0000000..281eadc --- /dev/null +++ b/Modules/Platform/WindowsKernelModeDriver-MSVC-CXX.cmake @@ -0,0 +1 @@ +include(Platform/Windows-MSVC-CXX) diff --git a/Modules/Platform/WindowsKernelModeDriver.cmake b/Modules/Platform/WindowsKernelModeDriver.cmake new file mode 100644 index 0000000..65b2eae --- /dev/null +++ b/Modules/Platform/WindowsKernelModeDriver.cmake @@ -0,0 +1 @@ +include(Platform/Windows) diff --git a/Modules/Platform/visionOS-Determine-CXX.cmake b/Modules/Platform/visionOS-Determine-CXX.cmake new file mode 100644 index 0000000..ac80fa6 --- /dev/null +++ b/Modules/Platform/visionOS-Determine-CXX.cmake @@ -0,0 +1 @@ +include(Platform/Darwin-Determine-CXX) diff --git a/Modules/Platform/visionOS-Initialize.cmake b/Modules/Platform/visionOS-Initialize.cmake new file mode 100644 index 0000000..e8431bc --- /dev/null +++ b/Modules/Platform/visionOS-Initialize.cmake @@ -0,0 +1,7 @@ +include(Platform/Darwin-Initialize) + +if(NOT _CMAKE_OSX_SYSROOT_PATH MATCHES "/XR(OS|Simulator)") + message(FATAL_ERROR "${CMAKE_OSX_SYSROOT} is not an visionOS SDK") +endif() + +set(_CMAKE_FEATURE_DETECTION_TARGET_TYPE STATIC_LIBRARY) diff --git a/Modules/Platform/visionOS.cmake b/Modules/Platform/visionOS.cmake new file mode 100644 index 0000000..850ddc2 --- /dev/null +++ b/Modules/Platform/visionOS.cmake @@ -0,0 +1 @@ +include(Platform/Darwin) diff --git a/Modules/UsePkgConfig.cmake b/Modules/UsePkgConfig.cmake index 32d228d..b020259 100644 --- a/Modules/UsePkgConfig.cmake +++ b/Modules/UsePkgConfig.cmake @@ -35,25 +35,25 @@ macro(PKGCONFIG _package _include_DIR _link_DIR _link_FLAGS _cflags) # if pkg-config has been found if(PKGCONFIG_EXECUTABLE) - exec_program(${PKGCONFIG_EXECUTABLE} ARGS ${_package} --exists RETURN_VALUE _return_VALUE OUTPUT_VARIABLE _pkgconfigDevNull ) + execute_process(COMMAND ${PKGCONFIG_EXECUTABLE} ${_package} --exists RESULT_VARIABLE _return_VALUE OUTPUT_VARIABLE _pkgconfigDevNull ) # and if the package of interest also exists for pkg-config, then get the information if(NOT _return_VALUE) - exec_program(${PKGCONFIG_EXECUTABLE} ARGS ${_package} --variable=includedir + execute_process(COMMAND ${PKGCONFIG_EXECUTABLE} ${_package} --variable=includedir OUTPUT_VARIABLE ${_include_DIR} ) string(REGEX REPLACE "[\r\n]" " " ${_include_DIR} "${${_include_DIR}}") - exec_program(${PKGCONFIG_EXECUTABLE} ARGS ${_package} --variable=libdir + execute_process(COMMAND ${PKGCONFIG_EXECUTABLE} ${_package} --variable=libdir OUTPUT_VARIABLE ${_link_DIR} ) string(REGEX REPLACE "[\r\n]" " " ${_link_DIR} "${${_link_DIR}}") - exec_program(${PKGCONFIG_EXECUTABLE} ARGS ${_package} --libs + execute_process(COMMAND ${PKGCONFIG_EXECUTABLE} ${_package} --libs OUTPUT_VARIABLE ${_link_FLAGS} ) string(REGEX REPLACE "[\r\n]" " " ${_link_FLAGS} "${${_link_FLAGS}}") - exec_program(${PKGCONFIG_EXECUTABLE} ARGS ${_package} --cflags + execute_process(COMMAND ${PKGCONFIG_EXECUTABLE} ${_package} --cflags OUTPUT_VARIABLE ${_cflags} ) string(REGEX REPLACE "[\r\n]" " " ${_cflags} "${${_cflags}}") diff --git a/Modules/UseSWIG.cmake b/Modules/UseSWIG.cmake index ca16bc2..cece973 100644 --- a/Modules/UseSWIG.cmake +++ b/Modules/UseSWIG.cmake @@ -189,7 +189,7 @@ ensure generated files will receive the required settings. :ref:`Makefile <Makefile Generators>`, :ref:`Ninja <Ninja Generators>`, :generator:`Xcode`, and :ref:`Visual Studio <Visual Studio Generators>` - (:generator:`Visual Studio 11 2012` and above) generators. Default value is + (:generator:`Visual Studio 12 2013` and above) generators. Default value is ``FALSE``. .. versionadded:: 3.21 @@ -353,7 +353,7 @@ as well as ``SWIG``: :ref:`Makefile <Makefile Generators>`, :ref:`Ninja <Ninja Generators>`, :generator:`Xcode`, and :ref:`Visual Studio <Visual Studio Generators>` - (:generator:`Visual Studio 11 2012` and above) generators. Default value is + (:generator:`Visual Studio 12 2013` and above) generators. Default value is ``FALSE``. Source file property ``USE_SWIG_DEPENDENCIES``, if not defined, will be |