[Cmake-commits] CMake branch, next, updated. v2.8.12.2-7476-g8395352
Stephen Kelly
steveire at gmail.com
Thu Feb 6 13:10:00 EST 2014
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, next has been updated
via 8395352b939899f7340683f551170d6a8e0e2fd0 (commit)
via 257ee81b00176e9c8bb18ce42313a9075b8a7b60 (commit)
via cc2b13a6b994953c8b1d66e82a90c2c3f6927923 (commit)
from ff39b3d5b4230cb898e24efde73463889aae5534 (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 -----------------------------------------------------------------
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=8395352b939899f7340683f551170d6a8e0e2fd0
commit 8395352b939899f7340683f551170d6a8e0e2fd0
Merge: ff39b3d 257ee81
Author: Stephen Kelly <steveire at gmail.com>
AuthorDate: Thu Feb 6 13:09:59 2014 -0500
Commit: CMake Topic Stage <kwrobot at kitware.com>
CommitDate: Thu Feb 6 13:09:59 2014 -0500
Merge topic 'update-buildsystem-docs' into next
257ee81b Fix hyperlink anchor names and text.
cc2b13a6 Move style section.
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=257ee81b00176e9c8bb18ce42313a9075b8a7b60
commit 257ee81b00176e9c8bb18ce42313a9075b8a7b60
Author: Stephen Kelly <steveire at gmail.com>
AuthorDate: Thu Feb 6 19:02:01 2014 +0100
Commit: Stephen Kelly <steveire at gmail.com>
CommitDate: Thu Feb 6 19:02:01 2014 +0100
Fix hyperlink anchor names and text.
diff --git a/Help/command/add_executable.rst b/Help/command/add_executable.rst
index 296adc3..231eeed 100644
--- a/Help/command/add_executable.rst
+++ b/Help/command/add_executable.rst
@@ -44,7 +44,7 @@ buildsystem properties.
add_executable(<name> IMPORTED [GLOBAL])
-An :ref:`IMPORTED executable target <Imported Target>` references an
+An :ref:`IMPORTED executable target <Imported Targets>` references an
executable file located outside the project. No rules are generated to
build it, and the :prop_tgt:`IMPORTED` target property is ``True``. The
target name has scope in the directory in which it is created and below, but
@@ -64,10 +64,10 @@ properties for more information.
add_executable(<name> ALIAS <target>)
-Creates an :ref:`Alias Target`, such that ``<name>`` can
+Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can
be used to refer to ``<target>`` in subsequent commands. The ``<name>``
does not appear in the generated buildsystem as a make target. The
-``<target>`` may not be an :ref:`Imported Target` or an
+``<target>`` may not be an :ref:`Imported Target <Imported Targets>` or an
``ALIAS``. ``ALIAS`` targets can be used as targets to read properties
from, executables for custom commands and custom targets. They can also be
tested for existance with the regular :command:`if(TARGET)` subcommand.
diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst
index 6450485..0944269 100644
--- a/Help/command/add_library.rst
+++ b/Help/command/add_library.rst
@@ -49,7 +49,7 @@ properties.
add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED
[GLOBAL])
-An :ref:`IMPORTED library target <Imported Target>` references a library
+An :ref:`IMPORTED library target <Imported Targets>` references a library
file located outside the project. No rules are generated to build it, and
the :prop_tgt:`IMPORTED` target property is ``True``. The target name has
scope in the directory in which it is created and below, but the ``GLOBAL``
@@ -97,10 +97,10 @@ adding at least one real source file to any target that references
add_library(<name> ALIAS <target>)
-Creates an :ref:`Alias Target`, such that ``<name>`` can be
+Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
used to refer to ``<target>`` in subsequent commands. The ``<name>`` does
not appear in the generatedbuildsystem as a make target. The ``<target>``
-may not be an :ref:`Imported Target` or an ``ALIAS``.
+may not be an :ref:`Imported Target <Imported Targets>` or an ``ALIAS``.
``ALIAS`` targets can be used as linkable targets and as targets to
read properties from. They can also be tested for existance with the
regular :command:`if(TARGET)` subcommand. The ``<name>`` may not be used
@@ -115,21 +115,22 @@ installed or exported.
add_library(<name> INTERFACE [IMPORTED [GLOBAL]])
-Creates an :ref:`Interface Library`. An ``INTERFACE`` library target does
-not directly create build output, though it may have properties set on it
-and it may be installed, exported and imported. Typically the
-``INTERFACE_*`` properties are populated on the interface target using the
-:command:`set_property`, :command:`target_link_libraries(INTERFACE)`,
+Creates an :ref:`Interface Library <Interface Libraries>`. An ``INTERFACE``
+library target does not directly create build output, though it may
+have properties set on it and it may be installed, exported and
+imported. Typically the ``INTERFACE_*`` properties are populated on
+the interface target using the :command:`set_property`,
+:command:`target_link_libraries(INTERFACE)`,
:command:`target_include_directories(INTERFACE)`,
:command:`target_compile_options(INTERFACE)`
and :command:`target_compile_definitions(INTERFACE)` commands, and then it
is used as an argument to :command:`target_link_libraries` like any other
target.
-An ``INTERFACE`` :ref:`Imported Target` may also be created with this
-signature. An ``IMPORTED`` library target references a library defined
-outside the project. The target name has scope in the directory in which
-it is created and below, but the ``GLOBAL`` option extends visibility. It
-may be referenced like any target built within the project. ``IMPORTED``
-libraries are useful for convenient reference from commands like
-:command:`target_link_libraries`.
+An ``INTERFACE`` :ref:`Imported Target <Imported Targets>` may also be
+created with this signature. An ``IMPORTED`` library target references a
+library defined outside the project. The target name has scope in the
+directory in which it is created and below, but the ``GLOBAL`` option
+extends visibility. It may be referenced like any target built within
+the project. ``IMPORTED`` libraries are useful for convenient reference
+from commands like :command:`target_link_libraries`.
diff --git a/Help/command/target_compile_definitions.rst b/Help/command/target_compile_definitions.rst
index 0a4219e..3c9fe87 100644
--- a/Help/command/target_compile_definitions.rst
+++ b/Help/command/target_compile_definitions.rst
@@ -12,7 +12,7 @@ Add compile definitions to a target.
Specify compile definitions to use when compiling a given <target. The
named ``<target>`` must have been created by a command such as
:command:`add_executable` or :command:`add_library` and must not be an
-:ref:`Imported Target`.
+:ref:`Imported Target <Imported Targets>`.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC``
diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst
index ef50e0a..bced169 100644
--- a/Help/command/target_link_libraries.rst
+++ b/Help/command/target_link_libraries.rst
@@ -29,7 +29,7 @@ the Debug configuration (or to configurations named in the
``general`` keyword corresponds to all configurations, and is purely
optional (assumed if omitted). Higher granularity may be achieved for
per-configuration rules by creating and linking to
-:ref:`IMPORTED library targets <Imported Target>`.
+:ref:`IMPORTED library targets <Imported Targets>`.
Library dependencies are transitive by default with this signature.
When this target is linked into another target then the libraries
diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst
index 0424d81..91a9b2f 100644
--- a/Help/manual/cmake-buildsystem.7.rst
+++ b/Help/manual/cmake-buildsystem.7.rst
@@ -668,7 +668,7 @@ Some target types do not represent outputs of the buildsystem, but only inputs
such as external dependencies, aliases or other non-build artifacts. Pseudo
targets are not represented in the generated buildsystem.
-.. _`Imported Target`:
+.. _`Imported Targets`:
Imported Targets
----------------
@@ -706,7 +706,7 @@ accessible globally in the buildsystem.
See the :manual:`cmake-packages(7)` manual for more on creating packages
with :prop_tgt:`IMPORTED` targets.
-.. _`Alias Target`:
+.. _`Alias Targets`:
Alias Targets
-------------
@@ -749,7 +749,7 @@ property from it:
message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.")
endif()
-.. _`Interface Library`:
+.. _`Interface Libraries`:
Interface Libraries
-------------------
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index ad4ed12..3d54304 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -503,7 +503,7 @@ Style
.. code-block:: rst
- This command creates an :ref:`Imported Target`.
+ This command creates an :ref:`<Imported Target <Imported Targets>`.
instead of:
@@ -521,12 +521,14 @@ Style
.. _`Imported Targets`:
- creates a suitable anchor.
+ 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 Target`).
+ concept (:ref:`Imported Targets`).
11)
Where a property, command or variable is related conceptually to others,
diff --git a/Help/prop_tgt/ALIASED_TARGET.rst b/Help/prop_tgt/ALIASED_TARGET.rst
index 559c636..b04048b 100644
--- a/Help/prop_tgt/ALIASED_TARGET.rst
+++ b/Help/prop_tgt/ALIASED_TARGET.rst
@@ -3,5 +3,5 @@ ALIASED_TARGET
Name of target aliased by this target.
-If this is an :ref:`Alias Target`, this property contains the name of the
-target aliased.
+If this is an :ref:`Alias Targets <Alias Target>`, this property contains
+the name of the target aliased.
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=cc2b13a6b994953c8b1d66e82a90c2c3f6927923
commit cc2b13a6b994953c8b1d66e82a90c2c3f6927923
Author: Stephen Kelly <steveire at gmail.com>
AuthorDate: Thu Feb 6 18:49:04 2014 +0100
Commit: Stephen Kelly <steveire at gmail.com>
CommitDate: Thu Feb 6 18:49:04 2014 +0100
Move style section.
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index 3a80dca..ad4ed12 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -207,170 +207,6 @@ processed by `Sphinx`_ to generate the CMake help manuals.
.. _`reStructuredText`: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
.. _`Sphinx`: http://sphinx-doc.org
-Style
------
-
-1)
- Command signatures should be marked up as plain literal blocks, not as
- cmake ``code-blocks``.
-
-2)
- Signatures are separated from preceding content by a horizontal
- line. That is, use:
-
- .. code-block:: rst
-
- ... preceding paragraph.
-
- ---------------------------------------------------------------------
-
- ::
-
- add_library(<lib> ...)
-
- This signature is used for ...
-
-3)
- 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.
-
-4)
- Use two spaces for indentation. Use two spaces between sentences in
- prose.
-
-5)
- 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.
-
-6)
- 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.
-
-7)
- Mark up 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.
-
-8)
- Mark up all other 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.
-
-9)
- Mark up references to keywords in signatures, file names, and other
- technical terms with ``inline-literl`` 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.
-
-
-10)
- 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`.
-
- 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.
-
- 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 Target`).
-
-11)
- 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.
-
-12)
- 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.
-
-13)
- When referring to 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 :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ...
-
-14)
- 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.
-
-15)
- Use American English spellings in prose.
-
-
Markup Constructs
-----------------
@@ -581,6 +417,170 @@ 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
+-----
+
+1)
+ Command signatures should be marked up as plain literal blocks, not as
+ cmake ``code-blocks``.
+
+2)
+ Signatures are separated from preceding content by a horizontal
+ line. That is, use:
+
+ .. code-block:: rst
+
+ ... preceding paragraph.
+
+ ---------------------------------------------------------------------
+
+ ::
+
+ add_library(<lib> ...)
+
+ This signature is used for ...
+
+3)
+ 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.
+
+4)
+ Use two spaces for indentation. Use two spaces between sentences in
+ prose.
+
+5)
+ 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.
+
+6)
+ 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.
+
+7)
+ Mark up 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.
+
+8)
+ Mark up all other 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.
+
+9)
+ Mark up references to keywords in signatures, file names, and other
+ technical terms with ``inline-literl`` 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.
+
+
+10)
+ 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`.
+
+ 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.
+
+ 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 Target`).
+
+11)
+ 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.
+
+12)
+ 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.
+
+13)
+ When referring to 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 :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ...
+
+14)
+ 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.
+
+15)
+ Use American English spellings in prose.
+
+
Modules
=======
-----------------------------------------------------------------------
Summary of changes:
Help/command/add_executable.rst | 6 +-
Help/command/add_library.rst | 31 +--
Help/command/target_compile_definitions.rst | 2 +-
Help/command/target_link_libraries.rst | 2 +-
Help/manual/cmake-buildsystem.7.rst | 6 +-
Help/manual/cmake-developer.7.rst | 330 ++++++++++++++-------------
Help/prop_tgt/ALIASED_TARGET.rst | 4 +-
7 files changed, 192 insertions(+), 189 deletions(-)
hooks/post-receive
--
CMake
More information about the Cmake-commits
mailing list