This fixes typos, syncs docs code style a bit and refactors functions
descriptions.
- Initial example improved and synced with the current
`feature_summary()` output
- The global properties are listed with indentation
- Added reference links where it makes sense to better understand the
terminology
- CMake versions added for all properties (they got introduced in CMake
3.8)
- All "macro" words renamed to "function"
- "Legacy Macros" renamed to "Deprecated Functions"
Because cmake_parse_arguments() has been implemented as a native
command, there is no need to include(CMakeParseArguments) anymore.
Its inclusion has been removed from several CMake modules.
Tests/CMakeOnly/CMakeLists.txt has been changed to include the
*building* CMake's copy of CMakeParseArguments rather than the
*built* CMake's copy. This file included the *built* copy because
when this file was introduced, CMake could still be built with versions
that didn't supply cmake_parse_arguments(). Now, CMake requires 3.1 or
greater, where cmake_parse_arguments() existed but was still in the
form of a module, so we include it from the *building* CMake.
Some are user facing.
Found using
codespell -q 3 --skip="./Utilities" -I .cmake-whitelist.txt`
whereby the whitelist contained:
ans
dum
helpfull
emmited
emmitted
buil
iff
isnt
nto
ot
pathes
substract
te
todays
upto
whitespaces
The global property FeatureSummary_<TYPE>_DESCRIPTION can be defined for
each type to replace the type name with the specified string whenever
the package type is used in an output string.
These new global properties were added:
* FeatureSummary_PKG_TYPES: Package types accepted by FeatureSummary
(default REQUIRED RECOMMENDED OPTIONAL RUNTIME).
* FeatureSummary_REQUIRED_PKG_TYPES: Package types that will cause
FeatureSummary to abort when called with
FATAL_ON_MISSING_REQUIRED_PACKAGES and a package in these categories
is missing (default REQUIRED).
* FeatureSummary_DEFAULT_PKG_TYPE: Default package type assigned when
not explicitly assigned by the user (default OPTIONAL).
This allows to add and remove new package types that can be printed
selectively using the "WHAT" argument.
The OPTIONAL type is used anyway as default when the type is not set
Since RUNTIME < OPTIONAL, forcing it here forces the user to set
"RUNTIME" at the first SET_PACKAGE_PROPERTIES, otherwise it is
impossible to set it later.
Without this it is impossible, for example, to add package information
(URL and DESCRIPTION) in the FindPackage file, but allow the package
to be RUNTIME.
The cmake_parse_arguments command is builtin with version 3.5.
The CMakeParseArguments module is empty and exists for backwards
compatibility with CMake 3.4 and lower.
Remove the includes of CMakeParseArguments from CMake's modules.
The modules are always used with the current version of CMake.
Leave the includes in the tests, as the tests may be run with an older
version of CMake.
Per-source copyright/license notice headers that spell out copyright holder
names and years are hard to maintain and often out-of-date or plain wrong.
Precise contributor information is already maintained automatically by the
version control tool. Ultimately it is the receiver of a file who is
responsible for determining its licensing status, and per-source notices are
merely a convenience. Therefore it is simpler and more accurate for
each source to have a generic notice of the license name and references to
more detailed information on copyright holders and full license terms.
Our `Copyright.txt` file now contains a list of Contributors whose names
appeared source-level copyright notices. It also references version control
history for more precise information. Therefore we no longer need to spell
out the list of Contributors in each source file notice.
Replace CMake per-source copyright/license notice headers with a short
description of the license and links to `Copyright.txt` and online information
available from "https://cmake.org/licensing". The online URL also handles
cases of modules being copied out of our source into other projects, so we
can drop our notices about replacing links with full license text.
Run the `Utilities/Scripts/filter-notices.bash` script to perform the majority
of the replacements mechanically. Manually fix up shebang lines and trailing
newlines in a few files. Manually update the notices in a few files that the
script does not handle.
If a feature is added multiple times via ADD_FEATURE_INFO it should
appear only once in FEATURE_SUMMARY.
Signed-off-by: Gregor Jasny <gjasny@googlemail.com>
Convert several preformatted code block literals that enumerate lists of
options or variables to use reST definition lists instead. Manually
wrap other long lines in code blocks.
For example it is now possible to do:
feature_summary(WHAT ENABLED_FEATURES
DISABLED_FEATURES)
That produces an output like:
--
-- The following features have been enabled:
* Feature1
* Feature2
-- The following features have been disabled:
* Feature2
Skipping the lists that are empty.
Without this patch this would require to do:
message(STATUS "")
feature_summary(WHAT ENABLED_FEATURES
DESCRIPTION "The following features have been enabled:")
feature_summary(WHAT DISABLED_FEATURES
DESCRIPTION "The following features have been disabled:")
And empty lists would not be skipped.
The behaviour when WHAT has a single argument (ALL or any option) is
unchanged.
Set a global property in the find_package implementation. Track and
reset that property in the find_dependency macro. Read the property
in FeatureSummary when determining whether to print output.
This means that packages which are found only as dependencies are not
listed by FeatureSummary, but if a project uses find_package elsewhere
directly, then it will be listed by FeatureSummary.
Suggested-by: Alex Merry
http://thread.gmane.org/gmane.comp.kde.devel.frameworks/10640
This solves a lots of warnings, e.g. in the FindModulesExecuteAll test. If the
installed version on the system is rather old this may even lead to bugs, e.g.
https://bugs.gentoo.org/show_bug.cgi?id=436540
Ancient versions of CMake required else(), endif(), and similar block
termination commands to have arguments matching the command starting the
block. This is no longer the preferred style.
Run the following shell code:
for c in else endif endforeach endfunction endmacro endwhile; do
echo 's/\b'"$c"'\(\s*\)(.\+)/'"$c"'\1()/'
done >convert.sed &&
git ls-files -z -- bootstrap '*.cmake' '*.cmake.in' '*CMakeLists.txt' |
egrep -z -v '^(Utilities/cm|Source/kwsys/)' |
egrep -z -v 'Tests/CMakeTests/While-Endwhile-' |
xargs -0 sed -i -f convert.sed &&
rm convert.sed
