diff options
| author | Alex Merry <alex.merry@kde.org> | 2014-04-10 21:38:09 +0100 |
|---|---|---|
| committer | Alex Merry <alex.merry@kde.org> | 2014-04-11 21:12:58 +0100 |
| commit | c20d22c951e61a06701f6c2201add7c11915e7c5 (patch) | |
| tree | a8f375967eaeeceffac6da5098700b4563bf2306 | |
| parent | ddd33b850bb519174511a34eeda40af69a1f7144 (diff) | |
| download | extra-cmake-modules-c20d22c951e61a06701f6c2201add7c11915e7c5.tar.gz extra-cmake-modules-c20d22c951e61a06701f6c2201add7c11915e7c5.tar.bz2 | |
Add documentation generation using Sphinx
This is deliberately modelled very closely on CMake's documentation
system. It's a hefty patch, because it involved changing all the
documentation to be in reStructuredText format. I also cleaned up the
copyright/license statements at the same time.
Note that the find modules contain the full license, due to the fact
that ecm_use_find_module() copies them out of the ECM distribution.
60 files changed, 1693 insertions, 548 deletions
diff --git a/CMakeLists.txt b/CMakeLists.txt index 7ac655a6..0f752aa3 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -11,26 +11,15 @@ set(ECM_VERSION ${ECM_MAJOR_VERSION}.${ECM_MINOR_VERSION}.${ECM_PATCH_VERSION}) enable_testing() add_subdirectory(tests) -set(SHARE_INSTALL_DIR share/ECM ) -set(MODULES_INSTALL_DIR ${SHARE_INSTALL_DIR}/modules/) -set(KDE_MODULES_INSTALL_DIR ${SHARE_INSTALL_DIR}/kde-modules/) -set(FIND_MODULES_INSTALL_DIR ${SHARE_INSTALL_DIR}/find-modules/) -set(CMAKECONFIG_INSTALL_DIR ${SHARE_INSTALL_DIR}/cmake/) -set(DOC_INSTALL_DIR ${SHARE_INSTALL_DIR}/doc/) - -# create and install docs -# add_custom_target(ManPage ALL -# COMMAND ${CMAKE_COMMAND} -DCMAKE_MODULE_PATH=${CMAKE_SOURCE_DIR}/modules\;${CMAKE_SOURCE_DIR}/find-modules\;${CMAKE_SOURCE_DIR}/kde-modules --help-custom-modules "${CMAKE_BINARY_DIR}/extra-cmake-modules.7" -# COMMAND ${CMAKE_COMMAND} -DCMAKE_MODULE_PATH=${CMAKE_SOURCE_DIR}/modules\;${CMAKE_SOURCE_DIR}/find-modules\;${CMAKE_SOURCE_DIR}/kde-modules --help-custom-modules "${CMAKE_BINARY_DIR}/extra-cmake-modules.html" -# COMMAND ${CMAKE_COMMAND} -DCMAKE_MODULE_PATH=${CMAKE_SOURCE_DIR}/modules\;${CMAKE_SOURCE_DIR}/find-modules\;${CMAKE_SOURCE_DIR}/kde-modules --help-custom-modules "${CMAKE_BINARY_DIR}/extra-cmake-modules.txt" -# VERBATIM -# ) - -# install(FILES "${CMAKE_BINARY_DIR}/extra-cmake-modules.7" DESTINATION man/man7/) - -# install(FILES "${CMAKE_BINARY_DIR}/extra-cmake-modules.txt" "${CMAKE_BINARY_DIR}/extra-cmake-modules.html" -# DESTINATION ${DOC_INSTALL_DIR}) - +set(SHARE_INSTALL_DIR share) +set(MODULES_INSTALL_DIR ${SHARE_INSTALL_DIR}/ECM/modules/) +set(KDE_MODULES_INSTALL_DIR ${SHARE_INSTALL_DIR}/ECM/kde-modules/) +set(FIND_MODULES_INSTALL_DIR ${SHARE_INSTALL_DIR}/ECM/find-modules/) +set(CMAKECONFIG_INSTALL_DIR ${SHARE_INSTALL_DIR}/ECM/cmake/) +set(DOC_INSTALL_DIR ${SHARE_INSTALL_DIR}/doc/ECM) +set(MAN_INSTALL_DIR ${SHARE_INSTALL_DIR}/man) + +add_subdirectory(docs) file(GLOB installModuleFiles ${CMAKE_SOURCE_DIR}/modules/*[^~]) install(FILES ${installModuleFiles} DESTINATION ${MODULES_INSTALL_DIR}) diff --git a/README.md b/README.md deleted file mode 100644 index baa80c33..00000000 --- a/README.md +++ /dev/null @@ -1,94 +0,0 @@ -Extra CMake Modules -=================== - -Additional functionality for the CMake build system - - -Introduction ------------- - -The Extra CMake Modules package, or ECM, adds to the modules provided by CMake, -including both ones used by `find_package()` to find common software and ones -that can be used directly in `CMakeLists.txt` files to perform common tasks. - -In addition, it provides common build settings used in software produced by the -KDE community. - -While the driving force of this module is to reduce duplication in CMake scripts -across KDE software, it is intended to be useful for any software that uses the -CMake build system. - - -Usage ------ - -To use ECM, add the following to your `CMakeLists.txt`: - - find_package(ECM <ecm-version> REQUIRED NO_MODULE) - set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH}) - -(note that you may want to append `${ECM_MODULE_PATH}` to `CMAKE_MODULE_PATH` -instead). You can then just include the modules you require, or use -`find_package()` as needed. For example: - - include(ECMInstallIcons) - -Developers of KDE software will often want to use the KDE standard settings -provided by ECM; they can do the following: - - find_package(ECM <ecm-version> REQUIRED NO_MODULE) - set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH} ${ECM_KDE_MODULE_DIR}) - include(KDEInstallDirs) - include(KDECompilerSettings) - include(KDECMakeSettings) - -Note that any combination of the above includes can be used if you only want -some of the settings. Some of the functionality of `KDECMakeSettings` can also -be selectively disabled; see the documentation at the top of -`kde-modules/KDECMakeSettings.cmake` for more details. - - -Organization ------------- - -This module is organised as follows: - -- `attic/` contains most of the CMake modules shipped with kdelibs 4. These - can be used to form the basis of cleaned-up modules, either for inclusion in - ECM or for private use in a project. -- `find-modules/` contains the modules used by CMake's `find_package()` command. -- `kde-modules/` contains modules that provide some common settings for KDE - applications and frameworks. -- `modules/` contains the modules that should be included directly by CMake - scripts, other than those in `kde-modules/`. -- `tests/` contains automated tests for the functionality provided by ECM - modules. - - -Creating Modules ----------------- - -Proposed new modules should be submitted using the -[KDE Review Board instance][RB], and be assigned to the `buildsystem`, -`extracmakemodules` and `kdeframeworks` groups. You should be able to point to -two separate projects that will make use of the module. See the `docs/` -directory for more information on writing the modules themselves. - -[RB]: https://git.reviewboard.kde.org/ - - -License -------- - -All code in this repository is licensed under the [BSD 2-Clause license][1]. - -[1]: http://opensource.org/licenses/BSD-2-Clause - - -Links ------ - -- Home page: <https://projects.kde.org/projects/kdesupport/extra-cmake-modules> -- Mailing list: <https://mail.kde.org/mailman/listinfo/kde-buildsystem> -- IRC channel: \#kde-devel on Freenode -- Git repository: <https://projects.kde.org/projects/kdesupport/extra-cmake-modules/repository> diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..a079cae5 --- /dev/null +++ b/README.rst @@ -0,0 +1,98 @@ +Extra CMake Modules +******************* + +Introduction +============ + +The Extra CMake Modules package, or ECM, adds to the modules provided by CMake, +including both ones used by ``find_package()`` to find common software and ones +that can be used directly in ``CMakeLists.txt`` files to perform common tasks. + +In addition, it provides common build settings used in software produced by the +KDE community. + +While the driving force of this module is to reduce duplication in CMake scripts +across KDE software, it is intended to be useful for any software that uses the +CMake build system. + + +Usage +===== + +To use ECM, add the following to your ``CMakeLists.txt``: + +.. code-block:: cmake + + find_package(ECM REQUIRED NO_MODULE) + set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH}) + +(note that you may want to append ``${ECM_MODULE_PATH}`` to +``CMAKE_MODULE_PATH`` instead). You can then just include the modules you +require, or use ``find_package()`` as needed. For example: + +.. code-block:: cmake + + include(ECMInstallIcons) + +Developers of KDE software will often want to use the KDE standard settings +provided by ECM; they can do the following: + +.. code-block:: cmake + + find_package(ECM REQUIRED NO_MODULE) + set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH}) + include(KDEInstallDirs) + include(KDECompilerSettings) + include(KDECMakeSettings) + +Note that any combination of the above includes can be used if you only want +some of the settings. Some of the functionality of +:kde-module:`KDECMakeSettings` can also be selectively disabled. + + +Organization +------------ + +ECM provides three different types of modules. + +* Core modules provide helpful macros for use in project CMake scripts. + See :manual:`ecm-modules(7)` for more information. +* Find modules extend the functionality of CMake's ``find_package()`` command. + See :manual:`ecm-find-modules(7)` for more information. +* KDE modules provide common settings for software produced by KDE; much of this + may also be useful to other projects. See :manual:`ecm-kde-modules(7)` for + more information. + +The ``${ECM_MODULE_DIR}``, ``${ECM_FIND_MODULE_DIR}`` and +``${ECM_KDE_MODULE_DIR}`` variables may be used instead of +``${ECM_MODULE_PATH}`` if you only need some of this functionality. + + +Submitting Modules +================== + +Proposed new modules should be submitted using the +`KDE Review Board instance`_, and be assigned to the ``buildsystem``, +``extracmakemodules`` and ``kdeframeworks`` groups. You should be able to point to +two separate projects that will make use of the module. + +.. _KDE Review Board instance: https://git.reviewboard.kde.org/ + + +License +======= + +All code is licensed under the `BSD 3-Clause license`_. + +.. _BSD 3-Clause license: http://opensource.org/licenses/BSD-3-Clause + + +.. only:: html + + Links + ===== + + * `Home page <https://projects.kde.org/projects/kdesupport/extra-cmake-modules>`_ + * `Mailing list <https://mail.kde.org/mailman/listinfo/kde-buildsystem>`_ + * IRC channel: #kde-devel on Freenode + * `Git repository <https://projects.kde.org/projects/kdesupport/extra-cmake-modules/repository>`_ diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt new file mode 100644 index 00000000..ff04e7de --- /dev/null +++ b/docs/CMakeLists.txt @@ -0,0 +1,125 @@ +#============================================================================= +# CMake - Cross Platform Makefile Generator +# Copyright 2000-2013 Kitware, Inc., Insight Software Consortium +# Copyright 2014 Alex Merry <alex.merry@kde.org> +# +# 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. +#============================================================================= + +# Distros sometimes rename Python executables to allow for parallel +# installation of Python2 and Python3 versions +find_program(SPHINX_EXECUTABLE + NAMES + sphinx-build + sphinx-build2 + sphinx-build3 + DOC "Sphinx Documentation Builder (sphinx-doc.org)" +) +if(SPHINX_EXECUTABLE) + set(build_docs_default ON) +else() + set(build_docs_default OFF) +endif() + +option(BUILD_HTML_DOCS "Build html help with Sphinx" ${build_docs_default}) +option(BUILD_MAN_DOCS "Build man pages with Sphinx" ${build_docs_default}) +option(BUILD_QTHELP_DOCS "Build Qt help with Sphinx" OFF) + +if(NOT BUILD_HTML_DOCS AND NOT BUILD_MAN_DOCS AND NOT BUILD_QTHELP_DOCS) + return() +elseif(NOT SPHINX_EXECUTABLE) + message(FATAL_ERROR "SPHINX_EXECUTABLE (sphinx-build) was not found!") +endif() + +# the docs/ directory +set(conf_docs "${CMAKE_CURRENT_SOURCE_DIR}") +# where cmake.py and other sphinx files are +set(conf_path "${CMAKE_CURRENT_SOURCE_DIR}/sphinx") +set(conf_version "${extra-cmake-modules_VERSION_MAJOR}.${extra-cmake-modules_VERSION_MINOR}.${extra-cmake-modules_VERSION_PATCH}") +set(conf_release "${extra-cmake-modules_VERSION}") +configure_file(sphinx/conf.py.in conf.py @ONLY) + +set(doc_formats "") +if(BUILD_HTML_DOCS) + list(APPEND doc_formats html) +endif() +if(BUILD_MAN_DOCS) + list(APPEND doc_formats man) +endif() +if(BUILD_QTHELP_DOCS) + find_program(QCOLLECTIONGENERATOR_EXECUTABLE + NAMES qcollectiongenerator + DOC "qcollectiongenerator tool" + ) + if (NOT QCOLLECTIONGENERATOR_EXECUTABLE) + message(FATAL_ERROR "QCOLLECTIONGENERATOR_EXECUTABLE (qcollectiongenerator) not found!") + endif() + list(APPEND doc_formats qthelp) + + set(qthelp_extra_commands + COMMAND + qcollectiongenerator + ${CMAKE_CURRENT_BINARY_DIR}/qthelp/extra-cmake-modules.qhcp + ) +endif() + + +set(doc_format_outputs "") +set(doc_format_last "") +foreach(format ${doc_formats}) + set(doc_format_output "doc_format_${format}") + set(doc_format_log "build-${format}.log") + add_custom_command( + OUTPUT ${doc_format_output} + COMMAND + ${SPHINX_EXECUTABLE} + -c ${CMAKE_CURRENT_BINARY_DIR} + -d ${CMAKE_CURRENT_BINARY_DIR}/doctrees + -b ${format} + ${CMAKE_CURRENT_SOURCE_DIR} + ${CMAKE_CURRENT_BINARY_DIR}/${format} + > ${doc_format_log} # log stdout, pass stderr + DEPENDS ${doc_format_last} + COMMENT "sphinx-build ${format}: see ${CMAKE_CURRENT_BINARY_DIR}/${doc_format_log}" + VERBATIM + ) + set_property(SOURCE ${doc_format_output} PROPERTY SYMBOLIC 1) + list(APPEND doc_format_outputs ${doc_format_output}) + set(doc_format_last ${doc_format_output}) +endforeach() + +add_custom_target(documentation ALL DEPENDS ${doc_format_outputs}) + +if(BUILD_MAN_DOCS) + file(GLOB man_rst RELATIVE ${extra-cmake-modules_SOURCE_DIR}/docs/manual + ${extra-cmake-modules_SOURCE_DIR}/docs/manual/*.[1-9].rst) + foreach(m ${man_rst}) + if("x${m}" MATCHES "^x(.+)\\.([1-9])\\.rst$") + set(name "${CMAKE_MATCH_1}") + set(sec "${CMAKE_MATCH_2}") + install( + FILES ${CMAKE_CURRENT_BINARY_DIR}/man/${name}.${sec} + DESTINATION ${MAN_INSTALL_DIR}/man${sec} + ) + endif() + endforeach() +endif() +if(BUILD_HTML_DOCS) + install( + DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html + DESTINATION ${DOC_INSTALL_DIR} + PATTERN .buildinfo EXCLUDE + PATTERN objects.inv EXCLUDE + ) +endif() +if(BUILD_QTHELP_DOCS) + install( + FILES ${CMAKE_CURRENT_BINARY_DIR}/qthelp/extra-cmake-modules.qch + DESTINATION ${DOC_INSTALL_DIR} + ) +endif() diff --git a/docs/find-module/FindEGL.rst b/docs/find-module/FindEGL.rst new file mode 100644 index 00000000..6eb9710c --- /dev/null +++ b/docs/find-module/FindEGL.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../find-modules/FindEGL.cmake diff --git a/docs/find-module/FindOpenEXR.rst b/docs/find-module/FindOpenEXR.rst new file mode 100644 index 00000000..abefc855 --- /dev/null +++ b/docs/find-module/FindOpenEXR.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../find-modules/FindOpenEXR.cmake diff --git a/docs/find-module/FindSharedMimeInfo.rst b/docs/find-module/FindSharedMimeInfo.rst new file mode 100644 index 00000000..678eb516 --- /dev/null +++ b/docs/find-module/FindSharedMimeInfo.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../find-modules/FindSharedMimeInfo.cmake diff --git a/docs/find-module/FindWayland.rst b/docs/find-module/FindWayland.rst new file mode 100644 index 00000000..c64c6d85 --- /dev/null +++ b/docs/find-module/FindWayland.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../find-modules/FindWayland.cmake diff --git a/docs/find-module/FindX11_XCB.rst b/docs/find-module/FindX11_XCB.rst new file mode 100644 index 00000000..30b92464 --- /dev/null +++ b/docs/find-module/FindX11_XCB.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../find-modules/FindX11_XCB.cmake diff --git a/docs/find-module/FindXCB.rst b/docs/find-module/FindXCB.rst new file mode 100644 index 00000000..31e22282 --- /dev/null +++ b/docs/find-module/FindXCB.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../find-modules/FindXCB.cmake diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..1441005f --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,19 @@ +.. title:: Extra CMake Modules Reference Documentation + +Reference Manuals +################# + +.. toctree:: + :maxdepth: 1 + :glob: + + /manual/ecm.7 + /manual/* + +.. only:: html + + Index and Search + ################ + + * :ref:`genindex` + * :ref:`search` diff --git a/docs/kde-module/KDECMakeSettings.rst b/docs/kde-module/KDECMakeSettings.rst new file mode 100644 index 00000000..48ab140e --- /dev/null +++ b/docs/kde-module/KDECMakeSettings.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../kde-modules/KDECMakeSettings.cmake diff --git a/docs/kde-module/KDECompilerSettings.rst b/docs/kde-module/KDECompilerSettings.rst new file mode 100644 index 00000000..28f3e9c5 --- /dev/null +++ b/docs/kde-module/KDECompilerSettings.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../kde-modules/KDECompilerSettings.cmake diff --git a/docs/kde-module/KDEFrameworkCompilerSettings.rst b/docs/kde-module/KDEFrameworkCompilerSettings.rst new file mode 100644 index 00000000..6b8d7df5 --- /dev/null +++ b/docs/kde-module/KDEFrameworkCompilerSettings.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../kde-modules/KDEFrameworkCompilerSettings.cmake diff --git a/docs/kde-module/KDEInstallDirs.rst b/docs/kde-module/KDEInstallDirs.rst new file mode 100644 index 00000000..06435172 --- /dev/null +++ b/docs/kde-module/KDEInstallDirs.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../kde-modules/KDEInstallDirs.cmake diff --git a/docs/manual/ecm-find-modules.7.rst b/docs/manual/ecm-find-modules.7.rst new file mode 100644 index 00000000..4e3fc984 --- /dev/null +++ b/docs/manual/ecm-find-modules.7.rst @@ -0,0 +1,18 @@ +.. ecm-manual-description: ECM Find Modules Reference + +ecm-find-modules(7) +******************* + +.. only:: html or latex + + .. contents:: + +All Find Modules +================ + +.. toctree:: + :maxdepth: 1 + :glob: + + /find-module/* + diff --git a/docs/manual/ecm-kde-modules.7.rst b/docs/manual/ecm-kde-modules.7.rst new file mode 100644 index 00000000..b3dffd77 --- /dev/null +++ b/docs/manual/ecm-kde-modules.7.rst @@ -0,0 +1,18 @@ +.. ecm-manual-description: ECM KDE Modules Reference + +ecm-kde-modules(7) +****************** + +.. only:: html or latex + + .. contents:: + +All KDE Modules +=============== + +.. toctree:: + :maxdepth: 1 + :glob: + + /kde-module/* + diff --git a/docs/manual/ecm-modules.7.rst b/docs/manual/ecm-modules.7.rst new file mode 100644 index 00000000..70b09f5e --- /dev/null +++ b/docs/manual/ecm-modules.7.rst @@ -0,0 +1,18 @@ +.. ecm-manual-description: ECM Modules Reference + +ecm-modules(7) +************** + +.. only:: html or latex + + .. contents:: + +All Modules +=========== + +.. toctree:: + :maxdepth: 1 + :glob: + + /module/* + diff --git a/docs/manual/ecm.7.rst b/docs/manual/ecm.7.rst new file mode 100644 index 00000000..fdc444a6 --- /dev/null +++ b/docs/manual/ecm.7.rst @@ -0,0 +1,11 @@ +.. ecm-manual-description: Extra CMake Modules + +ecm(7) +****** + +.. only:: html or latex + + .. contents:: + +.. include:: ../../README.rst + :start-line: 2 diff --git a/docs/module/ECMAddTests.rst b/docs/module/ECMAddTests.rst new file mode 100644 index 00000000..f971953a --- /dev/null +++ b/docs/module/ECMAddTests.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../modules/ECMAddTests.cmake diff --git a/docs/module/ECMCreateQmFromPoFiles.rst b/docs/module/ECMCreateQmFromPoFiles.rst new file mode 100644 index 00000000..13340c0a --- /dev/null +++ b/docs/module/ECMCreateQmFromPoFiles.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../modules/ECMCreateQmFromPoFiles.cmake diff --git a/docs/module/ECMDBusAddActivationService.rst b/docs/module/ECMDBusAddActivationService.rst new file mode 100644 index 00000000..2052faeb --- /dev/null +++ b/docs/module/ECMDBusAddActivationService.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../modules/ECMDBusAddActivationService.cmake diff --git a/docs/module/ECMFindModuleHelpers.rst b/docs/module/ECMFindModuleHelpers.rst new file mode 100644 index 00000000..bec8f822 --- /dev/null +++ b/docs/module/ECMFindModuleHelpers.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../modules/ECMFindModuleHelpers.cmake diff --git a/docs/module/ECMGenerateHeaders.rst b/docs/module/ECMGenerateHeaders.rst new file mode 100644 index 00000000..ad3e4819 --- /dev/null +++ b/docs/module/ECMGenerateHeaders.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../modules/ECMGenerateHeaders.cmake diff --git a/docs/module/ECMGeneratePriFile.rst b/docs/module/ECMGeneratePriFile.rst new file mode 100644 index 00000000..1cb4d6a4 --- /dev/null +++ b/docs/module/ECMGeneratePriFile.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../modules/ECMGeneratePriFile.cmake diff --git a/docs/module/ECMInstallIcons.rst b/docs/module/ECMInstallIcons.rst new file mode 100644 index 00000000..7bb70ea5 --- /dev/null +++ b/docs/module/ECMInstallIcons.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../modules/ECMInstallIcons.cmake diff --git a/docs/module/ECMMarkAsTest.rst b/docs/module/ECMMarkAsTest.rst new file mode 100644 index 00000000..8b6a8752 --- /dev/null +++ b/docs/module/ECMMarkAsTest.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../modules/ECMMarkAsTest.cmake diff --git a/docs/module/ECMMarkNonGuiExecutable.rst b/docs/module/ECMMarkNonGuiExecutable.rst new file mode 100644 index 00000000..2684fee6 --- /dev/null +++ b/docs/module/ECMMarkNonGuiExecutable.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../modules/ECMMarkNonGuiExecutable.cmake diff --git a/docs/module/ECMOptionalAddSubdirectory.rst b/docs/module/ECMOptionalAddSubdirectory.rst new file mode 100644 index 00000000..af9595ec --- /dev/null +++ b/docs/module/ECMOptionalAddSubdirectory.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../modules/ECMOptionalAddSubdirectory.cmake diff --git a/docs/module/ECMPackageConfigHelpers.rst b/docs/module/ECMPackageConfigHelpers.rst new file mode 100644 index 00000000..21102c4f --- /dev/null +++ b/docs/module/ECMPackageConfigHelpers.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../modules/ECMPackageConfigHelpers.cmake diff --git a/docs/module/ECMSetupVersion.rst b/docs/module/ECMSetupVersion.rst new file mode 100644 index 00000000..f984a81f --- /dev/null +++ b/docs/module/ECMSetupVersion.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../modules/ECMSetupVersion.cmake diff --git a/docs/module/ECMUseFindModules.rst b/docs/module/ECMUseFindModules.rst new file mode 100644 index 00000000..48bbf35a --- /dev/null +++ b/docs/module/ECMUseFindModules.rst @@ -0,0 +1 @@ +.. ecm-module:: ../../modules/ECMUseFindModules.cmake diff --git a/docs/sphinx/.gitignore b/docs/sphinx/.gitignore new file mode 100644 index 00000000..0d20b648 --- /dev/null +++ b/docs/sphinx/.gitignore @@ -0,0 +1 @@ +*.pyc diff --git a/docs/sphinx/conf.py.in b/docs/sphinx/conf.py.in new file mode 100644 index 00000000..24ba82c8 --- /dev/null +++ b/docs/sphinx/conf.py.in @@ -0,0 +1,63 @@ +#============================================================================= +# CMake - Cross Platform Makefile Generator +# Copyright 2000-2013 Kitware, Inc., Insight Software Consortium +# +# 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. +#============================================================================= +import sys +import os +import re +import glob + +sys.path.insert(0, r'@conf_path@') + +source_suffix = '.rst' +master_doc = 'index' + +project = 'Extra CMake Modules' +copyright = 'KDE Developers' +version = '@conf_version@' # feature version +release = '@conf_release@' # full version string + +primary_domain = 'ecm' + +exclude_patterns = [] + +extensions = ['ecm'] +templates_path = ['@conf_path@/templates'] + +ecm_manuals = sorted(glob.glob(r'@conf_docs@/manual/*.rst')) +ecm_manual_description = re.compile('^\.\. ecm-manual-description:(.*)$') +man_pages = [] +for fpath in ecm_manuals: + try: + name, sec, rst = os.path.basename(fpath).split('.') + desc = None + f = open(fpath, 'r') + for l in f: + m = ecm_manual_description.match(l) + if m: + desc = m.group(1).strip() + break + f.close() + if desc: + man_pages.append(('manual/%s.%s' % (name, sec), + name, desc, [], int(sec))) + else: + sys.stderr.write("ERROR: No ecm-manual-description in '%s'\n" % fpath) + except Exception, e: + sys.stderr.write("ERROR: %s\n" % str(e)) +man_show_urls = False + +html_show_sourcelink = True +html_static_path = ['@conf_path@/static'] +html_style = 'ecm.css' +html_theme = 'default' +html_title = 'Extra CMake Modules %s Documentation' % release +html_short_title = '%s Documentation' % release +html_favicon = '@conf_path@/kde-favicon.ico' diff --git a/docs/sphinx/ecm.py b/docs/sphinx/ecm.py new file mode 100644 index 00000000..9b76e1a9 --- /dev/null +++ b/docs/sphinx/ecm.py @@ -0,0 +1,301 @@ +# Copyright 2014 Alex Merry <alex.merry@kde.org> +# Based on cmake.py from CMake: +# Copyright 2000-2013 Kitware, Inc., Insight Software Consortium +# +# 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. + +import os +import re + +# Monkey patch for pygments reporting an error when generator expressions are +# used. +# https://bitbucket.org/birkenfeld/pygments-main/issue/942/cmake-generator-expressions-not-handled +from pygments.lexers import CMakeLexer +from pygments.token import Name, Operator +from pygments.lexer import bygroups +CMakeLexer.tokens["args"].append(('(\\$<)(.+?)(>)', + bygroups(Operator, Name.Variable, Operator))) + +# Monkey patch for sphinx generating invalid content for qcollectiongenerator +# https://bitbucket.org/birkenfeld/sphinx/issue/1435/qthelp-builder-should-htmlescape-keywords +from sphinx.util.pycompat import htmlescape +from sphinx.builders.qthelp import QtHelpBuilder +old_build_keywords = QtHelpBuilder.build_keywords +def new_build_keywords(self, title, refs, subitems): + old_items = old_build_keywords(self, title, refs, subitems) + new_items = [] + for item in old_items: + before, rest = item.split("ref=\"", 1) + ref, after = rest.split("\"") + if ("<" in ref and ">" in ref): + new_items.append(before + "ref=\"" + htmlescape(ref) + "\"" + after) + else: + new_items.append(item) + return new_items +QtHelpBuilder.build_keywords = new_build_keywords + + +from docutils.parsers.rst import Directive, directives +from docutils.transforms import Transform +try: + from docutils.utils.error_reporting import SafeString, ErrorString +except ImportError: + # error_reporting was not in utils before version 0.11: + from docutils.error_reporting import SafeString, ErrorString + +from docutils import io, nodes + +from sphinx.directives import ObjectDescription +from sphinx.domains import Domain, ObjType +from sphinx.roles import XRefRole +from sphinx.util.nodes import make_refnode +from sphinx import addnodes + +class ECMModule(Directive): + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {'encoding': directives.encoding} + + def __init__(self, *args, **keys): + self.re_start = re.compile(r'^#\[(?P<eq>=*)\[\.rst:$') + Directive.__init__(self, *args, **keys) + + def run(self): + settings = self.state.document.settings + if not settings.file_insertion_enabled: + raise self.warning('"%s" directive disabled.' % self.name) + + env = self.state.document.settings.env + rel_path, path = env.relfn2path(self.arguments[0]) + path = os.path.normpath(path) + encoding = self.options.get('encoding', settings.input_encoding) + e_handler = settings.input_encoding_error_handler + try: + settings.record_dependencies.add(path) + f = io.FileInput(source_path=path, encoding=encoding, + error_handler=e_handler) + except UnicodeEncodeError, error: + raise self.severe('Problems with "%s" directive path:\n' + 'Cannot encode input file path "%s" ' + '(wrong locale?).' % + (self.name, SafeString(path))) + except IOError, error: + raise self.severe('Problems with "%s" directive path:\n%s.' % + (self.name, ErrorString(error))) + raw_lines = f.read().splitlines() + f.close() + rst = None + lines = [] + for line in raw_lines: + if rst is not None and rst != '#': + # Bracket mode: check for end bracket + pos = line.find(rst) + if pos >= 0: + if line[0] == '#': + line = '' + else: + line = line[0:pos] + rst = None + else: + # Line mode: check for .rst start (bracket or line) + m = self.re_start.match(line) + if m: + rst = ']%s]' % m.group('eq') + line = '' + elif line == '#.rst:': + rst = '#' + line = '' + elif rst == '#': + if line == '#' or line[:2] == '# ': + line = line[2:] + else: + rst = None + line = '' + elif rst is None: + line = '' + lines.append(line) + if rst is not None and rst != '#': + raise self.warning('"%s" found unclosed bracket "#[%s[.rst:" in %s' % + (self.name, rst[1:-1], path)) + self.state_machine.insert_input(lines, path) + return [] + +class _ecm_index_entry: + def __init__(self, desc): + self.desc = desc + + def __call__(self, title, targetid): + return ('pair', u'%s ; %s' % (self.desc, title), targetid, 'main') + +_ecm_index_objs = { + 'manual': _ecm_index_entry('manual'), + 'module': _ecm_index_entry('module'), + 'find-module': _ecm_index_entry('find-module'), + 'kde-module': _ecm_index_entry('kde-module'), + } + +def _ecm_object_inventory(env, document, line, objtype, targetid): + inv = env.domaindata['ecm']['objects'] + if targetid in inv: + document.reporter.warning( + 'ECM object "%s" also described in "%s".' % + (targetid, env.doc2path(inv[targetid][0])), line=line) + inv[targetid] = (env.docname, objtype) + +class ECMTransform(Transform): + + # Run this transform early since we insert nodes we want + # treated as if they were written in the documents. + default_priority = 210 + + def __init__(self, document, startnode): + Transform.__init__(self, document, startnode) + self.titles = {} + + def parse_title(self, docname): + """Parse a document title as the first line starting in [A-Za-z0-9<] + or fall back to the document basename if no such line exists. + Return the title or False if the document file does not exist. + """ + env = self.document.settings.env + title = self.titles.get(docname) + if title is None: + fname = os.path.join(env.srcdir, docname+'.rst') + try: + f = open(fname, 'r') + except IOError: + title = False + else: + for line in f: + if len(line) > 0 and (line[0].isalnum() or line[0] == '<'): + title = line.rstrip() + break + f.close() + if title is None: + title = os.path.basename(docname) + self.titles[docname] = title + return title + + def apply(self): + env = self.document.settings.env + + # Treat some documents as ecm domain objects. + objtype, sep, tail = env.docname.rpartition('/') + make_index_entry = _ecm_index_objs.get(objtype) + if make_index_entry: + title = self.parse_title(env.docname) + # Insert the object link target. + targetid = '%s:%s' % (objtype, title) + targetnode = nodes.target('', '', ids=[targetid]) + self.document.insert(0, targetnode) + # Insert the object index entry. + indexnode = addnodes.index() + indexnode['entries'] = [make_index_entry(title, targetid)] + self.document.insert(0, indexnode) + # Add to ecm domain object inventory + _ecm_object_inventory(env, self.document, 1, objtype, targetid) + +class ECMObject(ObjectDescription): + + def handle_signature(self, sig, signode): + # called from sphinx.directives.ObjectDescription.run() + signode += addnodes.desc_name(sig, sig) + return sig + + def add_target_and_index(self, name, sig, signode): + targetid = '%s:%s' % (self.objtype, name) + if targetid not in self.state.document.ids: + signode['names'].append(targetid) + signode['ids'].append(targetid) + signode['first'] = (not self.names) + self.state.document.note_explicit_target(signode) + _ecm_object_inventory(self.env, self.state.document, + self.lineno, self.objtype, targetid) + + make_index_entry = _ecm_index_objs.get(self.objtype) + if make_index_entry: + self.indexnode['entries'].append(make_index_entry(name, targetid)) + +class ECMXRefRole(XRefRole): + + # See sphinx.util.nodes.explicit_title_re; \x00 escapes '<'. + _re = re.compile(r'^(.+?)(\s*)(?<!\x00)<(.*?)>$', re.DOTALL) + _re_sub = re.compile(r'^([^()\s]+)\s*\(([^()]*)\)$', re.DOTALL) + + def __call__(self, typ, rawtext, text, *args, **keys): + # CMake cross-reference targets may contain '<' so escape + # any explicit `<target>` with '<' not preceded by whitespace. + while True: + m = ECMXRefRole._re.match(text) + if m and len(m.group(2)) == 0: + text = '%s\x00<%s>' % (m.group(1), m.group(3)) + else: + break + return XRefRole.__call__(self, typ, rawtext, text, *args, **keys) + +class ECMDomain(Domain): + """ECM domain.""" + name = 'ecm' + label = 'ECM' + object_types = { + 'module': ObjType('module', 'module'), + 'kde-module': ObjType('kde-module', 'kde-module'), + 'find-module': ObjType('find-module', 'find-module'), + 'manual': ObjType('manual', 'manual'), + } + directives = {} + roles = { + 'module': XRefRole(), + 'kde-module': XRefRole(), + 'find-module': XRefRole(), + 'manual': XRefRole(), + } + initial_data = { + 'objects': {}, # fullname -> docname, objtype + } + + def clear_doc(self, docname): + for fullname, (fn, _) in self.data['objects'].items(): + if fn == docname: + del self.data['objects'][fullname] + + def resolve_xref(self, env, fromdocname, builder, + typ, target, node, contnode): + targetid = '%s:%s' % (typ, target) + obj = self.data['objects'].get(targetid) + if obj is None: + # TODO: warn somehow? + return None + return make_refnode(builder, fromdocname, obj[0], targetid, + contnode, target) + + def get_objects(self): + for refname, (docname, type) in self.data['objects'].iteritems(): + yield (refname, refname, type, docname, refname, 1) + +def setup(app): + app.add_directive('ecm-module', ECMModule) + app.add_transform(ECMTransform) + app.add_domain(ECMDomain) diff --git a/docs/sphinx/kde-favicon.ico b/docs/sphinx/kde-favicon.ico Binary files differnew file mode 100644 index 00000000..3741beba --- /dev/null +++ b/docs/sphinx/kde-favicon.ico diff --git a/docs/sphinx/static/ecm.css b/docs/sphinx/static/ecm.css new file mode 100644 index 00000000..2a326d47 --- /dev/null +++ b/docs/sphinx/static/ecm.css @@ -0,0 +1,8 @@ +/* Import the Sphinx theme style. */ +@import url("default.css"); + +/* Wrap sidebar content even within words so that long + document names do not escape sidebar borders. */ +div.sphinxsidebarwrapper { + word-wrap: break-word; +} diff --git a/find-modules/FindEGL.cmake b/find-modules/FindEGL.cmake index 6237f5cb..765b6692 100644 --- a/find-modules/FindEGL.cmake +++ b/find-modules/FindEGL.cmake @@ -1,20 +1,55 @@ -# Try to find EGL on a Unix system +#.rst: +# FindEGL +# ------- # -# This will define: +# Try to find EGL on a Unix system. # -# EGL_FOUND - True if EGL is available -# EGL_LIBRARIES - Link these to use EGL -# EGL_INCLUDE_DIRS - Include directory for EGL -# EGL_DEFINITIONS - Compiler flags for using EGL +# This will define the following variables: # -# Additionally, the following imported targets will be defined: +# ``EGL_FOUND`` +# True if EGL is available +# ``EGL_LIBRARIES`` +# Link these to use EGL +# ``EGL_INCLUDE_DIRS`` +# Include directory for EGL +# ``EGL_DEFINITIONS`` +# Compiler flags for using EGL # -# EGL::EGL +# and the following imported targets: # -# Copyright (c) 2014 Martin Gräßlin <mgraesslin@kde.org> +# ``EGL::EGL`` +# The EGL library # -# Redistribution and use is allowed according to the terms of the BSD license. -# For details see the accompanying COPYING-CMAKE-SCRIPTS file. +# 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. + +#============================================================================= +# Copyright 2014 Martin Gräßlin <mgraesslin@kde.org> +# +# 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. +#============================================================================= if(CMAKE_VERSION VERSION_LESS 2.8.12) message(FATAL_ERROR "CMake 2.8.12 is required by FindEGL.cmake") diff --git a/find-modules/FindOpenEXR.cmake b/find-modules/FindOpenEXR.cmake index 00a2364e..85afebdf 100644 --- a/find-modules/FindOpenEXR.cmake +++ b/find-modules/FindOpenEXR.cmake @@ -1,17 +1,32 @@ -# Try to find the OpenEXR libraries +#.rst: +# FindOpenEXR +# ----------- # -# This will define: +# Try to find the OpenEXR libraries. # -# OpenEXR_FOUND - True if OpenEXR is available -# OpenEXR_LIBRARIES - Link to these to use OpenEXR -# OpenEXR_INCLUDE_DIRS - Include directory for OpenEXR -# OpenEXR_DEFINITIONS - Compiler flags required to link against OpenEXR -# OpenEXR::IlmImf - imported target to link against (instead of using the above variables) +# This will define the following variables: # +# ``OpenEXR_FOUND`` +# True if OpenEXR is available +# ``OpenEXR_LIBRARIES`` +# Link to these to use OpenEXR +# ``OpenEXR_INCLUDE_DIRS`` +# Include directory for OpenEXR +# ``OpenEXR_DEFINITIONS`` +# Compiler flags required to link against OpenEXR +# +# and the following imported targets: +# +# ``OpenEXR::IlmImf`` +# The OpenEXR core 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. - -# Copyright (c) 2006, Alexander Neundorf, <neundorf@kde.org> -# Copyright (c) 2013-2014, Alex Merry, <alex.merry@kdemail.net> +#============================================================================= +# Copyright 2013-2014 Alex Merry <alex.merry@kdemail.net> +# Copyright 2006 Alexander Neundorf <neundorf@kde.org> # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions @@ -35,6 +50,7 @@ # 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. +#============================================================================= if(${CMAKE_VERSION} VERSION_LESS 2.8.12) diff --git a/find-modules/FindSharedMimeInfo.cmake b/find-modules/FindSharedMimeInfo.cmake index 8dc6f1c4..263a5028 100644 --- a/find-modules/FindSharedMimeInfo.cmake +++ b/find-modules/FindSharedMimeInfo.cmake @@ -1,29 +1,56 @@ -# Try to find the shared-mime-info package +#.rst: +# FindSharedMimeInfo +# ------------------ # -# This will define +# Try to find the shared-mime-info package. # -# SharedMimeInfo_FOUND - True if system has the shared-mime-info package -# UPDATE_MIME_DATABASE_EXECUTABLE - The update-mime-database executable +# This will define the following variables: # -# In addition, the following targets are defined: +# ``SharedMimeInfo_FOUND`` +# True if system has the shared-mime-info package +# ``UPDATE_MIME_DATABASE_EXECUTABLE`` +# The update-mime-database executable # -# SharedMimeInfo::UpdateMimeDatabase +# and the following imported targets: # -# The follow macro is available: +# ``SharedMimeInfo::UpdateMimeDatabase`` +# The update-mime-database executable # -# update_xdg_mimetypes(path) +# The follow macro is available:: # -# Updates the XDG mime database at install time (unless the DESTDIR environment -# variable is set, in which case it is up to package managers to perform this -# task). +# update_xdg_mimetypes(<path>) # +# Updates the XDG mime database at install time (unless the ``$DESTDIR`` +# environment variable is set, in which case it is up to package managers to +# perform this task). - -# Copyright (c) 2007, Pino Toscano, <toscano.pino@tiscali.it> -# Copyright (c) 2013-2014, Alex Merry, <alex.merry@kdemail.net> +#============================================================================= +# Copyright 2013-2014 Alex Merry <alex.merry@kdemail.net> +# Copyright 2007 Pino Toscano <toscano.pino@tiscali.it> +# +# 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. # -# Redistribution and use is allowed according to the terms of the BSD license. -# For details see the accompanying COPYING-CMAKE-SCRIPTS file. +# 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. +#============================================================================= if(CMAKE_VERSION VERSION_LESS 2.8.12) message(FATAL_ERROR "CMake 2.8.12 is required by FindSharedMimeInfo.cmake") diff --git a/find-modules/FindWayland.cmake b/find-modules/FindWayland.cmake index c7c599c2..b7790e75 100644 --- a/find-modules/FindWayland.cmake +++ b/find-modules/FindWayland.cmake @@ -1,8 +1,12 @@ -# Try to find Wayland on a Unix system +#.rst: +# FindWayland +# ----------- +# +# Try to find Wayland on a Unix system. # # This is a component-based find module, which makes use of the COMPONENTS # and OPTIONAL_COMPONENTS arguments to find_module. The following components -# are available: +# are available:: # # Client Server Cursor Egl # @@ -12,33 +16,51 @@ # This module will define the following variables, independently of the # components searched for or found: # -# Wayland_FOUND - True if (the requestion version of) Wayland is available -# Wayland_VERSION - Found Wayland version +# ``Wayland_FOUND`` +# True if (the requestion version of) Wayland is available +# ``Wayland_VERSION`` +# Found Wayland version # -# For each searched-for components, Wayland_<component>_FOUND will be set to true -# if the corresponding Wayland library was found, and false otherwise. If -# Wayland_<component>_FOUND is true, the imported target Wayland::<component> will be -# defined. This module will also attempt to determine Wayland_*_VERSION variables -# for each imported target, although Wayland_VERSION should normally be sufficient. +# For each searched-for components, ``Wayland_<component>_FOUND`` will be set to +# true if the corresponding Wayland library was found, and false otherwise. If +# ``Wayland_<component>_FOUND`` is true, the imported target +# ``Wayland::<component>`` will be defined. This module will also attempt to +# determine ``Wayland_*_VERSION`` variables for each imported target, although +# ``Wayland_VERSION`` should normally be sufficient. # # The following variable will also be defined for convenience, and for # compatibility with old-style find module conventions: # -# Wayland_LIBRARIES - A list of all Wayland imported targets +# ``Wayland_LIBRARIES`` +# A list of all Wayland imported targets #============================================================================= -# Copyright 2014 Martin Gräßlin <mgraesslin@kde.org> # Copyright 2014 Alex Merry <alex.merry@kde.org> +# Copyright 2014 Martin Gräßlin <mgraesslin@kde.org> +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions +# are met: # -# Distributed under the OSI-approved BSD License (the "License"); -# see accompanying file COPYING-CMAKE-SCRIPTS for details. +# 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 distributed WITHOUT ANY WARRANTY; without even the -# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -# See the License for more information. +# 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. #============================================================================= -# (To distribute this file outside of extra-cmake-modules, substitute the full -# License text for the above reference.) include(${CMAKE_CURRENT_LIST_DIR}/../modules/ECMFindModuleHelpers.cmake) diff --git a/find-modules/FindX11_XCB.cmake b/find-modules/FindX11_XCB.cmake index e2c18a99..687a4f3d 100644 --- a/find-modules/FindX11_XCB.cmake +++ b/find-modules/FindX11_XCB.cmake @@ -1,17 +1,46 @@ -# - Try to find libX11-xcb -# Once done this will define +#.rst: +# FindX11_XCB +# ----------- # -# X11_XCB_FOUND - system has libX11-xcb -# X11_XCB_LIBRARIES - Link these to use libX11-xcb -# X11_XCB_INCLUDE_DIR - the libX11-xcb include dir -# X11_XCB_DEFINITIONS - compiler switches required for using libX11-xcb +# This will define the following variables: +# +# ``X11_XCB_FOUND`` +# System has libX11-xcb +# ``X11_XCB_LIBRARIES`` +# Link these to use libX11-xcb +# ``X11_XCB_INCLUDE_DIR`` +# The libX11-xcb include dir +# ``X11_XCB_DEFINITIONS`` +# Compiler switches required for using libX11-xcb -# Copyright (c) 2011 Fredrik Höglund <fredrik@kde.org> -# Copyright (c) 2008 Helio Chissini de Castro, <helio@kde.org> -# Copyright (c) 2007 Matthias Kretz, <kretz@kde.org> +#============================================================================= +# Copyright 2011 Fredrik Höglund <fredrik@kde.org> +# Copyright 2008 Helio Chissini de Castro <helio@kde.org> +# Copyright 2007 Matthias Kretz <kretz@kde.org> +# +# 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. # -# Redistribution and use is allowed according to the terms of the BSD license. -# For details see the accompanying COPYING-CMAKE-SCRIPTS file. +# 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. +#============================================================================= IF (NOT WIN32) # use pkg-config to get the directories and then use these values diff --git a/find-modules/FindXCB.cmake b/find-modules/FindXCB.cmake index a900a624..dd876b21 100644 --- a/find-modules/FindXCB.cmake +++ b/find-modules/FindXCB.cmake @@ -1,8 +1,12 @@ -# Try to find XCB on a Unix system +#.rst: +# FindXCB +# ------- # -# This is a component-based find module, which makes use of the COMPONENTS -# and OPTIONAL_COMPONENTS arguments to find_module. The following components -# are available: +# Try to find XCB on a Unix system. +# +# This is a component-based find module, which makes use of the COMPONENTS and +# OPTIONAL_COMPONENTS arguments to find_module. The following components are +# available:: # # XCB # ATOM AUX COMPOSITE CURSOR DAMAGE @@ -19,34 +23,52 @@ # This module will define the following variables, independently of the # components searched for or found: # -# XCB_FOUND - True if (the requestion version of) xcb is available -# XCB_VERSION - Found xcb version +# ``XCB_FOUND`` +# True if (the requestion version of) xcb is available +# ``XCB_VERSION`` +# Found xcb version # -# For each searched-for components, XCB_<component>_FOUND will be set to true -# if the corresponding xcb library was found, and false otherwise. If -# XCB_<component>_FOUND is true, the imported target XCB::<component> will be -# defined. This module will also attempt to determine XCB_*_VERSION variables -# for each imported target, although XCB_VERSION should normally be sufficient. +# For each searched-for components, ``XCB_<component>_FOUND`` will be set to +# true if the corresponding xcb library was found, and false otherwise. If +# ``XCB_<component>_FOUND`` is true, the imported target ``XCB::<component>`` +# will be defined. This module will also attempt to determine +# ``XCB_*_VERSION`` variables for each imported target, although +# ``XCB_VERSION`` should normally be sufficient. # # The following variable will also be defined for convenience, and for # compatibility with old-style find module conventions: # -# XCB_LIBRARIES - A list of all XCB imported targets +# ``XCB_LIBRARIES`` +# A list of all XCB imported targets #============================================================================= # Copyright 2011 Fredrik Höglund <fredrik@kde.org> # Copyright 2013 Martin Gräßlin <mgraesslin@kde.org> # Copyright 2014 Alex Merry <alex.merry@kde.org> # -# Distributed under the OSI-approved BSD License (the "License"); -# see accompanying file COPYING-CMAKE-SCRIPTS for details. +# 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 distributed WITHOUT ANY WARRANTY; without even the -# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -# See the License for more information. +# 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. #============================================================================= -# (To distribute this file outside of extra-cmake-modules, substitute the full -# License text for the above reference.) include(${CMAKE_CURRENT_LIST_DIR}/../modules/ECMFindModuleHelpers.cmake) diff --git a/kde-modules/KDECMakeSettings.cmake b/kde-modules/KDECMakeSettings.cmake index 3f675519..c206ff82 100644 --- a/kde-modules/KDECMakeSettings.cmake +++ b/kde-modules/KDECMakeSettings.cmake @@ -1,46 +1,64 @@ -# Change various CMake settings to what the KDE community views as more +#.rst: +# KDECMakeSettings +# ---------------- +# +# Changes various CMake settings to what the KDE community views as more # sensible defaults. # -# It is split into three parts, which can be independently disabled if -# desired. +# It is split into three parts, which can be independently disabled if desired. +# +# Runtime Paths +# ~~~~~~~~~~~~~ # -# RPATH +# The default runtime path (used on Unix systems to search for +# dynamically-linked libraries) is set to include the location that libraries +# will be installed to (as set in LIB_INSTALL_DIR), and also the linker search +# path. # -# The default runtime path (used on Unix systems to search for -# dynamically-linked libraries) is set to include the location that -# libraries will be installed to (as set in LIB_INSTALL_DIR), and also -# the linker search path. +# Note that ``LIB_INSTALL_DIR`` needs to be set before including this module. +# Typically, this is done by including the :kde-module:`KDEInstallDirs` module. # -# Note that LIB_INSTALL_DIR needs to be set before including this -# module. Typically, this is done by including the KDEInstallDirs -# module. +# This section can be disabled by setting ``KDE_SKIP_RPATH_SETTINGS`` to TRUE +# before including this module. # -# This section can be disabled by setting -# KDE_SKIP_RPATH_SETTINGS -# to TRUE before including this module. # +# Testing +# ~~~~~~~ # -# TEST +# Testing is enabled by default, and an option (BUILD_TESTING) is provided for +# users to control this. See the CTest module documentation in the CMake manual +# for more details. # -# Testing is enabled by default, and an option (BUILD_TESTING) is -# provided for users to control this. See the CTest module -# documentation in the CMake manual for more details. +# This section can be disabled by setting ``KDE_SKIP_TEST_SETTINGS`` to TRUE +# before including this module. # -# This section can be disabled by setting -# KDE_SKIP_TEST_SETTINGS -# to TRUE before including this module. # +# Build Settings +# ~~~~~~~~~~~~~~ # -# BUILD +# Various CMake build defaults are altered, such as searching source and build +# directories for includes first and enabling automoc by default. # -# Various CMake build defaults are altered, such as searching source -# and build directories for includes first and enabling automoc by -# default. +# This section can be disabled by setting ``KDE_SKIP_BUILD_SETTINGS`` to TRUE +# before including this module. + +#============================================================================= +# Copyright 2014 Alex Merry <alex.merry@kde.org> +# Copyright 2013 Aleix Pol <aleixpol@kde.org> +# Copyright 2012-2013 Stephen Kelly <steveire@gmail.com> +# Copyright 2007 Matthias Kretz <kretz@kde.org> +# Copyright 2006-2007 Laurent Montel <montel@kde.org> +# Copyright 2006-2013 Alex Neundorf <neundorf@kde.org> # -# This section can be disabled by setting -# KDE_SKIP_BUILD_SETTINGS -# to TRUE before including this module. +# 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.) ################# RPATH handling ################################## diff --git a/kde-modules/KDECompilerSettings.cmake b/kde-modules/KDECompilerSettings.cmake index d1f9d298..229e4f59 100644 --- a/kde-modules/KDECompilerSettings.cmake +++ b/kde-modules/KDECompilerSettings.cmake @@ -1,3 +1,7 @@ +#.rst: +# KDECompilerSettings +# ------------------- +# # Set useful compile and link flags for C++ (and C) code. # # Enables many more warnings than the default, and sets stricter modes @@ -5,25 +9,44 @@ # kde_target_enable_exceptions() can be used to re-enable them for a # specific target. # -# -# This module provides the following functions: +# This module provides the following functions:: # # kde_source_files_enable_exceptions([file1 [file2 [...]]]) # # Enables exceptions for specific source files. This should not be # used on source files in a language other than C++. # +# :: +# # kde_target_enable_exceptions(target <INTERFACE|PUBLIC|PRIVATE>) # # Enables exceptions for a specific target. This should not be used # on a target that has source files in a language other than C++. # +# :: +# # kde_enable_exceptions() # # Enables exceptions for C++ source files compiled for the # CMakeLists.txt file in the current directory and all subdirectories. -# +#============================================================================= +# Copyright 2014 Alex Merry <alex.merry@kde.org> +# Copyright 2013 Stephen Kelly <steveire@gmail.com> +# Copyright 2012-2013 Raphael Kubo da Costa <rakuco@FreeBSD.org> +# Copyright 2007 Matthias Kretz <kretz@kde.org> +# Copyright 2006-2007 Laurent Montel <montel@kde.org> +# Copyright 2006-2013 Alex Neundorf <neundorf@kde.org> +# +# 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.) ############################################################ # Toolchain minimal requirements diff --git a/kde-modules/KDEFrameworkCompilerSettings.cmake b/kde-modules/KDEFrameworkCompilerSettings.cmake index d0bf4dd7..3b77fc3c 100644 --- a/kde-modules/KDEFrameworkCompilerSettings.cmake +++ b/kde-modules/KDEFrameworkCompilerSettings.cmake @@ -1,4 +1,8 @@ -# Set stricter compile and link flags for KDE Frameworks modules +#.rst: +# KDEFrameworkCompilerSettings +# ---------------------------- +# +# Set stricter compile and link flags for KDE Frameworks modules. # # The KDECompilerSettings module is included and, in addition, various # defines that affect the Qt libraries are set to enforce certain @@ -7,7 +11,22 @@ # For example, constructions like QString("foo") are prohibited, instead # forcing the use of QLatin1String or QStringLiteral, and some # Qt-defined keywords like signals and slots will not be defined. + +#============================================================================= +# Copyright 2013 Albert Astals Cid <aacid@kde.org> +# Copyright 2007 Matthias Kretz <kretz@kde.org> +# Copyright 2006-2007 Laurent Montel <montel@kde.org> +# Copyright 2006-2013 Alex Neundorf <neundorf@kde.org> +# +# 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.) include(KDECompilerSettings) diff --git a/kde-modules/KDEInstallDirs.cmake b/kde-modules/KDEInstallDirs.cmake index 9ff23540..299e919e 100644 --- a/kde-modules/KDEInstallDirs.cmake +++ b/kde-modules/KDEInstallDirs.cmake @@ -1,68 +1,122 @@ -# Define KDE standard installation directories -# -# Inclusion of this module defines the following variables (default -# values in parentheses): -# -# BUNDLE_INSTALL_DIR - (Mac only) application bundles (/Applications/KDE5) -# BIN_INSTALL_DIR - user executables (bin) -# SBIN_INSTALL_DIR - system admin executables (sbin) -# LIB_INSTALL_DIR - object code libraries (lib or lib64 or lib/<multiarch-tuple> on Debian) -# LIBEXEC_INSTALL_DIR - internal executables (${LIB_INSTALL_DIR}/kde5/libexec) -# INSTALL_TARGETS_DEFAULT_ARGS - combines BUNDLE_INSTALL_DIR, BIN_INSTALL_DIR and LIB_INSTALL_DIR; see below -# -# INCLUDE_INSTALL_DIR - C and C++ header files (include/KF5) -# -# QT_PLUGIN_INSTALL_DIR - Qt plugins (${LIB_INSTALL_DIR}/plugins) -# PLUGIN_INSTALL_DIR - KDE plugins (${QT_PLUGIN_INSTALL_DIR}/kf5) -# IMPORTS_INSTALL_DIR - QML imports (${QT_PLUGIN_INSTALL_DIR}/imports) -# QML_INSTALL_DIR - QML2 imports (${LIB_INSTALL_DIR}/qml) -# -# CMAKECONFIG_INSTALL_PREFIX - CMake configuration files (${LIB_INSTALL_DIR}/cmake) -# -# DATA_INSTALL_DIR - read-only architecture-independent data (share) -# KCONF_UPDATE_INSTALL_DIR - kconf_update files (${DATA_INSTALL_DIR}/kconf_update) -# -# DBUS_INTERFACES_INSTALL_DIR - dbus interfaces (share/dbus-1/interfaces) -# DBUS_SERVICES_INSTALL_DIR - dbus services (share/dbus-1/services) -# DBUS_SYSTEM_SERVICES_INSTALL_DIR - dbus system services (share/dbus-1/system-services) -# HTML_INSTALL_DIR - HTML documentation (share/doc/HTML) -# ICON_INSTALL_DIR - the icons (share/icons) -# KCFG_INSTALL_DIR - kconfig files (share/config.kcfg) -# LOCALE_INSTALL_DIR - translations (share/locale) -# MAN_INSTALL_DIR - man pages (share/man) -# SERVICES_INSTALL_DIR - service (desktop, protocol, ...) files (share/kde5/services) -# SERVICETYPES_INSTALL_DIR - service types desktop files (share/kde5/servicetypes) -# SOUND_INSTALL_DIR - sound files (share/sounds) -# TEMPLATES_INSTALL_DIR - templates (share/templates) -# WALLPAPER_INSTALL_DIR - wallpapers (share/wallpapers) -# XDG_APPS_INSTALL_DIR - application desktop files (share/applications/kde5) -# XDG_DIRECTORY_INSTALL_DIR - XDG directory (share/desktop-directories) -# XDG_MIME_INSTALL_DIR - mimetype XML files (share/mime/packages) -# -# SYSCONF_INSTALL_DIR - sysconfig files (etc) -# CONFIG_INSTALL_DIR - config files (${SYSCONF_INSTALL_DIR}/xdg) -# AUTOSTART_INSTALL_DIR - autostart files (${CONFIG_INSTALL_DIR}/autostart) -# -# EXEC_INSTALL_PREFIX - prefix for default values of BIN_INSTALL_DIR, SBIN_INSTALL_DIR and LIB_INSTALL_DIR (empty by default) -# SHARE_INSTALL_PREFIX - replaces "share" in the other variables if set -# -# The *_INSTALL_DIR variables may be passed to the DESTINATION options of -# install() commands for the corresponding file type. They are set in the CMake -# cache, and so the defaults above can be overridden by users. -# -# Note that these variables do not provide any information about the -# location of already-installed KDE software. +#.rst: +# KDEInstallDirs +# -------------- +# +# Define KDE standard installation directories. +# +# Inclusion of this module defines the following variables (default values in +# parentheses): +# +# ``BUNDLE_INSTALL_DIR`` +# (Mac only) application bundles (``/Applications/KDE5``) +# ``BIN_INSTALL_DIR`` +# user executables (``bin``) +# ``SBIN_INSTALL_DIR`` +# system admin executables (``sbin``) +# ``LIB_INSTALL_DIR`` +# object code libraries (``lib or lib64 or lib/<multiarch-tuple> on +# Debian``) +# ``LIBEXEC_INSTALL_DIR`` +# internal executables (``${LIB_INSTALL_DIR}/kde5/libexec``) +# ``INSTALL_TARGETS_DEFAULT_ARGS`` +# combines BUNDLE_INSTALL_DIR, BIN_INSTALL_DIR and LIB_INSTALL_DIR; see +# below +# ``INCLUDE_INSTALL_DIR`` +# C and C++ header files (``include/KF5``) +# ``QT_PLUGIN_INSTALL_DIR`` +# Qt plugins (``${LIB_INSTALL_DIR}/plugins``) +# ``PLUGIN_INSTALL_DIR`` +# KDE plugins (``${QT_PLUGIN_INSTALL_DIR}/kf5``) +# ``IMPORTS_INSTALL_DIR`` +# QML imports (``${QT_PLUGIN_INSTALL_DIR}/imports``) +# ``QML_INSTALL_DIR`` +# QML2 imports (``${LIB_INSTALL_DIR}/qml``) +# ``CMAKECONFIG_INSTALL_PREFIX`` +# CMake configuration files (``${LIB_INSTALL_DIR}/cmake``) +# ``DATA_INSTALL_DIR`` +# read-only architecture-independent data (``share``) +# ``KCONF_UPDATE_INSTALL_DIR`` +# kconf_update files (``${DATA_INSTALL_DIR}/kconf_update``) +# ``DBUS_INTERFACES_INSTALL_DIR`` +# dbus interfaces (``share/dbus-1/interfaces``) +# ``DBUS_SERVICES_INSTALL_DIR`` +# dbus services (``share/dbus-1/services``) +# ``DBUS_SYSTEM_SERVICES_INSTALL_DIR`` +# dbus system services (``share/dbus-1/system-services``) +# ``HTML_INSTALL_DIR`` +# HTML documentation (``share/doc/HTML``) +# ``ICON_INSTALL_DIR`` +# the icons (``share/icons``) +# ``KCFG_INSTALL_DIR`` +# kconfig files (``share/config.kcfg``) +# ``LOCALE_INSTALL_DIR`` +# translations (``share/locale``) +# ``MAN_INSTALL_DIR`` +# man pages (``share/man``) +# ``SERVICES_INSTALL_DIR`` +# service (desktop, protocol, ...) files (``share/kde5/services``) +# ``SERVICETYPES_INSTALL_DIR`` +# service types desktop files (``share/kde5/servicetypes``) +# ``SOUND_INSTALL_DIR`` +# sound files (``share/sounds``) +# ``TEMPLATES_INSTALL_DIR`` +# templates (``share/templates``) +# ``WALLPAPER_INSTALL_DIR`` +# wallpapers (``share/wallpapers``) +# ``XDG_APPS_INSTALL_DIR`` +# application desktop files (``share/applications/kde5``) +# ``XDG_DIRECTORY_INSTALL_DIR`` +# XDG directory (``share/desktop-directories``) +# ``XDG_MIME_INSTALL_DIR`` +# mimetype XML files (``share/mime/packages``) +# ``SYSCONF_INSTALL_DIR`` +# sysconfig files (``etc``) +# ``CONFIG_INSTALL_DIR`` +# config files (``${SYSCONF_INSTALL_DIR}/xdg``) +# ``AUTOSTART_INSTALL_DIR`` +# autostart files (``${CONFIG_INSTALL_DIR}/autostart``) +# ``EXEC_INSTALL_PREFIX`` +# prefix for default values of BIN_INSTALL_DIR, SBIN_INSTALL_DIR and +# LIB_INSTALL_DIR (``empty by default``) +# ``SHARE_INSTALL_PREFIX`` +# replaces "share" in the other variables if set +# +# The ``*_INSTALL_DIR`` variables may be passed to the DESTINATION options of +# install() commands for the corresponding file type. They are set in the +# CMake cache, and so the defaults above can be overridden by users. +# +# Note that these variables do not provide any information about the location of +# already-installed KDE software. # # The INSTALL_TARGETS_DEFAULT_ARGS variable should be used when libraries or # user-executable applications are installed, in the following manner: # -# install(TARGETS mylib myapp ${INSTALL_TARGETS_DEFAULT_ARGS}) +# .. code-block:: cmake +# +# install(TARGETS mylib myapp ${INSTALL_TARGETS_DEFAULT_ARGS}) # # It MUST NOT be used for installing plugins, system admin executables or # executables only intended for use internally by other code. Those should use # one of the PLUGIN variables, SBIN_INSTALL_DIR or LIBEXEC_INSTALL_DIR # respectively. -# + +#============================================================================= +# Copyright 2014 Alex Merry <alex.merry@kde.org> +# Copyright 2013 Stephen Kelly <steveire@gmail.com> +# Copyright 2012 David Faure <faure@kde.org> +# Copyright 2007 Matthias Kretz <kretz@kde.org> +# Copyright 2006-2007 Laurent Montel <montel@kde.org> +# Copyright 2006-2013 Alex Neundorf <neundorf@kde.org> +# +# 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.) # Figure out what the default install directory for libraries should be. diff --git a/modules/ECMAddTests.cmake b/modules/ECMAddTests.cmake index 67026eca..9052d886 100644 --- a/modules/ECMAddTests.cmake +++ b/modules/ECMAddTests.cmake @@ -1,28 +1,50 @@ -include(ECMMarkAsTest) -include(ECMMarkNonGuiExecutable) -# This file provides the functions ecm_add_test() and ecm_add_tests(). +#.rst: +# ECMAddTests +# ----------- +# +# Add test executables. +# +# :: +# +# ecm_add_test(<sources> LINK_LIBRARIES <library> [<library> [...]] +# [TEST_NAME <name>] +# [NAME_PREFIX <prefix>] +# [GUI]) # -# ecm_add_test(<sources> TEST_NAME <name> NAME_PREFIX <prefix> LINK_LIBRARIES <libraries/targets> [GUI]) +# Add a new unit test using the passed source files. The parameter TEST_NAME is +# used to set the name of the resulting test. It may be omitted if there is +# exactly one source file. In that case the name of the source file (without the +# file extension) will be used as the test name. If the flag GUI is passed the +# test binary will be a GUI executable, otherwise the resulting binary will be a +# console application. The test will be linked against the libraries and/or +# targets passed to LINK_LIBRARIES. # -# Add a new unit test using the passed source files. The parameter TEST_NAME is used to set the name -# of the resulting test. It may be omitted if there is exactly one source file. In that case the name of -# the source file (without the file extension) will be used as the test name. -# If the flag GUI is passed the test binary will be a GUI executable, otherwise the resulting -# binary will be a console application. # -# ecm_add_tests(<sources> NAME_PREFIX <prefix> LINK_LIBRARIES <libraries/targets> [GUI]) +# :: # -# Add a new unit test for every source file passed. The name of the tests will be the name of the -# corresponding source file minus the file extension. If NAME_PREFIX is set, that string will be -# prepended to each of the unit test names. Each of the unit tests will be linked against the -# libraries and/or targets passed in the LINK_LIBRARIES parameter. -# If the flag GUI is passed the test binary will be a GUI executable, otherwise the resulting -# binary will be a console application. +# ecm_add_tests(<sources> LINK_LIBRARIES <library> [<library> [...]] +# [NAME_PREFIX <prefix>] +# [GUI]) # -# Copyright (c) 2013, Alexander Richardson, <arichardson.kde@gmail.com> +# This is a convenient version of ecm_add_test() for when you have many tests +# that consist of a single source file each. It behaves like calling +# ecm_add_test() once for each source file, with the same named arguments. + +#============================================================================= +# Copyright 2013 Alexander Richardson <arichardson.kde@gmail.com> +# +# Distributed under the OSI-approved BSD License (the "License"); +# see accompanying file COPYING-CMAKE-SCRIPTS for details. # -# Redistribution and use is allowed according to the terms of the BSD license. -# For details see the accompanying COPYING-CMAKE-SCRIPTS file. +# 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.) + +include(ECMMarkAsTest) +include(ECMMarkNonGuiExecutable) function(ecm_add_test) set(options GUI) diff --git a/modules/ECMCreateQmFromPoFiles.cmake b/modules/ECMCreateQmFromPoFiles.cmake index f24090b7..92d0d1a8 100644 --- a/modules/ECMCreateQmFromPoFiles.cmake +++ b/modules/ECMCreateQmFromPoFiles.cmake @@ -1,12 +1,20 @@ -# ecm_create_qm_from_po_files(PO_DIR <po_dir> -# POT_NAME <pot_name> -# [DATA_INSTALL_DIR <data_install_dir>] -# [DATA_INSTALL_SUB_DIR <data_install_sub_dir>] -# [CREATE_LOADER <source_file_var>]) +#.rst: +# ECMCreateQmFromPoFiles +# ---------------------- # -# ecm_create_qm_from_po_files() creates the necessary rules to compile .po -# files into .qm files, usable by QTranslator. It can also generate a C++ file -# which takes care of automatically loading those translations. +# Generate QTranslator (.qm) catalogs from Gettext (.po) catalogs. +# +# :: +# +# ecm_create_qm_from_po_files(PO_DIR <po_dir> +# POT_NAME <pot_name> +# [DATA_INSTALL_DIR <data_install_dir>] +# [DATA_INSTALL_SUB_DIR <data_install_sub_dir>] +# [CREATE_LOADER <source_file_var>]) +# +# Creates the necessary rules to compile .po files into .qm files, usable by +# QTranslator. It can also generate a C++ file which takes care of automatically +# loading those translations. # # PO_DIR is the path to a directory containing .po files. # @@ -18,7 +26,9 @@ # DATA_INSTALL_DIR defaults to ${DATA_INSTALL_DIR} if defined, otherwise it uses # "share". It must point to a directory which is in the list returned by: # -# QStandardPath::standardLocations(QStandardPath::GenericDataLocation) +# .. code-block:: cpp +# +# QStandardPath::standardLocations(QStandardPath::GenericDataLocation) # # otherwise the C++ loader will fail to load the translations. # @@ -33,14 +43,24 @@ # at startup. The path of the .cpp file is stored in <source_file_var>. This # variable must be added to the list of sources to build, like this: # +# .. code-block:: cmake +# # ecm_create_qm_from_po_files(PO_DIR po POT_NAME mylib CREATE_LOADER myloader) # set(mylib_SRCS foo.cpp bar.cpp ${myloader}) # add_library(mylib ${mylib_SRCS}) + +#============================================================================= +# Copyright 2014 Aurélien Gâteau <agateau@kde.org> # -# Copyright (c) 2014, Aurélien Gâteau, <agateau@kde.org> +# Distributed under the OSI-approved BSD License (the "License"); +# see accompanying file COPYING-CMAKE-SCRIPTS for details. # -# Redistribution and use is allowed according to the terms of the BSD license. -# For details see the accompanying COPYING-CMAKE-SCRIPTS file. +# 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.) # This gives us Qt5::lrelease and Qt5::lupdate but unfortunately no Qt5::lconvert # See https://bugreports.qt-project.org/browse/QTBUG-37937 diff --git a/modules/ECMDBusAddActivationService.cmake b/modules/ECMDBusAddActivationService.cmake index d65be03c..128482e3 100644 --- a/modules/ECMDBusAddActivationService.cmake +++ b/modules/ECMDBusAddActivationService.cmake @@ -1,35 +1,48 @@ -# Install a DBus ".service" file, so that a program can be started via DBus activation. +#.rst: +# ECMDBusAddActivationService +# --------------------------- # -# ecm_dbus_add_activation_service(inputfile) +# Install D-Bus activation .service files. # -# This macro will read the input file, generate a .service file from it, and install it -# into the right directory for the dbus server to find it. +# :: # -# Note that in the case of custom install prefixes, the user will have to add the prefix -# to XDG_DATA_DIRS before starting the DBus server. +# ecm_dbus_add_activation_service(<inputfile> [<inputfile> [...]]) +# +# This macro will configure the input file to generate a .service file, and +# install it into the right directory for the dbus server to find it. +# +# Note that in the case of custom install prefixes, the user will have to add +# the prefix to XDG_DATA_DIRS before starting the DBus server. # # Example: +# +# .. code-block:: cmake +# # ecm_dbus_add_activation_service(org.mydomain.myapp.service.in) # -# The file org.mydomain.myapp.service.in contains: +# The file org.mydomain.myapp.service.in contains:: # -# [D-BUS Service] -# Name=org.mydomain.myapp -# Exec=@CMAKE_INSTALL_PREFIX@/bin/myapp +# [D-BUS Service] +# Name=org.mydomain.myapp +# Exec=@CMAKE_INSTALL_PREFIX@/bin/myapp # # This will create and install PREFIX/share/dbus-1/services/org.mydomain.myapp.service # # See http://techbase.kde.org/Development/Tutorials/D-Bus/Autostart_Services for # a more complete documentation. -# + +#============================================================================= # Copyright 2012 David Faure <faure@kde.org> # # Distributed under the OSI-approved BSD License (the "License"); -# see accompanying file Copyright.txt for details. +# 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.) macro(ecm_dbus_add_activation_service _sources) foreach(_i ${_sources}) @@ -37,6 +50,8 @@ macro(ecm_dbus_add_activation_service _sources) string(REGEX REPLACE "\\.service.*$" ".service" _output_file ${_i}) set(_target ${CMAKE_CURRENT_BINARY_DIR}/${_output_file}) configure_file(${_service_file} ${_target}) + # FIXME: document use of ${DBUS_SERVICES_INSTALL_DIR}, and provide a + # fallback install(FILES ${_target} DESTINATION ${DBUS_SERVICES_INSTALL_DIR}) endforeach() endmacro() diff --git a/modules/ECMFindModuleHelpers.cmake b/modules/ECMFindModuleHelpers.cmake index e38fcaf2..15df9ef0 100644 --- a/modules/ECMFindModuleHelpers.cmake +++ b/modules/ECMFindModuleHelpers.cmake @@ -1,13 +1,23 @@ -# Helper macros for find modules +#.rst: +# ECMFindModuleHelpers +# -------------------- +# +# Helper macros for find modules: ecm_find_package_version_check(), +# ecm_find_package_parse_components() and +# ecm_find_package_handle_library_components(). +# +# :: # # ecm_find_package_version_check(<name>) # # Prints warnings if the CMake version or the project's required CMake version # is older than that required by extra-cmake-modules. # +# :: +# # ecm_find_package_parse_components(<name> # RESULT_VAR <variable> -# KNOWN_COMPONENTS <component> [<component>]* +# KNOWN_COMPONENTS <component1> [<component2> [...]] # [SKIP_DEPENDENCY_HANDLING]) # # This macro will populate <variable> with a list of components found in @@ -24,8 +34,10 @@ # If <component> is listed in <name>_FIND_COMPONENTS, then all its (transitive) # dependencies will also be added to <variable>. # +# :: +# # ecm_find_package_handle_library_components(<name> -# COMPONENTS <component> [<component>]* +# COMPONENTS <component> [<component> [...]] # [SKIP_DEPENDENCY_HANDLING]) # [SKIP_PKG_CONFIG]) # @@ -65,6 +77,9 @@ # the component that is searched for first (note that components are searched # for in the order they are passed to the macro). +# FIXME: we should actually set proper traditional variables, because it can +# be convenient to use them in the link interface of exported libraries + #============================================================================= # Copyright 2014 Alex Merry <alex.merry@kde.org> # diff --git a/modules/ECMGenerateHeaders.cmake b/modules/ECMGenerateHeaders.cmake index 739c2117..bac50869 100644 --- a/modules/ECMGenerateHeaders.cmake +++ b/modules/ECMGenerateHeaders.cmake @@ -1,26 +1,23 @@ -# - Function to generate forward includes for your project -# This module provides the function ECM_GENERATE_HEADERS +#.rst: +# ECMGenerateHeaders +# ------------------ # -# The ECM_GENERATE_HEADERS function is used to generate C/C++ forwarding header -# files for your project. +# Generate C/C++ CamelCase forwarding headers. # -# To be more precise, there will be two kinds of headers being generated. Lowercase -# and CamelCase, for convenience. That means that for a class named "ClassA" in a -# module called "Module" we will get 2 different files: Module/ClassA and -# module/classa.h. Both these files will be including a "classa.h" file that is -# expected to be in the headers dir (see HEADERS_DIR argument below). +# :: # -# ECM_GENERATE_HEADERS(camelcase_headers_var -# HEADER_NAMES ClassA [ClassB [...]] -# [OUTPUT_DIR output_dir] -# [PREFIX prefix] -# [REQUIRED_HEADERS variable] -# [RELATIVE relative_path]) +# ecm_generate_headers(<camelcase_headers_var> +# HEADER_NAMES <CamelCaseHeader> [<CamelCaseHeader> [...]] +# [OUTPUT_DIR <output_dir>] +# [PREFIX <prefix>] +# [REQUIRED_HEADERS <variable>] +# [RELATIVE <relative_path>]) # -# The paths to the generated CamelCase headers will be appended to -# camelcase_headers_var. -# -# HEADER_NAMES lists the generated CamelCase header names. +# For each CamelCase header name passed to HEADER_NAMES, a file of that name +# will be generated that will include a lowercased version with ``.h`` appended. +# For example, the header ``ClassA`` will include ``classa.h``. The file +# locations of these generated headers will be stored in +# <camelcase_headers_var>. # # PREFIX places the headers in subdirectories. This should be a CamelCase name # like KParts, which will cause the CamelCase headers to be placed in the KParts @@ -30,67 +27,81 @@ # used before installation, as long as the include_directories are set # appropriately. # -# The OUTPUT_DIR argument specifies where the files will be generated; this -# should be within the build directory. By default, CMAKE_CURRENT_BINARY_DIR -# will be used. This option can be used to avoid file conflicts. +# OUTPUT_DIR specifies where the files will be generated; this should be within +# the build directory. By default, ``${CMAKE_CURRENT_BINARY_DIR}`` will be used. +# This option can be used to avoid file conflicts. # -# The REQUIRED_HEADERS argument specifies an output variable name where all the -# required headers will be appended so that they can be installed together with -# the generated ones. This is mostly intended as a convenience so that adding a -# new header to a project only requires specifying the CamelCase variant in the +# REQUIRED_HEADERS specifies an output variable name where all the required +# headers will be appended so that they can be installed together with the +# generated ones. This is mostly intended as a convenience so that adding a new +# header to a project only requires specifying the CamelCase variant in the # CMakeLists.txt file; the lowercase variant will then be added to this # variable. # # The RELATIVE argument indicates where the lowercase headers can be found # relative to CMAKE_CURRENT_SOURCE_DIR. It does not affect the generated -# CamelCase files, but ECM_GENERATE_HEADERS uses it when checking that the +# CamelCase files, but ecm_generate_headers() uses it when checking that the # lowercase header exists, and to generate lowercase forwarding headers when # PREFIX is set. # # To allow other parts of the source distribution (eg: tests) to use the # generated headers before installation, it may be desirable to set the # INCLUDE_DIRECTORIES property for the library target to output_dir. For -# example, if output_dir is CMAKE_CURRENT_BINARY_DIR (the default), you could do -# target_include_directories(MyLib -# PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>") +# example, if OUTPUT_DIR is CMAKE_CURRENT_BINARY_DIR (the default), you could do +# +# .. code-block:: cmake +# +# target_include_directories(MyLib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>") # # Example usage (without PREFIX): -# ecm_generate_headers( -# MyLib_FORWARDING_HEADERS -# HEADERS -# MLFoo -# MLBar -# # etc -# REQUIRED_HEADERS MyLib_HEADERS -# ) -# install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS} -# DESTINATION ${CMAKE_INSTALL_PREFIX}/include -# COMPONENT Devel) # -# Example usage (with PREFIX): -# ecm_generate_headers( -# MyLib_FORWARDING_HEADERS -# HEADERS -# Foo -# Bar -# # etc -# PREFIX MyLib -# REQUIRED_HEADERS MyLib_HEADERS -# ) -# install(FILES ${MyLib_FORWARDING_HEADERS} -# DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib -# COMPONENT Devel) -# install(FILES ${MyLib_HEADERS} -# DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib -# COMPONENT Devel) +# .. code-block:: cmake # +# ecm_generate_headers( +# MyLib_FORWARDING_HEADERS +# HEADERS +# MLFoo +# MLBar +# # etc +# REQUIRED_HEADERS MyLib_HEADERS +# ) +# install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS} +# DESTINATION ${CMAKE_INSTALL_PREFIX}/include +# COMPONENT Devel) # +# Example usage (with PREFIX): +# +# .. code-block:: cmake +# +# ecm_generate_headers( +# MyLib_FORWARDING_HEADERS +# HEADERS +# Foo +# Bar +# # etc +# PREFIX MyLib +# REQUIRED_HEADERS MyLib_HEADERS +# ) +# install(FILES ${MyLib_FORWARDING_HEADERS} +# DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib +# COMPONENT Devel) +# install(FILES ${MyLib_HEADERS} +# DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib +# COMPONENT Devel) + +#============================================================================= # Copyright 2013 Aleix Pol Gonzalez <aleixpol@blue-systems.com> # Copyright 2014 Alex Merry <alex.merry@kdemail.net> # -# Redistribution and use is allowed according to the terms of the BSD license. -# For details see the accompanying COPYING-CMAKE-SCRIPTS file. +# 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.) include(CMakeParseArguments) diff --git a/modules/ECMGeneratePriFile.cmake b/modules/ECMGeneratePriFile.cmake index d39a9f96..bff2961f 100644 --- a/modules/ECMGeneratePriFile.cmake +++ b/modules/ECMGeneratePriFile.cmake @@ -1,33 +1,81 @@ -# This file provides the function ecm_generate_pri_file(). -# ECM_GENERATE_PRI_FILE() creates a .pri file for a library so that qmake-based -# apps can more easily use the library. -# It also sets ECM_MKSPECS_INSTALL_DIR as the directory to install the .pri file to. +#.rst: +# ECMGeneratePriFile +# ------------------ # -# Requirement: ${PROJECT_VERSION_STRING} must be set before ecm_generate_pri_file. -# This is usually done by calling ecm_setup_version, which sets it. +# Generate a ``.pri`` file for the benefit of qmake-based projects. # -# Syntax: -# ecm_generate_pri_file(BASE_NAME baseName -# LIB_NAME libName -# [DEPS "dep1 dep2"] -# [FILENAME_VAR filename_variable] ) +# As well as the function below, this module creates the cache variable +# ``ECM_MKSPECS_INSTALL_DIR`` and sets the default value to ``mkspecs/modules``. +# This assumes Qt and the current project are both installed to the same +# non-system prefix. Packagers who use ``-DCMAKE_INSTALL_PREFIX=/usr`` will +# certainly want to set ``ECM_MKSPECS_INSTALL_DIR`` to something like +# ``share/qt5/mkspecs/modules``. # -# * baseName is the name which .pro files will use to refer to the library, i.e. the public name, like KArchive. -# * libName is the name of the actual library to link to, i.e. the first argument to add_library(). -# * the deps are a space-separated list of base names of other libraries. Use core, widgets, etc. for Qt libs. -# * filename_variable is the name of a variable, which will be set to contain the path of the .pri file to install +# The main thing is that this should be the ``modules`` subdirectory of either +# the default qmake ``mkspecs`` directory or of a directory that will be in the +# ``$QMAKEPATH`` environment variable when qmake is run. +# +# :: +# +# ecm_generate_pri_file(BASE_NAME <baseName> +# LIB_NAME <libName> +# [DEPS "<dep> [<dep> [...]]"] +# [FILENAME_VAR <filename_variable>]) +# +# If your CMake project produces a Qt-based library, you may expect there to be +# applications that wish to use it that use a qmake-based build system, rather +# than a CMake-based one. Creating a ``.pri`` file will make use of your +# library convenient for them, in much the same way that CMake config files make +# things convenient for CMake-based applications. +# +# ecm_generate_pri_file() generates just such a file. It depends on a few +# variables being set: +# +# * ``PROJECT_VERSION_STRING``: typically set by :module:`ECMSetupVersion`, +# although the project() command in CMake 3.0.0 and later can also set this. +# * ``INCLUDE_INSTALL_DIR``: this must be relative to ``CMAKE_INSTALL_PREFIX``, +# and includes are assumed to be install in the <baseName> subdirectory. +# * ``LIB_INSTALL_DIR``: this must be relative to ``CMAKE_INSTALL_PREFIX``. +# +# BASE_NAME specifies the name qmake project (.pro) files should use to refer to +# the library (eg: KArchive). LIB_NAME is the name of the actual library to +# link to (ie: the first argument to add_library()). DEPS is a space-separated +# list of the base names of other libraries (for Qt libraries, use the same +# names you use with the ``QT`` variable in a qmake project file, such as "core" +# for QtCore). FILENAME_VAR specifies the name of a variable to store the path +# to the generated file in. # # Example usage: -# ecm_generate_pri_file(BASE_NAME KArchive LIB_NAME KF5KArchive DEPS "core" FILENAME_VAR PRI_FILENAME) -# install(FILES ${PRI_FILENAME} DESTINATION ${ECM_MKSPECS_INSTALL_DIR}) # -# Copyright (c) 2014, David Faure <faure@kde.org> +# .. code-block:: cmake +# +# ecm_generate_pri_file( +# BASE_NAME KArchive +# LIB_NAME KF5KArchive +# DEPS "core" +# FILENAME_VAR pri_filename +# ) +# install(FILES ${pri_filename} DESTINATION ${ECM_MKSPECS_INSTALL_DIR}) +# +# A qmake-based project that wished to use this would then do:: +# +# QT += KArchive +# +# in their ``.pro`` file. + +#============================================================================= +# Copyright 2014 David Faure <faure@kde.org> +# +# Distributed under the OSI-approved BSD License (the "License"); +# see accompanying file COPYING-CMAKE-SCRIPTS for details. # -# Redistribution and use is allowed according to the terms of the BSD license. -# For details see the accompanying COPYING-CMAKE-SCRIPTS file. +# 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.) -# This default value makes "installing qt and this lib into the same prefix" work out of the box. -# Packagers who use -DCMAKE_INSTALL_PREFIX=/usr will certainly want to set ECM_MKSPECS_INSTALL_DIR to something like share/qt5/mkspecs/modules set(ECM_MKSPECS_INSTALL_DIR mkspecs/modules CACHE PATH "The directory where mkspecs will be installed to.") function(ECM_GENERATE_PRI_FILE) @@ -58,6 +106,8 @@ function(ECM_GENERATE_PRI_FILE) set(PRI_TARGET_BASENAME ${EGPF_BASE_NAME}) set(PRI_TARGET_LIBNAME ${EGPF_LIB_NAME}) set(PRI_TARGET_QTDEPS ${EGPF_DEPS}) + # FIXME: Default value for INCLUDE_INSTALL_DIR, argument to override? + # What about absolute paths? set(PRI_TARGET_INCLUDES "${CMAKE_INSTALL_PREFIX}/${INCLUDE_INSTALL_DIR}/${PRI_TARGET_BASENAME}") set(PRI_TARGET_DEFINES "") @@ -66,6 +116,8 @@ function(ECM_GENERATE_PRI_FILE) set(${EGPF_FILENAME_VAR} ${PRI_FILENAME} PARENT_SCOPE) endif() + # FIXME: Default value for LIB_INSTALL_DIR, argument to override? + # What about absolute paths? file(GENERATE OUTPUT ${PRI_FILENAME} CONTENT diff --git a/modules/ECMInstallIcons.cmake b/modules/ECMInstallIcons.cmake index e6d2adef..d83003ba 100644 --- a/modules/ECMInstallIcons.cmake +++ b/modules/ECMInstallIcons.cmake @@ -1,35 +1,56 @@ -# - Function for installing icons -# This module provides the function ECM_INSTALL_ICONS(). - -# ECM_INSTALL_ICONS installs all icons in the current path that -# match a specific file naming convention into into the directory provided -# following the Freedesktop.org icon naming spec -# http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html - -# The filenames of the icons in the directory must be in the following format -# in order to be installed -# themeSize-Group-name.extension - -# The following file extensions are supported -# .png -# .mng -# .svgz - -# Where the theme is one of: -# "hi" for hicolor -# "lo" for locolor -# "cr" for the crystal icon theme -# "ox" for the oxygen icon theme - -# Size refers to the size of one dimension of the icon -# Typically, 16, 22, 32, 48, 64, 128 or 256 -# For svgz files the size should be set to "sc" - -# For example the file -# hi22-action-menu_new.png -# would be installed into -# PREFIX/hicolor/22x22/actions/menu_new.png - +#.rst: +# ECMInstallIcons +# --------------- +# +# Installs icons, sorting them into the correct directories according to the +# FreeDesktop.org icon naming specification. +# +# :: +# +# ecm_install_icons(<icon_install_dir> [<l10n_code>]) +# +# Installs all icons found in ``CMAKE_CURRENT_SOURCE_DIR`` to the correct +# subdirectory of ``<icon_install_dir>``. ``<icon_install_dir>`` should +# typically be something like ``share/icons``, although users of the +# :kde-module:`KDEInstallDirs` module would normally do +# +# .. code-block:: cmake +# +# ecm_install_icons(${ICON_INSTALL_DIR}) +# +# The icons must be named in the form:: +# +# <theme><size>-<group>-<name>.<ext> +# +# where ``<theme>`` is one of +# * ``hi`` for hicolor +# * ``lo`` for locolor +# * ``cr`` for the Crystal icon theme +# * ``ox`` for the Oxygen icon theme +# +# ``<size>`` is a numeric pixel size (typically 16, 22, 32, 48, 64, 128 or 256) +# or ``sc`` for scalable (SVG) files, ``<group>`` is one of the standard +# FreeDesktop.org icon groups (actions, animations, apps, categories, devices, +# emblems, emotes, intl, mimetypes, places, status) and ``<ext>`` is one of +# ``.png``, ``.mng`` or ``.svgz``. +# +# For example the file ``hi22-action-menu_new.png`` would be installed into +# ``<icon_install_dir>/hicolor/22x22/actions/menu_new.png`` + +#============================================================================= +# Copyright 2013 David Edmundson <kde@davidedmundson.co.uk> +# Copyright 2008 Chusslove Illich <caslav.ilic@gmx.net> +# Copyright 2006 Alex Neundorf <neundorf@kde.org> +# +# 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.) # a "map" of short type names to the directories @@ -47,6 +68,8 @@ set(_ECM_ICON_GROUP_emotes "emotes") set(_ECM_ICON_GROUP_animations "animations") set(_ECM_ICON_GROUP_intl "intl") +# FIXME: this is too KDE-specific; we should keep this map for compatibility, +# but get users to specify the full theme name # a "map" of short theme names to the theme directory set(_ECM_ICON_THEME_ox "oxygen") set(_ECM_ICON_THEME_cr "crystalsvg") @@ -73,6 +96,7 @@ macro (ECM_INSTALL_ICONS _defaultpath ) set(_group "${CMAKE_MATCH_3}") set(_name "${CMAKE_MATCH_4}") + # FIXME: don't use map set(_theme_GROUP ${_ECM_ICON_THEME_${_type}}) if( _theme_GROUP) _ECM_ADD_ICON_INSTALL_RULE(${CMAKE_CURRENT_BINARY_DIR}/install_icons.cmake @@ -127,6 +151,7 @@ macro (_ECM_ADD_ICON_INSTALL_RULE _install_SCRIPT _install_PATH _group _orig_NAM if (NOT ${_group} STREQUAL ${_install_NAME} ) set(_icon_GROUP ${_ECM_ICON_GROUP_${_group}}) if(NOT _icon_GROUP) + # FIXME: print warning if not in map (and not "actions") set(_icon_GROUP "actions") endif(NOT _icon_GROUP) # message(STATUS "icon: ${_current_ICON} size: ${_size} group: ${_group} name: ${_name} l10n: ${_l10n_SUBDIR}") @@ -146,4 +171,4 @@ macro (ECM_UPDATE_ICONCACHE) file(REMOVE \"${ICON_INSTALL_DIR}/hicolor/temp.txt\") endif (NOT DESTDIR_VALUE) ") -endmacro (ECM_UPDATE_ICONCACHE)
\ No newline at end of file +endmacro (ECM_UPDATE_ICONCACHE) diff --git a/modules/ECMMarkAsTest.cmake b/modules/ECMMarkAsTest.cmake index e20bfbfe..24b8cfc7 100644 --- a/modules/ECMMarkAsTest.cmake +++ b/modules/ECMMarkAsTest.cmake @@ -1,15 +1,32 @@ -# - Function for marking targets as being only for testing -# This module provides the function ECM_MARK_AS_TEST(). +#.rst: +# ECMMarkAsTest +# ------------- # -# The ECM_MARK_AS_TEST function is used to indicate that a target should only -# be built if the BUILD_TESTING option (provided by CTest) is enabled. +# Marks a target as only being required for tests. # -# ECM_MARK_AS_TEST( target1 target2 ... targetN ) +# :: # -# If BUILD_TESTING is False, then targets marked as tests are excluded from -# the ALL target. They are all part of the 'buildtests' target though, so -# even if building with BUILD_TESTING set to False, it is possible to build -# all tests by invoking the 'buildtests' target. +# ecm_mark_as_test(<target1> [<target2> [...]]) +# +# This will cause the specified targets to not be built unless either +# BUILD_TESTING is set to ON or the user invokes the ``buildtests`` target. +# +# BUILD_TESTING is created as a cache variable by the CTest module and by the +# :kde-module:`KDECMakeSettings` module. + +#============================================================================= +# Copyright 2012 Stephen Kelly <steveire@gmail.com> +# Copyright 2012 Alex Neundorf <neundorf@kde.org> +# +# 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.) if (NOT BUILD_TESTING) if(NOT TARGET buildtests) diff --git a/modules/ECMMarkNonGuiExecutable.cmake b/modules/ECMMarkNonGuiExecutable.cmake index 3c199ab5..9b680216 100644 --- a/modules/ECMMarkNonGuiExecutable.cmake +++ b/modules/ECMMarkNonGuiExecutable.cmake @@ -1,11 +1,29 @@ -# - Function for marking executables as being non-gui -# This module provides the function ECM_MARK_NONGUI_EXECUTABLE(). +#.rst: +# ECMMarkNonGuiExecutable +# ----------------------- # -# The ECM_MARK_NONGUI_EXECUTABLE function is used to indicate that an executable -# target should not be part of a MACOSX_BUNDLE, and should not be a WIN32_EXECUTABLE. +# Marks an executable target as not being a GUI application. # -# ECM_MARK_NONGUI_EXECUTABLE( target1 target2 ... targetN ) +# :: # +# ecm_mark_nongui_executable(<target1> [<target2> [...]]) +# +# This will indicate to CMake that the specified targets should not be included +# in a MACOSX_BUNDLE and should not be WIN32_EXECUTABLEs. On platforms other +# than MacOS X or Windows, this will have no effect. + +#============================================================================= +# Copyright 2012 Stephen Kelly <steveire@gmail.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.) function(ecm_mark_nongui_executable) foreach(_target ${ARGN}) diff --git a/modules/ECMOptionalAddSubdirectory.cmake b/modules/ECMOptionalAddSubdirectory.cmake index c7931f0c..6cbafa2d 100644 --- a/modules/ECMOptionalAddSubdirectory.cmake +++ b/modules/ECMOptionalAddSubdirectory.cmake @@ -1,28 +1,42 @@ -# - ECM_OPTIONAL_ADD_SUBDIRECTORY() combines ADD_SUBDIRECTORY() with an OPTION() -# -# ECM_OPTIONAL_ADD_SUBDIRECTORY(<dir>) -# -# If you use ECM_OPTIONAL_ADD_SUBDIRECTORY() instead of ADD_SUBDIRECTORY(), -# this will have two effects -# -# 1 - CMake will not complain if the directory doesn't exist -# This makes sense if you want to distribute just one of the subdirs -# in a source package, e.g. just one of the subdirs in kdeextragear. -# 2 - If the directory exists, it will offer an option to skip the -# subdirectory. -# This is useful if you want to compile only a subset of all -# directories. -# -# If the CMake variable DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is set to TRUE -# for the first CMake run on the project, all optional subdirectories will be disabled -# by default (but can of course be enabled via the respective options). -# E.g. the following will disable all optional subdirectories except the one named "kcalc": -# $ cmake -DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_kcalc=TRUE <srcdir> +#.rst: +# ECMOptionalAddSubdirectory +# -------------------------- +# +# Make subdiretories optional. +# +# :: +# +# ecm_optional_add_subdirectory(<dir>) +# +# This behaves like add_subdirectory(), except that it does not complain if the +# directory does not exist. Additionally, if the directory does exist, it +# creates an option to allow the user to skip it. +# +# This is useful for "meta-projects" that combine several mostly-independent +# sub-projects. +# +# If the CMake variable DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is set to TRUE for +# the first CMake run on the project, all optional subdirectories will be +# disabled by default (but can of course be enabled via the respective options). +# For example, the following will disable all optional subdirectories except the +# one named "foo": +# +# .. code-block:: sh +# +# cmake -DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_foo=TRUE myproject -# Copyright (c) 2007, Alexander Neundorf, <neundorf@kde.org> +#============================================================================= +# Copyright 2007 Alexander Neundorf <neundorf@kde.org> +# +# Distributed under the OSI-approved BSD License (the "License"); +# see accompanying file COPYING-CMAKE-SCRIPTS for details. # -# Redistribution and use is allowed according to the terms of the BSD license. -# For details see the accompanying COPYING-CMAKE-SCRIPTS file. +# 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.) function(ECM_OPTIONAL_ADD_SUBDIRECTORY _dir) diff --git a/modules/ECMPackageConfigHelpers.cmake b/modules/ECMPackageConfigHelpers.cmake index 2ccf32f6..da65c3ea 100644 --- a/modules/ECMPackageConfigHelpers.cmake +++ b/modules/ECMPackageConfigHelpers.cmake @@ -1,11 +1,28 @@ -# - ECM_CONFIGURE_PACKAGE_CONFIG_FILE(), WRITE_BASIC_PACKAGE_VERSION_FILE() +#.rst: +# ECMPackageConfigHelpers +# ----------------------- # -# WRITE_BASIC_PACKAGE_VERSION_FILE() is actually just the macro from the -# CMakePackageConfigHelpers module. +# Helper macros for generating CMake package config files. # -# ECM_CONFIGURE_PACKAGE_CONFIG_FILE() behaves like -# CONFIGURE_PACKAGE_CONFIG_FILE() from CMake 2.8.12, except that it adds an -# extra helper macro: find_dependency(). +# ``write_basic_package_version_file()`` is the same as the one provided by the +# CMakePackageConfigHelpers module in CMake; see that module's documentation for +# more information. +# +# :: +# +# ecm_configure_package_config_file(<input> <output> +# INSTALL_DESTINATION <path> +# [PATH_VARS <var1> [<var2> [...]] +# [NO_SET_AND_CHECK_MACRO] +# [NO_CHECK_REQUIRED_COMPONENTS_MACRO]) +# +# +# This behaves in the same way as configure_package_config_file() from CMake +# 2.8.12, except that it adds an extra helper macro: find_dependency(). +# +# :: +# +# find_dependency(<dep> [<version> [EXACT]]) # # find_dependency() should be used instead of find_package() to find package # dependencies. It forwards the correct parameters for EXACT, QUIET and @@ -17,10 +34,23 @@ # module directly. # # CMake 3.0.0 will include a CMakeFindDependencyMacro module that will provide -# the find_dependency macro (which you can include() in your *Config.cmake +# the find_dependency() macro (which you can include() in your package config # file), so this file is only useful for projects whose minimum required version # is 2.8.12. + +#============================================================================= +# Copyright 2014 Alex Merry <alex.merry@kdemail.net> +# Copyright 2013 Stephen Kelly <steveire@gmail.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.) include(${CMAKE_ROOT}/Modules/CMakePackageConfigHelpers.cmake) diff --git a/modules/ECMSetupVersion.cmake b/modules/ECMSetupVersion.cmake index 3a8defd8..3ae6fa8f 100644 --- a/modules/ECMSetupVersion.cmake +++ b/modules/ECMSetupVersion.cmake @@ -1,49 +1,70 @@ -# This file provides the function ecm_setup_version(). -# ECM_SETUP_VERSION() bundles three things which are usually done for versioned libraries: -# - it sets a set of version variables -# - optionally it creates a C version header file, which can then be installed along with the library -# - optionally it creates a CMake package version file, which can then be installed along with a -# CMake package Config.cmake file +#.rst: +# ECMSetupVersion +# --------------- +# +# Handle library version information. +# +# :: # # ecm_setup_version(<version> -# VARIABLE_PREFIX prefix +# VARIABLE_PREFIX <prefix> # [SOVERSION <soversion>] -# [VERSION_HEADER filename] -# [PACKAGE_VERSION_FILE filename] ) +# [VERSION_HEADER <filename>] +# [PACKAGE_VERSION_FILE <filename>] ) +# +# This parses a version string and sets up a standard set of version variables. +# It can optionally also create a C version header file and a CMake package +# version file to install along with the library. # +# If the ``<version>`` argument is of the form ``<major>.<minor>.<patch>`` +# (or ``<major>.<minor>.<patch>.<tweak>``), The following CMake variables are +# set:: # -# ecm_setup_version() sets the following CMake variables -# <prefix>_VERSION_MAJOR = <version_major_component> -# <prefix>_VERSION_MINOR = <version_minor_component> -# <prefix>_VERSION_PATCH = <version_patch_component> -# <prefix>_VERSION_STRING = <major>.<minor>.<patch> -# <prefix>_SOVERSION is set to <major> if <soversion> has not been specified. +# <prefix>_VERSION_MAJOR - <major> +# <prefix>_VERSION_MINOR - <minor> +# <prefix>_VERSION_PATCH - <patch> +# <prefix>_VERSION_STRING - <version> +# <prefix>_SOVERSION - <soversion>, or <major> if SOVERSION was not given +# PROJECT_VERSION_MAJOR - <major> +# PROJECT_VERSION_MINOR - <minor> +# PROJECT_VERSION_PATCH - <patch> +# PROJECT_VERSION_STRING - <version> # -# It also sets PROJECT_VERSION_MAJOR, PROJECT_VERSION_MINOR, PROJECT_VERSION_PATCH and -# PROJECT_VERSION_STRING, for easier use with configure_file and file(GENERATE). +# If the VERSION_HEADER option is used, a simple C header is generated with the +# given filename. If filename is a relative path, it is interpreted as relative +# to CMAKE_CURRENT_BINARY_DIR. The generated header contains the following +# macros:: # -# If the VERSION_HEADER option is used, a simple C header is generated with the given -# filename. If filename is a relative path, it is interpreted as relative to -# CMAKE_CURRENT_BINARY_DIR. -# The generated header contains the following macros: -# <prefix>_VERSION_MAJOR -# <prefix>_VERSION_MINOR -# <prefix>_VERSION_PATCH -# <prefix>_VERSION_STRING - containing the full version number as a C string -# <prefix>_VERSION - containing the full version combined into one integer +# <prefix>_VERSION_MAJOR - <major> as an integer +# <prefix>_VERSION_MINOR - <minor> as an integer +# <prefix>_VERSION_PATCH - <patch> as an integer +# <prefix>_VERSION_STRING - <version> as a C string +# <prefix>_VERSION - the version as an integer +# +# ``<prefix>_VERSION`` has ``<patch>`` in the bottom 8 bits, ``<minor>`` in the +# next 8 bits and ``<major>`` in the remaining bits. Note that ``<patch>`` and +# ``<minor>`` must be less than 256. # # If the PACKAGE_VERSION_FILE option is used, a simple CMake package version -# file is created using the write_basic_package_version_file() macro coming -# with CMake. It should be installed along the Config.cmake file of the library -# into the same directory where it can be found by find_package(). -# Also here, if the given filename is a relative path, it is interpreted as -# relative to CMAKE_CURRENT_BINARY_DIR. +# file is created using the write_basic_package_version_file() macro provided by +# CMake. It should be installed in the same location as the Config.cmake file of +# the library so that it can be found by find_package(). If the filename is a +# relative path, it is interpreted as relative to CMAKE_CURRENT_BINARY_DIR. -# Copyright (c) 2012, Alexander Neundorf, <neundorf@kde.org> +#============================================================================= +# Copyright 2012 Alexander Neundorf <neundorf@kde.org> # -# Redistribution and use is allowed according to the terms of the BSD license. -# For details see the accompanying COPYING-CMAKE-SCRIPTS file. - +# 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.) + +# FIXME: Figure out how this should interact with CMP0048 in CMake 3.0.0 include(CMakePackageConfigHelpers) diff --git a/modules/ECMUseFindModules.cmake b/modules/ECMUseFindModules.cmake index 6bf3c904..25f42666 100644 --- a/modules/ECMUseFindModules.cmake +++ b/modules/ECMUseFindModules.cmake @@ -1,40 +1,62 @@ -# - Selectively use some of the Find-modules provided by extra-cmake-modules (ECM) +#.rst: +# ECMUseFindModules +# ----------------- # -# ECM_USE_FIND_MODULES(DIR <dir> MODULES module1.cmake module2.cmake .. moduleN.cmake [NO_OVERRIDE] ) +# Selectively use some of the find modules provided by extra-cmake-modules. # -# This macro is automatically available once extra-cmake-modules has been found, so it is not -# necessary to include(ECMUseFindModules) explicitly. +# This module is automatically available once extra-cmake-modules has been +# found, so it is not necessary to ``include(ECMUseFindModules)`` explicitly. # -# Use this macro instead of simply adding ${ECM_FIND_MODULE_DIR} to CMAKE_MODULE_PATH -# if you want to use only a subset or some specific find-modules coming with extra-cmake-modules. -# The given find-modules will be copied to the given directory. This directory should then be added -# to CMAKE_MODULE_PATH. The given modules override modules of the same name coming with CMake, except -# if the NO_OVERRIDE option has been used. +# :: # -# DIR <dir> : the selected module files will be copied to that directory. The directory should be -# located somewhere inside ${CMAKE_BINARY_DIR}. It should then be added to CMAKE_MODULE_PATH . -# The directory is created if it does not exist yet. -# MODULES : the list of find-modules to be used from extra-cmake-modules -# NO_OVERRIDE: if used, the given modules will only be used if they do not exist in the currently used -# CMake version +# ecm_use_find_modules(DIR <dir> +# MODULES module1.cmake [module2.cmake [...]] +# [NO_OVERRIDE]) +# +# This allows selective use of the find modules provided by ECM, including +# deferring to CMake's versions of those modules if it has them. Rather than +# adding ``${ECM_FIND_MODULE_DIR}`` to ``CMAKE_MODULE_PATH``, you use +# ecm_use_find_modules() to copy the modules you want to a local (build) +# directory, and add that to ``CMAKE_MODULE_PATH``. +# +# The find modules given to MODULES will be copied to the directory given by DIR +# (which should be located in ``${CMAKE_BINARY_DIR}`` and added to +# ``CMAKE_MODULE_PATH``). If NO_OVERRIDE is given, only modules not also +# provided by CMake will be copied. # # Example: -# find_package(ECM 0.0.4 REQUIRED) -# ecm_use_find_modules(DIR ${CMAKE_BINARY_DIR}/cmake/ Modules FindBlueZ.cmake NO_OVERRIDE ) -# set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake/ ) # -# This example will make FindBlueZ.cmake available in your project, but only as long as it -# is not yet part of CMake. The file will be copied into ${CMAKE_BINARY_DIR}/cmake/, and then this -# directory is added to CMAKE_MODULE_PATH. +# .. code-block:: cmake +# +# find_package(ECM REQUIRED) +# ecm_use_find_modules( +# DIR ${CMAKE_BINARY_DIR}/cmake +# MODULES FindEGL.cmake +# NO_OVERRIDE +# ) +# set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake) +# +# This example will make ``FindEGL.cmake`` available in your project, but only +# as long as it is not yet part of CMake. Calls to ``find_package(EGL)`` will +# then make use of this copied module (or the CMake module if it exists). +# +# Another possible use for this macro is to take copies of find modules that can +# be installed along with config files if they are required as a dependency (for +# example, if targets provided by the find module are in the link interface of a +# library). +#============================================================================= # Copyright 2011 Alexander Neundorf <neundorf@kde.org> # # Distributed under the OSI-approved BSD License (the "License"); -# see accompanying file Copyright.txt for details. +# 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.) include(CMakeParseArguments) |