|
@@ -519,8 +519,16 @@ containing just the line::
|
|
|
|
|
|
The ``cmake-module`` directive will scan the module file to extract
|
|
The ``cmake-module`` directive will scan the module file to extract
|
|
reStructuredText markup from comment blocks that start in ``.rst:``.
|
|
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
|
|
.. code-block:: cmake
|
|
|
|
|
|
@@ -552,6 +560,9 @@ For example, a ``Modules/Findxxx.cmake`` module may contain:
|
|
|
|
|
|
.. code-block:: cmake
|
|
.. 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:
|
|
#.rst:
|
|
# FindXxx
|
|
# FindXxx
|
|
# -------
|
|
# -------
|
|
@@ -579,25 +590,6 @@ For example, a ``Modules/Findxxx.cmake`` module may contain:
|
|
<code>
|
|
<code>
|
|
endmacro()
|
|
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
|
|
Test the documentation formatting by running
|
|
``cmake --help-module <module-name>``, and also by enabling the
|
|
``cmake --help-module <module-name>``, and also by enabling the
|
|
``SPHINX_HTML`` and ``SPHINX_MAN`` options to build the documentation.
|
|
``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
|
|
We will describe how to create a simple find module for a library
|
|
``Foo``.
|
|
``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
|
|
.. 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
|
|
be documented where they are defined. See the `Module
|
|
Documentation`_ section above for more details.
|
|
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
|
|
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
|
|
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.
|
|
point of find modules), but there tends to be a common pattern for libraries.
|