[Cmake-commits] CMake branch, master, updated. v3.13.0-rc3-460-g64df9ef
Kitware Robot
kwrobot at kitware.com
Thu Nov 15 08:43:11 EST 2018
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "CMake".
The branch, master has been updated
via 64df9ef33a2f4eb9ef0cb17a2844308d9c7f7034 (commit)
via f21bad80a297e26b886f15f38f4d87cc5ce9687f (commit)
via b3d1d6d895355ee64c74cef1ab0040db02f81894 (commit)
via bd2c17d614e89b5786937565302c6fa54f121d22 (commit)
via 22cca9b8100a59cd156e2ba39819171a0cf71881 (commit)
via a82282a08c2ddf2eb3a89d61fbf53af1af3c4de9 (commit)
via b90ae70a3b3c77109a31dfc275b778205a817d1a (commit)
via bfbc5241e928203f934fd4fd83fa8beb35b0fe96 (commit)
via 3e5a047f1aee1059d262b4096c5059ce2acad147 (commit)
via 06cc050c1fa6141e5c376230ef7ab19ba2942a08 (commit)
via e0c26406aa53b5dc4c942017eaf2410d0057aa9a (commit)
via 83bbfb1d53077176af86d637f713652e3ee01198 (commit)
via 01d5e5c460a2a9cb3962990f8ef278389254f30a (commit)
via ca355d92d827a26d626a241535fe710600eead0d (commit)
from 44a5400d105b957d27780d515d0f1d51781f8de9 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=64df9ef33a2f4eb9ef0cb17a2844308d9c7f7034
commit 64df9ef33a2f4eb9ef0cb17a2844308d9c7f7034
Merge: f21bad8 e0c2640
Author: Brad King <brad.king at kitware.com>
AuthorDate: Thu Nov 15 13:37:48 2018 +0000
Commit: Kitware Robot <kwrobot at kitware.com>
CommitDate: Thu Nov 15 08:38:12 2018 -0500
Merge topic 'autogen_info_write'
e0c26406aa Autogen: Sort tests
83bbfb1d53 Autogen: Add a definitions test to the MocOnly test
01d5e5c460 Autogen: Add and use cmQtAutoGenInitializer::InfoWriter class
Acked-by: Kitware Robot <kwrobot at kitware.com>
Merge-request: !2610
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=f21bad80a297e26b886f15f38f4d87cc5ce9687f
commit f21bad80a297e26b886f15f38f4d87cc5ce9687f
Merge: b3d1d6d ca355d9
Author: Brad King <brad.king at kitware.com>
AuthorDate: Thu Nov 15 13:37:22 2018 +0000
Commit: Kitware Robot <kwrobot at kitware.com>
CommitDate: Thu Nov 15 08:37:32 2018 -0500
Merge topic 'test-XcodeProject-timeout'
ca355d92d8 Tests: Add option for custom RunCMake.XcodeProject timeout
Acked-by: Kitware Robot <kwrobot at kitware.com>
Merge-request: !2614
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=b3d1d6d895355ee64c74cef1ab0040db02f81894
commit b3d1d6d895355ee64c74cef1ab0040db02f81894
Merge: bd2c17d a82282a
Author: Brad King <brad.king at kitware.com>
AuthorDate: Thu Nov 15 13:36:18 2018 +0000
Commit: Kitware Robot <kwrobot at kitware.com>
CommitDate: Thu Nov 15 08:36:52 2018 -0500
Merge topic 'doc-developer-to-source-guide'
a82282a08c Help/dev: Factor out a CMake Documentation Guide for developing the docs
bfbc5241e9 Help: Fix policy markup example in cmake-developer(7)
3e5a047f1a Help: Drop compile features section from cmake-developer(7) manual
06cc050c1f Help/dev: Drop 'size_t' preference from source code guide
Acked-by: Kitware Robot <kwrobot at kitware.com>
Merge-request: !2615
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=bd2c17d614e89b5786937565302c6fa54f121d22
commit bd2c17d614e89b5786937565302c6fa54f121d22
Merge: 44a5400 22cca9b
Author: Brad King <brad.king at kitware.com>
AuthorDate: Thu Nov 15 13:35:54 2018 +0000
Commit: Kitware Robot <kwrobot at kitware.com>
CommitDate: Thu Nov 15 08:36:02 2018 -0500
Merge topic 'macro3'
22cca9b810 Help: describe differences between macro and function.
b90ae70a3b Help: in macro vs function example, use lowercase names.
Acked-by: Kitware Robot <kwrobot at kitware.com>
Merge-request: !2616
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=22cca9b8100a59cd156e2ba39819171a0cf71881
commit 22cca9b8100a59cd156e2ba39819171a0cf71881
Author: Joachim Wuttke (l) <j.wuttke at fz-juelich.de>
AuthorDate: Wed Nov 14 20:50:59 2018 +0100
Commit: Joachim Wuttke (l) <j.wuttke at fz-juelich.de>
CommitDate: Wed Nov 14 21:56:23 2018 +0100
Help: describe differences between macro and function.
diff --git a/Help/command/function.rst b/Help/command/function.rst
index 7b10381..53ba754 100644
--- a/Help/command/function.rst
+++ b/Help/command/function.rst
@@ -23,6 +23,9 @@ details.
See the :command:`cmake_policy()` command documentation for the behavior
of policies inside functions.
+See the :command:`macro()` command documentation for differences
+between CMake functions and macros.
+
Invocation
^^^^^^^^^^
diff --git a/Help/command/macro.rst b/Help/command/macro.rst
index 7450929..42a99fc 100644
--- a/Help/command/macro.rst
+++ b/Help/command/macro.rst
@@ -21,6 +21,9 @@ argument of the opening ``macro`` command.
See the :command:`cmake_policy()` command documentation for the behavior
of policies inside macros.
+See the :ref:`Macro vs Function` section below for differences
+between CMake macros and :command:`functions <function>`.
+
Invocation
^^^^^^^^^^
@@ -65,13 +68,36 @@ behavior. Checking that ``${ARGC}`` is greater than ``#`` is the only
way to ensure that ``${ARGV#}`` was passed to the function as an extra
argument.
+.. _`Macro vs Function`:
+
+Macro vs Function
+^^^^^^^^^^^^^^^^^
+
+The ``macro`` command is very similar to the :command:`function` command.
+Nonetheless, there are a few important differences.
+
+In a function, ``ARGC``, ``ARGC`` and ``ARGV0``, ``ARGV1``, ... are
+true variables in the usual CMake sense. In a macro, they are not.
+They are string replacements much like the C preprocessor would do
+with a macro. This has a number of consequences, as explained in
+the :ref:`Argument Caveats` section below.
+
+Another difference between macros and functions is the control flow.
+A function is executed by transfering control from the calling
+statement to the function body. A macro is executed as if the macro
+body were pasted in place of the calling statement. This has for
+consequence that a :command:`return()` in a macro body does not
+just terminate execution of the macro; rather, control is returned
+from the scope of the macro call. To avoid confusion, it is recommended
+to avoid :command:`return()` in macros altogether.
+
+.. _`Argument Caveats`:
+
Argument Caveats
^^^^^^^^^^^^^^^^
-Note that the parameters to a macro and values such as ``ARGN`` are
-not variables in the usual CMake sense. They are string
-replacements much like the C preprocessor would do with a macro.
-Therefore you will NOT be able to use commands like
+Since ``ARGC``, ``ARGC``, ``ARGV0`` etc are not variables,
+you will NOT be able to use commands like
.. code-block:: cmake
@@ -80,12 +106,11 @@ Therefore you will NOT be able to use commands like
if(ARGC GREATER 2) # ARGC is not a variable
foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
-In the first case, you can use ``if(${ARGV1})``.
-In the second and third case, the proper way to check if an optional
-variable was passed to the macro is to use ``if(${ARGC} GREATER 2)``.
-In the last case, you can use ``foreach(loop_var ${ARGN})`` but this
-will skip empty arguments.
-If you need to include them, you can use
+In the first case, you can use ``if(${ARGV1})``. In the second and
+third case, the proper way to check if an optional variable was
+passed to the macro is to use ``if(${ARGC} GREATER 2)``. In the
+last case, you can use ``foreach(loop_var ${ARGN})`` but this will
+skip empty arguments. If you need to include them, you can use
.. code-block:: cmake
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=a82282a08c2ddf2eb3a89d61fbf53af1af3c4de9
commit a82282a08c2ddf2eb3a89d61fbf53af1af3c4de9
Author: Brad King <brad.king at kitware.com>
AuthorDate: Wed Nov 14 14:23:14 2018 -0500
Commit: Brad King <brad.king at kitware.com>
CommitDate: Wed Nov 14 14:38:13 2018 -0500
Help/dev: Factor out a CMake Documentation Guide for developing the docs
Remove this content from the `cmake-developer(7)` manual because it
is relevant only to developers working on CMake itself. Move it to
a guide in the developer documentation.
diff --git a/Help/dev/README.rst b/Help/dev/README.rst
index ce62abc..84da4f1 100644
--- a/Help/dev/README.rst
+++ b/Help/dev/README.rst
@@ -36,8 +36,10 @@ Developer Documentation
CMake developer documentation is provided by the following documents:
* The `CMake Source Code Guide`_.
+* The `CMake Documentation Guide`_.
.. _`CMake Source Code Guide`: source.rst
+.. _`CMake Documentation Guide`: documentation.rst
Maintainer Documentation
========================
diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst
new file mode 100644
index 0000000..1b2c942
--- /dev/null
+++ b/Help/dev/documentation.rst
@@ -0,0 +1,538 @@
+CMake Documentation Guide
+*************************
+
+The following is a guide to the CMake documentation source for developers.
+See documentation on `CMake Development`_ for more information.
+
+.. _`CMake Development`: README.rst
+
+Help
+====
+
+The ``Help`` directory contains CMake help manual source files.
+They are written using the `reStructuredText`_ markup syntax and
+processed by `Sphinx`_ to generate the CMake help manuals.
+
+.. _`reStructuredText`: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
+.. _`Sphinx`: http://sphinx-doc.org
+
+Markup Constructs
+-----------------
+
+In addition to using Sphinx to generate the CMake help manuals, we
+also use a C++-implemented document processor to print documents for
+the ``--help-*`` command-line help options. It supports a subset of
+reStructuredText markup. When authoring or modifying documents,
+please verify that the command-line help looks good in addition to the
+Sphinx-generated html and man pages.
+
+The command-line help processor supports the following constructs
+defined by reStructuredText, Sphinx, and a CMake extension to Sphinx.
+
+..
+ Note: This list must be kept consistent with the cmRST implementation.
+
+CMake Domain directives
+ Directives defined in the `CMake Domain`_ for defining CMake
+ documentation objects are printed in command-line help output as
+ if the lines were normal paragraph text with interpretation.
+
+CMake Domain interpreted text roles
+ Interpreted text roles defined in the `CMake Domain`_ for
+ cross-referencing CMake documentation objects are replaced by their
+ link text in command-line help output. Other roles are printed
+ literally and not processed.
+
+``code-block`` directive
+ Add a literal code block without interpretation. The command-line
+ help processor prints the block content without the leading directive
+ line and with common indentation replaced by one space.
+
+``include`` directive
+ Include another document source file. The command-line help
+ processor prints the included document inline with the referencing
+ document.
+
+literal block after ``::``
+ A paragraph ending in ``::`` followed by a blank line treats
+ the following indented block as literal text without interpretation.
+ The command-line help processor prints the ``::`` literally and
+ prints the block content with common indentation replaced by one
+ space.
+
+``note`` directive
+ Call out a side note. The command-line help processor prints the
+ block content as if the lines were normal paragraph text with
+ interpretation.
+
+``parsed-literal`` directive
+ Add a literal block with markup interpretation. The command-line
+ help processor prints the block content without the leading
+ directive line and with common indentation replaced by one space.
+
+``productionlist`` directive
+ Render context-free grammar productions. The command-line help
+ processor prints the block content as if the lines were normal
+ paragraph text with interpretation.
+
+``replace`` directive
+ Define a ``|substitution|`` replacement.
+ The command-line help processor requires a substitution replacement
+ to be defined before it is referenced.
+
+``|substitution|`` reference
+ Reference a substitution replacement previously defined by
+ the ``replace`` directive. The command-line help processor
+ performs the substitution and replaces all newlines in the
+ replacement text with spaces.
+
+``toctree`` directive
+ Include other document sources in the Table-of-Contents
+ document tree. The command-line help processor prints
+ the referenced documents inline as part of the referencing
+ document.
+
+Inline markup constructs not listed above are printed literally in the
+command-line help output. We prefer to use inline markup constructs that
+look correct in source form, so avoid use of \\-escapes in favor of inline
+literals when possible.
+
+Explicit markup blocks not matching directives listed above are removed from
+command-line help output. Do not use them, except for plain ``..`` comments
+that are removed by Sphinx too.
+
+Note that nested indentation of blocks is not recognized by the
+command-line help processor. Therefore:
+
+* Explicit markup blocks are recognized only when not indented
+ inside other blocks.
+
+* Literal blocks after paragraphs ending in ``::`` but not
+ at the top indentation level may consume all indented lines
+ following them.
+
+Try to avoid these cases in practice.
+
+CMake Domain
+------------
+
+CMake adds a `Sphinx Domain`_ called ``cmake``, also called the
+"CMake Domain". It defines several "object" types for CMake
+documentation:
+
+``command``
+ A CMake language command.
+
+``generator``
+ A CMake native build system generator.
+ See the `cmake(1)`_ command-line tool's ``-G`` option.
+
+``manual``
+ A CMake manual page, like the `cmake(1)`_ manual.
+
+``module``
+ A CMake module.
+ See the `cmake-modules(7)`_ manual
+ and the `include()`_ command.
+
+``policy``
+ A CMake policy.
+ See the `cmake-policies(7)`_ manual
+ and the `cmake_policy()`_ command.
+
+``prop_cache, prop_dir, prop_gbl, prop_sf, prop_inst, prop_test, prop_tgt``
+ A CMake cache, directory, global, source file, installed file, test,
+ or target property, respectively. See the `cmake-properties(7)`_
+ manual and the `set_property()`_ command.
+
+``variable``
+ A CMake language variable.
+ See the `cmake-variables(7)`_ manual
+ and the `set()`_ command.
+
+Documentation objects in the CMake Domain come from two sources.
+First, the CMake extension to Sphinx transforms every document named
+with the form ``Help/<type>/<file-name>.rst`` to a domain object with
+type ``<type>``. The object name is extracted from the document title,
+which is expected to be of the form::
+
+ <object-name>
+ -------------
+
+and to appear at or near the top of the ``.rst`` file before any other
+lines starting in a letter, digit, or ``<``. If no such title appears
+literally in the ``.rst`` file, the object name is the ``<file-name>``.
+If a title does appear, it is expected that ``<file-name>`` is equal
+to ``<object-name>`` with any ``<`` and ``>`` characters removed.
+
+Second, the CMake Domain provides directives to define objects inside
+other documents:
+
+.. code-block:: rst
+
+ .. command:: <command-name>
+
+ This indented block documents <command-name>.
+
+ .. variable:: <variable-name>
+
+ This indented block documents <variable-name>.
+
+Object types for which no directive is available must be defined using
+the first approach above.
+
+.. _`Sphinx Domain`: http://sphinx-doc.org/domains.html
+.. _`cmake(1)`: https://cmake.org/cmake/help/latest/manual/cmake.1.html
+.. _`cmake-modules(7)`: https://cmake.org/cmake/help/latest/manual/cmake-modules.7.html
+.. _`cmake-policies(7)`: https://cmake.org/cmake/help/latest/manual/cmake-policies.7.html
+.. _`cmake-properties(7)`: https://cmake.org/cmake/help/latest/manual/cmake-properties.7.html
+.. _`cmake-variables(7)`: https://cmake.org/cmake/help/latest/manual/cmake-variables.7.html
+.. _`cmake_policy()`: https://cmake.org/cmake/help/latest/command/cmake_policy.html
+.. _`include()`: https://cmake.org/cmake/help/latest/command/include.html
+.. _`set()`: https://cmake.org/cmake/help/latest/command/set.html
+.. _`set_property()`: https://cmake.org/cmake/help/latest/command/set_property.html
+
+Cross-References
+----------------
+
+Sphinx uses reStructuredText interpreted text roles to provide
+cross-reference syntax. The `CMake Domain`_ provides for each
+domain object type a role of the same name to cross-reference it.
+CMake Domain roles are inline markup of the forms::
+
+ :type:`name`
+ :type:`text <name>`
+
+where ``type`` is the domain object type and ``name`` is the
+domain object name. In the first form the link text will be
+``name`` (or ``name()`` if the type is ``command``) and in
+the second form the link text will be the explicit ``text``.
+For example, the code:
+
+.. code-block:: rst
+
+ * The :command:`list` command.
+ * The :command:`list(APPEND)` sub-command.
+ * The :command:`list() command <list>`.
+ * The :command:`list(APPEND) sub-command <list>`.
+ * The :variable:`CMAKE_VERSION` variable.
+ * The :prop_tgt:`OUTPUT_NAME_<CONFIG>` target property.
+
+produces:
+
+* The `list()`_ command.
+* The `list(APPEND)`_ sub-command.
+* The `list() command`_.
+* The `list(APPEND) sub-command`_.
+* The `CMAKE_VERSION`_ variable.
+* The `OUTPUT_NAME_<CONFIG>`_ target property.
+
+Note that CMake Domain roles differ from Sphinx and reStructuredText
+convention in that the form ``a<b>``, without a space preceding ``<``,
+is interpreted as a name instead of link text with an explicit target.
+This is necessary because we use ``<placeholders>`` frequently in
+object names like ``OUTPUT_NAME_<CONFIG>``. The form ``a <b>``,
+with a space preceding ``<``, is still interpreted as a link text
+with an explicit target.
+
+.. _`list()`: https://cmake.org/cmake/help/latest/command/list.html
+.. _`list(APPEND)`: https://cmake.org/cmake/help/latest/command/list.html
+.. _`list(APPEND) sub-command`: https://cmake.org/cmake/help/latest/command/list.html
+.. _`list() command`: https://cmake.org/cmake/help/latest/command/list.html
+.. _`CMAKE_VERSION`: https://cmake.org/cmake/help/latest/variable/CMAKE_VERSION.html
+.. _`OUTPUT_NAME_<CONFIG>`: https://cmake.org/cmake/help/latest/prop_tgt/OUTPUT_NAME_CONFIG.html
+
+Style
+-----
+
+Style: Section Headers
+^^^^^^^^^^^^^^^^^^^^^^
+
+When marking section titles, make the section decoration line as long as
+the title text. Use only a line below the title, not above. For
+example:
+
+.. code-block:: rst
+
+ Title Text
+ ----------
+
+Capitalize the first letter of each non-minor word in the title.
+
+The section header underline character hierarchy is
+
+* ``#``: Manual group (part) in the master document
+* ``*``: Manual (chapter) title
+* ``=``: Section within a manual
+* ``-``: Subsection or `CMake Domain`_ object document title
+* ``^``: Subsubsection or `CMake Domain`_ object document section
+* ``"``: Paragraph or `CMake Domain`_ object document subsection
+
+Style: Whitespace
+^^^^^^^^^^^^^^^^^
+
+Use two spaces for indentation. Use two spaces between sentences in
+prose.
+
+Style: Line Length
+^^^^^^^^^^^^^^^^^^
+
+Prefer to restrict the width of lines to 75-80 columns. This is not a
+hard restriction, but writing new paragraphs wrapped at 75 columns
+allows space for adding minor content without significant re-wrapping of
+content.
+
+Style: Prose
+^^^^^^^^^^^^
+
+Use American English spellings in prose.
+
+Style: Starting Literal Blocks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Prefer to mark the start of literal blocks with ``::`` at the end of
+the preceding paragraph. In cases where the following block gets
+a ``code-block`` marker, put a single ``:`` at the end of the preceding
+paragraph.
+
+Style: CMake Command Signatures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Command signatures should be marked up as plain literal blocks, not as
+cmake ``code-blocks``.
+
+Signatures are separated from preceding content by a section header.
+That is, use:
+
+.. code-block:: rst
+
+ ... preceding paragraph.
+
+ Normal Libraries
+ ^^^^^^^^^^^^^^^^
+
+ ::
+
+ add_library(<lib> ...)
+
+ This signature is used for ...
+
+Signatures of commands should wrap optional parts with square brackets,
+and should mark list of optional arguments with an ellipsis (``...``).
+Elements of the signature which are specified by the user should be
+specified with angle brackets, and may be referred to in prose using
+``inline-literal`` syntax.
+
+Style: Boolean Constants
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use "``OFF``" and "``ON``" for boolean values which can be modified by
+the user, such as ``POSITION_INDEPENDENT_CODE``. Such properties
+may be "enabled" and "disabled". Use "``True``" and "``False``" for
+inherent values which can't be modified after being set, such as the
+``IMPORTED`` property of a build target.
+
+Style: Inline Literals
+^^^^^^^^^^^^^^^^^^^^^^
+
+Mark up references to keywords in signatures, file names, and other
+technical terms with ``inline-literal`` syntax, for example:
+
+.. code-block:: rst
+
+ If ``WIN32`` is used with :command:`add_executable`, the
+ :prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command
+ creates the file ``<name>.exe`` on Windows.
+
+Style: Cross-References
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Mark up linkable references as links, including repeats.
+An alternative, which is used by wikipedia
+(`<http://en.wikipedia.org/wiki/WP:REPEATLINK>`_),
+is to link to a reference only once per article. That style is not used
+in CMake documentation.
+
+Style: Referencing CMake Concepts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If referring to a concept which corresponds to a property, and that
+concept is described in a high-level manual, prefer to link to the
+manual section instead of the property. For example:
+
+.. code-block:: rst
+
+ This command creates an :ref:`Imported Target <Imported Targets>`.
+
+instead of:
+
+.. code-block:: rst
+
+ This command creates an :prop_tgt:`IMPORTED` target.
+
+The latter should be used only when referring specifically to the
+property.
+
+References to manual sections are not automatically created by creating
+a section, but code such as:
+
+.. code-block:: rst
+
+ .. _`Imported Targets`:
+
+creates a suitable anchor. Use an anchor name which matches the name
+of the corresponding section. Refer to the anchor using a
+cross-reference with specified text.
+
+Imported Targets need the ``IMPORTED`` term marked up with care in
+particular because the term may refer to a command keyword, a target
+property, or a concept.
+
+Where a property, command or variable is related conceptually to others,
+by for example, being related to the buildsystem description, generator
+expressions or Qt, each relevant property, command or variable should
+link to the primary manual, which provides high-level information. Only
+particular information relating to the command should be in the
+documentation of the command.
+
+Style: Referencing CMake Domain Objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When referring to `CMake Domain`_ objects such as properties, variables,
+commands etc, prefer to link to the target object and follow that with
+the type of object it is. For example:
+
+.. code-block:: rst
+
+ Set the :prop_tgt:`AUTOMOC` target property to ``ON``.
+
+Instead of
+
+.. code-block:: rst
+
+ Set the target property :prop_tgt:`AUTOMOC` to ``ON``.
+
+The ``policy`` directive is an exception, and the type us usually
+referred to before the link:
+
+.. code-block:: rst
+
+ If policy :policy:`CMP0022` is set to ``NEW`` the behavior is ...
+
+However, markup self-references with ``inline-literal`` syntax.
+For example, within the ``add_executable`` command documentation, use
+
+.. code-block:: rst
+
+ ``add_executable``
+
+not
+
+.. code-block:: rst
+
+ :command:`add_executable`
+
+which is used elsewhere.
+
+Modules
+=======
+
+The ``Modules`` directory contains CMake-language ``.cmake`` module files.
+
+Module Documentation
+--------------------
+
+To document CMake module ``Modules/<module-name>.cmake``, modify
+``Help/manual/cmake-modules.7.rst`` to reference the module in the
+``toctree`` directive, in sorted order, as::
+
+ /module/<module-name>
+
+Then add the module document file ``Help/module/<module-name>.rst``
+containing just the line::
+
+ .. cmake-module:: ../../Modules/<module-name>.cmake
+
+The ``cmake-module`` directive will scan the module file to extract
+reStructuredText markup from comment blocks that start in ``.rst:``.
+At the top of ``Modules/<module-name>.cmake``, begin with the following
+license notice:
+
+.. code-block:: cmake
+
+ # Distributed under the OSI-approved BSD 3-Clause License. See accompanying
+ # file Copyright.txt or https://cmake.org/licensing for details.
+
+After this notice, add a *BLANK* line. Then, add documentation using
+a `Line Comment`_ block of the form:
+
+.. code-block:: cmake
+
+ #.rst:
+ # <module-name>
+ # -------------
+ #
+ # <reStructuredText documentation of module>
+
+or a `Bracket Comment`_ of the form:
+
+::
+
+ #[[.rst:
+ <module-name>
+ -------------
+
+ <reStructuredText documentation of module>
+ #]]
+
+Any number of ``=`` may be used in the opening and closing brackets
+as long as they match. Content on the line containing the closing
+bracket is excluded if and only if the line starts in ``#``.
+
+Additional such ``.rst:`` comments may appear anywhere in the module file.
+All such comments must start with ``#`` in the first column.
+
+For example, a ``Findxxx.cmake`` module may contain:
+
+::
+
+ # Distributed under the OSI-approved BSD 3-Clause License. See accompanying
+ # file Copyright.txt or https://cmake.org/licensing for details.
+
+ #.rst:
+ # FindXxx
+ # -------
+ #
+ # This is a cool module.
+ # This module does really cool stuff.
+ # It can do even more than you think.
+ #
+ # It even needs two paragraphs to tell you about it.
+ # And it defines the following variables:
+ #
+ # * VAR_COOL: this is great isn't it?
+ # * VAR_REALLY_COOL: cool right?
+
+ <code>
+
+ #[========================================[.rst:
+ .. command:: xxx_do_something
+
+ This command does something for Xxx::
+
+ xxx_do_something(some arguments)
+ #]========================================]
+ macro(xxx_do_something)
+ <code>
+ endmacro()
+
+Test the documentation formatting by running
+``cmake --help-module <module-name>``, and also by enabling the
+``SPHINX_HTML`` and ``SPHINX_MAN`` options to build the documentation.
+Edit the comments until generated documentation looks satisfactory. To
+have a .cmake file in this directory NOT show up in the modules
+documentation, simply leave out the ``Help/module/<module-name>.rst``
+file and the ``Help/manual/cmake-modules.7.rst`` toctree entry.
+
+.. _`Line Comment`: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#line-comment
+.. _`Bracket Comment`: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#bracket-comment
diff --git a/Help/dev/source.rst b/Help/dev/source.rst
index 4a1fdc8..6697d38 100644
--- a/Help/dev/source.rst
+++ b/Help/dev/source.rst
@@ -49,7 +49,7 @@ The CMake source tree is organized as follows.
Shell and editor integration files.
* ``Help/``:
- Documentation.
+ Documentation. See the `CMake Documentation Guide`_.
* ``Help/dev/``:
Developer documentation.
@@ -85,4 +85,5 @@ The CMake source tree is organized as follows.
* ``Utilities/Release/``:
Scripts used to package CMake itself for distribution on ``cmake.org``.
+.. _`CMake Documentation Guide`: documentation.rst
.. _`Tests/README.rst`: ../../Tests/README.rst
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index d0174b8..b949464 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -10,532 +10,20 @@ cmake-developer(7)
Introduction
============
-This manual is intended for reference by developers modifying the CMake
-source tree itself, and by those authoring externally-maintained modules.
+This manual is intended for reference by developers working with
+:manual:`cmake-language(7)` code, whether writing their own modules,
+authoring their own build systems, or working on CMake itself.
See https://cmake.org/get-involved/ to get involved in development of
-CMake upstream.
-
-Help
-====
-
-The ``Help`` directory contains CMake help manual source files.
-They are written using the `reStructuredText`_ markup syntax and
-processed by `Sphinx`_ to generate the CMake help manuals.
-
-.. _`reStructuredText`: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
-.. _`Sphinx`: http://sphinx-doc.org
-
-Markup Constructs
------------------
-
-In addition to using Sphinx to generate the CMake help manuals, we
-also use a C++-implemented document processor to print documents for
-the ``--help-*`` command-line help options. It supports a subset of
-reStructuredText markup. When authoring or modifying documents,
-please verify that the command-line help looks good in addition to the
-Sphinx-generated html and man pages.
-
-The command-line help processor supports the following constructs
-defined by reStructuredText, Sphinx, and a CMake extension to Sphinx.
-
-..
- Note: This list must be kept consistent with the cmRST implementation.
-
-CMake Domain directives
- Directives defined in the `CMake Domain`_ for defining CMake
- documentation objects are printed in command-line help output as
- if the lines were normal paragraph text with interpretation.
-
-CMake Domain interpreted text roles
- Interpreted text roles defined in the `CMake Domain`_ for
- cross-referencing CMake documentation objects are replaced by their
- link text in command-line help output. Other roles are printed
- literally and not processed.
-
-``code-block`` directive
- Add a literal code block without interpretation. The command-line
- help processor prints the block content without the leading directive
- line and with common indentation replaced by one space.
-
-``include`` directive
- Include another document source file. The command-line help
- processor prints the included document inline with the referencing
- document.
-
-literal block after ``::``
- A paragraph ending in ``::`` followed by a blank line treats
- the following indented block as literal text without interpretation.
- The command-line help processor prints the ``::`` literally and
- prints the block content with common indentation replaced by one
- space.
-
-``note`` directive
- Call out a side note. The command-line help processor prints the
- block content as if the lines were normal paragraph text with
- interpretation.
-
-``parsed-literal`` directive
- Add a literal block with markup interpretation. The command-line
- help processor prints the block content without the leading
- directive line and with common indentation replaced by one space.
-
-``productionlist`` directive
- Render context-free grammar productions. The command-line help
- processor prints the block content as if the lines were normal
- paragraph text with interpretation.
-
-``replace`` directive
- Define a ``|substitution|`` replacement.
- The command-line help processor requires a substitution replacement
- to be defined before it is referenced.
-
-``|substitution|`` reference
- Reference a substitution replacement previously defined by
- the ``replace`` directive. The command-line help processor
- performs the substitution and replaces all newlines in the
- replacement text with spaces.
-
-``toctree`` directive
- Include other document sources in the Table-of-Contents
- document tree. The command-line help processor prints
- the referenced documents inline as part of the referencing
- document.
-
-Inline markup constructs not listed above are printed literally in the
-command-line help output. We prefer to use inline markup constructs that
-look correct in source form, so avoid use of \\-escapes in favor of inline
-literals when possible.
-
-Explicit markup blocks not matching directives listed above are removed from
-command-line help output. Do not use them, except for plain ``..`` comments
-that are removed by Sphinx too.
-
-Note that nested indentation of blocks is not recognized by the
-command-line help processor. Therefore:
-
-* Explicit markup blocks are recognized only when not indented
- inside other blocks.
-
-* Literal blocks after paragraphs ending in ``::`` but not
- at the top indentation level may consume all indented lines
- following them.
-
-Try to avoid these cases in practice.
-
-CMake Domain
-------------
-
-CMake adds a `Sphinx Domain`_ called ``cmake``, also called the
-"CMake Domain". It defines several "object" types for CMake
-documentation:
-
-``command``
- A CMake language command.
-
-``generator``
- A CMake native build system generator.
- See the :manual:`cmake(1)` command-line tool's ``-G`` option.
-
-``manual``
- A CMake manual page, like this :manual:`cmake-developer(7)` manual.
-
-``module``
- A CMake module.
- See the :manual:`cmake-modules(7)` manual
- and the :command:`include` command.
-
-``policy``
- A CMake policy.
- See the :manual:`cmake-policies(7)` manual
- and the :command:`cmake_policy` command.
-
-``prop_cache, prop_dir, prop_gbl, prop_sf, prop_inst, prop_test, prop_tgt``
- A CMake cache, directory, global, source file, installed file, test,
- or target property, respectively. See the :manual:`cmake-properties(7)`
- manual and the :command:`set_property` command.
-
-``variable``
- A CMake language variable.
- See the :manual:`cmake-variables(7)` manual
- and the :command:`set` command.
-
-Documentation objects in the CMake Domain come from two sources.
-First, the CMake extension to Sphinx transforms every document named
-with the form ``Help/<type>/<file-name>.rst`` to a domain object with
-type ``<type>``. The object name is extracted from the document title,
-which is expected to be of the form::
-
- <object-name>
- -------------
-
-and to appear at or near the top of the ``.rst`` file before any other
-lines starting in a letter, digit, or ``<``. If no such title appears
-literally in the ``.rst`` file, the object name is the ``<file-name>``.
-If a title does appear, it is expected that ``<file-name>`` is equal
-to ``<object-name>`` with any ``<`` and ``>`` characters removed.
-
-Second, the CMake Domain provides directives to define objects inside
-other documents:
-
-.. code-block:: rst
-
- .. command:: <command-name>
-
- This indented block documents <command-name>.
-
- .. variable:: <variable-name>
-
- This indented block documents <variable-name>.
-
-Object types for which no directive is available must be defined using
-the first approach above.
-
-.. _`Sphinx Domain`: http://sphinx-doc.org/domains.html
-
-Cross-References
-----------------
-
-Sphinx uses reStructuredText interpreted text roles to provide
-cross-reference syntax. The `CMake Domain`_ provides for each
-domain object type a role of the same name to cross-reference it.
-CMake Domain roles are inline markup of the forms::
-
- :type:`name`
- :type:`text <name>`
-
-where ``type`` is the domain object type and ``name`` is the
-domain object name. In the first form the link text will be
-``name`` (or ``name()`` if the type is ``command``) and in
-the second form the link text will be the explicit ``text``.
-For example, the code:
-
-.. code-block:: rst
-
- * The :command:`list` command.
- * The :command:`list(APPEND)` sub-command.
- * The :command:`list() command <list>`.
- * The :command:`list(APPEND) sub-command <list>`.
- * The :variable:`CMAKE_VERSION` variable.
- * The :prop_tgt:`OUTPUT_NAME_<CONFIG>` target property.
-
-produces:
-
-* The :command:`list` command.
-* The :command:`list(APPEND)` sub-command.
-* The :command:`list() command <list>`.
-* The :command:`list(APPEND) sub-command <list>`.
-* The :variable:`CMAKE_VERSION` variable.
-* The :prop_tgt:`OUTPUT_NAME_<CONFIG>` target property.
-
-Note that CMake Domain roles differ from Sphinx and reStructuredText
-convention in that the form ``a<b>``, without a space preceding ``<``,
-is interpreted as a name instead of link text with an explicit target.
-This is necessary because we use ``<placeholders>`` frequently in
-object names like ``OUTPUT_NAME_<CONFIG>``. The form ``a <b>``,
-with a space preceding ``<``, is still interpreted as a link text
-with an explicit target.
-
-Style
------
-
-Style: Section Headers
-^^^^^^^^^^^^^^^^^^^^^^
-
-When marking section titles, make the section decoration line as long as
-the title text. Use only a line below the title, not above. For
-example:
-
-.. code-block:: rst
-
- Title Text
- ----------
-
-Capitalize the first letter of each non-minor word in the title.
-
-The section header underline character hierarchy is
-
-* ``#``: Manual group (part) in the master document
-* ``*``: Manual (chapter) title
-* ``=``: Section within a manual
-* ``-``: Subsection or `CMake Domain`_ object document title
-* ``^``: Subsubsection or `CMake Domain`_ object document section
-* ``"``: Paragraph or `CMake Domain`_ object document subsection
-
-Style: Whitespace
-^^^^^^^^^^^^^^^^^
-
-Use two spaces for indentation. Use two spaces between sentences in
-prose.
-
-Style: Line Length
-^^^^^^^^^^^^^^^^^^
-
-Prefer to restrict the width of lines to 75-80 columns. This is not a
-hard restriction, but writing new paragraphs wrapped at 75 columns
-allows space for adding minor content without significant re-wrapping of
-content.
-
-Style: Prose
-^^^^^^^^^^^^
-
-Use American English spellings in prose.
-
-Style: Starting Literal Blocks
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Prefer to mark the start of literal blocks with ``::`` at the end of
-the preceding paragraph. In cases where the following block gets
-a ``code-block`` marker, put a single ``:`` at the end of the preceding
-paragraph.
-
-Style: CMake Command Signatures
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Command signatures should be marked up as plain literal blocks, not as
-cmake ``code-blocks``.
-
-Signatures are separated from preceding content by a section header.
-That is, use:
-
-.. code-block:: rst
-
- ... preceding paragraph.
-
- Normal Libraries
- ^^^^^^^^^^^^^^^^
-
- ::
-
- add_library(<lib> ...)
-
- This signature is used for ...
-
-Signatures of commands should wrap optional parts with square brackets,
-and should mark list of optional arguments with an ellipsis (``...``).
-Elements of the signature which are specified by the user should be
-specified with angle brackets, and may be referred to in prose using
-``inline-literal`` syntax.
-
-Style: Boolean Constants
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Use "``OFF``" and "``ON``" for boolean values which can be modified by
-the user, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`. Such properties
-may be "enabled" and "disabled". Use "``True``" and "``False``" for
-inherent values which can't be modified after being set, such as the
-:prop_tgt:`IMPORTED` property of a build target.
-
-Style: Inline Literals
-^^^^^^^^^^^^^^^^^^^^^^
-
-Mark up references to keywords in signatures, file names, and other
-technical terms with ``inline-literal`` syntax, for example:
-
-.. code-block:: rst
-
- If ``WIN32`` is used with :command:`add_executable`, the
- :prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command
- creates the file ``<name>.exe`` on Windows.
-
-Style: Cross-References
-^^^^^^^^^^^^^^^^^^^^^^^
-
-Mark up linkable references as links, including repeats.
-An alternative, which is used by wikipedia
-(`<http://en.wikipedia.org/wiki/WP:REPEATLINK>`_),
-is to link to a reference only once per article. That style is not used
-in CMake documentation.
-
-Style: Referencing CMake Concepts
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If referring to a concept which corresponds to a property, and that
-concept is described in a high-level manual, prefer to link to the
-manual section instead of the property. For example:
-
-.. code-block:: rst
-
- This command creates an :ref:`Imported Target <Imported Targets>`.
-
-instead of:
-
-.. code-block:: rst
-
- This command creates an :prop_tgt:`IMPORTED` target.
-
-The latter should be used only when referring specifically to the
-property.
-
-References to manual sections are not automatically created by creating
-a section, but code such as:
-
-.. code-block:: rst
-
- .. _`Imported Targets`:
-
-creates a suitable anchor. Use an anchor name which matches the name
-of the corresponding section. Refer to the anchor using a
-cross-reference with specified text.
-
-Imported Targets need the ``IMPORTED`` term marked up with care in
-particular because the term may refer to a command keyword
-(``IMPORTED``), a target property (:prop_tgt:`IMPORTED`), or a
-concept (:ref:`Imported Targets`).
-
-Where a property, command or variable is related conceptually to others,
-by for example, being related to the buildsystem description, generator
-expressions or Qt, each relevant property, command or variable should
-link to the primary manual, which provides high-level information. Only
-particular information relating to the command should be in the
-documentation of the command.
-
-Style: Referencing CMake Domain Objects
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When referring to `CMake Domain`_ objects such as properties, variables,
-commands etc, prefer to link to the target object and follow that with
-the type of object it is. For example:
-
-.. code-block:: rst
-
- Set the :prop_tgt:`AUTOMOC` target property to ``ON``.
-
-Instead of
-
-.. code-block:: rst
-
- Set the target property :prop_tgt:`AUTOMOC` to ``ON``.
-
-The ``policy`` directive is an exception, and the type us usually
-referred to before the link:
-
-.. code-block:: rst
-
- If policy :policy:`CMP0022` is set to ``NEW`` the behavior is ...
-
-However, markup self-references with ``inline-literal`` syntax.
-For example, within the :command:`add_executable` command
-documentation, use
-
-.. code-block:: rst
-
- ``add_executable``
-
-not
-
-.. code-block:: rst
-
- :command:`add_executable`
-
-which is used elsewhere.
-
-Modules
-=======
-
-The ``Modules`` directory contains CMake-language ``.cmake`` module files.
-
-Module Documentation
---------------------
-
-To document CMake module ``Modules/<module-name>.cmake``, modify
-``Help/manual/cmake-modules.7.rst`` to reference the module in the
-``toctree`` directive, in sorted order, as::
-
- /module/<module-name>
-
-Then add the module document file ``Help/module/<module-name>.rst``
-containing just the line::
-
- .. cmake-module:: ../../Modules/<module-name>.cmake
-
-The ``cmake-module`` directive will scan the module file to extract
-reStructuredText markup from comment blocks that start in ``.rst:``.
-At the top of ``Modules/<module-name>.cmake``, begin with the following
-license notice:
-
-.. code-block:: cmake
-
- # Distributed under the OSI-approved BSD 3-Clause License. See accompanying
- # file Copyright.txt or https://cmake.org/licensing for details.
-
-After this notice, add a *BLANK* line. Then, add documentation using
-a :ref:`Line Comment` block of the form:
-
-.. code-block:: cmake
-
- #.rst:
- # <module-name>
- # -------------
- #
- # <reStructuredText documentation of module>
-
-or a :ref:`Bracket Comment` of the form:
-
-::
-
- #[[.rst:
- <module-name>
- -------------
-
- <reStructuredText documentation of module>
- #]]
-
-Any number of ``=`` may be used in the opening and closing brackets
-as long as they match. Content on the line containing the closing
-bracket is excluded if and only if the line starts in ``#``.
-
-Additional such ``.rst:`` comments may appear anywhere in the module file.
-All such comments must start with ``#`` in the first column.
-
-For example, a ``Modules/Findxxx.cmake`` module may contain:
-
-::
-
- # Distributed under the OSI-approved BSD 3-Clause License. See accompanying
- # file Copyright.txt or https://cmake.org/licensing for details.
-
- #.rst:
- # FindXxx
- # -------
- #
- # This is a cool module.
- # This module does really cool stuff.
- # It can do even more than you think.
- #
- # It even needs two paragraphs to tell you about it.
- # And it defines the following variables:
- #
- # * VAR_COOL: this is great isn't it?
- # * VAR_REALLY_COOL: cool right?
-
- <code>
-
- #[========================================[.rst:
- .. command:: xxx_do_something
-
- This command does something for Xxx::
-
- xxx_do_something(some arguments)
- #]========================================]
- macro(xxx_do_something)
- <code>
- endmacro()
-
-Test the documentation formatting by running
-``cmake --help-module <module-name>``, and also by enabling the
-``SPHINX_HTML`` and ``SPHINX_MAN`` options to build the documentation.
-Edit the comments until generated documentation looks satisfactory. To
-have a .cmake file in this directory NOT show up in the modules
-documentation, simply leave out the ``Help/module/<module-name>.rst``
-file and the ``Help/manual/cmake-modules.7.rst`` toctree entry.
+CMake upstream. It includes links to contribution instructions, which
+in turn link to developer guides for CMake itself.
.. _`Find Modules`:
Find Modules
-------------
+============
-A "find module" is a ``Modules/Find<PackageName>.cmake`` file to be loaded
+A "find module" is a ``Find<PackageName>.cmake`` file to be loaded
by the :command:`find_package` command when invoked for ``<PackageName>``.
The primary task of a find module is to determine whether a package
@@ -594,16 +82,11 @@ and required is up to the find module, but should be documented.
For internal implementation, it is a generally accepted convention that
variables starting with underscore are for temporary use only.
-Like all modules, find modules should be properly documented. To add a
-module to the CMake documentation, follow the steps in the `Module
-Documentation`_ section above.
-
-
.. _`CMake Developer Standard Variable Names`:
Standard Variable Names
-^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------
For a ``FindXxx.cmake`` module that takes the approach of setting
variables (either instead of or in addition to creating imported
@@ -710,9 +193,8 @@ Make sure you comment them as deprecated, so that no-one starts using
them.
-
A Sample Find Module
-^^^^^^^^^^^^^^^^^^^^
+--------------------
We will describe how to create a simple find module for a library
``Foo``.
@@ -755,8 +237,7 @@ variables and imported targets are set by the module, such as
# Foo::Foo - The Foo library
If the package provides any macros, they should be listed here, but can
-be documented where they are defined. See the `Module
-Documentation`_ section above for more details.
+be documented where they are defined.
Now the actual libraries and so on have to be found. The code here will
obviously vary from module to module (dealing with that, after all, is the
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=b90ae70a3b3c77109a31dfc275b778205a817d1a
commit b90ae70a3b3c77109a31dfc275b778205a817d1a
Author: Joachim Wuttke (l) <j.wuttke at fz-juelich.de>
AuthorDate: Wed Nov 14 09:10:31 2018 +0100
Commit: Joachim Wuttke (l) <j.wuttke at fz-juelich.de>
CommitDate: Wed Nov 14 20:33:12 2018 +0100
Help: in macro vs function example, use lowercase names.
Follow our own advise not to change cases.
Omit the leading underscore.
diff --git a/Help/command/macro.rst b/Help/command/macro.rst
index e15e206..7450929 100644
--- a/Help/command/macro.rst
+++ b/Help/command/macro.rst
@@ -98,18 +98,18 @@ existing variable instead of the arguments. For example:
.. code-block:: cmake
- macro(_BAR)
+ macro(bar)
foreach(arg IN LISTS ARGN)
<commands>
endforeach()
endmacro()
- function(_FOO)
- _bar(x y z)
+ function(foo)
+ bar(x y z)
endfunction()
- _foo(a b c)
+ foo(a b c)
-Will loop over ``a;b;c`` and not over ``x;y;z`` as one might be expecting.
+Will loop over ``a;b;c`` and not over ``x;y;z`` as one might have expected.
If you want true CMake variables and/or better CMake scope control you
should look at the function command.
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=bfbc5241e928203f934fd4fd83fa8beb35b0fe96
commit bfbc5241e928203f934fd4fd83fa8beb35b0fe96
Author: Brad King <brad.king at kitware.com>
AuthorDate: Wed Nov 14 09:55:20 2018 -0500
Commit: Brad King <brad.king at kitware.com>
CommitDate: Wed Nov 14 14:29:13 2018 -0500
Help: Fix policy markup example in cmake-developer(7)
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index b30b705..d0174b8 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -412,7 +412,7 @@ referred to before the link:
.. code-block:: rst
- If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ...
+ If policy :policy:`CMP0022` is set to ``NEW`` the behavior is ...
However, markup self-references with ``inline-literal`` syntax.
For example, within the :command:`add_executable` command
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=3e5a047f1aee1059d262b4096c5059ce2acad147
commit 3e5a047f1aee1059d262b4096c5059ce2acad147
Author: Brad King <brad.king at kitware.com>
AuthorDate: Wed Nov 14 09:33:41 2018 -0500
Commit: Brad King <brad.king at kitware.com>
CommitDate: Wed Nov 14 14:29:13 2018 -0500
Help: Drop compile features section from cmake-developer(7) manual
We no longer add granular compile features. Only language standard
meta features like `cxx_std_##`` need to be added, and these can
be done by following existing patterns.
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index c3bbf28..b30b705 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -16,53 +16,6 @@ source tree itself, and by those authoring externally-maintained modules.
See https://cmake.org/get-involved/ to get involved in development of
CMake upstream.
-Adding Compile Features
-=======================
-
-CMake reports an error if a compiler whose features are known does not report
-support for a particular requested feature. A compiler is considered to have
-known features if it reports support for at least one feature.
-
-When adding a new compile feature to CMake, it is therefore necessary to list
-support for the feature for all CompilerIds which already have one or more
-feature supported, if the new feature is available for any version of the
-compiler.
-
-When adding the first supported feature to a particular CompilerId, it is
-necessary to list support for all features known to cmake (See
-:variable:`CMAKE_C_COMPILE_FEATURES` and
-:variable:`CMAKE_CXX_COMPILE_FEATURES` as appropriate), where available for
-the compiler. Ensure that the ``CMAKE_<LANG>_STANDARD_DEFAULT`` is set to
-the computed internal variable ``CMAKE_<LANG>_STANDARD_COMPUTED_DEFAULT``
-for compiler versions which should be supported.
-
-It is sensible to record the features for the most recent version of a
-particular CompilerId first, and then work backwards. It is sensible to
-try to create a continuous range of versions of feature releases of the
-compiler. Gaps in the range indicate incorrect features recorded for
-intermediate releases.
-
-Generally, features are made available for a particular version if the
-compiler vendor documents availability of the feature with that
-version. Note that sometimes partially implemented features appear to
-be functional in previous releases (such as ``cxx_constexpr`` in GNU 4.6,
-though availability is documented in GNU 4.7), and sometimes compiler vendors
-document availability of features, though supporting infrastructure is
-not available (such as ``__has_feature(cxx_generic_lambdas)`` indicating
-non-availability in Clang 3.4, though it is documented as available, and
-fixed in Clang 3.5). Similar cases for other compilers and versions
-need to be investigated when extending CMake to support them.
-
-When a vendor releases a new version of a known compiler which supports
-a previously unsupported feature, and there are already known features for
-that compiler, the feature should be listed as supported in CMake for
-that version of the compiler as soon as reasonably possible.
-
-Standard-specific/compiler-specific variables such
-``CMAKE_CXX98_COMPILE_FEATURES`` are deliberately not documented. They
-only exist for the compiler-specific implementation of adding the ``-std``
-compile flag for compilers which need that.
-
Help
====
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=06cc050c1fa6141e5c376230ef7ab19ba2942a08
commit 06cc050c1fa6141e5c376230ef7ab19ba2942a08
Author: Brad King <brad.king at kitware.com>
AuthorDate: Wed Nov 14 09:28:34 2018 -0500
Commit: Brad King <brad.king at kitware.com>
CommitDate: Wed Nov 14 14:28:57 2018 -0500
Help/dev: Drop 'size_t' preference from source code guide
We now use `std::size_t` in several places and it is fully supported by
C++11 compilers. Drop the recommendation to prefer plain `size_t`.
diff --git a/Help/dev/source.rst b/Help/dev/source.rst
index 57de818..4a1fdc8 100644
--- a/Help/dev/source.rst
+++ b/Help/dev/source.rst
@@ -40,13 +40,6 @@ building on older toolchains some constructs need to be handled with care:
derived from non-copyable classes must also be made non-copyable explicitly
with ``CM_DISABLE_COPY``.
-* Use ``size_t`` instead of ``std::size_t``.
-
- Various implementations have differing implementation of ``size_t``.
- When assigning the result of ``.size()`` on a container for example,
- the result should be assigned to ``size_t`` not to ``std::size_t``,
- ``unsigned int`` or similar types.
-
Source Tree Layout
==================
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=e0c26406aa53b5dc4c942017eaf2410d0057aa9a
commit e0c26406aa53b5dc4c942017eaf2410d0057aa9a
Author: Sebastian Holtermann <sebholt at xwmw.org>
AuthorDate: Tue Nov 13 13:24:33 2018 +0100
Commit: Sebastian Holtermann <sebholt at xwmw.org>
CommitDate: Wed Nov 14 19:21:03 2018 +0100
Autogen: Sort tests
diff --git a/Tests/Qt4Autogen/CMakeLists.txt b/Tests/Qt4Autogen/CMakeLists.txt
index 818e888..68b885b 100644
--- a/Tests/Qt4Autogen/CMakeLists.txt
+++ b/Tests/Qt4Autogen/CMakeLists.txt
@@ -6,4 +6,4 @@ include("../QtAutogen/TestMacros.cmake")
ADD_AUTOGEN_TEST(DefinesTest)
# Common tests
-include("../QtAutogen/CommonTests.cmake")
+include("../QtAutogen/Tests.cmake")
diff --git a/Tests/Qt5Autogen/CMakeLists.txt b/Tests/Qt5Autogen/CMakeLists.txt
index 527e5ff..49d33cc 100644
--- a/Tests/Qt5Autogen/CMakeLists.txt
+++ b/Tests/Qt5Autogen/CMakeLists.txt
@@ -3,4 +3,4 @@ set(QT_TEST_VERSION 5)
include("../QtAutogen/TestMacros.cmake")
# Common tests
-include("../QtAutogen/CommonTests.cmake")
+include("../QtAutogen/Tests.cmake")
diff --git a/Tests/QtAutogen/CommonTests.cmake b/Tests/QtAutogen/Tests.cmake
similarity index 83%
rename from Tests/QtAutogen/CommonTests.cmake
rename to Tests/QtAutogen/Tests.cmake
index 1cd9e7e..5025d43 100644
--- a/Tests/QtAutogen/CommonTests.cmake
+++ b/Tests/QtAutogen/Tests.cmake
@@ -1,52 +1,46 @@
-# Autogen tests common for Qt4 and Qt5
+# Qt4 and Qt5 tests
+ADD_AUTOGEN_TEST(AutogenOriginDependsOff autogenOriginDependsOff)
+ADD_AUTOGEN_TEST(AutogenOriginDependsOn)
+ADD_AUTOGEN_TEST(AutogenTargetDepends)
ADD_AUTOGEN_TEST(Complex QtAutogen)
+ADD_AUTOGEN_TEST(GlobalAutogenTarget)
ADD_AUTOGEN_TEST(LowMinimumVersion lowMinimumVersion)
ADD_AUTOGEN_TEST(MocOnly mocOnly)
ADD_AUTOGEN_TEST(MocOptions mocOptions)
-ADD_AUTOGEN_TEST(UicOnly uicOnly)
-ADD_AUTOGEN_TEST(RccOnly rccOnly)
-ADD_AUTOGEN_TEST(RccEmpty rccEmpty)
-ADD_AUTOGEN_TEST(RccOffMocLibrary)
-ADD_AUTOGEN_TEST(GlobalAutogenTarget)
-if(QT_TEST_ALLOW_QT_MACROS)
- ADD_AUTOGEN_TEST(MocSkipSource)
-endif()
-ADD_AUTOGEN_TEST(UicSkipSource)
-ADD_AUTOGEN_TEST(RccSkipSource)
-if(QT_TEST_VERSION GREATER 4)
- ADD_AUTOGEN_TEST(MocMacroName mocMacroName)
-endif()
-ADD_AUTOGEN_TEST(AutogenOriginDependsOff autogenOriginDependsOff)
-ADD_AUTOGEN_TEST(AutogenOriginDependsOn)
-ADD_AUTOGEN_TEST(AutogenTargetDepends)
-if(QT_TEST_ALLOW_QT_MACROS)
- ADD_AUTOGEN_TEST(MocIncludeStrict mocIncludeStrict)
- ADD_AUTOGEN_TEST(MocIncludeRelaxed mocIncludeRelaxed)
-endif()
-if(QT_TEST_ALLOW_QT_MACROS)
- ADD_AUTOGEN_TEST(MocCMP0071)
-endif()
-if(QT_TEST_VERSION GREATER 4)
- ADD_AUTOGEN_TEST(MocOsMacros)
-endif()
-ADD_AUTOGEN_TEST(UicInclude uicInclude)
-ADD_AUTOGEN_TEST(UicInterface QtAutoUicInterface)
ADD_AUTOGEN_TEST(ObjectLibrary someProgram)
-if(APPLE AND (QT_TEST_VERSION GREATER 4))
- ADD_AUTOGEN_TEST(MacOsFW)
-endif()
ADD_AUTOGEN_TEST(Parallel parallel)
ADD_AUTOGEN_TEST(Parallel1 parallel1)
ADD_AUTOGEN_TEST(Parallel2 parallel2)
ADD_AUTOGEN_TEST(Parallel3 parallel3)
ADD_AUTOGEN_TEST(Parallel4 parallel4)
ADD_AUTOGEN_TEST(ParallelAUTO parallelAUTO)
+ADD_AUTOGEN_TEST(RccEmpty rccEmpty)
+ADD_AUTOGEN_TEST(RccOffMocLibrary)
+ADD_AUTOGEN_TEST(RccOnly rccOnly)
+ADD_AUTOGEN_TEST(RccSkipSource)
+ADD_AUTOGEN_TEST(RerunMocBasic)
+ADD_AUTOGEN_TEST(RerunRccConfigChange)
+ADD_AUTOGEN_TEST(RerunRccDepends)
ADD_AUTOGEN_TEST(SameName sameName)
ADD_AUTOGEN_TEST(StaticLibraryCycle slc)
-# Rerun tests
-ADD_AUTOGEN_TEST(RerunMocBasic)
+ADD_AUTOGEN_TEST(UicInclude uicInclude)
+ADD_AUTOGEN_TEST(UicInterface QtAutoUicInterface)
+ADD_AUTOGEN_TEST(UicOnly uicOnly)
+ADD_AUTOGEN_TEST(UicSkipSource)
+
+if(QT_TEST_ALLOW_QT_MACROS)
+ ADD_AUTOGEN_TEST(MocCMP0071)
+ ADD_AUTOGEN_TEST(MocIncludeRelaxed mocIncludeRelaxed)
+ ADD_AUTOGEN_TEST(MocIncludeStrict mocIncludeStrict)
+ ADD_AUTOGEN_TEST(MocSkipSource)
+endif()
+
+# Qt5 only tests
if(QT_TEST_VERSION GREATER 4)
+ ADD_AUTOGEN_TEST(MocMacroName mocMacroName)
+ ADD_AUTOGEN_TEST(MocOsMacros)
ADD_AUTOGEN_TEST(RerunMocPlugin)
+ if(APPLE)
+ ADD_AUTOGEN_TEST(MacOsFW)
+ endif()
endif()
-ADD_AUTOGEN_TEST(RerunRccDepends)
-ADD_AUTOGEN_TEST(RerunRccConfigChange)
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=83bbfb1d53077176af86d637f713652e3ee01198
commit 83bbfb1d53077176af86d637f713652e3ee01198
Author: Sebastian Holtermann <sebholt at xwmw.org>
AuthorDate: Tue Nov 13 13:05:09 2018 +0100
Commit: Sebastian Holtermann <sebholt at xwmw.org>
CommitDate: Wed Nov 14 19:21:03 2018 +0100
Autogen: Add a definitions test to the MocOnly test
diff --git a/Tests/QtAutogen/MocOnly/CMakeLists.txt b/Tests/QtAutogen/MocOnly/CMakeLists.txt
index a37a2ae..5377728 100644
--- a/Tests/QtAutogen/MocOnly/CMakeLists.txt
+++ b/Tests/QtAutogen/MocOnly/CMakeLists.txt
@@ -13,3 +13,5 @@ add_executable(mocOnly
)
set_property(TARGET mocOnly PROPERTY AUTOMOC ON)
target_link_libraries(mocOnly ${QT_LIBRARIES})
+# Add compile definitions with unusual characters
+target_compile_definitions(mocOnly PUBLIC "TOKEN=\"hello\;\"" )
diff --git a/Tests/QtAutogen/MocOnly/main.cpp b/Tests/QtAutogen/MocOnly/main.cpp
index 1611f97..b83b806 100644
--- a/Tests/QtAutogen/MocOnly/main.cpp
+++ b/Tests/QtAutogen/MocOnly/main.cpp
@@ -2,6 +2,7 @@
#include "IncB.hpp"
#include "StyleA.hpp"
#include "StyleB.hpp"
+#include <iostream>
int main(int argv, char** args)
{
@@ -10,5 +11,8 @@ int main(int argv, char** args)
IncA incA;
IncB incB;
- return 0;
+ // Test the TOKEN definition passed on the command line
+ std::string token(TOKEN);
+ std::cout << "std::string(TOKEN): \"" << token << "\"\n";
+ return (token == "hello;") ? 0 : -1;
}
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=01d5e5c460a2a9cb3962990f8ef278389254f30a
commit 01d5e5c460a2a9cb3962990f8ef278389254f30a
Author: Sebastian Holtermann <sebholt at xwmw.org>
AuthorDate: Tue Nov 13 11:47:15 2018 +0100
Commit: Sebastian Holtermann <sebholt at xwmw.org>
CommitDate: Wed Nov 14 19:21:03 2018 +0100
Autogen: Add and use cmQtAutoGenInitializer::InfoWriter class
The new ``cmQtAutoGenInitializer::InfoWriter`` class provides an
interface to write strings/vectors/sets/maps in CMake format
into a file. Its use replaces various `cmJoin` calls that
failed to address escaping of semicolons in list elements.
Closes #18554
diff --git a/Source/cmQtAutoGenInitializer.cxx b/Source/cmQtAutoGenInitializer.cxx
index 793c0b2..e71feac 100644
--- a/Source/cmQtAutoGenInitializer.cxx
+++ b/Source/cmQtAutoGenInitializer.cxx
@@ -9,7 +9,6 @@
#include "cmCustomCommandLines.h"
#include "cmDuration.h"
#include "cmFilePathChecksum.h"
-#include "cmGeneratedFileStream.h"
#include "cmGeneratorTarget.h"
#include "cmGlobalGenerator.h"
#include "cmLinkItem.h"
@@ -175,6 +174,103 @@ static bool StaticLibraryCycle(cmGeneratorTarget const* targetOrigin,
return cycle;
}
+cmQtAutoGenInitializer::InfoWriter::InfoWriter(std::string const& filename)
+{
+ Ofs_.SetCopyIfDifferent(true);
+ Ofs_.Open(filename, false, true);
+}
+
+template <class IT>
+std::string cmQtAutoGenInitializer::InfoWriter::ListJoin(IT it_begin,
+ IT it_end)
+{
+ std::string res;
+ for (IT it = it_begin; it != it_end; ++it) {
+ if (it != it_begin) {
+ res += ';';
+ }
+ for (const char* c = it->c_str(); *c; ++c) {
+ if (*c == '"') {
+ // Escape the double quote to avoid ending the argument.
+ res += "\\\"";
+ } else if (*c == '$') {
+ // Escape the dollar to avoid expanding variables.
+ res += "\\$";
+ } else if (*c == '\\') {
+ // Escape the backslash to avoid other escapes.
+ res += "\\\\";
+ } else if (*c == ';') {
+ // Escape the semicolon to avoid list expansion.
+ res += "\\;";
+ } else {
+ // Other characters will be parsed correctly.
+ res += *c;
+ }
+ }
+ }
+ return res;
+}
+
+std::string cmQtAutoGenInitializer::InfoWriter::ConfigKey(
+ const char* key, std::string const& config)
+{
+ std::string ckey = key;
+ ckey += '_';
+ ckey += config;
+ return ckey;
+}
+
+void cmQtAutoGenInitializer::InfoWriter::Write(const char* key,
+ std::string const& value)
+{
+ Ofs_ << "set(" << key << " " << cmOutputConverter::EscapeForCMake(value)
+ << ")\n";
+};
+
+void cmQtAutoGenInitializer::InfoWriter::WriteUInt(const char* key,
+ unsigned int value)
+{
+ Ofs_ << "set(" << key << " " << value << ")\n";
+};
+
+template <class C>
+void cmQtAutoGenInitializer::InfoWriter::WriteStrings(const char* key,
+ C const& container)
+{
+ Ofs_ << "set(" << key << " \""
+ << ListJoin(container.begin(), container.end()) << "\")\n";
+}
+
+void cmQtAutoGenInitializer::InfoWriter::WriteConfig(
+ const char* key, std::map<std::string, std::string> const& map)
+{
+ for (auto const& item : map) {
+ Write(ConfigKey(key, item.first).c_str(), item.second);
+ }
+};
+
+template <class C>
+void cmQtAutoGenInitializer::InfoWriter::WriteConfigStrings(
+ const char* key, std::map<std::string, C> const& map)
+{
+ for (auto const& item : map) {
+ WriteStrings(ConfigKey(key, item.first).c_str(), item.second);
+ }
+}
+
+void cmQtAutoGenInitializer::InfoWriter::WriteNestedLists(
+ const char* key, std::vector<std::vector<std::string>> const& lists)
+{
+ std::vector<std::string> seplist;
+ for (const std::vector<std::string>& list : lists) {
+ std::string blist = "{";
+ blist += ListJoin(list.begin(), list.end());
+ blist += "}";
+ seplist.push_back(std::move(blist));
+ }
+ Write(key, cmJoin(seplist, cmQtAutoGen::ListSep));
+};
+
cmQtAutoGenInitializer::cmQtAutoGenInitializer(
cmQtAutoGenGlobalInitializer* globalInitializer, cmGeneratorTarget* target,
IntegerVersion const& qtVersion, bool mocEnabled, bool uicEnabled,
@@ -395,14 +491,15 @@ bool cmQtAutoGenInitializer::InitMoc()
{
bool const appendImplicit = (this->QtVersion.Major == 5);
auto GetIncludeDirs =
- [this, localGen, appendImplicit](std::string const& cfg) -> std::string {
+ [this, localGen,
+ appendImplicit](std::string const& cfg) -> std::vector<std::string> {
// Get the include dirs for this target, without stripping the implicit
// include dirs off, see
// https://gitlab.kitware.com/cmake/cmake/issues/13667
std::vector<std::string> dirs;
localGen->GetIncludeDirectories(dirs, this->Target, "CXX", cfg, false,
appendImplicit);
- return cmJoin(dirs, ";");
+ return dirs;
};
// Default configuration include directories
@@ -410,7 +507,7 @@ bool cmQtAutoGenInitializer::InitMoc()
// Other configuration settings
if (this->MultiConfig) {
for (std::string const& cfg : this->ConfigsList) {
- std::string dirs = GetIncludeDirs(cfg);
+ std::vector<std::string> dirs = GetIncludeDirs(cfg);
if (dirs != this->Moc.Includes) {
this->Moc.ConfigIncludes[cfg] = std::move(dirs);
}
@@ -421,10 +518,10 @@ bool cmQtAutoGenInitializer::InitMoc()
// Moc compile definitions
{
auto GetCompileDefinitions =
- [this, localGen](std::string const& cfg) -> std::string {
+ [this, localGen](std::string const& cfg) -> std::set<std::string> {
std::set<std::string> defines;
localGen->GetTargetDefines(this->Target, cfg, "CXX", defines);
- return cmJoin(defines, ";");
+ return defines;
};
// Default configuration defines
@@ -432,7 +529,7 @@ bool cmQtAutoGenInitializer::InitMoc()
// Other configuration defines
if (this->MultiConfig) {
for (std::string const& cfg : this->ConfigsList) {
- std::string defines = GetCompileDefinitions(cfg);
+ std::set<std::string> defines = GetCompileDefinitions(cfg);
if (defines != this->Moc.Defines) {
this->Moc.ConfigDefines[cfg] = std::move(defines);
}
@@ -466,10 +563,11 @@ bool cmQtAutoGenInitializer::InitUic()
}
// Uic target options
{
- auto UicGetOpts = [this](std::string const& cfg) -> std::string {
+ auto UicGetOpts =
+ [this](std::string const& cfg) -> std::vector<std::string> {
std::vector<std::string> opts;
this->Target->GetAutoUicOptions(opts, cfg);
- return cmJoin(opts, ";");
+ return opts;
};
// Default settings
@@ -478,7 +576,7 @@ bool cmQtAutoGenInitializer::InitUic()
// Configuration specific settings
if (this->MultiConfig) {
for (std::string const& cfg : this->ConfigsList) {
- std::string options = UicGetOpts(cfg);
+ std::vector<std::string> options = UicGetOpts(cfg);
if (options != this->Uic.Options) {
this->Uic.ConfigOptions[cfg] = std::move(options);
}
@@ -1108,104 +1206,72 @@ bool cmQtAutoGenInitializer::SetupCustomTargets()
bool cmQtAutoGenInitializer::SetupWriteAutogenInfo()
{
- cmMakefile* makefile = this->Target->Target->GetMakefile();
-
- cmGeneratedFileStream ofs;
- ofs.SetCopyIfDifferent(true);
- ofs.Open(this->AutogenTarget.InfoFile, false, true);
+ InfoWriter ofs(this->AutogenTarget.InfoFile);
if (ofs) {
// Utility lambdas
- auto CWrite = [&ofs](const char* key, std::string const& value) {
- ofs << "set(" << key << " " << cmOutputConverter::EscapeForCMake(value)
- << ")\n";
- };
- auto CWriteUInt = [&ofs](const char* key, unsigned int value) {
- ofs << "set(" << key << " " << value << ")\n";
- };
- auto CWriteList = [&CWrite](const char* key,
- std::vector<std::string> const& list) {
- CWrite(key, cmJoin(list, ";"));
- };
- auto CWriteNestedLists =
- [&CWrite](const char* key,
- std::vector<std::vector<std::string>> const& lists) {
- std::vector<std::string> seplist;
- for (const std::vector<std::string>& list : lists) {
- std::string blist = "{";
- blist += cmJoin(list, ";");
- blist += "}";
- seplist.push_back(std::move(blist));
- }
- CWrite(key, cmJoin(seplist, cmQtAutoGen::ListSep));
- };
- auto CWriteSet = [&CWrite](const char* key,
- std::set<std::string> const& list) {
- CWrite(key, cmJoin(list, ";"));
- };
- auto CWriteMap = [&ofs](const char* key,
- std::map<std::string, std::string> const& map) {
- for (auto const& item : map) {
- ofs << "set(" << key << "_" << item.first << " "
- << cmOutputConverter::EscapeForCMake(item.second) << ")\n";
- }
- };
+ cmMakefile* makefile = this->Target->Target->GetMakefile();
auto MfDef = [makefile](const char* key) {
return makefile->GetSafeDefinition(key);
};
- // Write
- ofs << "# Meta\n";
- CWrite("AM_MULTI_CONFIG", this->MultiConfig ? "TRUE" : "FALSE");
- CWrite("AM_PARALLEL", this->AutogenTarget.Parallel);
- CWrite("AM_VERBOSITY", this->Verbosity);
-
- ofs << "# Directories\n";
- CWrite("AM_CMAKE_SOURCE_DIR", MfDef("CMAKE_SOURCE_DIR"));
- CWrite("AM_CMAKE_BINARY_DIR", MfDef("CMAKE_BINARY_DIR"));
- CWrite("AM_CMAKE_CURRENT_SOURCE_DIR", MfDef("CMAKE_CURRENT_SOURCE_DIR"));
- CWrite("AM_CMAKE_CURRENT_BINARY_DIR", MfDef("CMAKE_CURRENT_BINARY_DIR"));
- CWrite("AM_CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE",
- MfDef("CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE"));
- CWrite("AM_BUILD_DIR", this->Dir.Build);
- CWrite("AM_INCLUDE_DIR", this->Dir.Include);
- CWriteMap("AM_INCLUDE_DIR", this->Dir.ConfigInclude);
-
- ofs << "# Files\n";
- CWriteList("AM_SOURCES", this->AutogenTarget.Sources);
- CWriteList("AM_HEADERS", this->AutogenTarget.Headers);
- CWrite("AM_SETTINGS_FILE", this->AutogenTarget.SettingsFile);
- CWriteMap("AM_SETTINGS_FILE", this->AutogenTarget.ConfigSettingsFile);
-
- ofs << "# Qt\n";
- CWriteUInt("AM_QT_VERSION_MAJOR", this->QtVersion.Major);
- CWrite("AM_QT_MOC_EXECUTABLE", this->Moc.Executable);
- CWrite("AM_QT_UIC_EXECUTABLE", this->Uic.Executable);
-
+ // Write common settings
+ ofs.Write("# Meta\n");
+ ofs.Write("AM_MULTI_CONFIG", this->MultiConfig ? "TRUE" : "FALSE");
+ ofs.Write("AM_PARALLEL", this->AutogenTarget.Parallel);
+ ofs.Write("AM_VERBOSITY", this->Verbosity);
+
+ ofs.Write("# Directories\n");
+ ofs.Write("AM_CMAKE_SOURCE_DIR", MfDef("CMAKE_SOURCE_DIR"));
+ ofs.Write("AM_CMAKE_BINARY_DIR", MfDef("CMAKE_BINARY_DIR"));
+ ofs.Write("AM_CMAKE_CURRENT_SOURCE_DIR",
+ MfDef("CMAKE_CURRENT_SOURCE_DIR"));
+ ofs.Write("AM_CMAKE_CURRENT_BINARY_DIR",
+ MfDef("CMAKE_CURRENT_BINARY_DIR"));
+ ofs.Write("AM_CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE",
+ MfDef("CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE"));
+ ofs.Write("AM_BUILD_DIR", this->Dir.Build);
+ ofs.Write("AM_INCLUDE_DIR", this->Dir.Include);
+ ofs.WriteConfig("AM_INCLUDE_DIR", this->Dir.ConfigInclude);
+
+ ofs.Write("# Files\n");
+ ofs.WriteStrings("AM_SOURCES", this->AutogenTarget.Sources);
+ ofs.WriteStrings("AM_HEADERS", this->AutogenTarget.Headers);
+ ofs.Write("AM_SETTINGS_FILE", this->AutogenTarget.SettingsFile);
+ ofs.WriteConfig("AM_SETTINGS_FILE",
+ this->AutogenTarget.ConfigSettingsFile);
+
+ ofs.Write("# Qt\n");
+ ofs.WriteUInt("AM_QT_VERSION_MAJOR", this->QtVersion.Major);
+ ofs.Write("AM_QT_MOC_EXECUTABLE", this->Moc.Executable);
+ ofs.Write("AM_QT_UIC_EXECUTABLE", this->Uic.Executable);
+
+ // Write moc settings
if (this->Moc.Enabled) {
- ofs << "# MOC settings\n";
- CWriteSet("AM_MOC_SKIP", this->Moc.Skip);
- CWrite("AM_MOC_DEFINITIONS", this->Moc.Defines);
- CWriteMap("AM_MOC_DEFINITIONS", this->Moc.ConfigDefines);
- CWrite("AM_MOC_INCLUDES", this->Moc.Includes);
- CWriteMap("AM_MOC_INCLUDES", this->Moc.ConfigIncludes);
- CWrite("AM_MOC_OPTIONS",
- this->Target->GetSafeProperty("AUTOMOC_MOC_OPTIONS"));
- CWrite("AM_MOC_RELAXED_MODE", MfDef("CMAKE_AUTOMOC_RELAXED_MODE"));
- CWrite("AM_MOC_MACRO_NAMES",
- this->Target->GetSafeProperty("AUTOMOC_MACRO_NAMES"));
- CWrite("AM_MOC_DEPEND_FILTERS",
- this->Target->GetSafeProperty("AUTOMOC_DEPEND_FILTERS"));
- CWrite("AM_MOC_PREDEFS_CMD", this->Moc.PredefsCmd);
- }
-
+ ofs.Write("# MOC settings\n");
+ ofs.WriteStrings("AM_MOC_SKIP", this->Moc.Skip);
+ ofs.WriteStrings("AM_MOC_DEFINITIONS", this->Moc.Defines);
+ ofs.WriteConfigStrings("AM_MOC_DEFINITIONS", this->Moc.ConfigDefines);
+ ofs.WriteStrings("AM_MOC_INCLUDES", this->Moc.Includes);
+ ofs.WriteConfigStrings("AM_MOC_INCLUDES", this->Moc.ConfigIncludes);
+ ofs.Write("AM_MOC_OPTIONS",
+ this->Target->GetSafeProperty("AUTOMOC_MOC_OPTIONS"));
+ ofs.Write("AM_MOC_RELAXED_MODE", MfDef("CMAKE_AUTOMOC_RELAXED_MODE"));
+ ofs.Write("AM_MOC_MACRO_NAMES",
+ this->Target->GetSafeProperty("AUTOMOC_MACRO_NAMES"));
+ ofs.Write("AM_MOC_DEPEND_FILTERS",
+ this->Target->GetSafeProperty("AUTOMOC_DEPEND_FILTERS"));
+ ofs.Write("AM_MOC_PREDEFS_CMD", this->Moc.PredefsCmd);
+ }
+
+ // Write uic settings
if (this->Uic.Enabled) {
- ofs << "# UIC settings\n";
- CWriteSet("AM_UIC_SKIP", this->Uic.Skip);
- CWrite("AM_UIC_TARGET_OPTIONS", this->Uic.Options);
- CWriteMap("AM_UIC_TARGET_OPTIONS", this->Uic.ConfigOptions);
- CWriteList("AM_UIC_OPTIONS_FILES", this->Uic.FileFiles);
- CWriteNestedLists("AM_UIC_OPTIONS_OPTIONS", this->Uic.FileOptions);
- CWriteList("AM_UIC_SEARCH_PATHS", this->Uic.SearchPaths);
+ ofs.Write("# UIC settings\n");
+ ofs.WriteStrings("AM_UIC_SKIP", this->Uic.Skip);
+ ofs.WriteStrings("AM_UIC_TARGET_OPTIONS", this->Uic.Options);
+ ofs.WriteConfigStrings("AM_UIC_TARGET_OPTIONS", this->Uic.ConfigOptions);
+ ofs.WriteStrings("AM_UIC_OPTIONS_FILES", this->Uic.FileFiles);
+ ofs.WriteNestedLists("AM_UIC_OPTIONS_OPTIONS", this->Uic.FileOptions);
+ ofs.WriteStrings("AM_UIC_SEARCH_PATHS", this->Uic.SearchPaths);
}
} else {
std::string err = "AutoGen: Could not write file ";
@@ -1220,47 +1286,33 @@ bool cmQtAutoGenInitializer::SetupWriteAutogenInfo()
bool cmQtAutoGenInitializer::SetupWriteRccInfo()
{
for (Qrc const& qrc : this->Rcc.Qrcs) {
- cmGeneratedFileStream ofs;
- ofs.SetCopyIfDifferent(true);
- ofs.Open(qrc.InfoFile, false, true);
+ InfoWriter ofs(qrc.InfoFile);
if (ofs) {
- // Utility lambdas
- auto CWrite = [&ofs](const char* key, std::string const& value) {
- ofs << "set(" << key << " " << cmOutputConverter::EscapeForCMake(value)
- << ")\n";
- };
- auto CWriteMap = [&ofs](const char* key,
- std::map<std::string, std::string> const& map) {
- for (auto const& item : map) {
- ofs << "set(" << key << "_" << item.first << " "
- << cmOutputConverter::EscapeForCMake(item.second) << ")\n";
- }
- };
-
// Write
- ofs << "# Configurations\n";
- CWrite("ARCC_MULTI_CONFIG", this->MultiConfig ? "TRUE" : "FALSE");
- CWrite("ARCC_VERBOSITY", this->Verbosity);
- ofs << "# Settings file\n";
- CWrite("ARCC_SETTINGS_FILE", qrc.SettingsFile);
- CWriteMap("ARCC_SETTINGS_FILE", qrc.ConfigSettingsFile);
-
- ofs << "# Directories\n";
- CWrite("ARCC_BUILD_DIR", this->Dir.Build);
- CWrite("ARCC_INCLUDE_DIR", this->Dir.Include);
- CWriteMap("ARCC_INCLUDE_DIR", this->Dir.ConfigInclude);
-
- ofs << "# Rcc executable\n";
- CWrite("ARCC_RCC_EXECUTABLE", this->Rcc.Executable);
- CWrite("ARCC_RCC_LIST_OPTIONS", cmJoin(this->Rcc.ListOptions, ";"));
-
- ofs << "# Rcc job\n";
- CWrite("ARCC_LOCK_FILE", qrc.LockFile);
- CWrite("ARCC_SOURCE", qrc.QrcFile);
- CWrite("ARCC_OUTPUT_CHECKSUM", qrc.PathChecksum);
- CWrite("ARCC_OUTPUT_NAME", cmSystemTools::GetFilenameName(qrc.RccFile));
- CWrite("ARCC_OPTIONS", cmJoin(qrc.Options, ";"));
- CWrite("ARCC_INPUTS", cmJoin(qrc.Resources, ";"));
+ ofs.Write("# Configurations\n");
+ ofs.Write("ARCC_MULTI_CONFIG", this->MultiConfig ? "TRUE" : "FALSE");
+ ofs.Write("ARCC_VERBOSITY", this->Verbosity);
+ ofs.Write("# Settings file\n");
+ ofs.Write("ARCC_SETTINGS_FILE", qrc.SettingsFile);
+ ofs.WriteConfig("ARCC_SETTINGS_FILE", qrc.ConfigSettingsFile);
+
+ ofs.Write("# Directories\n");
+ ofs.Write("ARCC_BUILD_DIR", this->Dir.Build);
+ ofs.Write("ARCC_INCLUDE_DIR", this->Dir.Include);
+ ofs.WriteConfig("ARCC_INCLUDE_DIR", this->Dir.ConfigInclude);
+
+ ofs.Write("# Rcc executable\n");
+ ofs.Write("ARCC_RCC_EXECUTABLE", this->Rcc.Executable);
+ ofs.WriteStrings("ARCC_RCC_LIST_OPTIONS", this->Rcc.ListOptions);
+
+ ofs.Write("# Rcc job\n");
+ ofs.Write("ARCC_LOCK_FILE", qrc.LockFile);
+ ofs.Write("ARCC_SOURCE", qrc.QrcFile);
+ ofs.Write("ARCC_OUTPUT_CHECKSUM", qrc.PathChecksum);
+ ofs.Write("ARCC_OUTPUT_NAME",
+ cmSystemTools::GetFilenameName(qrc.RccFile));
+ ofs.WriteStrings("ARCC_OPTIONS", qrc.Options);
+ ofs.WriteStrings("ARCC_INPUTS", qrc.Resources);
} else {
std::string err = "AutoRcc: Could not write file ";
err += qrc.InfoFile;
diff --git a/Source/cmQtAutoGenInitializer.h b/Source/cmQtAutoGenInitializer.h
index 53ad571..903ec85 100644
--- a/Source/cmQtAutoGenInitializer.h
+++ b/Source/cmQtAutoGenInitializer.h
@@ -4,9 +4,11 @@
#define cmQtAutoGenInitializer_h
#include "cmConfigure.h" // IWYU pragma: keep
+#include "cmGeneratedFileStream.h"
#include "cmQtAutoGen.h"
#include <map>
+#include <ostream>
#include <set>
#include <string>
#include <vector>
@@ -44,6 +46,39 @@ public:
std::vector<std::string> Resources;
};
+ /// @brief Writes a CMake info file
+ class InfoWriter
+ {
+ public:
+ /// @brief Open the given file
+ InfoWriter(std::string const& filename);
+
+ /// @return True if the file is open
+ operator bool() const { return static_cast<bool>(Ofs_); }
+
+ void Write(const char* text) { Ofs_ << text; }
+ void Write(const char* key, std::string const& value);
+ void WriteUInt(const char* key, unsigned int value);
+
+ template <class C>
+ void WriteStrings(const char* key, C const& container);
+ void WriteConfig(const char* key,
+ std::map<std::string, std::string> const& map);
+ template <class C>
+ void WriteConfigStrings(const char* key,
+ std::map<std::string, C> const& map);
+ void WriteNestedLists(const char* key,
+ std::vector<std::vector<std::string>> const& lists);
+
+ private:
+ template <class IT>
+ static std::string ListJoin(IT it_begin, IT it_end);
+ static std::string ConfigKey(const char* key, std::string const& config);
+
+ private:
+ cmGeneratedFileStream Ofs_;
+ };
+
public:
static IntegerVersion GetQtVersion(cmGeneratorTarget const* target);
@@ -129,10 +164,10 @@ private:
std::string Executable;
std::string PredefsCmd;
std::set<std::string> Skip;
- std::string Includes;
- std::map<std::string, std::string> ConfigIncludes;
- std::string Defines;
- std::map<std::string, std::string> ConfigDefines;
+ std::vector<std::string> Includes;
+ std::map<std::string, std::vector<std::string>> ConfigIncludes;
+ std::set<std::string> Defines;
+ std::map<std::string, std::set<std::string>> ConfigDefines;
std::string MocsCompilation;
} Moc;
@@ -143,8 +178,8 @@ private:
std::string Executable;
std::set<std::string> Skip;
std::vector<std::string> SearchPaths;
- std::string Options;
- std::map<std::string, std::string> ConfigOptions;
+ std::vector<std::string> Options;
+ std::map<std::string, std::vector<std::string>> ConfigOptions;
std::vector<std::string> FileFiles;
std::vector<std::vector<std::string>> FileOptions;
} Uic;
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=ca355d92d827a26d626a241535fe710600eead0d
commit ca355d92d827a26d626a241535fe710600eead0d
Author: Brad King <brad.king at kitware.com>
AuthorDate: Wed Nov 14 11:50:36 2018 -0500
Commit: Brad King <brad.king at kitware.com>
CommitDate: Wed Nov 14 11:50:36 2018 -0500
Tests: Add option for custom RunCMake.XcodeProject timeout
The test has many cases and can take a long time on busy machines.
diff --git a/Tests/RunCMake/CMakeLists.txt b/Tests/RunCMake/CMakeLists.txt
index b6b6519..2df15ee 100644
--- a/Tests/RunCMake/CMakeLists.txt
+++ b/Tests/RunCMake/CMakeLists.txt
@@ -335,6 +335,13 @@ endif()
if(XCODE_VERSION)
add_RunCMake_test(XcodeProject -DXCODE_VERSION=${XCODE_VERSION})
+
+ # This test can take a very long time due to lots of combinations.
+ # Use a long default timeout and provide an option to customize it.
+ if(NOT DEFINED CMake_TEST_XcodeProject_TIMEOUT)
+ set(CMake_TEST_XcodeProject_TIMEOUT 2000)
+ endif()
+ set_property(TEST RunCMake.XcodeProject PROPERTY TIMEOUT ${CMake_TEST_XcodeProject_TIMEOUT})
endif()
if(CMAKE_C_COMPILER_ID STREQUAL "AppleClang"
-----------------------------------------------------------------------
Summary of changes:
Help/command/function.rst | 3 +
Help/command/macro.rst | 55 +-
Help/dev/README.rst | 2 +
Help/dev/documentation.rst | 538 +++++++++++++++++++
Help/dev/source.rst | 10 +-
Help/manual/cmake-developer.7.rst | 586 +--------------------
Source/cmQtAutoGenInitializer.cxx | 330 +++++++-----
Source/cmQtAutoGenInitializer.h | 47 +-
Tests/Qt4Autogen/CMakeLists.txt | 2 +-
Tests/Qt5Autogen/CMakeLists.txt | 2 +-
Tests/QtAutogen/MocOnly/CMakeLists.txt | 2 +
Tests/QtAutogen/MocOnly/main.cpp | 6 +-
Tests/QtAutogen/{CommonTests.cmake => Tests.cmake} | 66 ++-
Tests/RunCMake/CMakeLists.txt | 7 +
14 files changed, 873 insertions(+), 783 deletions(-)
create mode 100644 Help/dev/documentation.rst
rename Tests/QtAutogen/{CommonTests.cmake => Tests.cmake} (83%)
hooks/post-receive
--
CMake
More information about the Cmake-commits
mailing list