From 6828b9df5aac1848766a75f675770224d41d22d6 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 31 Jul 2023 11:20:19 -0400 Subject: Help/dev: Extend documentation guide with another section nesting level --- Help/dev/documentation.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst index c6fb7a6..65c0ccf 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -431,6 +431,7 @@ The section header underline character hierarchy is * ``-``: Subsection or `CMake Domain`_ object document title * ``^``: Subsubsection or `CMake Domain`_ object document section * ``"``: Paragraph or `CMake Domain`_ object document subsection +* ``~``: `CMake Domain`_ object document subsubsection Style: Whitespace ^^^^^^^^^^^^^^^^^ -- cgit v0.12 From c949a8742e58887a29bb6c66b76f31d39f8dcb3d Mon Sep 17 00:00:00 2001 From: scivision Date: Wed, 26 Jul 2023 12:44:03 -0400 Subject: ExternalProject: Add option subsection anchors for accessibility from TOC Use RST subsections for each major step of `ExternalProject_Add()`. This makes finding options easier with less scrolling. For example, finding important Download vs. Test options etc. Fixes: #25129 --- Modules/ExternalProject.cmake | 1755 +++++++++++++++++++++-------------------- 1 file changed, 893 insertions(+), 862 deletions(-) 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 `` - 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 `` - Directory in which to store temporary files. - - ``STAMP_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 `` - .. versionadded:: 3.14 - - Directory in which to store the logs of each step. - - ``DOWNLOAD_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 `` - 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 `` - Specify the build directory location. This option is ignored if - ``BUILD_IN_SOURCE`` is enabled. - - ``INSTALL_DIR `` - Installation prefix to be placed in the ```` 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 ````. - - 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 = /tmp - STAMP_DIR = /src/-stamp - DOWNLOAD_DIR = /src - SOURCE_DIR = /src/ - BINARY_DIR = /src/-build - INSTALL_DIR = - LOG_DIR = - - Otherwise, if the ``EP_BASE`` directory property is set then components - of an external project are stored under the specified base:: - - TMP_DIR = /tmp/ - STAMP_DIR = /Stamp/ - DOWNLOAD_DIR = /Download/ - SOURCE_DIR = /Source/ - BINARY_DIR = /Build/ - INSTALL_DIR = /Install/ - LOG_DIR = - - If no ``PREFIX``, ``EP_PREFIX``, or ``EP_BASE`` is specified, then the - default is to set ``PREFIX`` to ``-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 ...`` - Overrides the command used for the download step - (:manual:`generator expressions ` are - supported). If this option is specified, all other download options will - be ignored. Providing an empty string for ```` effectively disables - the download step. - - *URL Download* - ``URL [...]`` - 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 =`` - Hash of the archive file to be downloaded. The argument should be of - the form ``=`` 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 `` - Equivalent to ``URL_HASH MD5=``. - - ``DOWNLOAD_NAME `` - 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 `` - .. 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 `` - .. 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 ```` in subsequent - steps or as the property ``DOWNLOADED_FILE`` with the - :command:`ExternalProject_Get_Property` command. - - ``DOWNLOAD_NO_PROGRESS `` - Can be used to disable logging the download progress. If this option is - not given, download progress messages will be logged. - - ``TIMEOUT `` - Maximum time allowed for file download operations. - - ``INACTIVITY_TIMEOUT `` - .. versionadded:: 3.19 - - Terminate the operation after a period of inactivity. - - ``HTTP_USERNAME `` - .. versionadded:: 3.7 - - Username for the download operation if authentication is required. - - ``HTTP_PASSWORD `` - .. versionadded:: 3.7 - - Password for the download operation if authentication is required. - - ``HTTP_HEADER [...]`` - .. 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 `` - 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 `` - 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 `` - .. 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 `` - .. 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 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 `` - 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 `` - The optional name of the remote. If this option is not specified, it - defaults to ``origin``. - - ``GIT_SUBMODULES ...`` - 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 `` - .. 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 `` - .. 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 `` - .. 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 [...]`` - .. versionadded:: 3.8 - - Specify a list of config options to pass to ``git clone``. Each option - listed will be transformed into its own ``--config