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.

Since this module's documentation already includes complete usage
examples, make them more complete by showing the include() explicitly.

Issue: #16309

Revise the documentation using reStructuredText inline markup and
explicit blocks so that it formats well.

Use a bracket comment to hold the documentation instead of a block of
line comments.  This will make further updates easier.

Automate with:

find Modules -type f -print0 | xargs -0 perl -i -0pe \
's/set\(([a-zA-Z0-9_]+)(\s+)"\$\{\1\}([^"])/string(APPEND \1\2"\3/g'

ARGV# could be defined from a parent scope.

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>

Help format the blocks better for display without a wide screen.

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.

Since now these can be used with the WHAT argument a title is required.

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

Run the convert-help.bash script to convert documentation:

 ./convert-help.bash "/path/to/CMake-build/bin"

Then remove it.

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

Ancient CMake versions required upper-case commands.  Later command
names became case-insensitive.  Now the preferred style is lower-case.

Run the following shell code:

cmake --help-command-list |
grep -v "cmake version" |
while read c; do
    echo 's/\b'"$(echo $c | tr '[:lower:]' '[:upper:]')"'\(\s*\)(/'"$c"'\1(/g'
done >convert.sed &&
git ls-files -z -- bootstrap '*.cmake' '*.cmake.in' '*CMakeLists.txt' |
egrep -z -v '^(Utilities/cm|Source/kwsys/)' |
xargs -0 sed -i -f convert.sed &&
rm convert.sed

Alex

The patch fixes the following lintian warnings:

W: cmake-data: manpage-has-errors-from-man usr/share/man/man1/cmakemodules.1.gz 2728: warning: macro `..' not defined
I: cmake-data: spelling-error-in-manpage usr/share/man/man1/cmakemodules.1.gz overriden overridden
I: cmake-data: spelling-error-in-manpage usr/share/man/man1/cmakemodules.1.gz overriden overridden
I: cmake-data: spelling-error-in-manpage usr/share/man/man1/cmakemodules.1.gz explicitely explicitly
I: cmake-data: spelling-error-in-manpage usr/share/man/man1/cmakemodules.1.gz jave java
W: cmake-data: manpage-has-errors-from-man usr/share/man/man1/cmakeprops.1.gz 1040: warning [p 25, 3.7i]: can't break line
W: cmake: manpage-has-errors-from-man usr/share/man/man1/cmake.1.gz 4233: warning [p 85, 1.3i]: can't break line
I: cmake: spelling-error-in-manpage usr/share/man/man1/cmake.1.gz overriden overridden
I: cmake: spelling-error-in-manpage usr/share/man/man1/cmake.1.gz overriden overridden
I: cmake: spelling-error-in-manpage usr/share/man/man1/cmake.1.gz explicitely explicitly
I: cmake: spelling-error-in-manpage usr/share/man/man1/cmake.1.gz jave java

Patch by Yury Kudryashov

Alex

Patch by Yury Kudrashov

Alex

Alex

-move the compat function to the bottom of the file
-make all except one endif() empty

Alex

This way e.g. a REQUIRED cannot become OPTIONAL, only the other way round

Alex

Alex

Now found packages are not stored in ENABLED/DISABLED_FEATURES
anymore, but always in PACKAGES_FOUND/NOT_FOUND.
ENABLED/DISABLED_FEATURES is now only used via
ADD_FEATURE_INFO(), e.g. for stuff set via option().

Alex

What was given as comment to set_package_info(), now goes into
the PURPOSE field. It was not clear what the comment should contain,
with the PURPOSE this is much clearer now.

Alex

With the PURPOSE a project can state what the package in question
is used for in the project (as opposed to describing what the package
does in general).
TYPE can be one of OPTIONAL (default)
                   RUNTIME - not needed for building, only at runtime
                   RECOMMENDED - as OPTIONAL, but you should really have it
                   REQUIRED - cmake will fail if one of these is not found

This can be set using the new function set_package_properties()

Alex

Alex

Alex

Alex

ADD_FEATURE_INFO() can be used to set the info for a feature,
e.g. an option().
set_feature_info() has been renamed to set_package_info(), since this is
about found or not found packages. For compatiblity set_feature_info()
is still provided.

Alex

Alex

Alex

find_package() now also stores the required version automatically, so it
can be used by FeatureSummary.cmake.
This was one of the requested features for setting up nightly builds
for KDE, since with this functionality it will be possible to write
a file at the end of each project which lists all required packages
and their versions. This file could then be compared for equality
with an older one and if something has changed the build maintainer
can be emailed.

In FeatureSummary.cmake there is now a new function feature_summary(),
which also allows to print the log to a file or into a variable.
It also allows to specify whether to append to a file or to write a new
one, and what information to log.

Docs are still missing.

Alex