From c20d22c951e61a06701f6c2201add7c11915e7c5 Mon Sep 17 00:00:00 2001 From: Alex Merry Date: Thu, 10 Apr 2014 21:38:09 +0100 Subject: 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. --- modules/ECMGeneratePriFile.cmake | 96 +++++++++++++++++++++++++++++++--------- 1 file changed, 74 insertions(+), 22 deletions(-) (limited to 'modules/ECMGeneratePriFile.cmake') 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 +# LIB_NAME +# [DEPS " [ [...]]"] +# [FILENAME_VAR ]) +# +# 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 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 +# .. 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 +# +# 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 -- cgit v1.2.1