kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Help: Update cmake-developer(7) module license docs for new notice

This commit is contained in:
Brad King 2016-09-27 14:53:35 -04:00
parent 756169ac99
commit 19671831cf
1 changed files with 24 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
Help/manual/cmake-developer.7.rst
View File

@ -519,8 +519,16 @@ containing just the line::
The ``cmake-module`` directive will scan the module file to extract
reStructuredText markup from comment blocks that start in ``.rst:``.
Add to the top of ``Modules/<module-name>.cmake`` a
:ref:`Line Comment` block of the form:
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
@ -552,6 +560,9 @@ For example, a ``Modules/Findxxx.cmake`` module may contain:
.. code-block:: cmake
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#.rst:
# FindXxx
# -------
@ -579,25 +590,6 @@ For example, a ``Modules/Findxxx.cmake`` module may contain:
<code>
endmacro()
After the top documentation block, leave a *BLANK* line, and then add a
copyright and licence notice block like this one (change only the year
range and name)
.. code-block:: cmake
#=============================================================================
# Copyright 2009-2011 Your Name
#
# Distributed under the OSI-approved BSD License (the "License");
# see accompanying file Copyright.txt for details.
#
# This software is distributed WITHOUT ANY WARRANTY; without even the
# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
# See the License for more information.
#=============================================================================
# (To distribute this file outside of CMake, substitute the full
# License text for the above reference.)
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.
@ -791,10 +783,17 @@ A Sample Find Module
We will describe how to create a simple find module for a library
``Foo``.
The first thing that is needed is documentation. CMake's documentation
system requires you to start the file with a documentation marker and
the name of the module. You should follow this with a simple statement
of what the module does.
The first thing that is needed is a 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.
Next we need module documentation. CMake's documentation system requires you
to follow the license notice with a blank line and then with a documentation
marker and the name of the module. You should follow this with a simple
statement of what the module does.
.. code-block:: cmake
@ -825,24 +824,6 @@ 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.
After the documentation, leave a blank line, and then add a copyright and
licence notice block
.. code-block:: cmake
#=============================================================================
# Copyright 2009-2011 Your Name
#
# Distributed under the OSI-approved BSD License (the "License");
# see accompanying file Copyright.txt for details.
#
# This software is distributed WITHOUT ANY WARRANTY; without even the
# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
# See the License for more information.
#=============================================================================
# (To distribute this file outside of CMake, substitute the full
# License text for the above reference.)
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
point of find modules), but there tends to be a common pattern for libraries.