Improve the manuals

This adds an ecm-developer manual that replaces writing-find-modules.md
(a lot of which was upstreamed to CMake's own documentation). It also
adds introductory text to the ecm-*-modules manuals.

4 files changed, 337 insertions, 0 deletions

diff --git a/docs/manual/ecm-developer.7.rst b/docs/manual/ecm-developer.7.rst
new file mode 100644
index 00000000..3ed3f786
--- /dev/null
+++ b/docs/manual/ecm-developer.7.rst
@@ -0,0 +1,231 @@
+.. ecm-manual-description: ECM Developer Reference
+
+ecm-developer(7)
+****************
+
+.. only:: html or latex
+
+   .. contents::
+
+
+Writing Modules
+===============
+
+The CMake 3 documentation (and `cmake-developer(7)`_ in particular) has a lot of
+useful information about writing CMake modules, including a large section
+devoted to find modules. This guide will only highlight things that are
+particular to the Extra CMake Modules project.
+
+Most of these are stylistic points. For example, the license header for a module
+in ECM should look like::
+
+  #=============================================================================
+  # Copyright 20XX Your Name <your.email@example.com>
+  #
+  # Distributed under the OSI-approved BSD License (the "License");
+  # see accompanying file COPYING-CMAKE-SCRIPTS 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 extra-cmake-modules, substitute the full
+  #  License text for the above reference.)
+
+Functions should be used instead of macros unless there is a good reason not to
+(and that reason should be noted in a comment), and lowercase should be used for
+macros, functions and commands.
+
+4 spaces is the generally-recommended indent, although there are several files
+that use 2 spaces; consistency within a file is more important than consistency
+across files.
+
+If in doubt, look at how other modules in Extra CMake Modules are written, and
+follow the same pattern.
+
+
+Find Modules
+------------
+
+A good template for find module documentation is::
+
+  #.rst:
+  # FindFoo
+  # -------
+  #
+  # Finds the Foo library.
+  #
+  # This will define the following variables:
+  #
+  # ``Foo_FOUND``
+  #     True if (the requested version of) Foo is available
+  # ``Foo_VERSION``
+  #     The version of Foo, if it is found
+  # ``Foo_LIBRARIES``
+  #     This can be passed to target_link_libraries() instead of the ``Foo::Foo``
+  #     target
+  # ``Foo_INCLUDE_DIRS``
+  #     This should be passed to target_include_directories() if the target is not
+  #     used for linking
+  # ``Foo_DEFINITIONS``
+  #     This should be passed to target_compile_options() if the target is not
+  #     used for linking
+  #
+  # If ``Foo_FOUND`` is TRUE, it will also define the following imported target:
+  #
+  # ``Foo::Foo``
+  #     The Foo library
+  #
+  # In general we recommend using the imported target, as it is easier to use.
+  # Bear in mind, however, that if the target is in the link interface of an
+  # exported library, it must be made available by the package config file.
+
+Note the use of definition lists for the variables.
+
+Because of the :module:`ECMUseFindModules` module, projects may easily make
+local copies of find modules, and may install those copies with their own CMake
+project config files. For this reason, find modules should include the full BSD
+3-clause license::
+
+  #=============================================================================
+  # Copyright 20XX Your Name <your.email@example.com>
+  #
+  # Redistribution and use in source and binary forms, with or without
+  # modification, are permitted provided that the following conditions
+  # are met:
+  #
+  # 1. Redistributions of source code must retain the copyright
+  #    notice, this list of conditions and the following disclaimer.
+  # 2. Redistributions in binary form must reproduce the copyright
+  #    notice, this list of conditions and the following disclaimer in the
+  #    documentation and/or other materials provided with the distribution.
+  # 3. The name of the author may not be used to endorse or promote products
+  #    derived from this software without specific prior written permission.
+  #
+  # THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+  # IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+  # OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+  # IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+  # INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+  # NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+  # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+  # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+  # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+  # THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+  #=============================================================================
+
+Find modules should always provide imported targets in addition to the
+traditional variables (like ``Foo_LIBRARIES``, etc).
+
+Unlike find modules shipped with CMake, if the module requires a specific CMake
+version it is not enough to warn when the minimum required version is not high
+enough: you should also produce an error when the actual CMake version being
+used is not high enough. This can be done with:
+
+.. code-block:: cmake
+
+  if(CMAKE_VERSION VERSION_LESS 2.8.12)
+      message(FATAL_ERROR "CMake 2.8.12 is required by FindFoo.cmake")
+  endif()
+  if(CMAKE_MINIMUM_REQUIRED_VERSION VERSION_LESS 2.8.12)
+      message(AUTHOR_WARNING "Your project should require at least CMake 2.8.12 to use FindFoo.cmake")
+  endif()
+
+The :module:`ECMFindModuleHelpers` module has several useful functions and
+macros. For example, it allows you to replace the above version check with:
+
+.. code-block:: cmake
+
+  ecm_find_package_version_check(Foo)
+
+Components
+~~~~~~~~~~
+
+Using :module:`ECMFindModuleHelpers`, creating a find module for a library with
+several inter-dependent components is reasonably straightforward. After the
+documentation, you need to include the module and do the usual version check:
+
+.. code-block:: cmake
+
+  include(ECMFindModuleHelpers)
+  ecm_find_package_version_check(Foo)
+
+The important macros are ``ecm_find_package_parse_components`` and
+``ecm_find_package_handle_library_components``.  These take a list of
+components, and query other variables you provide to find out the information
+they require.  The documentation for :module:`ECMFindModuleHelpers` provides
+more information, but a simple setup might look like:
+
+.. code-block:: cmake
+
+  set(Foo_known_components Bar Baz)
+  set(Foo_Bar_pkg_config "foo-bar")
+  set(Foo_Bar_lib "bar")
+  set(Foo_Bar_header "foo/bar.h")
+  set(Foo_Bar_pkg_config "foo-baz")
+  set(Foo_Baz_lib "baz")
+  set(Foo_Baz_header "foo/baz.h")
+
+If ``Baz`` depends on ``Bar``, for example, you can specify this with
+
+.. code-block:: cmake
+
+  set(Foo_Baz_component_deps "Bar")
+
+Then call the macros:
+
+.. code-block:: cmake
+
+  ecm_find_package_parse_components(Foo
+      RESULT_VAR Foo_components
+      KNOWN_COMPONENTS ${Foo_known_components}
+  )
+  ecm_find_package_handle_library_components(Foo
+      COMPONENTS ${Foo_components}
+  )
+
+Of course, if your components need unusual handling, you may want to replace
+``ecm_find_package_handle_library_components`` with, for example, a ``foreach``
+loop over the components (the body of which should implement most of what a
+normal find module does, including setting ``Foo_<component>_FOUND``).
+
+At this point, you should set ``Foo_VERSION`` using whatever information you
+have available (such as from parsing header files).  Note that
+``ecm_find_package_handle_library_components`` will set it to the version
+reported by pkg-config of the first component found, but this depends on the
+presence of pkg-config files, and the version of a component may not be the same
+as the version of the whole package.  After that, finish off with
+
+.. code-block:: cmake
+
+  include(FindPackageHandleStandardArgs)
+  find_package_handle_standard_args(Foo
+      FOUND_VAR
+          Foo_FOUND
+      REQUIRED_VARS
+          Foo_LIBRARIES
+      VERSION_VAR
+          Foo_VERSION
+      HANDLE_COMPONENTS
+  )
+  
+  include(FeatureSummary)
+  set_package_properties(Foo PROPERTIES
+      URL "http://www.foo.example.com/"
+      DESCRIPTION "A library for doing useful things")
+
+
+Submitting Modules
+==================
+
+Proposed new modules should be submitted using the `KDE Review Board instance`_,
+and be assigned to the ``buildsystem`` and ``extracmakemodules`` groups.  You
+should be able to point to two separate projects that will make use of the
+module.
+
+The mailing list can be found at
+https://mail.kde.org/mailman/listinfo/kde-buildsystem\ .
+
+
+.. _KDE Review Board instance: https://git.reviewboard.kde.org/
+.. _cmake-developer(7): http://www.cmake.org/cmake/help/git-master/manual/cmake-developer.7.html
diff --git a/docs/manual/ecm-find-modules.7.rst b/docs/manual/ecm-find-modules.7.rst
index 4e3fc984..0f09c22a 100644
--- a/docs/manual/ecm-find-modules.7.rst
+++ b/docs/manual/ecm-find-modules.7.rst
@@ -7,6 +7,45 @@ ecm-find-modules(7)
 
    .. contents::
 
+Introduction
+============
+
+Find modules are used by the CMake ``find_package`` command to search for
+packages that do not provide their own CMake package config files. CMake
+provides an extensive set of find modules, and Extra CMake Modules (ECM) adds
+to that.
+
+To use ECM's find modules, you need to tell CMake to find the ECM package, and
+then add either ``${ECM_MODULE_PATH}`` or ``${ECM_FIND_MODULE_DIR}`` to the
+``CMAKE_MODULE_PATH`` variable:
+
+.. code-block:: cmake
+
+  find_package(ECM REQUIRED NO_MODULE)
+  set(CMAKE_MODULE_PATH ${ECM_FIND_MODULE_DIR})
+
+Using ``${ECM_MODULE_PATH}`` will also make the modules intended for direct use
+by CMake scripts available (see :manual:`ecm-modules(7)` and
+:manual:`ecm-kde-modules(7)`).
+
+You can also make local copies of find modules using the
+``ecm_use_find_modules`` function from :module:`ECMUseFindModules`, which is
+automatically included when ECM is found:
+
+.. code-block:: cmake
+
+  find_package(ECM REQUIRED NO_MODULE)
+  ecm_use_find_modules(
+      DIR "${CMAKE_BINARY_DIR}/cmake"
+      MODULES FindEGL.cmake
+  )
+  set(CMAKE_MODULE_PATH "${CMAKE_BINARY_DIR}/cmake")
+
+This allows selective use of ECM's find modules, and the NO_OVERRIDE argument
+can be used to ensure that if CMake ships its own version of that find module,
+it will be used instead.
+
+
 All Find Modules
 ================
 
@@ -16,3 +55,10 @@ All Find Modules
 
    /find-module/*
 
+.. only:: man
+
+  See Also
+  ========
+
+  :manual:`ecm(7)`, :manual:`ecm-modules(7)`, :manual:`ecm-kde-modules(7)`
+
diff --git a/docs/manual/ecm-kde-modules.7.rst b/docs/manual/ecm-kde-modules.7.rst
index b3dffd77..184458f9 100644
--- a/docs/manual/ecm-kde-modules.7.rst
+++ b/docs/manual/ecm-kde-modules.7.rst
@@ -7,6 +7,28 @@ ecm-kde-modules(7)
 
    .. contents::
 
+Introduction
+============
+
+Extra CMake Modules (ECM) provides several modules that provide default settings
+(like installation directories, compiler flags and other CMake options) aimed at
+software produced by the KDE modules; these are documented here. ECM also
+provides modules with more general functionality, documented in
+:manual:`ecm-modules(7)`, and ones that extend the functionality of the
+``find_package`` command, documented in :manual:`ecm-find-modules(7)`.
+
+To use these modules, you need to tell CMake to find the ECM package, and
+then add either ``${ECM_MODULE_PATH}`` or ``${ECM_KDE_MODULE_DIR}`` to the
+``CMAKE_MODULE_PATH`` variable:
+
+.. code-block:: cmake
+
+  find_package(ECM REQUIRED NO_MODULE)
+  set(CMAKE_MODULE_PATH ${ECM_MODULE_DIR})
+
+Using ``${ECM_MODULE_PATH}`` will also make the other types of modules
+available.
+
 All KDE Modules
 ===============
 
@@ -16,3 +38,10 @@ All KDE Modules
 
    /kde-module/*
 
+.. only:: man
+
+  See Also
+  ========
+
+  :manual:`ecm(7)`, :manual:`ecm-modules(7)`, :manual:`ecm-find-modules(7)`
+
diff --git a/docs/manual/ecm-modules.7.rst b/docs/manual/ecm-modules.7.rst
index 70b09f5e..16fd8612 100644
--- a/docs/manual/ecm-modules.7.rst
+++ b/docs/manual/ecm-modules.7.rst
@@ -7,6 +7,30 @@ ecm-modules(7)
 
    .. contents::
 
+Introduction
+============
+
+Extra CMake Modules (ECM) provides various modules that provide useful functions
+for CMake scripts. ECM actually provides three types of modules: those that
+extend the functionality of the ``find_package`` command are documented in
+:manual:`ecm-find-modules(7)`; those that provide standard settings for software
+produced by the KDE community are documented in :manual:`ecm-kde-modules(7)`.
+The rest provide macros and functions for general use by CMake scripts and are
+documented here.
+
+To use these modules, you need to tell CMake to find the ECM package, and
+then add either ``${ECM_MODULE_PATH}`` or ``${ECM_MODULE_DIR}`` to the
+``CMAKE_MODULE_PATH`` variable:
+
+.. code-block:: cmake
+
+  find_package(ECM REQUIRED NO_MODULE)
+  set(CMAKE_MODULE_PATH ${ECM_MODULE_DIR})
+
+Using ``${ECM_MODULE_PATH}`` will also make the find modules and KDE modules
+available.
+
+
 All Modules
 ===========
 
@@ -16,3 +40,10 @@ All Modules
 
    /module/*
 
+.. only:: man
+
+  See Also
+  ========
+
+  :manual:`ecm(7)`, :manual:`ecm-find-modules(7)`, :manual:`ecm-kde-modules(7)`
+