BRIEF_DOCS and FULL_DOCS became optional as of edb5059216
(define_property(): Make BRIEF_DOCS and FULL_DOCS optional,
2022-01-18). Remove these options from the define_property()
calls, since they served no useful purpose. The canonical
documentation of those properties is in the RST docs at the top of
the file.
ExternalProject_Add() supports USES_TERMINAL_* flags to enable user
input for different steps. The Subversion download options ignored
these flags when checking out or updated a Subversion repo.
Fixes: #23348
Add the option to keep the current filestamps when extracting an
archive in ExternalProject_Add.
Enabling this option makes the behavior consistent with how
ExternalProject_Add is used when checking out code from revision
control instead of an archive.
Fixes: #22746
8abd714176 Help: Clarify that ENVIRONMENT test properties take ;-separated lists
02cf404ace Help: Add advice for dealing with semicolons in lists
c4117d9116 ExternalProject: Document that LIST_SEPARATOR works for CMAKE_ARGS too
Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Ben Boeckel <ben.boeckel@kitware.com>
Merge-request: !7066
Since `CMAKE_ARGS` is used to construct the default `CONFIGURE_COMMAND`
for CMake-based external projects, the `LIST_SEPARATOR` option works for
it too.
This brings the patch step into line with all the others which already
had their own `USES_TERMINAL_<step>` keyword. All steps (including
patch) already have their own `LOG_<step>` keyword too, so the lack of
`USES_TERMINAL_PATCH` was inconsistent.
This makes the scripts easier to work on, since the separate files
don't require the extra level of escaping that the inlined code did.
This also means the scripts can be rendered with appropriate
syntax highlighting in IDEs, etc.
This is in preparation for moving more inline content to separate
scripts as well. Having them in a separate subdirectory is consistent
with other modules and will make them easier to find and work with.
This change was originally made in 404cddb7bb (ExternalProject:
Fix misuse of IS_NEWER_THAN in timestamp checks, 2021-02-21),
but was reverted by 57d442e182 (Revert ExternalProject and
FetchContent refactoring, 2021-03-10) due to regressions from
other changes. Reapply this fix on its own, since it is still valid.
When using a file system which only has second resolution timestamps,
there is a reasonably high likelihood of timestamps being the same.
The IS_NEWER_THAN test returns true when timestamps are the same,
so don't redo downloads when they match exactly.
1cb65e680d (ExternalProject: Prevent the noisy detached head
messages on checkout, 2021-01-17) unconditionally added the advice.detachedHead
git config setting, but it requires git 1.7.7 or later. Since it isn't fatal to not
have it, just noisier, only add it when it is supported.
Fixes: #22206
Refactoring of the ExternalProject and FetchContent modules moved
the commands into CMake scripts. This broke custom commands that
used shell redirection or special build tool variables of the form
$(MakeVar). Undo the sequence of commits that performed this
refactoring and follow-up fixes associated with it.
The following commits are reverted by this change:
4f3d1abbb4 (ExternalProject: Refactor pre-configure steps to support
no-target uses, 2021-02-05)
17e5516e60 (FetchContent: Invoke steps directly and avoid a separate
sub-build, 2021-01-29)
bd876f3849 (FetchContent: Restore patch command support,
2021-02-18)
404cddb7bb (ExternalProject: Fix misuse of IS_NEWER_THAN in
timestamp checks, 2021-02-21)
b0da671243 (FetchContent: Don't update timestamps if files don't
change, 2021-02-18)
Fixes: #21892
The refactoring in 17e5516e60 (FetchContent: Invoke steps directly and
avoid a separate sub-build, 2021-01-29) uses a different way of writing
out the step scripts and updating time stamps when steps are executed.
That inadvertently always wrote out the scripts for custom commands,
even when the contents didn't change. This caused their timestamp to
always be updated, resulting in those steps always being seen as
out-of-date and needing to be re-executed.
The way timestamps were checked to determine whether to re-execute
a step also did not adequately account for file systems which only have
second-resolution timestamps. The IS_NEWER_THAN if condition also
returns true when timestamps are the same, so one needs to use the
negative form to get a true "is newer than" test.
ExternalProject is not susceptible to this problem because it uses
file(GENERATE) to write out the script files and that only updates the file's
timestamp if the contents change. It also mostly leaves timestamp
checking to the build tool.
The refactoring in 17e5516e60 (FetchContent: Invoke steps directly and
avoid a separate sub-build, 2021-01-29) contained a typo which resulted
in any PATCH_COMMAND being ignored. Fix the typo and add a test case
that would have caught the regression.
The cost of setting up and executing a separate sub-build to do the
download, update and patch steps required for FetchContent population
can be significant with some platforms and CMake generators. Avoid the
sub-build altogether by invoking the step scripts directly.
Previously, if no generator was set (e.g. population was being done in
script mode), a generator needed to be available on the default PATH.
Since we no longer use a sub-build, this restriction is also now gone.
Fixes: #21703
The mkdir, download, update and patch steps are used by
FetchContent during the configure phase of the main build. Because
these steps need a target, this has so far required a sub-build to be
set up. The changes here factor out the preparation of the scripts
from the creation of the targets, allowing future work to leverage these
steps without a sub-build (see #21703).
As part of the refactoring, some rationalisation of the stamp files,
repository info files and script names was done to make things more
consistent between download methods and step implementations.
Every download method now records its own specific repository info
in a file and that file is a dependency of the download step. The source
directory is also written to that file, so if the SOURCE_DIR changes, the
download will be retriggered (the existing implementation fails in this
scenario). Each download method now also has just one driver script
that implements the whole step (it may pull in other scripts to do its
task though). The patch step gained support for USES_TERMINAL as
a result of generalising the implementation for custom commands.
Fixes: #21748
The previous implementation was scanning the documentation in
the file at runtime to determine the set of supported keywords for
each public function. This was fragile, made it difficult to restructure
the documentation and was sometimes observable in runtime
performance measurements. Change to a more conventional
approach where supported keywords are explicitly listed in the
code.
The internal _ExternalProject_SELF variable is no longer needed.
CMake now provides CMAKE_CURRENT_FUNCTION_LIST_DIR which
can be used for the same purpose and avoids having to set a
variable when the module is read. This also removes the
requirement that the module must be included by the current or a
parent scope. It is now enough that the module has been included
once somewhere before calling any of its functions.
The above changes combined mean that the module can now use
include_guard() and avoid having to re-parse the very long file every
time.
When checking out a specific commit by its git hash, git will output
a very noisy message about checking out a detached HEAD. This
is not particularly helpful for us here and makes the output overall
quite verbose. Add a git config setting to prevent it.
76fdeb6d13 Tests: FindGit already provides the git version, re-use it
315a200f0c FindGit: Cache the GIT_EXECUTABLE version for the current run
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !5712
The git version should not change while CMake is running. When
using FetchContent with many dependencies, the repeated calls
to get the git version every time ExternalProject is used can be
measurable on some platforms. This commit queries that version
only once and then caches it in a global property for the rest of that
run. The git version can still safely change between runs because it
is not cached, only the GIT_EXECUTABLE location is cached.
Relates: #21703
When doing an ExternalProject superbuild with all output logged to
files, the output currently looks as follows:
```
[652/904] Performing install step for 'plasma-framework'
-- plasma-framework install command succeeded. See also /root/build/kde/frameworks/plasma-framework/log/plasma-framework-install-*.log
[658/904] Performing build step for 'khtml'
-- khtml build command succeeded. See also /root/build/kde/frameworks/khtml/log/khtml-build-*.log
[659/904] Performing install step for 'khtml'
-- khtml install command succeeded. See also /root/build/kde/frameworks/khtml/log/khtml-install-*.log
[661/904] Performing configure step for 'krunner'
-- krunner configure command succeeded. See also /root/build/kde/frameworks/krunner/log/krunner-configure-*.log
[661/904] Performing build step for 'krunner'
```
More specifically, because a success line is printed for every
succeeded step, we lose the advantage of Ninja's progress bar
which will now also print a new line instead of updating the same
link as happens when using Ninja in a normal CMake project.
By silencing the success message when using the Ninja generator,
Ninja's progress bar works as expected and updates inline instead
of printing a new line for each progress update.
With this change, the above output is reduced to a single line
progress bar:
```
[661/904] Performing build step for 'krunner'
```
The ExternalProject module cannot be implemented in the Xcode "new build
system" without using CMP0114's NEW behavior. When configuring for that
build system, warn if the policy is not set to NEW and use NEW behavior
anyway.
`ExternalProject_Add_StepTargets` and `INDEPENDENT_STEP_TARGETS` have
some limitations and lack some sanity checks. They can cause confusing
build systems to be generated. The basic problems are:
* The notion of step independence is attached to the step target
rather than the step itself.
* The custom commands implementing the steps are duplicated in the
step targets and the primary targets. This can cause races.
It is also incompatible with the Xcode "new build system".
Fix this by introducing policy CMP0114 to change the way step target
dependencies are handled. Define independence from external
dependencies as a property of each individual step regardless of whether
there is a target for it. Add dependencies among the primary target and
the step targets such that each custom command only appears in one
target. When some steps are disconnected from the primary target, add
step targets for the steps commonly depended upon so that there is a
place to hold their custom commands uniquely.
Fixes: #18663
When updates are disconnected, don't depend on skip-update because that
target is always considered out of date. Depend directly on the patch target
instead because it already depends on the appropriate target regardless of
whether updates are disconnected or not. This in turn means nothing depends
on the skip-update target, so it has also been removed.
Relates: #21086
The skip-update target is always considered out-of-date. The change in
7249ba9677 (ExternalProject: Enforce that patch depends on update, 2020-04-03)
made the patch target depend on skip-update, which in turn made it
always out of date too. The patch command should only be re-run if the download
needs to be performed again where updates are disconnected.
Fixes: #21086
The optimization from commit 627fc5b44f (ExternalProject: Avoid
unnecessary checkout on clone, 2019-07-29, v3.16.0-rc1~325^2) triggers a
bug in the Git 2.20.x series that is not in older or newer versions.
Drop the optimization for that specific range of Git versions.
Fixes: #21009
GitLab now uses a `/-/` component between the `group/project` part of
the URL and the `{issues,merge_requests,tree}` part so that it can
support `group/subgroup/project` with arbitrary depth.
The refactoring exposed that the original implementation
was referring to an undefined variable src_name, which was
previously only used in error messages. This has been fixed
as part of the refactoring work.
Fixes: #20336
When looking at `list(FIND)` result, zero index is ignored due to
incorrect error handling, and users can't set dependencies on mkdir
step.
Fixes: #20605
