Avoid requiring all build machines for the upstream packaging process to
have Python and Sphinx installed. Instead create a way to build the
documentation once on the host machine and copy it to each build machine
as a tarball with content to include in the installation tree for
packaging.
Add a Utilities/Sphinx directory to hold CMake build code to run the
Sphinx (sphinx-doc.org) documentation generation tool. Create a
CMakeLists.txt file there capable of building either as a subdirectory
of the main CMake build, or as a standalone documentation build.
Add cache options SPHINX_MAN and SPHINX_HTML to select output formats
and SPHINX_EXECUTABLE to specify the sphinx-build executable. Add
bootstrap options --sphix-man and --sphinx-html to select output formats
and --sphinx-build=<sb> to specify the sphinx-build executable.
Create a "conf.py.in" file to configure_file into "conf.py" to tell
sphinx-build how to build our documents. Create a "cmake.py" Sphinx
extension module defining:
* The "cmake-module" directive used in Help/module/*.rst files to
scan .rst markup from the corresponding Modules/*.cmake file.
* A Sphinx domain called "cmake" defining documentation object types
for CMake Help/<type> directories: command, generator, manual,
module, policy, prop_*, and variable. Add a "role" for each type
to perform cross-references. Teach the roles to treat "<XYZ>"
as placeholders instead of explicit targets if not preceded by
a space. Add cmake domain directives to define command and
variable objects explicitly in .rst file content. This will
allow modules to define their own commands and variables and
have them indexed and linkable.
* A Sphinx document transform that converts Help/<type>/*.rst documents
into cmake domain objects of the corresponding <type> and adds index
entries for them. This will automatically index all CMake documentation
objects and provide cross-reference targets for them with no special
markup in the .rst files.
Drop the 'documentation' build target. We will no longer use the
executables to generate their own documentation. New infrastructure
will be introduced later to generate documentation.
The final location and name of a build-target is not determined
until generate-time. However, reading the LOCATION property from
a target is currently allowed at configure time. Apart from creating
possibly-erroneous results, this has an impact on the implementation
of cmake itself, and prevents some major cleanups from being made.
Disallow reading LOCATION from build-targets with a policy. Port some
existing uses of it in CMake itself to use the TARGET_FILE generator
expression.
Ensure CMAKE_DATA_DIR, CMAKE_DOC_DIR, and CMAKE_MAN_DIR are always
relative paths in CMake code, and set defaults accordingly. Use the
install() command instead of install_files() and install_targets().
This is more modern and also avoids stripping of the first character
from user-specified destinations.
While at it, fix the default destinations reported in the bootstrap
help.
Drop the "cmake -E chdir" wrapper and instead pass the DTD directory to
xmllint's --path option using url encoding. While at it, move the
XHTML1 DTD to "Utilities/xml/xhtml1" to make room for additional DTDs.
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
The older install_files command uses a leading slash in front
of the destination directory, whereas the modern signature does
not. Use the modern signature since that's what the CMake devs
are now used to.
In commit bb1df1ec, we temporarily ran an alternate test,
guaranteed to fail when the --help output of xmllint did
not contain --nonet and --path.
This commit simply eliminates the test altogether in
this condition rather than make an attempt (doomed to
fail) to pull down the dtd over the internet.
On date=2010-11-04, the CMake dashboard results showed that
the test failed on the following CMake dashboard machines:
dash8.kitware
dash8.kitwarein.com
dashsun1
dashsun1.kitware
ferrari
This is a very small subset of the dashboard machines, and
we have enough proof from enough other machines that the test
passes with xmllint versions new enough to have the --nonet
support.
Therefore, eliminate the CMake.HTML test on machines with old
versions of xmllint. To run the test, make sure you run it
on a machine with a new enough xmllint.
Also, emit "xmllint" and "xmllint --version" output before
failing so that we can inspect the output from all the
dashboard machines in CDash test results.
Organize Utilities/CMakeLists.txt to avoid duplicate install command
calls. We collect each type of documentation in a variable listing its
files for installation and then use one install call at the end.
This converts the CMake license to a pure 3-clause OSI-approved BSD
License. We drop the previous license clause requiring modified
versions to be plainly marked. We also update the CMake copyright to
cover the full development time range.
We use a custom command to run 'cmake-gui --help...' to generate the
documentation for the application. Since this is a Qt application, the
executable must find the Qt DLLs in order to run. As a convenience, if
QtCore4.dll appears next to qmake.exe, we put its location in the PATH
environment variable when running the custom command on Windows.
-generate and install the policy documentation files
-generate and install the docbook files for cmake, ctest, cpack, ccmake (cmake-gui not yet ?)
Alex
commands, modules and properties as html, text and man pages.
The names of the man pages are cmcommands, cmcompat, cmprops and cmmodules,
so they are easy to type.
Alex
-in the full documentation there is now an extra section for
compatibility commands, so users see which commands they shouldn't use
-cmake -h <command> now also works with lower case commands
--help-fullm --help-command, --help-module and --help-property now determine
the output format from the extension of the given filename
Let me know if there are some things I overlooked.
Alex
Brad King
Stephen Kelly
Daniel Pfeifer
Marcin Wojdyr
Kitware Robot
David Cole
Alex Neundorf
Bill Hoffman
Ken Martin
Andy Cedilnik
Sebastien Barre