Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ECM-MODULES(7)		      Extra CMake Modules		ECM-MODULES(7)

NAME
       ecm-modules - ECM Modules Reference

INTRODUCTION
       Extra  CMake Modules (ECM) provides various modules that	provide	useful
       functions for CMake scripts. ECM	actually provides three	types of  mod-
       ules  that  can be used from CMake scripts: those that extend the func-
       tionality   of	the   find_package   command   are    documented    in
       ecm-find-modules(7);  those that	provide	standard settings for software
       produced	by the KDE community  are  documented  in  ecm-kde-modules(7).
       The  rest provide macros	and functions for general use by CMake scripts
       and are documented here.

       To use these modules, you need to tell CMake to find the	 ECM  package,
       and  then  add  either  ${ECM_MODULE_PATH}  or ${ECM_MODULE_DIR}	to the
       CMAKE_MODULE_PATH variable:

	  find_package(ECM REQUIRED NO_MODULE)
	  set(CMAKE_MODULE_PATH	${ECM_MODULE_DIR})

       Using ${ECM_MODULE_PATH}	will also make the find	modules	and  KDE  mod-
       ules available.

       Note   that   there   are   also	  toolchain   modules,	documented  in
       ecm-toolchains(7), but these are	used by	users  building	 the  software
       rather than developers writing CMake scripts.

ALL MODULES
   CheckAtomic
       Check  if  the  compiler	 supports  std:atomic out of the box or	if li-
       batomic is needed for atomic support. If	it is needed libatomicis added
       to CMAKE_REQUIRED_LIBRARIES. So after running CheckAtomic you  can  use
       std:atomic.

       Since 5.75.0.

   ECMAddAndroidApk
       Functions  for creating Android APK packages using Qt6s androiddeployqt
       tool as well as the associated Fastlane metadata.

	  ecm_add_android_apk(<target>
	      [ANDROID_DIR <dir>]
	      [PACKAGE_NAME <name>]
	      #	TODO extra args?
	  )

       Creates an Android APK for the given target.

       If ANDROID_DIR is given,	the Android manifest file as well as  any  po-
       tential Gradle build system files or Java/Kotlin	source files are taken
       from  that  directory.	If not set, the	standard template shipped with
       Qt6 is used, which in usually not what you want for production applica-
       tions.

       If PACKAGE_NAME is given, it is used as name for	the Android  APK.   If
       not set,	the target name	is used. Since 6.10.0

       The use of this function	creates	a build	target called create-apk-<tar-
       get>  which  will  run androiddeployqt to produce an (unsigned) APK, as
       well as convert Appstream application metadata (if  present)  into  the
       Fastlane	format used by F-Droid and Play	store automation.

       Theres  also  a	create-apk  convenience	target being created that will
       build all APKs defined in a project.

       When building for another platform than	Android,  this	function  does
       nothing.

       The    following	   variables	impact	  the	 behavior:   ECM_ADDI-
       TIONAL_FIND_ROOT_PATH
	  See documentation in the Android toolchain file.

       ECM_APK_STAGING_ROOT_PATH
	      For use with Crafts image	directory. If set this is used as  the
	      source  for  all content of the APK rather than the search paths
	      used for building.  This allows  to  separate  e.g.  development
	      files from what ends up in the APK.

       Since 6.0.0

       For  automatically  deriving  APK  versions  from  CMake	this creates a
       ecm-version.gradle file which defines the following variables:  ecmVer-
       sionName:  Set to PROJECT_VERSION ecmVersionCode: Derived from the cur-
       rent time in local builds, and from CI_PIPELINE_CREATED_AT
	  in builds from Gitlab	pipelines. This	ensures	a strictly  increasing
	  version  code	as well	as synchronized	version	codes for APKs of mul-
	  tiple	architectures when build in a Gitlab pipeline.

       This can	be included by calling apply from: '../ecm-version.gradle'  in
       the projects build.gradle file and is typically used in manifest	place-
       holders:

       ``
       ` defaultConfig {
	  versionName ecmVersionName versionCode ecmVersionCode	manifestPlace-
	  holders = [versionName: ecmVersionName, versionCode: ecmVersionCode]

   }
       Since 6.12.0

   ECMAddAppIcon
       Add icons to executable files and packages.

	  ecm_add_app_icon(<sources_var_name(|target (since 5.83))>
			   ICONS <icon>	[<icon>	[...]]
			   [SIDEBAR_ICONS <icon> [<icon> [...]]	# Since	5.49
			   [OUTFILE_BASENAME <name>]) #	Since 5.49
			   )

       The given icons,	whose names must match the pattern:

	  <size>-<other_text>.png

       will  be	 added	as platform-specific application icons to the variable
       named <sources_var_name>	or, if the first argument is a	target	(since
       5.83), to the SOURCES property of <target>.  Any	target must be created
       with add_executable() and not be	an alias.

       Other  icon  files  are ignored but on macOS SVG	files can be supported
       and it is thus possible to mix those with png files in a	 single	 macro
       call.

       The  platforms currently	supported are Windows and macOS, on all	others
       the call	has no effect and is ignored.

       <size> is a numeric pixel size (typically 16, 32, 48, 64, 128 or	 256).
       <other_text>  can  be  any other	text. See the platform notes below for
       any recommendations about icon sizes.

       SIDEBAR_ICONS can be used to add	macOS sidebar icons to	the  generated
       iconset.	 They  are  used when a	folder monitored by the	application is
       dragged into Finders sidebar. Since 5.49.

       OUTFILE_BASENAME	will be	used as	the basename for the icon file.	If you
       specify it, the icon file will be called	<OUTFILE_BASENAME>.icns	on ma-
       cOS and <OUTFILE_BASENAME>.ico on Windows. If you dont specify  it,  it
       defaults	to <sources_var_name>.<ext>. Since 5.49.

       Windows notes

	      	Icons are compiled into	the executable using a resource	file.

	      	Icons  may  not	 show up in Windows Explorer if	the executable
		target does not	have the WIN32_EXECUTABLE property set.

	      	Icotool	(see FindIcoTool) is required.

	      	Supported sizes: 16, 24, 32, 48, 64, 128, 256, 512 and 1024.

       macOS notes

	      	The executable target must  have  the  MACOSX_BUNDLE  property
		set.

	      	Icons are added	to the bundle.

	      	If  the	ksvg2icns tool from KIconThemes	is available, .svg and
		.svgz files are	accepted; the first that is converted success-
		fully to .icns will provide the	application  icon.  SVG	 files
		are ignored otherwise.

	      	The  tool  iconutil (provided by Apple)	is required for	bitmap
		icons.

	      	Supported sizes: 16, 32, 64, 128, 256 (and 512,	1024 after  OS
		X 10.9).

	      	At least a 128x128px (or an SVG) icon is required.

	      	Larger	sizes are automatically	used to	substitute for smaller
		sizes on Retina	(high-resolution)  displays.  For  example,  a
		32px  icon,  if	provided, will be used as a 32px icon on stan-
		dard-resolution	displays, and as a 16px-equivalent icon	 (with
		an  @2x	 tag)  on  high-resolution  displays.  That is why you
		should provide 64px and	1024px icons  although	they  are  not
		supported  anymore  directly.  Instead	they  will  be used as
		32px@2x	and 512px@2x. If an SVG	icon  is  provided,  ksvg2icns
		will  be  used internally to automatically generate all	appro-
		priate sizes, including	the high-resolution ones.

	      	This function sets the MACOSX_BUNDLE_ICON_FILE variable	to the
		name of	the generated icns file, so that it will  be  used  as
		the  MACOSX_BUNDLE_ICON_FILE  target  property	when  you call
		add_executable.

	      	Sidebar	icons should typically provided	in 16, 32, 64, 128 and
		256px.

       Since 1.7.0.

   ECMAddQch
       This module provides the	ecm_add_qch function for generating API	 docu-
       mentation files in the QCH format, and the ecm_install_qch_export func-
       tion for	generating and installing exported CMake targets for such gen-
       erated  QCH files to enable builds of other software with generation of
       QCH files to create links into the given	QCH files.

	  ecm_add_qch(<target_name>
	      NAME <name>
	      VERSION <version>
	      QCH_INSTALL_DESTINATION <qchfile_install_path>
	      TAGFILE_INSTALL_DESTINATION <tagsfile_install_path>
	      [COMPONENT <component>]
	      [BASE_NAME <basename>]
	      [SOURCE_DIRS <dir> [<dir2> [...]]]
	      [SOURCES <file> [<file2> [...]]]
	      |MD_MAINPAGE <md_file>]
	      [INCLUDE_DIRS <incdir> [<incdir2>	[...]]]
	      [IMAGE_DIRS <idir> [<idir2> [...]]]
	      [EXAMPLE_DIRS <edir> [<edir2> [...]]]
	      [ORG_DOMAIN <domain>]
	      [NAMESPACE <namespace>]
	      [LINK_QCHS <qch> [<qch2> [...]]]
	      [PREDEFINED_MACROS <macro[=content]> [<macro2[=content]> [...]]]
	      [BLANK_MACROS <macro> [<macro2> [...]]]
	      [CONFIG_TEMPLATE <configtemplate_file>]
	      [VERBOSE]
	  )

       This macro adds a target	called <target_name> for the  creation	of  an
       API  documentation manual in the	QCH format from	the given sources.  It
       currently uses doxygen, future versions	might  optionally  also	 allow
       other  tools.   Next  to	the QCH	file the target	will generate a	corre-
       sponding	doxygen	tag file, which	enables	creating links from other doc-
       umentation into the generated QCH file.

       It is recommended to make the use of this macro optional, by  depending
       the  call  to ecm_add_qch on a CMake option being set, with a name like
       BUILD_QCH and being TRUE	by default. This will allow the	developers  to
       saves  resources	 on  normal source development build cycles by setting
       this option to FALSE.

       The macro will set the  target  properties  DOXYGEN_TAGFILE,  QHP_NAME-
       SPACE,  QHP_NAMESPACE_VERSIONED,	QHP_VIRTUALFOLDER and LINK_QCHS	to the
       respective values, to allow other code access to	them, e.g.  the	 macro
       ecm_install_qch_export.	 To enable the use of the target <target_name>
       as item for LINK_QCHS in	 further  ecm_add_qch  calls  in  the  current
       build,  additionally  a	target	property DOXYGEN_TAGFILE_BUILD is set,
       with the	path of	the created doxygen tag	file in	the build dir.	If ex-
       isting, ecm_add_qch will	use this property instead  of  DOXYGEN_TAGFILE
       for access to the tags file.

       NAME specifies the name for the generated documentation.

       VERSION	specifies  the version of the library for which	the documenta-
       tion is created.

       BASE_NAME specifies the base name for the generated files.  The default
       basename	is <name>.

       SOURCE_DIRS specifies the dirs (incl. subdirs) with  the	 source	 files
       for which the API documentation should be generated.  Dirs can be rela-
       tive  to	 the current source dir. Dependencies to the files in the dirs
       are not tracked currently, other	than with the SOURCES argument.	So  do
       not  use	for sources generated during the build.	 Needs to be used when
       SOURCES or CONFIG_TEMPLATE are not used.

       SOURCES specifies the source files  for	which  the  API	 documentation
       should  be generated.  Needs to be used when SOURCE_DIRS	or CONFIG_TEM-
       PLATE are not used.

       MD_MAINPAGE specifies a file in Markdown	format that should be used  as
       main  page.  This  page	will overrule any \mainpage command in the in-
       cluded sources.

       INCLUDE_DIRS specifies the dirs which should be searched	 for  included
       headers.	Dirs can be relative to	the current source dir.	Since 5.63.

       IMAGE_DIRS specifies the	dirs which contain images that are included in
       the documentation. Dirs can be relative to the current source dir.

       EXAMPLE_DIRS  specifies	the  dirs  which contain examples that are in-
       cluded in the documentation. Dirs can be	relative to the	current	source
       dir.

       QCH_INSTALL_DESTINATION specifies where the generated QCH file will  be
       installed.

       TAGFILE_INSTALL_DESTINATION specifies where the generated tag file will
       be installed.

       COMPONENT  specifies the	installation component name with which the in-
       stall rules for the generated QCH file and tag file are associated.

       NAMESPACE can be	used to	set a custom namespace <namespace> of the gen-
       erated QCH file.	The namepspace is used as the unique id	by QHelpEngine
       (cmp.  https://doc.qt.io/qt-5/qthelpproject.html#namespace).   The  de-
       fault  namespace	 is <domain>.<name>.  Needs to be used when ORG_DOMAIN
       is not used.

       ORG_DOMAIN can be used to define	the organization domain	prefix for the
       default namespace of the	generated QCH file.  Needs  to	be  used  when
       NAMESPACE is not	used.

       LINK_QCHS  specifies  a	list of	other QCH targets which	should be used
       for creating references to API documentation of code  in	 external  li-
       braries.	 For each target <qch> in the list these target	properties are
       expected	to be defined: DOXYGEN_TAGFILE,	QHP_NAMESPACE and QHP_VIRTUAL-
       FOLDER.	 If  any of these is not existing, <qch> will be ignored.  Use
       the macro ecm_install_qch_export	for  exporting	a  target  with	 these
       properties  with	 the  CMake config of a	library.  Any target <qch> can
       also be one created before in the same buildsystem by another  call  of
       ecm_add_qch.

       PREDEFINED_MACROS specifies a list of C/C++ macros which	should be han-
       dled as given by	the API	dox generation tool.  Examples are macros only
       defined	in generated files, so whose definition	might be not available
       to the tool.

       BLANK_MACROS specifies a	list of	C/C++ macro names which	should be  ig-
       nored  by the API dox generation	tool and handled as if they resolve to
       empty strings.  Examples	are export macros only	defined	 in  generated
       files, so whose definition might	be not available to the	tool.

       CONFIG_TEMPLATE	specifies  a custom cmake template file	for the	config
       file that is created to control the execution of	the API	dox generation
       tool.  The following CMake variables need to be used:  -	 ECM_QCH_DOXY-
       GEN_QHELPGENERATOR_EXECUTABLE - ECM_QCH_DOXYGEN_FILEPATH, ECM_QCH_DOXY-
       GEN_TAGFILE  The	following CMake	variables can be used: - ECM_QCH_DOXY-
       GEN_PROJECTNAME - ECM_QCH_DOXYGEN_PROJECTVERSION	- ECM_QCH_DOXYGEN_VIR-
       TUALFOLDER - ECM_QCH_DOXYGEN_FULLNAMESPACE - ECM_QCH_DOXYGEN_TAGFILES -
       ECM_QCH_DOXYGEN_WARN_LOGFILE - ECM_QCH_DOXYGEN_QUIET There is no	 guar-
       antue that the other CMake variables currently used in the default con-
       fig  file  template will	also be	present	with the same semantics	in fu-
       ture versions of	this macro.

       VERBOSE tells the API dox generation tool to be more verbose about  its
       activity.

       The  default  config  file  for the API dox generation tool, so the one
       when not	using CONFIG_TEMPLATE, allows code to handle the case of being
       processed by the	tool by	defining the C/C++ preprocessor	macro  K_DOXY-
       GEN when	run (since v5.67.0). For backward-compatibility	also the defi-
       nition DOXYGEN_SHOULD_SKIP_THIS is set, but its usage is	deprecated.

       Example usage:

	  ecm_add_qch(
	      MyLib_QCH
	      NAME MyLib
	      VERSION "0.42.0"
	      ORG_DOMAIN org.myorg
	      SOURCE_DIRS
		  src
	      LINK_QCHS
		  Qt5Core_QCH
		  Qt5Xml_QCH
		  Qt5Gui_QCH
		  Qt5Widgets_QCH
	      BLANK_MACROS
		  MyLib_EXPORT
		  MyLib_DEPRECATED
	      TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
	      QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
	      COMPONENT	Devel
	  )

       Example usage (with two QCH files, second linking first):

	  ecm_add_qch(
	      MyLib_QCH
	      NAME MyLib
	      VERSION ${MyLib_VERSION}
	      ORG_DOMAIN org.myorg
	      SOURCES ${MyLib_PUBLIC_HEADERS}
	      MD_MAINPAGE src/mylib/README.md
	      LINK_QCHS	Qt5Core_QCH
	      TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
	      QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
	      COMPONENT	Devel
	  )
	  ecm_add_qch(
	      MyOtherLib_QCH
	      NAME MyOtherLib
	      VERSION ${MyOtherLib_VERSION}
	      ORG_DOMAIN org.myorg
	      SOURCES ${MyOtherLib_PUBLIC_HEADERS}
	      MD_MAINPAGE src/myotherlib/README.md
	      LINK_QCHS	Qt5Core_QCH MyLib_QCH
	      TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
	      QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
	      COMPONENT	Devel
	  )

	  ecm_install_qch_export(
	      TARGETS [<name> [<name2> [...]]]
	      FILE <file>
	      DESTINATION <dest>
	      [COMPONENT <component>]
	  )

       This  macro  creates and	installs a CMake file <file> which exports the
       given QCH targets <name>	etc., so they can be picked up by  CMake-based
       builds	of   other  software  that  also  generate  QCH	 files	(using
       ecm_add_qch) and	which should include links to the QCH files created by
       the given targets.  The installed CMake file <file> is expected	to  be
       included	 by the	CMake config file created for the software the related
       QCH files are documenting.

       TARGETS specifies the QCH targets which should be exported. If a	target
       does not	exist or does not have all needed properties, a	 warning  will
       be  generated  and  the target skipped.	This behaviour might change in
       future versions to result in a fail instead.

       FILE specifies the name of the created CMake  file,  typically  with  a
       .cmake extension.

       DESTINATION  specifies  the directory on	disk to	which the file will be
       installed. It usually is	the same as the	one  where  the	 CMake	config
       files for this software are installed.

       COMPONENT  specifies the	installation component name with which the in-
       stall rule is associated.

       Example usage:

	  ecm_install_qch_export(
	      TARGETS MyLib_QCH
	      FILE MyLibQCHTargets.cmake
	      DESTINATION "${CMAKE_INSTALL_PREFIX}/lib/cmake/MyLib"
	      COMPONENT	Devel
	  )

       Since 5.36.0.

   ECMAddQtDesignerPlugin
       This module provides the	ecm_add_qtdesignerplugin function for generat-
       ing Qt Designer plugins for custom widgets. Each	of  those  widgets  is
       described using a second	function ecm_qtdesignerplugin_widget.

	  ecm_add_qtdesignerplugin(<target_name>
	      NAME <name>
	      WIDGETS <widgetid> [<widgetid2> [...]]
	      LINK_LIBRARIES <lib> [<lib2> [...]]
	      INSTALL_DESTINATION <install_path>
	      [OUTPUT_NAME <output_name>]
	      [DEFAULT_GROUP <group>]
	      [DEFAULT_HEADER_CASE <SAME_CASE|LOWER_CASE|UPPER_CASE>]
	      [DEFAULT_HEADER_EXTENSION	<header_extension>]
	      [DEFAULT_ICON_DIR	<icon_dir>]
	      [INCLUDE_FILES <include_file> [<include_file2> [...]]]
	      [SOURCES <src> [<src2> [...]]]
	      [COMPONENT <component>]
	  )

       NAME  specifies the base	name to	use in the generated sources.  The de-
       fault is	<target_name>.

       WIDGETS specifies the widgets the plugin	should	support.  Each	widget
       has  to be defined before by a call of ecm_qtdesignerplugin_widget with
       the respective <widgetid>, in a scope including the current call.

       LINK_LIBRARIES specifies	the libraries to link against. This will be at
       least the library providing the widget class(es).

       INSTALL_DESTINATION specifies where the generated plugin	binary will be
       installed.

       OUTPUT_NAME specifies the name of the plugin  binary.  The  default  is
       <target_name>.

       DEFAULT_GROUP specifies the default group in Qt Designer	where the wid-
       gets will be placed. The	default	is Custom.

       DEFAULT_HEADER_CASE  specifies  how  the	 name of the header is derived
       from the	widget class name.  The	default	is LOWER_CASE.

       DEFAULT_HEADER_EXTENSION	specifies what file name extension is used for
       the header file derived from the	class name.  The default is h.

       DEFAULT_ICON_DIR	specifies what file name extension  is	used  for  the
       header file derived from	the class name.	 The default is	pics.

       INCLUDE_FILES  specifies	 additional  include files to include with the
       generated source	file. This can be needed for custom code used in  ini-
       tializing or creating widgets.

       SOURCES	specifies  additional  source  files to	build the plugin from.
       This can	be needed to support custom code used in initializing or  cre-
       ating widgets.

       COMPONENT  specifies the	installation component name with which the in-
       stall rules for the generated plugin are	associated.

	  ecm_qtdesignerplugin_widget(<widgetid>
	      [CLASS_NAME <class_name>]
	      [INCLUDE_FILE <include_file>]
	      [CONTAINER]
	      [ICON <iconfile>]
	      [TOOLTIP <tooltip>]
	      [WHATSTHIS <whatsthis>]
	      [GROUP <group>]
	      [CREATE_WIDGET_CODE_FROM_VARIABLE	<create_widget_code_variable>]
	      [INITIALIZE_CODE_FROM_VARIABLE <initialize_code_variable]
	      [DOM_XML_FROM_VARIABLE <dom_xml_variable>]
	      [IMPL_CLASS_NAME <impl_class_name>]
	      [CONSTRUCTOR_ARGS_CODE <constructor_args_code>]
	      [CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE <constructor_args_code_variable>]
	  )

       CLASS_NAME specifies the	name of	 the  widget  class,  including	 name-
       spaces.	The default is <widgetid>.

       INCLUDE_FILE  specifies	the  include file to use for the class of this
       widget. The default is derived from <class_name>	as configured  by  the
       DEFAULT_HEADER_*	 options  of  ecm_add_qtdesignerplugin,	also replacing
       any namespace separators	with /.

       CONTAINER specifies, if set, that this widget is	a container for	 other
       widgets.

       ICON specifies the icon file to use as symbol for this widget.  The de-
       fault is	{lowercased <class_name>}.png in the default icons dir as con-
       figured	by the DEFAULT_ICON_DIR	option of ecm_add_qtdesignerplugin, if
       such a file exists.

       TOOLTIP specifies the tooltip text to use for this widget.  Default  is
       <class_name> Widget.

       WHATSTHIS  specifies  the  Whats-This text to use for this widget.  De-
       faults to the tooltip.

       GROUP specifies the group in Qt	Designer  where	 the  widget  will  be
       placed.	 The  default is set as	configured by the DEFAULT_GROUP	option
       of ecm_add_qtdesignerplugin.

       CREATE_WIDGET_CODE_FROM_VARIABLE	specifies the variable to get from the
       C++ code	to use as factory code to create an instance  of  the  widget,
       for  the	override of QDesignerCustomWidgetInterface::createWidget(QWid-
       get* parent).  The default is  return  new  <impl_class_name><construc-
       tor_args_code>;.

       INITIALIZE_CODE_FROM_VARIABLE  specifies	 the  variable to get from the
       C++ code	 to  use  with	the  override  of  QDesignerCustomWidgetInter-
       face::initialize(QDesignerFormEditorInterface*  core).  The code	has to
       use the present class member m_initialized  to  track  and  update  the
       state.  The  default  code simply sets m_initialized to true, if	it was
       not before.

       DOM_XML_FROM_VARIABLE specifies the variable to get from	the string  to
       use   with   the	  optional   override  of  QDesignerCustomWidgetInter-
       face::domXml().	Default	does not override.

       IMPL_CLASS_NAME specifies the name of the widget	class to use  for  the
       widget instance with Qt Designer. The default is	<class_name>.

       CONSTRUCTOR_ARGS_CODE specifies the C++ code to use for the constructor
       arguments  with	the  default of	CREATE_WIDGET_CODE_FROM_VARIABLE. Note
       that the	parentheses are	required. The default is (parent).

       CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE specifies the variable to get  from
       the  C++	code instead of	passing	it directly via	CONSTRUCTOR_ARGS_CODE.
       This can	be needed if the code is more  complex	and  e.g.  includes  ;
       chars.

       Example usage:

	  ecm_qtdesignerplugin_widget(FooWidget
	      TOOLTIP "Enables to browse foo."
	      GROUP "Views (Foo)"
	  )

	  set(BarWidget_CREATE_WIDGET_CODE
	  "
	      auto* widget = new BarWidget(parent);
	      widget->setBar("Example bar");
	      return widget;
	  ")

	  ecm_qtdesignerplugin_widget(BarWidget
	      TOOLTIP "Displays	bars."
	      GROUP "Display (Foo)"
	      CREATE_WIDGET_CODE_FROM_VARIABLE BarWidget_CREATE_WIDGET_CODE
	  )

	  ecm_add_qtdesignerplugin(foowidgets
	      NAME FooWidgets
	      OUTPUT_NAME foo2widgets
	      WIDGETS
		  FooWidget
		  BarWidget
	      LINK_LIBRARIES
		  Foo::Widgets
	      INSTALL_DESTINATION "${KDE_INSTALL_QTPLUGINDIR}/designer"
	      COMPONENT	Devel
	  )

       Since 5.62.0.

   ECMAddTests
       Convenience functions for adding	tests.

	  ecm_add_tests(<sources>
	      [COMPILE_DEFINITIONS <definition>	[<definition> [...]]] #	Since 6.13.0
	      [ENVIRONMENT <list>]  # Since 6.13.0
	      LINK_LIBRARIES <library> [<library> [...]]
	      [NAME_PREFIX <prefix>]
	      [GUI]
	      [TARGET_NAMES_VAR	<target_names_var>]
	      [TEST_NAMES_VAR <test_names_var>]
	      [WORKING_DIRECTORY <dir>]	#  Since 5.111
	  )

       A  convenience function for adding multiple tests, each consisting of a
       single source file. For each file in <sources>, an executable target is
       created (whose name is the base name of the source file)	with the  com-
       piler  definitions passed with COMPILE_DEFINITIONS. This	will be	linked
       against the libraries given with	LINK_LIBRARIES.	Each  executable  will
       be  added as a test with	the same name and can have an environment pro-
       vided by	ENVIRONMENT.

       If NAME_PREFIX is given,	this prefix will  be  prepended	 to  the  test
       names,  but  not	 the  target  names.  As a result, it will not prevent
       clashes between tests with the same name	 in  different	parts  of  the
       project,	 but it	can be used to give an indication of where to look for
       a failing test.

       If the flag GUI is passed the test binaries will	 be  GUI  executables,
       otherwise  the resulting	binaries will be console applications (regard-
       less of the value of CMAKE_WIN32_EXECUTABLE or CMAKE_MACOSX_BUNDLE). Be
       aware that this changes the executable entry point on Windows (although
       some frameworks,	such as	Qt, abstract this difference away).

       The tests will be build with -DQT_FORCE_ASSERTS to enable assertions in
       the test	executable even	for release builds.

       The TARGET_NAMES_VAR and	TEST_NAMES_VAR	arguments,  if	given,	should
       specify	a  variable  name  to receive the list of generated target and
       test names, respectively. This makes it convenient to apply  properties
       to  them	 as  a	whole,	for  example, using set_target_properties() or
       set_tests_properties().

       The  generated  target	executables   will   have   the	  effects   of
       ecm_mark_as_test() (from	the ECMMarkAsTest module) applied to it.

       WORKING_DIRECTORY  sets the test	property WORKING_DIRECTORY in which to
       execute the test. By default the	 test  will  be	 run  in  ${CMAKE_CUR-
       RENT_BINARY_DIR}.  The working directory	can be specified using genera-
       tor expressions.	Since 5.111.

	  ecm_add_test(
	      <sources>
	      [COMPILE_DEFINITIONS <definition>	[<definition> [...]]] #	Since 6.13.0
	      [ENVIRONMENT <list>]  # Since 6.13.0
	      LINK_LIBRARIES <library> [<library> [...]]
	      [TEST_NAME <name>]
	      [NAME_PREFIX <prefix>]
	      [GUI]
	      [WORKING_DIRECTORY <dir>]	#  Since 5.111
	  )

       This is a single-test form of ecm_add_tests that	allows multiple	source
       files to	be used	for a single test. If  using  multiple	source	files,
       TEST_NAME must be given;	this will be used for both the target and test
       names  (and,  as	with ecm_add_tests(), the NAME_PREFIX argument will be
       prepended to the	test name).

       WORKING_DIRECTORY sets the test property	WORKING_DIRECTORY in which  to
       execute	the  test.  By	default	 the  test will	be run in ${CMAKE_CUR-
       RENT_BINARY_DIR}. The working directory can be specified	using  genera-
       tor expressions.	Since 5.111.

       Since pre-1.0.0.

   ECMCheckOutboundLicense
       Assert that source file licenses	are compatible with a desired outbound
       license	of a compiled binary artifact (e.g., library, plugin or	appli-
       cation).

       This module provides the	ecm_check_outbound_license function that  gen-
       erates unit tests for checking the compatibility	of license statements.
       The  license statements in all tested files are required	to be added by
       using the SPDX marker SPDX-License-Identifier.

       During the CMake	configuration of the project, a	temporary license bill
       of materials (BOM) in SPDX format is generated  by  calling  the	 REUSE
       tool  (see  <https://reuse.software>).  That  BOM is parsed and license
       computations based on an	internal compatibility matrix are performed.

       Preconditions for using this module:

	      	All tested  input  source  files  must	contain	 the  SPDX-Li-
		cense-Identifier tag.

	      	Python3	must be	available.

	      	The   REUSE  tool  must	 be  available,	 which	generates  the
		bill-of-materials by running reuse spdx	on the	tested	direc-
		tory.

       When this module	is included, a SKIP_LICENSE_TESTS option is added (de-
       fault  OFF).  Turning  this  option  on skips the generation of license
       tests, which might be convenient	if licenses shall not be tested	in all
       build configurations.

	  ecm_check_outbound_license(LICENSES <outbound-licenses>
				     FILES <source-files>
				     [TEST_NAME	<name>]
				     [WILL_FAIL])

       This method adds	a custom unit test to ensure  the  specified  outbound
       license	to be compatible with the specified license headers. Note that
       a convenient way	is to use the CMake GLOB argument of  the  FILE	 func-
       tion.

       LICENSES	(List of one or	multiple outbound license regarding which the
       compatibility of	the source code	files shall be tested.)

	      Currently, the following values are supported (values are	SPDX
	      registry identifiers):

		      MIT

		      BSD-2-Clause

		      BSD-3-Clause

		      LGPL-2.0-only

		      LGPL-2.1-only

		      LGPL-3.0-only

		      GPL-2.0-only

		      GPL-3.0-only

       FILES: (List of source files that contain valid SPDX-License-Identifier
       markers.)
	      The  paths  can be relative to the CMake file that generates the
	      test case	or be absolute paths.

       TEST_NAME (Optional parameter that defines the name of the generated
       test case.)
	      If no name is defined, the relative path to the  test  directory
	      with appended license name is used. Every	test has licensecheck_
	      as prefix.

       WILL_FAIL (Optional parameter that inverts the test result. This	para-
       meter is	usually	only)
	      used for tests of	the module.

       Since 5.75.0

   ECMConfiguredInstall
       Takes a list of files, runs configure_file on each and installs the re-
       sultant configured files	in the given location.

       Any  suffix  of	.in in the passed file names will be stripped from the
       file name at the	installed location.

	  ecm_install_configured_files(
	      INPUT <file> [<file2> [...]]
	      DESTINATION <INSTALL_DIRECTORY>
	      [COPYONLY]
	      [ESCAPE_QUOTES]
	      [@ONLY]
	      [COMPONENT <component>])

       Example usage:

	  ecm_install_configured_files(INPUT foo.txt.in	DESTINATION ${KDE_INSTALL_DATADIR} @ONLY)

       This will install the file as foo.txt with any cmake variable  replace-
       ments made into the data	directory.

       Since 5.73.0.

   ECMCoverageOption
       Allow users to easily enable GCov code coverage support.

       Code  coverage allows you to check how much of your codebase is covered
       by your tests. This module makes	it easy	 to  build  with  support  for
       GCov.

       When this module	is included, a BUILD_COVERAGE option is	added (default
       OFF). Turning this option on enables GCCs coverage instrumentation, and
       links against libgcov.

       NOTE:
	  This will probably break the build if	you are	not using GCC.

       Since 1.3.0.

   ECMCreateQmFromPoFiles
       WARNING:
	  This	module	is  deprecated	and  will  be  removed by ECM 1.0. Use
	  ECMPoQmTools instead.

       Generate	QTranslator (.qm) catalogs from	Gettext	(.po) catalogs.

	  ecm_create_qm_from_po_files(PO_FILES <file1>... <fileN>
				      [CATALOG_NAME <catalog_name>]
				      [INSTALL_DESTINATION <install_destination>])

       Creates the necessary rules to compile .po files	into  .qm  files,  and
       install them.

       The  .qm	 files	are  installed in <install_destination>/<lang>/LC_MES-
       SAGES, where <install_destination> is the INSTALL_DESTINATION  argument
       and <lang> is extracted from the	Language field inside the .po file.

       INSTALL_DESTINATION  defaults to	${LOCALE_INSTALL_DIR} if defined, oth-
       erwise it uses ${CMAKE_INSTALL_LOCALEDIR} if that is defined, otherwise
       it uses share/locale.

       CATALOG_NAME defines the	name of	the installed .qm files. If  set,  .qm
       files will be installed as <catalog_name>.qm. If	not set	.qm files will
       be named	after the name of their	source .po file.

       Setting	the catalog name is useful when	all .po	files for a target are
       kept in a single	source directory.  For	example,  the  mylib  probject
       might keep all its translations in a po directory, like this:

	  po/
	      es.po
	      fr.po

       Without setting CATALOG_NAME, those .po will be turned into .qm and in-
       stalled as:

	  share/locale/fr/LC_MESSAGES/fr.qm
	  share/locale/es/LC_MESSAGES/es.qm

       If CATALOG_NAME is set to mylib,	they will be installed as:

	  share/locale/fr/LC_MESSAGES/mylib.qm
	  share/locale/es/LC_MESSAGES/mylib.qm

       Which is	what the loader	created	by ecm_create_qm_loader() expects.

       ecm_create_qm_from_po_files() creates a translation target. This	target
       builds all .po files into .qm files.

	  ecm_create_qm_loader(<source_files_var> <catalog_name>)

       ecm_create_qm_loader()  generates a C++ file which ensures translations
       are automatically loaded	at startup. The	path of	the .cpp file  is  ap-
       pended to <source_files_var>.  Typical usage is like:

	  set(mylib_SRCS foo.cpp bar.cpp)
	  ecm_create_qm_loader(mylib_SRCS mylib)
	  add_library(mylib ${mylib_SRCS})

       This  generates a C++ file which	loads mylib.qm at startup, assuming it
       has been	installed by ecm_create_qm_from_po_files(),  and  compiles  it
       into mylib.

       Since pre-1.0.0.

   ECMDeprecationSettings
       This module provides the	ecm_set_disabled_deprecation_versions function
       setting the excluding deprecated	API for	Qt and KF projects.

       This  method  expects  pairs of the identifier and deprecation version.
       For the identifier  QT  this  functions	adds  the  definition  QT_DIS-
       ABLE_DEPRECATED_BEFORE  with the	given version in a hexadecimal format.
       Otherwise the name for the  definition  is  generated  using  ${IDENTI-
       FIER}_DISABLE_DEPRECATED_BEFORE_AND_AT,	following  the	naming	of the
       generated code in ECMGenerateExportHeader.  The version for the defini-
       tion can	be overwritten,	by passing definition name and the deprecation
       version as a CMake definition. This allows one to exclude  deprecations
       without having to edit the CMakeLists.txt file.

       This module provides the	following function:

	  ecm_set_disabled_deprecation_versions(
	      [DISABLE_NEWER_WARNINGS] # since 5.96
	      [<identifier> <deprecation_version>]
	      [<identifier2> <deprecation_version2>]
	  )

       DISABLE_NEWER_WARNINGS  disables	additionally the compiler warnings for
       API deprecated in newer versions	of the same major version.

       Example usage:

	  set(QT_MIN_VERSION "5.15.2")
	  set(KF5_MIN_VERSION "5.90")

	  ecm_set_disabled_deprecation_versions(
	    QT ${QT_MIN_VERSION}
	    KF ${KF5_MIN_VERSION}
	    KCOREADDONS	5.89.0 # In case we depend on deprecated KCoreAddons API
	  )

       Since 5.91

   ECMEnableSanitizers
       Enable compiler sanitizer flags.

       The following sanitizers	are supported:

        Address Sanitizer

        Memory	Sanitizer

        Thread	Sanitizer

        Leak Sanitizer

        Undefined Behaviour Sanitizer

       All of them are implemented in Clang, depending on  your	 version,  and
       there  is  an work in progress in GCC, where some of them are currently
       implemented.

       This module will	check your current compiler version to see if it  sup-
       ports the sanitizers that you want to enable

   Usage
       Simply add:

	  include(ECMEnableSanitizers)

       to   your   CMakeLists.txt.  Note  that	this  module  is  included  in
       KDECompilerSettings, so projects	using that module do not need to  also
       include this one.

       The  sanitizers	are  not  enabled  by  default.	 Instead, you must set
       ECM_ENABLE_SANITIZERS (either in	your CMakeLists.txt or on the  command
       line)  to  a semicolon-separated	list of	sanitizers you wish to enable.
       The options are:

        address

        memory

        thread

        leak

        undefined

        fuzzer

       The sanitizers address, memory and thread are mutually exclusive.   You
       cannot enable two of them in the	same build.

       leak requires the  address sanitizer.

       NOTE:
	  To  reduce  the overhead induced by the instrumentation of the sani-
	  tizers, it is	advised	 to  enable  compiler  optimizations  (-O1  or
	  higher).

   Example
       This is an example of usage:

	  mkdir	build
	  cd build
	  cmake	-DECM_ENABLE_SANITIZERS='address;leak;undefined' ..

       NOTE:
	  Most of the sanitizers will require Clang. To	enable it, use:

	      -DCMAKE_CXX_COMPILER=clang++

       Since 1.3.0.

   ECMFindModuleHelpers
       Helper	macros	for  find  modules:  ecm_find_package_version_check(),
       ecm_find_package_parse_components()   and   ecm_find_package_handle_li-
       brary_components().

	  ecm_find_package_version_check(<name>)

       Prints  warnings	 if  the  CMake	version	or the projects	required CMake
       version is older	than that required by extra-cmake-modules.

	  ecm_find_package_parse_components(<name>
	      RESULT_VAR <variable>
	      KNOWN_COMPONENTS <component1> [<component2> [...]]
	      [SKIP_DEPENDENCY_HANDLING])

       This macro will populate	<variable> with	a list of components found  in
       <name>_FIND_COMPONENTS, after checking that all those components	are in
       the  list  of KNOWN_COMPONENTS; if there	are any	unknown	components, it
       will  print  an	error  or  warning  (depending	 on   the   value   of
       <name>_FIND_REQUIRED) and call return().

       The  order of components	in <variable> is guaranteed to match the order
       they are	listed in the KNOWN_COMPONENTS argument.

       If SKIP_DEPENDENCY_HANDLING is not set, for each	component the variable
       <name>_<component>_component_deps will be checked for dependent	compo-
       nents.	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> [...]]
	      [SKIP_DEPENDENCY_HANDLING])
	      [SKIP_PKG_CONFIG])

       Creates an imported library target for each component.	The  operation
       of this macro depends on	the presence of	a number of CMake variables.

       The <name>_<component>_lib variable should contain the name of this li-
       brary,  and  <name>_<component>_header variable should contain the name
       of a header file	associated with	it (whatever relative path is normally
       passed to #include). <name>_<component>_header_subdir variable  can  be
       used to specify which subdirectory of the include path the headers will
       be  found  in.	ecm_find_package_components() will then	search for the
       library and include directory (creating	appropriate  cache  variables)
       and create an imported library target named <name>::<component>.

       Additional variables can	be used	to provide additional information:

       If  SKIP_PKG_CONFIG, the	<name>_<component>_pkg_config variable is set,
       and pkg-config is found,	the pkg-config module given by	<name>_<compo-
       nent>_pkg_config	 will  be searched for and used	to help	locate the li-
       brary and header	file.  It will also  be	 used  to  set	<name>_<compo-
       nent>_VERSION.

       Note  that if version information is found via pkg-config, <name>_<com-
       ponent>_FIND_VERSION can	be set to require  a  particular  version  for
       each component.

       If  SKIP_DEPENDENCY_HANDLING  is	 not set, the INTERFACE_LINK_LIBRARIES
       property	of the imported	target for <component> will be set to  contain
       the  imported  targets  for  the	 components  listed  in	<name>_<compo-
       nent>_component_deps.  <component>_FOUND	will also be set to  FALSE  if
       any  of	the  components	 in  <name>_<component>_component_deps are not
       found.	This  requires	the  components	 in  <name>_<component>_compo-
       nent_deps to be listed before <component> in the	COMPONENTS argument.

       The following variables will be set:

       <name>_TARGETS
	      the imported targets

       <name>_LIBRARIES
	      the found	libraries

       <name>_INCLUDE_DIRS
	      the combined required include directories	for the	components

       <name>_DEFINITIONS
	      the other	CFLAGS provided	by pkg-config, if any

       <name>_VERSION
	      the  value of <name>_<component>_VERSION for the first component
	      that has this variable set (note that  components	 are  searched
	      for  in  the order they are passed to the	macro),	although if it
	      is already set, it will not be altered

       NOTE:
	  These	variables are never cleared, so	if ecm_find_package_handle_li-
	  brary_components() is	called multiple	times  with  different	compo-
	  nents	 (typically  because  of  multiple  find_package() calls) then
	  <name>_TARGETS, for example, will contain all	the targets  found  in
	  any call (although no	duplicates).

       Since pre-1.0.0.

   ECMFindQmlModule
       Finds QML import	modules	to set them as runtime dependencies.

       Because QML modules are not compile time	requirements, they can be easy
       to  miss	 by packagers and developers, causing QML apps to fail to dis-
       play.  Use this CMake module to ensure a	QML  module  is	 installed  at
       compile time during CMake configuration.

       Internally, this	CMake module looks for the qmldir and, if needed, uses
       qmlplugindump  to find the plugins and set them up as runtime dependen-
       cies.

	  ecm_find_qmlmodule(<module_name>
	    <version> #	Optional for Qt6 builds
	    [REQUIRED] # Since 6.0
	  )

       Usage example:

	  ecm_find_qmlmodule(org.kde.kirigami 2.1)
	  ecm_find_qmlmodule(org.kde.kirigami 2.1 REQUIRED) # CMake will fail if the required version is not found
	  ecm_find_qmlmodule(org.kde.kirigami) # Find it without a given version
	  ecm_find_qmlmodule(org.kde.kirigami REQUIRED)	# CMake	will fail if it	is not found

       Since 5.38.0.

   ECMGenerateDBusServiceFile
       This module provides the	 ecm_generate_dbus_service_file	 function  for
       generating and installing a D-Bus service file.

	  ecm_generate_dbus_service_file(
	      NAME <service name>
	      EXECUTABLE <executable>
	      [SYSTEMD_SERVICE <systemd	service>]
	      DESTINATION <install_path>
	      [RENAME <dbus service filename>] # Since 5.75
	  )

       A  D-Bus	 service file <service name>.service will be generated and in-
       stalled in the relevant D-Bus config location.  This  filename  can  be
       customized with RENAME.

       <executable>  must  be  an  absolute path to the	installed service exe-
       cutable.	When using it with KDEInstallDirs it needs to  be  the	_FULL_
       variant of the path variable.

       NOTE:
	  On  Windows,	the  macro  will  only use the file name part of <exe-
	  cutable> since D-Bus service executables are to be installed in  the
	  same directory as the	D-Bus daemon.

       Optionally,  a  <systemd	service> can be	specified to launch the	corre-
       sponding	systemd	service	instead	of the <executable> if the D-Bus  dae-
       mon is started by systemd.

       Example usage:

	  ecm_generate_dbus_service_file(
	      NAME org.kde.kded5
	      EXECUTABLE ${KDE_INSTALL_FULL_BINDIR}/kded5
	      DESTINATION ${KDE_INSTALL_DBUSSERVICEDIR}
	  )

	  ecm_generate_dbus_service_file(
	      NAME org.kde.kded5
	      EXECUTABLE ${KDE_INSTALL_FULL_BINDIR}/kded5
	      SYSTEMD_SERVICE plasma-kded.service
	      DESTINATION ${KDE_INSTALL_DBUSSERVICEDIR}
	      RENAME org.kde.daemon.service
	  )

       Since 5.73.0.

   ECMGenerateExportHeader
       This module provides the	ecm_generate_export_header function for	gener-
       ating export macros for libraries with version-based control over visi-
       bility  of  and	compiler  warnings  for	deprecated API for the library
       user, as	well as	over excluding deprecated API and their	implementation
       when building the library itself.

       For preparing some values useful	in the	context	 it  also  provides  a
       function	ecm_export_header_format_version.

	  ecm_generate_export_header(<library_target_name>
	      VERSION <version>
	      [BASE_NAME <base_name>]
	      [GROUP_BASE_NAME <group_base_name>]
	      [EXPORT_MACRO_NAME <export_macro_name>]
	      [EXPORT_FILE_NAME	<export_file_name>]
	      [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
	      [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
	      [INCLUDE_GUARD_NAME <include_guard_name>]
	      [STATIC_DEFINE <static_define>]
	      [PREFIX_NAME <prefix_name>]
	      [DEPRECATED_BASE_VERSION <deprecated_base_version>]
	      [DEPRECATION_VERSIONS <deprecation_version> [<deprecation_version2> [...]]]
	      [EXCLUDE_DEPRECATED_BEFORE_AND_AT	<exclude_deprecated_before_and_at_version>]
	      [NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE]
	      [NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE]
	      [USE_VERSION_HEADER [<version_file_name>]] #  Since 5.106
	      [VERSION_BASE_NAME <version_base_name>] #	 Since 5.106
	      [VERSION_MACRO_NAME <version_macro_name>]	#  Since 5.106
	      [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
	  )

       VERSION	specifies the version of the library, given in the format <ma-
       jor>.<minor>.<patchlevel>.

       GROUP_BASE_NAME specifies the name to use for the macros	 defining  li-
       brary  group default values. If set, this will generate code supporting
       <group_base_name>_NO_DEPRECATED_WARNINGS,	<group_base_name>_DIS-
       ABLE_DEPRECATED_BEFORE_AND_AT,	    <group_base_name>_DEPRECATED_WARN-
       INGS_SINCE  and <group_base_name>_NO_DEPRECATED (see  below).   If  not
       set, the	generated code will ignore any such macros.

       DEPRECATED_BASE_VERSION	specifies  the	default	 version before	and at
       which deprecated	API is disabled. Possible values are 0,	CURRENT	(which
       resolves	to <version>) and a version string in the format  <major>.<mi-
       nor>.<patchlevel>.  The default is the value of <exclude_deprecated_be-
       fore_and_at_version> if set, or <major>.0.0, with  <major>  taken  from
       <version>.

       DEPRECATION_VERSIONS  specifies	versions  in <major>.<minor> format in
       which API was declared deprecated. Any version used with	the  generated
       macro  <prefix_name><base_name>_DEPRECATED_VERSION(major,  minor, text)
       or  <prefix_name><base_name>_DEPRECATED_VERSION_BELATED(major,	minor,
       textmajor,  textminor,  text)  needs  to	 be listed here, otherwise the
       macro will fail to work.

       EXCLUDE_DEPRECATED_BEFORE_AND_AT	specifies the version  for  which  all
       API  deprecated	before	and  at	should be excluded from	the build com-
       pletely.	 Possible values are 0 (default), CURRENT (which  resolves  to
       <version>)  and	a version string in the	format <major>.<minor>.<patch-
       level>.

       NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE specifies	 that  the  definition
       <prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE  will  not
       be set for the library inside its own build, and	thus will  be  defined
       by  either  explicit definition in the build system configuration or by
       the default value mechanism (see	below).	 The default is	that it	is set
       for the build,  to  the	version	 specified  by	EXCLUDE_DEPRECATED_BE-
       FORE_AND_AT, so no deprecation warnings are done	for any	own deprecated
       API used	in the library implementation itself.

       NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE	specifies  that	the definition
       <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
       will not	be set in the public interface of the library inside  its  own
       build,	and   the   same   for	 the  definition  <prefix_name><upper-
       case_base_name>_DEPRECATED_WARNINGS_SINCE   (if	 not	disabled    by
       NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE  already).   The default is that
       they are	 set,  to  the	version	 specified  by	EXCLUDE_DEPRECATED_BE-
       FORE_AND_AT,  so	 e.g.  test and	examples part of the project automati-
       cally build against the full API	included in the	build and without  any
       deprecation warnings for	it.

       USE_VERSION_HEADER   defines   whether	a   given  header  file	 <ver-
       sion_file_name> providing macros	specifying the library version	should
       be included in the generated header file. By default angle-brackets are
       used  for  the  include	statement.  To	generate  includes with	double
       quotes, add double quotes to the	argument string	(needs escaping), e.g.
       \"version.h\".  The macro from the included version header holding  the
       library	version	 is given as <version_macro_name> by the argument VER-
       SION_MACRO_NAME and used	in the	generated  code	 for  calculating  de-
       faults.	If  not	 specified, the	defaults for the version file name and
       the version macro are derived from <version_base_name> as  passed  with
       VERSION_BASE_NAME,  which  again	 defaults  to <base_name> or otherwise
       <library_target_name>.  The  macro  name	 defaults  to  <uppercase_ver-
       sion_base_name>_VERSION,	 the  version  file  name  to  <lowercase_ver-
       sion_base_name>_version.h.  Since 5.106.

       CUSTOM_CONTENT_FROM_VARIABLE specifies the name	of  a  variable	 whose
       content	will  be appended at the end of	the generated file, before any
       final inclusion guard closing. Note that	before 5.98  this  was	broken
       and would only append the string	passed as argument value.

       The function ecm_generate_export_header defines C++ preprocessor	macros
       in  the generated export	header,	some for use in	the sources of the li-
       brary the header	is generated for, other	for use	 by  projects  linking
       agsinst the library.

       The  macros for use in the library C++ sources are these, next to those
       also defined by GenerateExportHeader:

       <prefix_name><uppercase_base_name>_DEPRECATED_VERSION(major, minor,
       text)
	      to   use	 to   conditionally   set    a	  <prefix_name><upper-
	      case_base_name>_DEPRECATED macro for a class, struct or function
	      (other  elements	to be supported	in future versions), depending
	      on the visibility	macro flags set	(see below)

       <prefix_name><uppercase_base_name>_DEPRECATED_VERSION_BELATED(major,
       minor, textmajor, textminor, text)
	      to   use	 to   conditionally   set    a	  <prefix_name><upper-
	      case_base_name>_DEPRECATED macro for a class, struct or function
	      (other  elements	to be supported	in future versions), depending
	      on the visibility	macro flags set	(see below), with major	&  mi-
	      nor  applied  for	 the  logic  and textmajor & textminor for the
	      warnings message.	 Useful	for retroactive	tagging	of API for the
	      compiler without injecting the API  into	the  compiler  warning
	      conditions of already released versions.	Since 5.71.

       <prefix_name><uppercase_base_name>_ENUMERATOR_DEPRECATED_VERSION(major,
       minor, text)
	      to    use	   to	conditionally	set   a	  <prefix_name><upper-
	      case_base_name>_DEPRECATED macro for an enumerator, depending on
	      the warnings macro flags set (see	below).	In builds using	 C++14
	      standard	or  earlier,  where  enumerator	attributes are not yet
	      supported, the macro will	always yield an	 empty	string.	  With
	      MSVC it is also always an	empty string for now.  Since 5.82.

       <prefix_name><uppercase_base_name>_ENUMERATOR_DEPRECATED_VERSION_BE-
       LATED(major, minor, textmajor, textminor, text)
	      to    use	   to	conditionally	set   a	  <prefix_name><upper-
	      case_base_name>_DEPRECATED macro for an enumerator, depending on
	      the warnings macro flags set (see	below),	with major & minor ap-
	      plied for	the logic and textmajor	& textminor for	 the  warnings
	      message.	 In builds using C++14 standard	or earlier, where enu-
	      merator attributes are not yet supported,	the macro will	always
	      yield  an	 empty	string.	 Useful	for retroactive	tagging	of API
	      for the compiler without injecting the  API  into	 the  compiler
	      warning  conditions  of already released versions.  With MSVC it
	      is also always an	empty string for now.  Since 5.82.

       <prefix_name><uppercase_base_name>_ENABLE_DEPRECATED_SINCE(major, mi-
       nor)
	      evaluates	to TRUE	or FALSE depending  on	the  visibility	 macro
	      flags set	(see below). To	be used	mainly with #if/#endif to mark
	      sections of code which should be included	depending on the visi-
	      bility requested.

       <prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major,	minor)
	      evaluates	 to  TRUE  or  FALSE  depending	 on  the  value	of EX-
	      CLUDE_DEPRECATED_BEFORE_AND_AT. To be used mainly	with  #if/#en-
	      dif  to  mark sections of	two types of code: implementation code
	      for deprecated API and declaration code of deprecated API	 which
	      only may be disabled at build time of the	library	for BC reasons
	      (e.g. virtual methods, see notes below).

       <prefix_name><uppercase_base_name>_EXCLUDE_DEPRECATED_BEFORE_AND_AT
	      holds  the  version used to exclude deprecated API at build time
	      of the library.

       The macros used to control visibility when building against the library
       are:

       <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
	      definition to set	to a value in single hex number	version	 nota-
	      tion (0x<major><minor><patchlevel>).

       <prefix_name><uppercase_base_name>_NO_DEPRECATED
	      flag  to	define to disable all deprecated API, being a shortcut
	      for  settings  <prefix_name><uppercase_base_name>_DISABLE_DEPRE-
	      CATED_BEFORE_AND_AT  to  the  current  version. If both are set,
	      this flag	overrules.

       <prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE
	      definition to set	to a value in single hex number	version	 nota-
	      tion (0x<major><minor><patchlevel>). Warnings will be only acti-
	      vated  for  API  deprecated  up to and including the version. If
	      <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BE-
	      FORE_AND_AT is set (directly or via the group default), it  will
	      default to that version, resulting in no warnings. Otherwise the
	      default  is  the	current	version, resulting in warnings for all
	      deprecated API.

       <prefix_name><uppercase_base_name>_NO_DEPRECATED_WARNINGS
	      flag to define to	disable	 all  deprecation  warnings,  being  a
	      shortcut	for  setting <prefix_name><uppercase_base_name>_DEPRE-
	      CATED_WARNINGS_SINCE to 0. If both are set, this flag overrules.

       When the	GROUP_BASE_NAME	has been used, the same	macros	but  with  the
       given  <group_base_name>	prefix are available to	define the defaults of
       these macros, if	not explicitly set.

       WARNING:
	  The tricks applied here for hiding deprecated	API  to	 the  compiler
	  when building	against	a library do not work for all deprecated API:

	   virtual  methods  need  to	stay  visible to the compiler to build
	    proper virtual method tables for subclasses

	   enumerators	from enums cannot be simply removed, as	 this  changes
	    auto  values of following enumerators, also	can poke holes in enu-
	    merator series used	as index into tables

	  In such cases	the API	can be only hidden at build time  of  the  li-
	  brary,  itself,  by generated	hard coded macro settings, using <pre-
	  fix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor).

       Examples:

       Preparing a library Foo created by target foo, which is part of a group
       of libraries Bar, where some API	of Foo got deprecated at versions  5.0
       & 5.12:

	  ecm_generate_export_header(foo
	      GROUP_BASE_NAME BAR
	      VERSION ${FOO_VERSION}
	      DEPRECATION_VERSIONS 5.0 5.12
	  )

       In  the	library	 Foo  sources in the headers the API would be prepared
       like this, using	the generated macros  FOO_ENABLE_DEPRECATED_SINCE  and
       FOO_DEPRECATED_VERSION:

	  #include <foo_export.h>

	  #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
	  /**
	    * @deprecated Since	5.0
	    */
	  FOO_EXPORT
	  FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
	  void doFoo();
	  #endif

	  #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
	  /**
	    * @deprecated Since	5.12
	    */
	  FOO_EXPORT
	  FOO_DEPRECATED_VERSION(5, 12,	"Use doBar2()")
	  void doBar();
	  #endif

       Projects	 linking against the Foo library can control which part	of its
       deprecated API should be	hidden to the compiler by adding a  definition
       using  the  FOO_DISABLE_DEPRECATED_BEFORE_AND_AT	 macro variable	set to
       the desired value (in version hex number	notation):

	  add_definitions(-DFOO_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)

       Or using	the macro variable of the group:

	  add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)

       If both are specified, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT  will  take
       precedence.

       To  build  a  variant  of a library with	some deprecated	API completely
       left out	from the build,	not only optionally  invisible	to  consumers,
       one  uses  the EXCLUDE_DEPRECATED_BEFORE_AND_AT parameter. This is best
       combined	with a cached CMake variable.

	  set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control the range of deprecated API excluded from the build [default=0].")

	  ecm_generate_export_header(foo
	      VERSION ${FOO_VERSION}
	      EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
	      DEPRECATION_VERSIONS 5.0 5.12
	  )

       The macros used in the headers for library  consumers  are  reused  for
       disabling  the  API excluded in the build of the	library. For disabling
       the implementation of that API as well as for disabling deprecated  API
       which only can be disabled at build time	of the library for BC reasons,
       one uses	the generated macro FOO_BUILD_DEPRECATED_SINCE,	like this:

	  #include <foo_export.h>

	  enum Bars {
	      One,
	  #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
	      Two FOO_ENUMERATOR_DEPRECATED_VERSION(5, 0, "Use Three"),	// macro available since 5.82
	  #endif
	      Three,
	  };

	  #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
	  /**
	    * @deprecated Since	5.0
	    */
	  FOO_EXPORT
	  FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
	  void doFoo();
	  #endif

	  #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
	  /**
	    * @deprecated Since	5.12
	    */
	  FOO_EXPORT
	  FOO_DEPRECATED_VERSION(5, 12,	"Use doBar2()")
	  void doBar();
	  #endif

	  class	FOO_EXPORT Foo {
	  public:
	  #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
	      /**
		* @deprecated Since 5.0
		*/
	      FOO_DEPRECATED_VERSION(5,	0, "Feature removed")
	      virtual void doWhat();
	  #endif
	  };

	  #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
	  void doFoo()
	  {
	      // [...]
	  }
	  #endif

	  #if FOO_BUILD_DEPRECATED_SINCE(5, 12)
	  void doBar()
	  {
	      // [...]
	  }
	  #endif

	  #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
	  void Foo::doWhat()
	  {
	      // [...]
	  }
	  #endif

       So  e.g.	 if EXCLUDE_DEPRECATED_BEFORE_AND_AT is	set to 5.0.0, the enu-
       merator Two as well as the methods ::doFoo() and	Foo::doWhat() will  be
       not available to	library	consumers. The methods will not	have been com-
       piled  into  the	library	binary,	and the	declarations will be hidden to
       the compiler, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT also cannot be  used
       to reactivate them.

       When  using the NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE and the project
       for the Foo library includes also tests and  examples  linking  against
       the library and using deprecated	API (like tests	covering it), one bet-
       ter explicitly sets FOO_DISABLE_DEPRECATED_BEFORE_AND_AT	for those tar-
       gets to the version before and at which all deprecated API has been ex-
       cluded from the build.  Even more when building against other libraries
       from  the same group Bar	and disabling some deprecated API of those li-
       braries using  the  group  macro	 BAR_DISABLE_DEPRECATED_BEFORE_AND_AT,
       which also works	as default for FOO_DISABLE_DEPRECATED_BEFORE_AND_AT.

       To   get	  the	hex  number  style  value  the	helper	macro  ecm_ex-
       port_header_format_version() will be used:

	  set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control what part of deprecated API is excluded from build [default=0].")

	  ecm_generate_export_header(foo
	      VERSION ${FOO_VERSION}
	      GROUP_BASE_NAME BAR
	      EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
	      NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE
	      DEPRECATION_VERSIONS 5.0 5.12
	  )

	  ecm_export_header_format_version(${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
	      CURRENT_VERSION ${FOO_VERSION}
	      HEXNUMBER_VAR foo_no_deprecated_before_and_at
	  )

	  # disable all	deprecated API up to 5.9.0 from	all other libs of group	"BAR" that we use ourselves
	  add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050900)

	  add_executable(app app.cpp)
	  target_link_libraries(app foo)
	  target_compile_definitions(app
	       PRIVATE "FOO_DISABLE_DEPRECATED_BEFORE_AND_AT=${foo_no_deprecated_before_and_at}")

       Since 5.64.0.

   ECMGenerateHeaders
       Generate	C/C++ CamelCase	forwarding headers.

	  ecm_generate_headers(<camelcase_forwarding_headers_var>
	      HEADER_NAMES <CamelCaseName> [<CamelCaseName> [...]]
	      [ORIGINAL	<CAMELCASE|LOWERCASE>]
	      [HEADER_EXTENSION	<header_extension>]
	      [OUTPUT_DIR <output_dir>]
	      [PREFIX <prefix>]
	      [REQUIRED_HEADERS	<variable>]
	      [COMMON_HEADER <HeaderName>]
	      [RELATIVE	<relative_path>])

       For each	CamelCase header name passed to	HEADER_NAMES, a	file  of  that
       name  will be generated that will include a version with	.h or, if set,
       .<header_extension> appended.  For example, the generated header	ClassA
       will include classa.h (or ClassA.h, see ORIGINAL).  If a	 CamelCaseName
       consists	of multiple comma-separated files, e.g.	 ClassA,ClassB,ClassC,
       then  multiple camelcase	header files will be generated which are redi-
       rects to	the first header file.	The file locations of these  generated
       headers will be stored in <camelcase_forwarding_headers_var>.

       ORIGINAL	specifies how the name of the original header is written: low-
       ercased or also camelcased.  The	default	is LOWERCASE. Since 1.8.0.

       HEADER_EXTENSION	 specifies  what  file	name extension is used for the
       header files.  The default is h.	Since 5.48.0.

       PREFIX places the generated headers in subdirectories.  This should  be
       a CamelCase name	like KParts, which will	cause the CamelCase forwarding
       headers	to  be	placed in the KParts directory (e.g. KParts/Part).  It
       will also, for the convenience of code in the source distribution, gen-
       erate  forwarding  headers  based   on	the   original	 names	 (e.g.
       kparts/part.h).	 This  allows includes like "#include <kparts/part.h>"
       to be used before installation, as long as the include_directories  are
       set appropriately.

       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.

       REQUIRED_HEADERS	 specifies  an	output variable	name where all the re-
       quired 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 original variant will
       then be added to	this variable.

       COMMON_HEADER generates an additional convenience header	which includes
       all other header	files.

       The RELATIVE argument indicates where the original headers can be found
       relative	to CMAKE_CURRENT_SOURCE_DIR.  It does not affect the generated
       CamelCase  forwarding  files,  but  ecm_generate_headers() uses it when
       checking	that the original header exists, and  to  generate  originally
       named 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 usage (without PREFIX):

	  ecm_generate_headers(
	      MyLib_FORWARDING_HEADERS
	      HEADERS
		  MLFoo
		  MLBar
		  # etc
	      REQUIRED_HEADERS MyLib_HEADERS
	      COMMON_HEADER MLGeneral
	  )
	  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
		  # several classes are	contained in bar.h, so generate
		  # additional files
		  Bar,BarList
		  # 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)

       Since pre-1.0.0.

   ECMGeneratePkgConfigFile
       Generate	a pkg-config file for the benefit of autotools-based projects.

	  ecm_generate_pkgconfig_file(BASE_NAME	<baseName>
				[LIB_NAME <libName>]
				[DEPS [PRIVATE|PUBLIC] <dep> [[PRIVATE|PUBLIC] <dep> [...]]]
				[FILENAME_VAR <filename_variable>]
				[INCLUDE_INSTALL_DIR <dir>]
				[LIB_INSTALL_DIR <dir>]
				[DEFINES -D<variable=value>...]
				[DESCRIPTION <library description>] # since 5.41.0
				[URL <url>] # since 5.89.0
				[INSTALL])

       BASE_NAME is the	name of	the module. Its	the name projects will use  to
       find the	module.

       LIB_NAME	 is  the  name of the library that is being exported. If unde-
       fined, it will default to the BASE_NAME.	That means the	LIB_NAME  will
       be set as the name field	as well	as the library to link to.

       DEPS  is	the list of libraries required by this library.	Libraries that
       are not exposed to applications should be marked	with PRIVATE. The  de-
       fault  is  PUBLIC,  but	note that according to the Guide to pkg-config
       marking dependencies as private is usually preferred.  The  PUBLIC  and
       PRIVATE keywords	are supported since 5.89.0.

       FILENAME_VAR  is	specified with a variable name.	This variable will re-
       ceive the location of the generated file	will be	set, within the	 build
       directory. This way it can be used in case some processing is required.
       See also	INSTALL.

       INCLUDE_INSTALL_DIR  specifies where the	includes will be installed. If
       its not specified, it will  default  to	INSTALL_INCLUDEDIR,  CMAKE_IN-
       STALL_INCLUDEDIR	 or just include/ in case they are specified, with the
       BASE_NAME postfixed.

       LIB_INSTALL_DIR specifies where the library is being installed. If  its
       not specified, it will default to LIB_INSTALL_DIR, CMAKE_INSTALL_LIBDIR
       or just lib/ in case they are specified.

       DEFINES	is a list of preprocessor defines that it is recommended users
       of the library pass to the compiler when	using it.

       DESCRIPTION describes what this library is. If its not specified, CMake
       will first try to get the description from the  metainfo.yaml  file  or
       will create one based on	LIB_NAME. Since	5.41.0.

       URL An URL where	people can get more information	about and download the
       package.	Defaults to https://www.kde.org/. Since	5.89.0.

       INSTALL	will  cause the	module to be installed to the pkgconfig	subdi-
       rectory of LIB_INSTALL_DIR, unless the ECM_PKGCONFIG_INSTALL_DIR	 cache
       variable	is set to something different.

       NOTE:
	  The first call to ecm_generate_pkgconfig_file() with the INSTALL ar-
	  gument  will cause ECM_PKGCONFIG_INSTALL_DIR to be set to the	cache,
	  and will be used in any subsequent calls.

       To properly use this macro a version needs to be	set. To	 retrieve  it,
       ECM_PKGCONFIG_INSTALL_DIR  uses	PROJECT_VERSION.  To  set  it, use the
       project() command or the	ecm_setup_version() macro

       Example usage:

	  ecm_generate_pkgconfig_file(
	      BASE_NAME	KF5Archive
	      DEPS Qt5Core
	      FILENAME_VAR pkgconfig_filename
	      INSTALL
	  )

       Since 1.3.0.

   ECMGeneratePriFile
       Generate	a .pri file for	the benefit of qmake-based projects.

       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.

       The  main  thing	is that	this should be the modules subdirectory	of ei-
       ther 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>
				[VERSION <version>] # since 5.83
				[DEPS "<dep> [<dep> [...]]"]
				[FILENAME_VAR <filename_variable>]
				[INCLUDE_INSTALL_DIRS <dir> [<dir> [...]]]  # since 5.92
				[INCLUDE_INSTALL_DIR <dir>] # deprecated since 5.92
				[LIB_INSTALL_DIR <dir>])

       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.

       VERSION	specifies  the version of the library the .pri file describes.
       If not set, the value is	taken from the context	variable  PROJECT_VER-
       SION.   This  variable  is  usually set by the project(... VERSION ...)
       command or, if CMake policy CMP0048 is  not  NEW,  by  ECMSetupVersion.
       For  backward-compatibility  with  older	 ECM versions the PROJECT_VER-
       SION_STRING variable as set by ECMSetupVersion will be  preferred  over
       PROJECT_VERSION	if  set, unless	the minimum required version of	ECM is
       5.83 and	newer. Since 5.83.

       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 ac-
       tual 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.

       INCLUDE_INSTALL_DIRS  are  the paths (relative to CMAKE_INSTALL_PREFIX)
       that include files will be installed to.	It defaults  to	 ${INCLUDE_IN-
       STALL_DIR}/<baseName>  if  the  INCLUDE_INSTALL_DIR variable is set. If
       that variable is	not set, the CMAKE_INSTALL_INCLUDEDIR variable is used
       instead,	and if neither are set include is used.	 LIB_INSTALL_DIR oper-
       ates similarly for the installation location for	libraries; it defaults
       to ${LIB_INSTALL_DIR}, ${CMAKE_INSTALL_LIBDIR} or lib, in that order.

       INCLUDE_INSTALL_DIR is the old variant of INCLUDE_INSTALL_DIRS,	taking
       only one	directory.

       Example usage:

	  ecm_generate_pri_file(
	      BASE_NAME	KArchive
	      LIB_NAME KF5KArchive
	      DEPS "core"
	      FILENAME_VAR pri_filename
	      VERSION 4.2.0
	  )
	  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.

       Since pre-1.0.0.

   ECMGeneratePythonBindings
       This  module  is	 experimental and internal.  The interface will	likely
       change in the coming releases.

       Generate	Python bindings	using Shiboken.

	  ecm_generate_python_bindings(PACKAGE_NAME <pythonlibrary>
				       VERSION <version>
				       WRAPPED_HEADER <filename>
				       TYPESYSTEM <filename>
				       [EXPORT_TYPESYSTEM]
				       GENERATED_SOURCES <filename> [<filename>	[...]]
				       DEPENDENCIES <target> [<target> [...]]
				       QT_VERSION <version>
				       HOMEPAGE_URL <url>
				       ISSUES_URL <url>
				       AUTHOR <string>
				       README <filename> )

       <pythonlibrary> is the name of the Python library that will be created.

       VERSION is the version of the library.

       WRAPPED_HEADER is a C++ header that contains all	the required  includes
       for the library.

       TYPESYSTEM is the XML file where	the bindings are defined.

       EXPORT_TYPESYSTEM specifies that	the typesystem XML file	and the	gener-
       ated header are exported	and can	be used	by other typesystem XML	files.

       GENERATED_SOURCES is the	list of	generated C++ source files by Shiboken
       that will be used to build the shared library.

       QT_VERSION is the minimum required Qt version of	the library.

       DEPENDENCIES is the list	of dependencies	that the bindings uses.

       HOMEPAGE_URL is a URL to	the proyect homepage.

       ``
       ISSUES_URL` is a	URL where users	can report bugs	and feature requests.

       AUTHOR is a string with the author of the library.

       README is a Markdown file that will be used as the projects description
       on the Python Package Index.

   ECMGenerateQDoc
       This  module provides the ecm_generate_qdoc function for	generating API
       documentation files for projects	based on qdoc.

       It allows to generate both online HTML documentation as	well  as  (in-
       stalled)	QCH files.

	  ecm_generate_qdoc(<target_name> <qdocconf_file>)

       target_name is the library target for which the documentation is	gener-
       ated.

       qdocconf_file  is  the  .qdocconf  file that controls the documentation
       generation.

       If  the	project	 contains  multiple  libraries	with  documented  APIs
       ecm_generate_qdoc should	be called for each one.

       Example usage:

	  ecm_add_qch(KF6::CoreAddons kcoreaddons.qdocconf)

       Documentation  is not built as part of the normal build,	it needs to be
       explicity invoked using the following build targets:

        prepare_docs runs the prepare step from qdoc, which processes sources
	 and creates index files

        generate_docs runs the	generate step from qdoc, generating the	 final
	 documentation from the	index files

        install_html_docs  installs  the  generated  HTML  documentation into
	 KDE_INSTALL_QTQCHDIR from KDEInstallDirs

        generate_qch creates QCH files	out of the HTML	documentation

        install_qch_docs installs the	QCH  files  into  KDE_INSTALL_QTQCHDIR
	 from KDEInstallDirs

       The following global parameters are understood:

        QDOC_BIN: This	can be used to select another qdoc executable than the
	 one found by find_package. This is useful to test with	different ver-
	 sions of the qdoc tool.

        DOC_DESTDIR:  This  is	 where the HTML	and index files	will be	gener-
	 ated. This is useful to aggregate results from	multiple projects into
	 a single directory.

       When combining documentation from  multiple  projects  the  recommended
       procedure  is to	use a common DOC_DESTDIR and run the prepare stage for
       all before running the generate stage for all. This  ensures  that  the
       index files are all available during the	generate phase and cross-link-
       ing works as expected.

       Since 6.11.0.

   ECMGenerateQmlTypes
       Generates plugins.qmltypes files	for QML	plugins.

	  ecm_generate_qmltypes(<org.kde.pluginname> 1.3
				DESTINATION <${KDE_INSTALL_QMLDIR}/org/kde/pluginname>)

       Makes  it possible to generate plugins.qmltypes files for the QML plug-
       ins that	our project offers. These files	offer introspection  upon  our
       plugin  and are useful for integrating with IDE language	support	of our
       plugin. It offers information about the objects its methods  and	 their
       argument	types.

       The  developer will be in charge	of making sure that these files	are up
       to date.	 The plugin.qmltypes file will sit in  the  source  directory.
       This function will include the code that	installs the file in the right
       place  and  a  small  unit  test	named qmltypes-pluginname-version that
       makes sure that it doesnt need updating.

       Since 5.33.0

   ECMInstallIcons
       Installs	icons, sorting them into the correct directories according  to
       the FreeDesktop.org icon	naming specification.

	  ecm_install_icons(ICONS <icon> [<icon> [...]]
			    DESTINATION	<icon_install_dir>
			    [LANG <l10n_code>]
			    [THEME <theme>])

       The given icons,	whose names must match the pattern:

	  <size>-<group>-<name>.<ext>

       will  be	 installed  to the appropriate subdirectory of DESTINATION ac-
       cording to the FreeDesktop.org icon naming scheme. By default, they are
       installed to the	hicolor	theme, but this	can be changed using the THEME
       argument.  If the icons are localized, the LANG argument	can be used to
       install them in a locale-specific directory.

       <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, de-
       vices, emblems, emotes, intl, mimetypes,	places,	status)	and  <ext>  is
       one of .png, .mng or .svgz.

       The typical installation	directory is share/icons.

	  ecm_install_icons(ICONS 22-actions-menu_new.png
			    DESTINATION	share/icons)

       The  above  code	 will  install	the  file  22-actions-menu_new.png  as
       ${CMAKE_INSTALL_PREFIX}/share/icons/<theme>/22x22/actions/menu_new.png

       Users  of  the  KDEInstallDirs  module  would  normally	use  ${KDE_IN-
       STALL_ICONDIR}  as  the	DESTINATION, while users of the	GNUInstallDirs
       module should use ${CMAKE_INSTALL_DATAROOTDIR}/icons.

       An old form of arguments	will also be accepted:

	  ecm_install_icons(<icon_install_dir> [<l10n_code>])

       This matches files named	like:

	  <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

        br for	the Breeze icon	theme

       With this syntax, the file hi22-actions-menu_new.png would be installed
       into <icon_install_dir>/hicolor/22x22/actions/menu_new.png

       Since pre-1.0.0.

   ECMMarkAsTest
       Marks a target as only being required for tests.

	  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 KDECMakeSettings module.

       Since pre-1.0.0.

   ECMMarkNonGuiExecutable
       Marks an	executable target as not being a GUI application.

	  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.

       Since pre-1.0.0.

   ECMOptionalAddSubdirectory
       Make subdirectories 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. The	option
       will be named BUILD_<dir>.

       This is useful for meta-projects	that combine  several  mostly-indepen-
       dent sub-projects.

       If  the	CMake  variable	 DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is	set to
       TRUE for	the first CMake	run on the project, all	 optional  subdirecto-
       ries  will be disabled by default (but can of course be enabled via the
       respective options).  For example, the following	will disable  all  op-
       tional subdirectories except the	one named foo:

	  cmake	-DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_foo=TRUE myproject

       Since pre-1.0.0.

   ECMPackageConfigHelpers
       Helper macros for generating CMake package config files.

       write_basic_package_version_file()  is  the same	as the one provided by
       the CMakePackageConfigHelpers module in CMake; see that	modules	 docu-
       mentation 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_depen-
       dency().	 It  is	highly recommended that	you read the documentation for
       CMakePackageConfigHelpers for more information, particularly  with  re-
       gard to the PATH_VARS argument.

       Note  that there	is no argument that will disable the find_dependency()
       macro; if you do	not require this macro,	you should use configure_pack-
       age_config_file from the	CMakePackageConfigHelpers module.

       CMake 3.0 includes a CMakeFindDependencyMacro module that provides  the
       find_dependency() macro (which you can include()	in your	package	config
       file), so this file is only useful for projects wishing to provide con-
       fig files that will work	with CMake 2.8.12.

   Additional Config File Macros
	  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  REQUIRED  which  were passed	to the original	find_package()
       call.  It also sets an informative diagnostic message if	the dependency
       could not be found.

       Since pre-1.0.0.

   ECMPoQmTools
       This  module  provides  the  ecm_process_po_files_as_qm	 and   ecm_in-
       stall_po_files_as_qm  functions	for generating QTranslator (.qm) cata-
       logs from Gettext (.po) catalogs, and the ecm_create_qm_loader function
       for generating the necessary code to load them in a Qt  application  or
       library.

	  ecm_process_po_files_as_qm(<lang> [ALL]
				     [INSTALL_DESTINATION <install_destination>]
				     PO_FILES <pofile> [<pofile> [...]])

       Compile .po files into .qm files	for the	given language.

       If  INSTALL_DESTINATION	is  given, the .qm files are installed in <in-
       stall_destination>/<lang>/LC_MESSAGES. Typically, <install_destination>
       is set to share/locale.

       ecm_process_po_files_as_qm creates a translations target.  This	target
       builds  all .po files into .qm files.  If ALL is	specified, these rules
       are added to the	all target (and	so the .qm files will be built by  de-
       fault).

	  ecm_create_qm_loader(<sources_var_name(|target (since	5.83))>	<catalog_name>)

       Generates  C++ code which ensures translations are automatically	loaded
       at startup. The generated files are  appended  to  the  variable	 named
       <sources_var_name>  or, if the first argument is	a target (since	5.83),
       to the SOURCES property of <target>. Any	target must  be	 created  with
       add_executable()	or add_library() and not be an alias.

       It  assumes that	the .qm	file for the language code <lang> is installed
       as    <sharedir>/locale/<lang>/LC_MESSAGES/<catalog_name>.qm,	 where
       <sharedir>  is  one of the directories given by the GenericDataLocation
       of QStandardPaths.

       Typical usage is	like:

	  set(mylib_SRCS foo.cpp bar.cpp)
	  ecm_create_qm_loader(mylib_SRCS mycatalog)
	  add_library(mylib ${mylib_SRCS})

	  # Or,	since 5.83:
	  add_library(mylib foo.cpp bar.cpp)
	  ecm_create_qm_loader(mylib mycatalog)

	  ecm_install_po_files_as_qm(<podir>)

       Searches	for .po	files and installs them	to the standard	location.

       This is a convenience function which relies on all .po files being kept
       in <podir>/<lang>/, where <lang>	is the	language  the  .po  files  are
       written in.

       For example, given the following	directory structure:

	  po/
	    fr/
	      mylib.po

       ecm_install_po_files_as_qm(po)  compiles	mylib.po into mylib.qm and in-
       stalls it in  <install_destination>/fr/LC_MESSAGES.   <install_destina-
       tion>  defaults	to ${LOCALE_INSTALL_DIR} if defined, otherwise it uses
       ${CMAKE_INSTALL_LOCALEDIR}  if  that  is	 defined,  otherwise  it  uses
       share/locale.

       Since pre-1.0.0.

   ECMQmlModule
       Helper functions	to make	it easier to create QML	modules.

       This  CMake module lets you create QML-enabled targets, add C++ and QML
       files to	them, and finalize the module if needed. When using Qt	6,  it
       allows for declarative registration of QML types.

       This  CMake  module  reduces boilerplate	and takes care of special han-
       dling of	QML modules between shared and static builds:

        When building a static	version	of a  QML  module,  the	 relevant  QML
	 source	files are bundled into the static library.

        When  using a shared build, the QML plugin and	relevant QML files are
	 copied	to the targets RUNTIME_OUTPUT_DIRECTORY	to make	it  easier  to
	 run things directly from the build directory.

       Since  6.0.0,  when  using  Qt 6, most functionality of this module has
       been implemented	by upstream Qt.	Most of	the functions  here  will  now
       forward to the similar Qt functions.

       Example usage with an executable	as backing target:

	  add_executable(app)
	  ecm_add_qml_module(app
	      URI "org.example.Example"
	  )

	  target_sources(app PRIVATE main.cpp)
	  target_link_libraries(app PRIVATE Qt::Quick)

	  ecm_target_qml_sources(app SOURCES ExampleItem.qml) #	This will have 1.0 as the default version
	  ecm_target_qml_sources(app SOURCES AnotherExampleItem.qml VERSION 1.5)

	  install(TARGETS app ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

       The  above example creates an executable	target,	modifies the target to
       allow it	to accept QML files and	properties, adds source	files  to  it,
       and installs it.

       The executable is the backing target for	the QML	module,	which in prac-
       tical  terms  means the QML module is embedded into the executable, al-
       ways being loaded as part of the	application, and no plugin library  is
       created.

       Example usage with a separate QML module:

	  add_library(ExampleModule)
	  ecm_add_qml_module(ExampleModule
	      URI org.example.Example
	      GENERATE_PLUGIN_SOURCE
	  )

	  target_sources(ExampleModule PRIVATE ExamplePlugin.cpp)
	  target_link_libraries(ExampleModule PRIVATE Qt::Quick)

	  ecm_target_qml_sources(ExampleModule SOURCES ExampleItem.qml)

	  ecm_finalize_qml_module(ExampleModule	DESTINATION ${KDE_INSTALL_QMLDIR})

	  install(TARGETS ExampleModule	${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

       The  above example creates a library target, modifies the target	to al-
       low it to accept	QML files and properties, adds source files to it, and
       finalizes the target.

       The library acts	as a plugin that is expected to	be linked to  an  exe-
       cutable	later  on, in which case GENERATE_PLUGIN_SOURCE	and ecm_final-
       ize_qml_module()	are both required.

	  ecm_add_qml_module(<target name>
	      URI <module uri>
	      [VERSION <module version>]
	      [NO_PLUGIN] # Deprecated since 6.0.0 when	using Qt 6
	      [CLASSNAME <class	name>] # Deprecated since 6.0.0	when using Qt 6, use CLASS_NAME	instead
	      [QT_NO_PLUGIN] # Since 6.0.0, when using Qt 6
	      [GENERATE_PLUGIN_SOURCE] # Since 6.0.0, when using Qt 6
	      [DEPENDENCIES <dependency> ...] #	Since 6.0.0, when using	Qt 6, inherited	from qt_add_qml_module()
	      [IMPORTS <import>	...] # Since 6.0.0, when using Qt 6, inherited from qt_add_qml_module()
	  )

       This will declare a new CMake target called <target name>. The URI  ar-
       gument  is  required  and should	be a proper QML	module URI. The	URI is
       used, among others, to generate a subdirectory where the	module will be
       installed to.

       If the VERSION argument is specified, it	is used	to initialize the  de-
       fault  version  that is used by	ecm_target_qml_sources when adding QML
       files. If it is not specified, a	 default of 1.0	is used. Additionally,
       if a version greater than or equal to 2.0 is specified, the major  ver-
       sion  is	 appended to the Qt5 installation path of the module.  In case
       you dont	specify	a version for the module, but specify  a  version  for
       the individual sources, the latter will be set as the resulting version
       for this	module.	This will also be used in the ECMFindQmlModule module.

       If  the	option	NO_PLUGIN is set, a target is declared that is not ex-
       pected to contain any C++ QML plugin.

       If the optional CLASSNAME argument is supplied,	it  will  be  used  as
       class  name  in	the generated QMLDIR file. If it is not	specified, the
       target name will	be used	instead.

       You can add C++ and QML source files to the target using	target_sources
       and ecm_target_qml_sources, respectively.

       Since 5.91.0

       Since 6.0.0, when used with Qt 6, this will forward to  qt_add_qml_mod-
       ule. Any	extra arguments	will be	forwarded as well. The NO_PLUGIN argu-
       ment is deprecated and implies GENERATE_PLUGIN_SOURCE, since modules in
       Qt  6 always require a plugin or	backing	target.	If you want to use Qts
       behaviour for NO_PLUGIN,	use  QT_NO_PLUGIN  instead.  Additionally,  to
       maintain	 backward  compatibility,  by default we pass NO_GENERATE_PLU-
       GIN_SOURCE to qt_add_qml_module.

       If you are using	the executable as backing target for your QML  module,
       the  default  behavior  should suffice. If you are using	a separate QML
       module, you will	need to	have Qt	generate the plugin sources, in	 which
       case you	should pass GENERATE_PLUGIN_SOURCE.

       The  DEPENDENCIES  and  IMPORTS	options	 come from qt_add_qml_module()
       since Qt	6, and behave as in upstream Qt.

       Use DEPENDENCIES	for things like	QtCore,	 QtQuick,  your.custom.qmlmod-
       ule, as well as C++ only	dependencies. This is required for QML-exposed
       C++  code, like when subclassing	a type or using	it as a	parameter type
       in properties and invokables.

       Use IMPORTS to make a type available a part of a	modules	public	inter-
       face.  In  other	 words,	if a QML file imports this module, it also im-
       ports all the modules listed under IMPORTS.

       See Declaring module dependencies and 10	Tips to	 Make  Your  QML  Code
       Faster and More Maintainable for	details.

	  ecm_add_qml_module_dependencies(<target> DEPENDS <module string> [<module string> ...])

       Adds  the  list of dependencies specified by the	DEPENDS	argument to be
       listed as dependencies in the generated QMLDIR file of <target>.

       Since 5.91.0

       Since 6.0.0, this is deprecated and ignored when	using  Qt  6,  instead
       use the DEPENDENCIES and	IMPORTS	arguments to ecm_add_qml_module.

	  ecm_target_qml_sources(<target> SOURCES <source.qml> [<source.qml> ...] [VERSION <version>] [PATH <path>] [PRIVATE])

       Adds  the list of QML files specified by	the SOURCES argument as	source
       files to	the QML	module target <target>.

       If the optional VERSION argument	is specified, all QML  files  will  be
       added with the specified	version. If it is not specified, they will use
       the version of the QML module target.

       If  the	optional  PRIVATE argument is specified, the QML files will be
       included	in the target but not in the generated qmldir file.  Any  ver-
       sion argument will be ignored.

       The  optional PATH argument declares a subdirectory of the module where
       the files should	be copied to. By default, files	will be	copied to  the
       module root.

       This  function  will fail if <target> is	not a QML module target	or any
       of the specified	files do not exist.

       Since 5.91.0

       Since 6.0.0, when  used	with  Qt  6,  this  will  forward  to  qt_tar-
       get_qml_sources().    The   SOURCES  argument  will  be	translated  to
       QML_SOURCES. VERSION and	PRIVATE	will  set  Qts	QT_QML_SOURCE_VERSIONS
       and  QT_QML_INTERNAL_TYPE  properties on	SOURCES	before calling qt_tar-
       get_qml_sources(). Since	Qt includes the	path relative to  the  current
       source  dir,  for  each	source file a resource alias will be generated
       with the	path stripped. If the PATH argument is set, it	will  be  pre-
       fixed  to the alias. Any	additional arguments will be passed to qt_tar-
       get_qml_sources().

	  ecm_finalize_qml_module(<target>
	      [DESTINATION <QML	install	destination>] #	Optional since 6.0
	      [VERSION <Project	Version>] # Added for 6.0 when using Qt	6
	      [EXPORT <export-set>] # Added for	6.8 when using Qt 6
	  )

       Finalizes the specified QML module target.

       This is required	in case	you do not use the executable as backing  tar-
       get.

       This  must be called after all other setup (like	adding sources)	on the
       target has been done. It	will perform a number of tasks:

        It will generate a qmldir file	from the QML files added to  the  tar-
	 get.  If  the	module has a C++ plugin, this will also	be included in
	 the qmldir file.

        If BUILD_SHARED_LIBS is off, a	QRC file is  generated	from  the  QML
	 files	added  to the target. This QRC file will be included when com-
	 piling	the C++	QML module. The	built static library will be installed
	 in a subdirectory of DESTINATION based	on the	QML  modules  URI.  If
	 this  value is	not set, KDE_INSTALL_QMLDIR will be used. Note that if
	 NO_PLUGIN is set, a C++ QML plugin will be generated to  include  the
	 QRC files.

        If  BUILD_SHARED_LIBS in on, all generated files, QML sources and the
	 C++ plugin will be installed in a subdirectory	of  DESTINATION	 based
	 on  the QML modules URI. In addition, these files will	also be	copied
	 to the	targets	RUNTIME_OUTPUT_DIRECTORY in a similar subdirectory.

        If BUILD_SHARED_LIBS is off, EXPORT allows to specify a CMake	export
	 set all installed targets should be added to.

       This function will fail if <target> is not a QML	module target.

       Since 5.91.0

       Since  6.0.0, when using	Qt 6, this will	instead	install	the files gen-
       erated by qt_add_qml_module. The	optional VERSION  argument  was	 added
       that  will  default to PROJECT_VERSION and which	will write a file that
       is used by ECMFindQmlModule to detect the version of the	QML module.

       Since 6.1.0

       Enabling	the global option VERBOSE_QML_COMPILER during CMake configura-
       tion will activate verbose output for qmlcachegen.

   ECMQtDeclareLoggingCategory
       This module provides the	ecm_qt_declare_logging_category	 function  for
       generating   declarations  for  logging	categories  in	Qt5,  and  the
       ecm_qt_install_logging_categories  function  for	 generating  and   in-
       stalling	 a file	in KDebugSettings format with the info about all those
       categories, as well as a	file with info about any renamed categories if
       defined.	 To include in that file any logging categories	that are manu-
       ally defined also a  function  ecm_qt_export_logging_category  is  pro-
       vided.

	  ecm_qt_declare_logging_category(<sources_var_name(|target (since 5.80))>
	      HEADER <filename>
	      IDENTIFIER <identifier>
	      CATEGORY_NAME <category_name>
	      [OLD_CATEGORY_NAMES <oldest_cat_name> [<second_oldest_cat_name> [...]]]
	      [DEFAULT_SEVERITY	<Debug|Info|Warning|Critical|Fatal>]
	      [EXPORT <exportid>]
	      [DESCRIPTION <description>]
	  )

       A header	file, <filename>, will be generated along with a corresponding
       source file. These will provide a QLoggingCategory category that	can be
       referred	to from	C++ code using <identifier>, and from the logging con-
       figuration using	<category_name>.

       The  generated  source file will	be added to the	variable with the name
       <sources_var_name>. If the given	argument is a target  though,  instead
       both  the  generated  header file and the generated source file will be
       added to	the target as private sources (since 5.80).  The  target  must
       not be an alias.

       If <filename> is	not absolute, it will be taken relative	to the current
       binary directory.

       <identifier> may	include	namespaces (eg:	foo::bar::IDENT).

       If  EXPORT  is passed, the category will	be registered for the group id
       <exportid>. Info	about the categories of	that group can then be	gener-
       ated  in	 a  file  and  installed  by that group	id with	the ecm_qt_in-
       stall_logging_categories	function. In that case also  DESCRIPTION  will
       need  to	 be passed, with <description> being a short single line text.
       And OLD_CATEGORY_NAMES can be used to inform about any renamings	of the
       category, so user settings can be migrated. Since 5.68.0.

       Since 5.14.0.

	  ecm_qt_export_logging_category(
	      IDENTIFIER <identifier>
	      CATEGORY_NAME <category_name>
	      [OLD_CATEGORY_NAMES <oldest_category_name> [<second_oldest_category_name>	[...]]]
	      EXPORT <exportid>
	      DESCRIPTION <description>
	      [DEFAULT_SEVERITY	<Debug|Info|Warning|Critical|Fatal>]
	  )

       Registers a logging category for	being included in  the	generated  and
       installed  KDebugSettings  files. To be used for	categories who are de-
       clared by manual	code or	other ways  instead  of	 code  generated  with
       ecm_qt_declare_logging_category.

       <identifier> may	include	namespaces (eg:	foo::bar::IDENT).

       EXPORT  specifies  the  group id	with which the category	will be	regis-
       tered.  Info about the categories of that group can then	 be  generated
       in  a  file and installed by that group id with the ecm_qt_install_log-
       ging_categories function.

       DESCRIPTION specifies a short single line text describing the category.

       OLD_CATEGORY_NAMES can be used to inform	about  any  renamings  of  the
       category, so user settings can be migrated.

       Since 5.68.0.

	  ecm_qt_install_logging_categories(
	      EXPORT <exportid>
	      [FILE <filename>]
	      DESTINATION <install_path>
	      [SORT]
	      [COMPONENT <component>]
	  )

       Generates  and  installs	 a file	in KDebugSettings format with the info
       about all the categories	registered for the group <exportid>,  as  well
       as a file with info about any renamed categories, if there are.

       The method call needs to	be after the last ecm_qt_declare_logging_cate-
       gory  call  which uses the same <exportid>. This	can be in the same di-
       rectory,	or any subdirectory or parent directory.

       EXPORT specifies	the group id of	categories whose information should be
       stored in the file generated and	installed.

       FILE specifies the name of the file generated and  installed.  It  will
       default to lower-cased <exportid>.categories. The name of the file with
       info about renamed categories will use the same final base name and the
       suffix  .renamecategories. Note:	Before 5.113, the base name should not
       have any	further	. in the name, as its end would	be defined by that.

       DESTINATION specifies where the generated file will be installed.

       IF SORT is set, entries will be sorted by identifiers.

       COMPONENT specifies the installation component name with	which the  in-
       stall rules for the generated file are associated.

       Since  5.85.0  this is a	no-op when building for	Android, as KDebugSet-
       tings is	not available on that platform and the logging category	 files
       therefore just bloat the	APK.

       Example usage:

	  ecm_qt_declare_logging_category(
	      MYPROJECT_SRCS
	      HEADER "myproject_debug.h"
	      IDENTIFIER "MYPROJECT_DEBUG"
	      CATEGORY_NAME "myproject"
	      OLD_CATEGORY_NAMES "myprojectlog"
	      DESCRIPTION "My project"
	      EXPORT MyProject
	  )

	  ecm_qt_export_logging_category(
	      IDENTIFIER "MYPROJECT_SUBMODULE_DEBUG"
	      CATEGORY_NAME "myproject.submodule"
	      DESCRIPTION "My project -	submodule"
	      EXPORT MyProject
	  )

	  ecm_qt_install_logging_categories(
	      EXPORT MyProject
	      FILE myproject.categories
	      DESTINATION "${KDE_INSTALL_LOGGINGCATEGORIESDIR}"
	  )

       Since 5.68.0.

   ECMQueryQt
       This module can be used to query	the installation paths used by Qt.

       For  Qt5	this uses qmake, and for Qt6 this used qtpaths (the latter has
       built-in	 support  to  query  the  paths	 of  a	target	platform  when
       cross-compiling).

       This module defines the following function:

	  ecm_query_qt(<result_variable> <qt_variable> [TRY])

       Passing	TRY will result	in the method not making the build fail	if the
       executable used for querying has	not been  found,  but  instead	simply
       print a warning message and return an empty string.

       Example usage:

	  include(ECMQueryQt)
	  ecm_query_qt(bin_dir QT_INSTALL_BINS)

       If the call succeeds ${bin_dir} will be set to <prefix>/path/to/bin/dir
       (e.g.  /usr/lib64/qt/bin/).

       Since: 5.93

   ECMSetupQtPluginMacroNames
       Instruct	 CMakes	 automoc  about	C++ preprocessor macros	used to	define
       Qt-style	plugins.

	  ecm_setup_qtplugin_macro_names(
	      [JSON_NONE <macro_name> [<macro_name> [...]]]
	      [JSON_ARG1 <macro_name> [<macro_name> [...]]]
	      [JSON_ARG2 <macro_name> [<macro_name> [...]]]
	      [JSON_ARG3 <macro_name> [<macro_name> [...]]]
	      [CONFIG_CODE_VARIABLE <variable_name>] )

       CMakes automoc needs some support when parsing C++ source files to  de-
       tect whether moc	should be run on those files and if there are also de-
       pendencies  on  other files, like those with Qt plugin metadata in JSON
       format. Because automoc just greps overs	the  raw  plain	 text  of  the
       sources	without	 any C++ preprocessor-like processing.	CMake in newer
       versions	provides the variables CMAKE_AUTOMOC_DEPEND_FILTERS (CMake  >=
       3.9.0)  and  CMAKE_AUTOMOC_MACRO_NAMES (CMake >=	3.10) to allow the de-
       veloper to assist automoc.

       This macro cares	for the	explicit setup needed for those	variables  for
       common cases of C++ preprocessor	macros used for	Qt-style plugins.

       JSON_NONE lists the names of C++	preprocessor macros for	Qt-style plug-
       ins which do not	refer to external files	with the plugin	metadata.

       JSON_ARG1 lists the names of C++	preprocessor macros for	Qt-style plug-
       ins  where  the first argument to the macro is the name of the external
       file with the plugin metadata.

       JSON_ARG2 is the	same as	JSON_ARG1 but with the	file  name  being  the
       second argument.

       JSON_ARG3  is  the  same	 as JSON_ARG1 but with the file	name being the
       third argument.

       CONFIG_CODE_VARIABLE specifies the name of the variable which will  get
       set  as value some generated CMake code for instructing automoc for the
       given macro names, as useful in an installed  CMake  config  file.  The
       variable	 can  then  be	used  as usual in the template file for	such a
       CMake config file, by @<variable_name>@.

       Example usage:

       Given some plugin-oriented Qt-based software which defines a custom C++
       preprocessor macro EXPORT_MYPLUGIN for declaring	the central plugin ob-
       ject:

	  #define EXPORT_MYPLUGIN_WITH_JSON(classname, jsonFile) \
	  class	classname : public QObject \
	  { \
	      Q_OBJECT \
	      Q_PLUGIN_METADATA(IID "myplugin" FILE jsonFile) \
	      explicit classname() {} \
	  };

       In the CMake buildsystem	of the library one calls

	  ecm_setup_qtplugin_macro_names(
	      JSON_ARG2
		 EXPORT_MYPLUGIN_WITH_JSON
	  )

       to instruct automoc about the usage of that macro in the	sources	of the
       library itself.

       Given the software installs a library including	the  header  with  the
       macro definition	and a CMake config file, so 3rd-party can create addi-
       tional  plugins by linking against the library, one passes additionally
       the name	of a variable which shall be  set  as  value  the  CMake  code
       needed to instruct automoc about	the usage of that macro.

	  ecm_setup_qtplugin_macro_names(
	      JSON_ARG2
		 EXPORT_MYPLUGIN_WITH_JSON
	      CONFIG_CODE_VARIABLE
		 PACKAGE_SETUP_AUTOMOC_VARIABLES
	  )

       This  variable  then  is	used in	the template file (e.g.	 MyProjectCon-
       fig.cmake.in) for the libarys installed CMake config file and that  way
       will  ensure  that  in the 3rd-party plugins buildsystem	automoc	is in-
       structed	as well	as needed:

	  @PACKAGE_SETUP_AUTOMOC_VARIABLES@

       Since 5.45.0.

   ECMSetupVersion
       Handle library version information.

	  ecm_setup_version(<version>
			    VARIABLE_PREFIX <prefix>
			    [SOVERSION <soversion>]
			    [VERSION_HEADER <filename>]
			    [PACKAGE_VERSION_FILE <filename> [COMPATIBILITY <compat>]] )

       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:

	  <prefix>_VERSION_MAJOR  - <major>
	  <prefix>_VERSION_MINOR  - <minor>
	  <prefix>_VERSION_PATCH  - <patch>
	  <prefix>_VERSION	  - <version>
	  <prefix>_SOVERSION	  - <soversion>, or <major> if SOVERSION was not given

       For backward-compatibility also this variable is	set (only if the mini-
       mum required version of ECM is <	5.83):

	  <prefix>_VERSION_STRING - <version> (use <prefix>_VERSION instead)

       If  CMake policy	CMP0048	is not NEW, the	following CMake	variables will
       also be set:

	  PROJECT_VERSION_MAJOR	  - <major>
	  PROJECT_VERSION_MINOR	  - <minor>
	  PROJECT_VERSION_PATCH	  - <patch>
	  PROJECT_VERSION	  - <version>

       For backward-compatibility, if CMake policy CMP0048 is  not  NEW,  also
       this  variable is set (only if the minimum required version of ECM is <
       5.83):

	  PROJECT_VERSION_STRING  - <version> (use PROJECT_VERSION instead)

       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	inter-
       preted as relative to CMAKE_CURRENT_BINARY_DIR.	The  generated	header
       contains	the following macros:

	  <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  <mi-
       nor> must be less than 256.

       If the PACKAGE_VERSION_FILE option is used, a simple CMake package ver-
       sion 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_pack-
       age().	If the filename	is a relative path, it is interpreted as rela-
       tive to CMAKE_CURRENT_BINARY_DIR. The optional COMPATIBILITY option  is
       forwarded   to	write_basic_package_version_file(),  and  defaults  to
       AnyNewerVersion.

       If CMake	policy CMP0048 is NEW, an alternative form of the  command  is
       available:

	  ecm_setup_version(PROJECT
			    [VARIABLE_PREFIX <prefix>]
			    [SOVERSION <soversion>]
			    [VERSION_HEADER <filename>]
			    [PACKAGE_VERSION_FILE <filename>] )

       This  will  use	the  version information set by	the project() command.
       VARIABLE_PREFIX defaults	to the project name.  Note that	 PROJECT  must
       be  the	first  argument.   In  all other respects, it behaves like the
       other form of the command.

       Since pre-1.0.0.

       COMPATIBILITY option available since 1.6.0.

   ECMSourceVersionControl
       Tries to	determine whether the source is	 under	version	 control  (git
       clone, svn checkout, etc).

       ECM_SOURCE_UNDER_VERSION_CONTROL	 is  set when indication is found that
       CMAKE_SOURCE_DIR	is under version control.

       Since 5.63

   ECMUninstallTarget
       Add an uninstall	target.

       By including this module, an uninstall target will  be  added  to  your
       CMake  project.	This will remove all files installed (or updated) by a
       previous	invocation of the install target. It  will  not	 remove	 files
       created or modified by an install(SCRIPT) or install(CODE) command; you
       should  create a	custom uninstallation target for these and use add_de-
       pendency	to make	the uninstall target depend on it:

	  include(ECMUninstallTarget)
	  install(SCRIPT install-foo.cmake)
	  add_custom_target(uninstall_foo COMMAND ${CMAKE_COMMAND} -P uninstall-foo.cmake)
	  add_dependency(uninstall uninstall_foo)

       The target will fail if the install target has not yet been run (so  it
       is  not	possible  to run CMake on the project and then immediately run
       the uninstall target).

       WARNING:
	  CMake	deliberately does not provide an uninstall target  by  default
	  on  the  basis that such a target has	the potential to remove	impor-
	  tant files from a users computer. Use	with caution.

       Since 1.7.0.

   ECMUseFindModules
       Selectively use some of the find	modules	provided  by  extra-cmake-mod-
       ules.

       This  module  is	 automatically	available once extra-cmake-modules has
       been found, so it is not	necessary  to  include(ECMUseFindModules)  ex-
       plicitly.

	  ecm_use_find_modules(DIR <dir>
			       MODULES module1.cmake [module2.cmake [...]]
			       [NO_OVERRIDE])

       This  allows selective use of the find modules provided by ECM, includ-
       ing deferring to	CMakes 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 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 ex-
       ists).

       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).

       Since pre-1.0.0.

   ECMWinResolveSymlinks
       Resolve pseudo-symlinks created by git when cloning on Windows.

	  ecm_win_resolve_symlinks(<dir>)

       When git	checks out a repository	with UNIX symlinks on Windows machine,
       it  creates a text file for each	symlink, containing a relative path to
       the real	file.  This function would recursively walk over specified di-
       rectory and replace pseudo-symlinks with	corresponding real files  con-
       tents. It would then run	git update-index --assume-unchanged on them to
       trick git.

       This is useful for projects like	breeze-icons that contain many identi-
       cal icons implemented as	symlinks.

       Since 5.28

   QtVersionOption
       Adds  a	build option to	select the major Qt version if necessary, that
       is, if the major	Qt version has not yet been determined otherwise (e.g.
       by a corresponding find_package() call).	 This module is	typically  in-
       cluded by other modules requiring knowledge about the major Qt version.

       If  the	ECM version passed to find_package was at least	5.240.0	Qt6 is
       picked by default.  Otherwise Qt5 is picked.

       QT_MAJOR_VERSION	is defined to either be	5 or 6.

       Since 5.82.0.

SEE ALSO
       ecm(7), ecm-find-modules(7), ecm-kde-modules(7)

COPYRIGHT
       KDE Developers

6.14				 May 27, 2025			ECM-MODULES(7)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ecm-modules&sektion=7&manpath=FreeBSD+Ports+14.3.quarterly>

home | help