From d7a4750c785f4dae48c03f3dafac6e483c3a1177 Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Mon, 14 Apr 2025 01:15:26 +0200 Subject: FindKDE3: Update documentation - This syncs the module documentation with other similar find modules. - Added note about KDE version 3 being obsolete and newer KDE version should be used. A link to upstream docs is added. - Fixed typo "SKIP_AUTOMAKE" to "SKIP_AUTOMOC". - Documented commands. Instead of mentioning "macros", this now uses the more general wording "commands" and lists them similar to other documentation pages. - Lowercase style used for commands. - Reworded descriptions to match the implementations a bit. --- Modules/FindKDE3.cmake | 198 ++++++++++++++++++++++++++++++++--------------- Modules/KDE3Macros.cmake | 38 ++------- 2 files changed, 144 insertions(+), 92 deletions(-) diff --git a/Modules/FindKDE3.cmake b/Modules/FindKDE3.cmake index ab816d0..15aaefa 100644 --- a/Modules/FindKDE3.cmake +++ b/Modules/FindKDE3.cmake @@ -5,139 +5,215 @@ FindKDE3 -------- -Find the KDE3 include and library dirs, KDE preprocessors and define a some macros +.. note:: + This module is specifically intended for KDE version 3, which is obsolete and + no longer maintained. For modern application development using KDE + technologies with CMake, use a newer version of KDE, and refer to the + `KDE documentation + `_. +This module finds KDE 3 include directories, libraries, and KDE-specific +preprocessor tools. It provides usage requirements for building KDE 3 software +and defines several helper commands to simplify working with KDE 3 in CMake. + +Result Variables +^^^^^^^^^^^^^^^^ This module defines the following variables: +``KDE3_FOUND`` + Boolean indicating whether KDE 3 is found. ``KDE3_DEFINITIONS`` - compiler definitions required for compiling KDE software -``KDE3_INCLUDE_DIR`` - the KDE include directory + Compiler definitions required for compiling KDE 3 software. ``KDE3_INCLUDE_DIRS`` - the KDE and the Qt include directory, for use with include_directories() + The KDE and the Qt include directories, for use with the + :command:`target_include_directories` command. ``KDE3_LIB_DIR`` - the directory where the KDE libraries are installed, for use with link_directories() + The directory containing the installed KDE 3 libraries, for use with the + :command:`target_link_directories` command. ``QT_AND_KDECORE_LIBS`` - this contains both the Qt and the kdecore library + A list containing both the Qt and the kdecore library, typically used together + when linking KDE 3. + +Cache Variables +^^^^^^^^^^^^^^^ + +The following cache variables may also be set: + +``KDE3_INCLUDE_DIR`` + The directory containing KDE 3 header files. ``KDE3_DCOPIDL_EXECUTABLE`` - the dcopidl executable + The path to the ``dcopidl`` executable. ``KDE3_DCOPIDL2CPP_EXECUTABLE`` - the dcopidl2cpp executable + The path to the ``dcopidl2cpp`` executable. ``KDE3_KCFGC_EXECUTABLE`` - the kconfig_compiler executable -``KDE3_FOUND`` - set to TRUE if all of the above has been found + The path to the ``kconfig_compiler`` executable. -The following user adjustable options are provided: +Hints +^^^^^ + +This module accepts the following variables: ``KDE3_BUILD_TESTS`` - enable this to build KDE testcases + Provided as a user adjustable option. Set this variable to boolean true to + build KDE 3 testcases. + +Commands +^^^^^^^^ + +This module provides the following commands to work with KDE 3 in CMake: + +.. command:: kde3_automoc -It also adds the following macros (from ``KDE3Macros.cmake``) ``SRCS_VAR`` is -always the variable which contains the list of source files for your -application or library. + Enables automatic processing with ``moc`` for the given source files: -KDE3_AUTOMOC(file1 ... fileN) + .. code-block:: cmake -:: + kde3_automoc(...) - Call this if you want to have automatic moc file handling. - This means if you include "foo.moc" in the source file foo.cpp - a moc file for the header foo.h will be created automatically. - You can set the property SKIP_AUTOMAKE using set_source_files_properties() - to exclude some files in the list from being processed. + Call this command to enable automatic ``moc`` file handling. For example, + if a source file (e.g., ``foo.cpp``) contains ``include "foo.moc"``, a + ``moc`` file for the corresponding header (``foo.h``) will be generated + automatically. To skip processing for a specific source file, set the + :prop_sf:`SKIP_AUTOMOC` source file property. +.. command:: kde3_add_moc_files + Processes header files with ``moc``: -KDE3_ADD_MOC_FILES(SRCS_VAR file1 ... fileN ) + .. code-block:: cmake -:: + kde3_add_moc_files( ...) - If you don't use the KDE3_AUTOMOC() macro, for the files - listed here moc files will be created (named "foo.moc.cpp") + If not using ``kde3_automoc()``, this command can be used to generate ``moc`` + files for one or more ```` files. The generated files are named + ``.moc.cpp`` and the resulting list of these generated source files + is stored in the variable named ```` for use in project targets. +.. command:: kde3_add_dcop_skels + Generates KIDL and DCOP skeletons: -KDE3_ADD_DCOP_SKELS(SRCS_VAR header1.h ... headerN.h ) + .. code-block:: cmake -:: + kde3_add_dcop_skels( ...) - Use this to generate DCOP skeletions from the listed headers. + This command generates ``.kidl`` and DCOP skeleton source files from the given + DCOP header files. The resulting list of generated source files is stored in + the variable named ```` for use in project targets. +.. command:: kde3_add_dcop_stubs + Generates DCOP stubs: -KDE3_ADD_DCOP_STUBS(SRCS_VAR header1.h ... headerN.h ) + .. code-block:: cmake -:: + kde3_add_dcop_stubs( ...) - Use this to generate DCOP stubs from the listed headers. + Use this command to generate DCOP stubs from one or more given header files. + The resulting list of generated source files is stored in the variable named + ```` for use in project targets. +.. command:: kde3_add_ui_files + Adds Qt designer UI files: -KDE3_ADD_UI_FILES(SRCS_VAR file1.ui ... fileN.ui ) + .. code-block:: cmake -:: + kde3_add_ui_files( ...) - Use this to add the Qt designer ui files to your application/library. + This command creates the implementation files from the given Qt designer + ``.ui`` files. The resulting list of generated files is stored in the + variable named ```` for use in project targets. +.. command:: kde3_add_kcfg_files + Adds KDE kconfig compiler files: -KDE3_ADD_KCFG_FILES(SRCS_VAR file1.kcfgc ... fileN.kcfgc ) + .. code-block:: cmake -:: + kde3_add_kcfg_files( ...) - Use this to add KDE kconfig compiler files to your application/library. + Use this command to add KDE kconfig compiler files (``.kcfgc``) to the + application/library. The resulting list of generated source files is stored + in the variable named ```` for use in project targets. +.. command:: kde3_install_libtool_file + Creates and installs a libtool file: -KDE3_INSTALL_LIBTOOL_FILE(target) + .. code-block:: cmake -:: + kde3_install_libtool_file() - This will create and install a simple libtool file for the given target. + This command creates and installs a basic libtool file for the given target + ````. +.. command:: kde3_add_executable + Adds KDE executable: -KDE3_ADD_EXECUTABLE(name file1 ... fileN ) + .. code-block:: cmake -:: + kde3_add_executable( ...) - Currently identical to add_executable(), may provide some advanced - features in the future. + This command is functionally identical to the built-in + :command:`add_executable` command. It was originally intended to support + additional features in future versions of this module. +.. command:: kde3_add_kpart + Creates a KDE plugin: -KDE3_ADD_KPART(name [WITH_PREFIX] file1 ... fileN ) + .. code-block:: cmake -:: + kde3_add_kpart( [WITH_PREFIX] ...) - Create a KDE plugin (KPart, kioslave, etc.) from the given source files. - If WITH_PREFIX is given, the resulting plugin will have the prefix "lib", - otherwise it won't. - It creates and installs an appropriate libtool la-file. + This command creates a KDE plugin (KPart, kioslave, etc.) from one or more + source files ````. It also creates and installs an appropriate + libtool ``.la`` file. + If the ``WITH_PREFIX`` option is given, the resulting plugin name will be + prefixed with ``lib``. Otherwise, no prefix is added. +.. command:: kde3_add_kdeinit_executable -KDE3_ADD_KDEINIT_EXECUTABLE(name file1 ... fileN ) + Creates a KDE application as a module loadable via kdeinit: -:: + .. code-block:: cmake - Create a KDE application in the form of a module loadable via kdeinit. - A library named kdeinit_ will be created and a small executable - which links to it. + kde3_add_kdeinit_executable( ...) + This command creates a library named ``kdeinit_`` from one or more + source files ````. It also builds a small executable linked against + this library. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ -The option KDE3_ENABLE_FINAL to enable all-in-one compilation is no -longer supported. +The following variables have been either removed or are provided for backward +compatibility: +``KDE3_ENABLE_FINAL`` + .. versionchanged:: 2.4.8 + This variable is now removed and no longer supported. + This hint variable was provided as an option in earlier CMake versions to + enable all-in-one compilation. -Author: Alexander Neundorf +Examples +^^^^^^^^ + +Finding KDE 3: + +.. code-block:: cmake + + find_package(KDE3) #]=======================================================================] +# Author: Alexander Neundorf + if(NOT UNIX AND KDE3_FIND_REQUIRED) message(FATAL_ERROR "Compiling KDE3 applications and libraries under Windows is not supported") endif() diff --git a/Modules/KDE3Macros.cmake b/Modules/KDE3Macros.cmake index 3214bd7..1bca52f 100644 --- a/Modules/KDE3Macros.cmake +++ b/Modules/KDE3Macros.cmake @@ -1,31 +1,12 @@ # Distributed under the OSI-approved BSD 3-Clause License. See accompanying # file LICENSE.rst or https://cmake.org/licensing for details. -# - -# See FindKDE3.cmake for documentation. -# -# this file contains the following macros: -# KDE3_ADD_DCOP_SKELS -# KDE3_ADD_DCOP_STUBS -# KDE3_ADD_MOC_FILES -# KDE3_ADD_UI_FILES -# KDE3_ADD_KCFG_FILES -# KDE3_AUTOMOC -# KDE3_INSTALL_LIBTOOL_FILE -# KDE3_CREATE_FINAL_FILE -# KDE3_ADD_KPART -# KDE3_ADD_KDEINIT_EXECUTABLE -# KDE3_ADD_EXECUTABLE - - -#neundorf@kde.org +# This file contains KDE 3 macros. See FindKDE3.cmake for documentation. +# Author: neundorf@kde.org # Included for backward compatibility, otherwise unused. include(AddFileDependencies) -#create the kidl and skeletion file for dcop stuff -#usage: KDE_ADD_COP_SKELS(foo_SRCS ${dcop_headers}) macro(KDE3_ADD_DCOP_SKELS _sources) foreach (_current_FILE ${ARGN}) @@ -131,8 +112,6 @@ macro(KDE3_ADD_KCFG_FILES _sources) endmacro() -#create the moc files and add them to the list of sources -#usage: KDE_ADD_MOC_FILES(foo_SRCS ${moc_headers}) macro(KDE3_ADD_MOC_FILES _sources) foreach (_current_FILE ${ARGN}) @@ -155,8 +134,6 @@ endmacro() get_filename_component( KDE3_MODULE_DIR ${CMAKE_CURRENT_LIST_FILE} PATH) -#create the implementation files from the ui files and add them to the list of sources -#usage: KDE_ADD_UI_FILES(foo_SRCS ${ui_files}) macro(KDE3_ADD_UI_FILES _sources ) foreach (_current_FILE ${ARGN}) @@ -245,7 +222,7 @@ macro(KDE3_AUTOMOC) endforeach () endmacro() -# only used internally by KDE3_INSTALL_ICONS +# Only used internally by kde3_install_icons(). macro (_KDE3_ADD_ICON_INSTALL_RULE _install_SCRIPT _install_PATH _group _orig_NAME _install_NAME) # if the string doesn't match the pattern, the result is the full string, so all three have the same content @@ -358,7 +335,7 @@ macro(KDE3_ADD_KPART _target_NAME _with_PREFIX) endif () # if (KDE3_ENABLE_FINAL) -# KDE3_CREATE_FINAL_FILE(${_target_NAME}_final.cpp ${_first_SRC} ${ARGN}) +# kde3_create_final_file(${_target_NAME}_final.cpp ${_first_SRC} ${ARGN}) # add_library(${_target_NAME} MODULE ${_target_NAME}_final.cpp) # else () add_library(${_target_NAME} MODULE ${_first_SRC} ${ARGN}) @@ -368,15 +345,14 @@ macro(KDE3_ADD_KPART _target_NAME _with_PREFIX) set_target_properties(${_target_NAME} PROPERTIES PREFIX "") endif() - KDE3_INSTALL_LIBTOOL_FILE(${_target_NAME}) - + kde3_install_libtool_file(${_target_NAME}) endmacro() macro(KDE3_ADD_KDEINIT_EXECUTABLE _target_NAME ) # if (KDE3_ENABLE_FINAL) -# KDE3_CREATE_FINAL_FILE(${_target_NAME}_final.cpp ${ARGN}) +# kde3_create_final_file(${_target_NAME}_final.cpp ${ARGN}) # add_library(kdeinit_${_target_NAME} SHARED ${_target_NAME}_final.cpp) # else () add_library(kdeinit_${_target_NAME} SHARED ${ARGN} ) @@ -393,7 +369,7 @@ endmacro() macro(KDE3_ADD_EXECUTABLE _target_NAME ) # if (KDE3_ENABLE_FINAL) -# KDE3_CREATE_FINAL_FILE(${_target_NAME}_final.cpp ${ARGN}) +# kde3_create_final_file(${_target_NAME}_final.cpp ${ARGN}) # add_executable(${_target_NAME} ${_target_NAME}_final.cpp) # else () add_executable(${_target_NAME} ${ARGN} ) -- cgit v0.12