These policies were introduced after 2.8.12 in anticipation of 2.8.13.
However, we've now decided the next release will be 3.0.0, so update the
version of introduction accordingly.
The full policy documentation was moved to Help/policy/*.rst by commit
f051814e (Convert builtin help to reStructuredText source files,
2013-10-15). We no longer need the builtin string literals.
In commit 87cc62ca (Drop "full" documentation output types, 2013-09-13)
we dropped code using the LongDescription field of policy definitions.
We need to follow it up with a change similar to commit 399e9c46 (Drop
builtin property documentation, 2013-09-16) to remove the policy
documentation. Do that now. Keep the short description as it is used
in policy error and warning messages.
This has not been allowed since they were introduced in
commit 91438222 (target_link_libraries: Add LINK_(PUBLIC|PRIVATE)
options, 2011-10-07), but allowing this form makes it more compatible
with the newer PUBLIC and PRIVATE keywords.
Teach the CMake language parser to recognize Lua-style "long bracket"
arguments. These start with two '[' separated by zero or more '='
characters e.g. "[[" or "[=[" or "[==[". They end with two ']'
separated by the same number of '=' as the opening bracket. There is no
nesting of brackets of the same level (number of '='). No escapes,
variable expansion, or other processing is performed on the content
between such brackets so they always represent exactly one argument.
Also teach CMake to parse and ignore "long comment" syntax. A long
comment starts with "#" immediately followed by an opening long bracket.
It ends at the matching close long bracket.
Teach the RunCMake.Syntax test to cover long bracket and long comment
cases.
Read input files in binary mode instead of text mode and convert CRLF
newlines to LF newlines explicitly in our own buffer. This is necessary
to read CMake source files with CRLF newlines on platforms whose C
runtime libraries do not transform newlines in text mode. For example,
a Cygwin or Linux binary may not transform CRLF -> LF in files read from
a Windows filesystem. Perform the conversion ourselves to ensure that
multi-line string literals in CMake source files have LF newlines
everywhere.
Teach the lexer to read a UTF-8, UTF-16 BE/LE, or UTF-32 BE/LE
Byte-Order-Mark from the start of a file if any is present. Report an
error on files using UTF-16 or UTF-32 and accept a UTF-8 or missing BOM.
Teach the lexer to treat a single letter as an identifier instead of an
unquoted argument. Outside of a command invocation, the parser treats
an identifier as a command name and an unquoted argument as an error.
Inside of a command invocation, the parser treats an identifier as an
unquoted argument. Therefore this change to the lexer will make what
was previously an error case work with no other behavioral change.
9b212ad Make --help-* options available from all command-line tools
5dde65a Help: De-duplicate manual/(cmake|ccmake).1.rst build options
ae944d1 Help: Organize manual/*.1.rst sections
4f7d708 Help: Drop leftover conversion content from manual/*.1.rst
Check for "cmake -E ..." up front (along with "cmake --build ...") and
skip normal command line processing. Drop the special handling for -E
from the normal processing to simplify things. Strictly speaking, it
was previously possible to invoke command mode with -E anywhere in the
command line e.g. "cmake echo -E message" or "cmake echo message -E",
but no one should be using it as it was not documented and looks
strange.
Make the standard --help-* options available from all command-line
tools. Drop options that are no longer supported:
--copyright, --help-full, --help-html, --help-man,
--help-compatcommands, --help-custom-modules
De-duplicate Help/manual/*.1.rst help options by using an
OPTIONS_HELP.txt file included from each manual.
Add "Synopsis", "Description", and "See Also" manual page section
headers. These are typical of .1 man section pages. Also de-duplicate
the See Also section links using a separate LINKS.txt file included from
each manual.
The Intel Fortran compiler needs the /fpp option to enable C
preprocessing. Without the option the compiler may warn and ignore
preprocessor lines instead of failing with an error. Detect the
warning and treat it as failure so that we move on to try /fpp and
detect the correct id. Without this it works only by luck because
Intel is the first compiler id in our detection source file.
7038a93 Modules/readme.txt: Update steps to add module documentation
a77e308 CPack: Replace #<type> markup with reStructuredText equivalent
e7ca48f Help: Factor out cmake-generator-expressions manual page
97e8650 Help: Factor out COMPILE_DEFINITIONS disclaimer duplication
8982161 Help: Factor out find_* command duplication
30b2186 Help: Factor out *_OUTPUT_(NAME|DIRECTORY).rst duplication
bfe07aa Build Help documentation during CMake build using Sphinx
53ded59 Drop unused builtin documentation APIs
0c39a75 Drop the 'Full' field from cmDocumentationEntry
e33d8d2 Drop builtin command documentation
399e9c4 Drop builtin property documentation
6035c04 get_property: Drop test for builtin property documentation
80a3273 Drop all documentation formatters except Usage
b336a1eb Teach COMPATIBLE_INTERFACE_* checks to use Help .rst documents
ec6df36 Teach --help-* options to load documentation from .rst files
25f2877 Add class cmRST to do basic reStructuredText processing
...
Drop #end and #module. Convert #section to a subsection header.
Convert #variable to the cmake domain "variable" directive.
Convert #macro to the cmake domain "command" directive.
Perform minor formatting fixes in text near these changes.
Generator expressions are supported in many places and are a distinct
concept worthy of their own manual page. The old builtin documentation
was previously represented by preprocessor macros to generate it into
each place that supports them. Factor out the duplicate content into a
dedicated cmake-generator-expressions manual page and reference it from
each original location.
The COMPILE_DEFINITIONS escaping disclaimer was represented in builtin
documentation using a preprocessor macro. Factor the duplicate content
out into a separate .txt file and include it in each document with the
reStructuredText include directive.
These documents were represented in the builtin documentation using a
common starting point with placeholders substituted by each command.
Convert them back to this approach using the reStructuredText include
directive and substitutions to avoid duplication.
Portions of these documents contain duplicate content generated from
preprocessor macros in the original builtin documentation source.
Factor the common parts out into .txt files using reStructuredText
include directives and substitutions to avoid duplication.
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 all DefineProperty calls for non-chained properties. Drop the
documentation from the chained ones. The documentation for all
properties is now in Help/prop_*/*.rst files.
We now need only the Usage formatter to support command-line options
that print basic usage, and the supporting indented=>preformatted markup
processor to support CMake message formatting. Drop all other
documentation formatters and move the remaining code up into the top
cmDocumentationFormatter class.
These checks want to know if named target properties are builtin, which
is now known by checking the Help/prop_tgt directory. (Previously the
check could be confused by a define_property call in the project.)
Install the Help directory next to Modules to make it available in CMake
distributions. Use cmRST to read Help .rst documents and print them as
help output.
Add options
--help-manual-list
--help-manual
to list available manuals or print one of them. Implement the options
--help-commands
--help-modules
--help-policies
--help-properties
--help-variables
by mapping to the corresponding manual page. Implement the options
--help-command-list
--help-module-list
--help-policy-list
--help-property-list
--help-variable-list
by globbing the available Help .rst documents of the corresponding type
and reading their titles. Implement the options
--help-command
--help-module
--help-policy
--help-property
--help-variable
by globbing the matching Help .rst document(s) and printing them.
Create a cmRST class to perform just enough reStructuredText processing
to support display of Help documents in human-readable text format.
This will be used to implement --help-* command-line options.
Support directives "include", "replace", "parsed-literal", "toctree"
(Sphinx), and "cmake-module" (CMake Sphinx Extension to scan .cmake
modules). Support inline CMake Sphinx Domain roles to convert
cross-references to corresponding title text. Support inline
substitutions defined by the "replace" directive, but keep it simple by
requiring replacements to be defined before use.
Add a CMakeLib "testRST" case to cover processing of supported
constructs and compare results against expected output.
As reported by Coverity Scan, if the configured file contains a #include,
Untrusted array index read
The array index could be controlled by an attacker, leading to reads outside
the bounds of the array.
In main: Read from array at index computed using an unscrutinized value from
an untrusted source (CWE-129)
CID 1081283 (#1 of 1): Untrusted array index read (TAINTED_SCALAR)
25. tainted_data: Using tainted variable "testToRun" as an index into an array
"cmakeGeneratedFunctionMapEntries".
We will no longer support full documentation generation from executables
and will instead generate documentation with other tools. Disable (with
a warning left behind) the command-line options:
--copyright
--help-compatcommands
--help-full
--help-html
--help-man
Drop supporting code. Drop manual sections generation from executables.
Remove internal documentation construction APIs. Drop unused sections
See Also, Author, Copyright, Compat Commands, Custom Modules.
Add a top-level document holding the Sphinx root toctree. List all
reference manuals from Help/manual/*.rst and the Sphinx-generated
general index (genindex) and search pages.
Kitware Robot
Brad King
Stephen Kelly
Nils Gladitz
Rolf Eike Beer
Matt McCormick