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-mod-
       ules(7);	 those that provide standard settings for software produced by
       the KDE community are documented	in ecm-kde-modules(7).	The rest  pro-
       vide macros and functions for general use by CMake scripts and are doc-
       umented 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
   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 Mac 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 Mac OS	X, on all oth-
       ers 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	Mac OS X sidebar icons to  the	gener-
       ated  iconset. They are used when a folder monitored by the application
       is dragged into Finderas	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 Mac
       OS X and	<OUTFILE_BASENAME>.ico on Windows. If you donat	specify	it, it
       defaults	to <sources_var_name>.<ext>. Since 5.49.

       Windows notes

	      o	Icons are compiled into	the executable using a resource	file.

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

	      o	Icotool	(see FindIcoTool) is required.

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

       Mac OS X	notes

	      o	The executable target must  have  the  MACOSX_BUNDLE  property
		set.

	      o	Icons are added	to the bundle.

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

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

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

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

	      o	Larger sizes are automatically used to substitute for  smaller
		sizes  on  aRetinaa (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 a@2xa 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. ksvg2icns	handles	this internally.

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

	      o	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
       a<target_name>a.

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

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

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

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

       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 a<widgetid>a.

       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 a/a.

       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  a{lowercased	<class_name>}.pnga in the default icons	dir as
       configured 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
       a<class_name> Widgeta.

       WHATSTHIS specifies the Whatas-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 areturn  new  <impl_class_name><construc-
       tor_args_code>;a.

       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	a<class_name>a.

       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 a(parent)a.

       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 a;a
       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> LINK_LIBRARIES <library> [<library> [...]]
				  [NAME_PREFIX <prefix>]
				  [GUI]
				  [TARGET_NAMES_VAR <target_names_var>]
				  [TEST_NAMES_VAR <test_names_var>])

       A convenience function for adding multiple tests, each consisting of  a
       single  source  file.  For each file in <sources>, an executable	target
       will be created (the name of which will be the basename of  the	source
       file).  This  will  be linked against the libraries given with LINK_LI-
       BRARIES.	Each executable	will be	added as a test	with the same name.

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

	  ecm_add_test(<sources> LINK_LIBRARIES	<library> [<library> [...]]
				 [TEST_NAME <name>]
				 [NAME_PREFIX <prefix>]
				 [GUI])

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

       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:

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

	      o	Python3	must be	available.

	      o	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 command of the	FILE function.

       LICENSES
	      List  of	one  or	 multiple outbound license regarding which the
	      compatibility.INDENT 7.0
	  of the source	code files shall be tested. Currently,	the  following
	  values

	      are supported (values are	SPDX registry identifiers):

		     o MIT

		     o BSD-2-Clause

		     o BSD-3-Clause

		     o LGPL-2.0-only

		     o LGPL-2.1-only

		     o LGPL-3.0-only

		     o GPL-2.0-only

		     o 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  gen-
	      erates 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  di-
	      rectory  with  appended license name is used. Every test has li-
	      censecheck_ as prefix.

       WILL_FAIL
	      Optional parameter that inverts the test result. This  parameter
	      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 a.ina 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 GCCas coverage instrumentation,
       and links against libgcov.

       Note that 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	ECMPo-
	  QmTools 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	aLanguagea 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 amyliba probject
       might keep all its translations in a apoa 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 amyliba, 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 atranslationa target. This tar-
       get 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 amylib.qma	at  startup,  assuming
       it has been installed by	ecm_create_qm_from_po_files(), and compiles it
       into mylib.

       Since pre-1.0.0.

   ECMEnableSanitizers
       Enable compiler sanitizer flags.

       The following sanitizers	are supported:

       o Address Sanitizer

       o Memory	Sanitizer

       o Thread	Sanitizer

       o Leak Sanitizer

       o 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 KDECompil-
       erSettings, 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:

       o address

       o memory

       o thread

       o leak

       o undefined

       o fuzzer

       The sanitizers aaddressa, amemorya and athreada are mutually exclusive.
       You cannot enable two of	them in	the same build.

       aleaka requires the  aaddressa 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 projectas	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 a#includea). <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 aothera 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  that  these  variables  are  never	 cleared, so if	ecm_find_pack-
       age_handle_library_components() is called multiple times	with different
       components  (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.

   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]
	      [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
	  )

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

       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  a0a,  aCURRENTa
       (which  resolves	to <version>) and a version string in the format a<ma-
       jor>.<minor>.<patchlevel>a. The default is the value of	a<exclude_dep-
       recated_before_and_at_version>a	if set,	or a<major>.0.0a, with <major>
       taken from <version>.

       DEPRECATION_VERSIONS specifies versions in a<major>.<minor>a 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 a0a (default), aCURRENTa (which resolves
       to  <version>)  and  a  version	string	in  the	 format	 a<major>.<mi-
       nor>.<patchlevel>a.

       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.

       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	a0a.  If both are set, this flag over-
	      rules.

       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.

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

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

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

       In such cases the API can be only ahiddena 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 aFooa created by target afooa, which	is part	 of  a
       group  of  libraries  aBara,  where some	API of aFooa 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 aFooa 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 aFooa library can control  which  part  of
       its deprecated API should be hidden to the compiler by adding a defini-
       tion 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 a5.0.0a, 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	aFooa 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 aBara and disabling some deprecated	API  of	 those
       libraries  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 aha. 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 "<dep> [<dep> [...]]"]
				[FILENAME_VAR <filename_variable>]
				[INCLUDE_INSTALL_DIR <dir>]
				[LIB_INSTALL_DIR <dir>]
				[DEFINES -D<variable=value>...]
				[DESCRIPTION <library description>] # since 5.41.0
				[INSTALL])

       BASE_NAME is the	name of	the module. Itas 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.

       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
       itas not	specified, it will default  to	INSTALL_INCLUDEDIR,  CMAKE_IN-
       STALL_INCLUDEDIR	 or  just  ainclude/a in case they are specified, with
       the BASE_NAME postfixed.

       LIB_INSTALL_DIR specifies where the library is being installed. If itas
       not specified, it will default to LIB_INSTALL_DIR, CMAKE_INSTALL_LIBDIR
       or just alib/a 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 itas	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.

       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	that the first call to
       ecm_generate_pkgconfig_file  with  the  INSTALL	argument  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_DIR <dir>]
				[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 acorea for QtCore).	FILENAME_VAR specifies
       the name	of a variable to store the path	to the generated file in.

       INCLUDE_INSTALL_DIR is the path (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.

       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.

   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 doesnat 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	ahicolora 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

       o hi for	hicolor

       o lo for	locolor

       o cr for	the Crystal icon theme

       o ox for	the Oxygen icon	theme

       o 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 ameta-projectsa 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 afooa:

	  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	moduleas 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 atranslationsa target. This	target
       builds all .po files into .qm files.  If	ALL is specified, these	 rules
       are  added  to  the aalla target	(and so	the .qm	files will be built by
       default).

	  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.

   ECMQMLModules
       Find  QML  import modules through a find_qmlmodule() call.  It uses the
       qmlplugindump application to find the plugins and sets them up as  run-
       time dependencies.

       This  is	useful so that when we configure a project we are noified when
       some QML	imports	are not	present	in the system, thus having the	appli-
       cation compilable but fail at runtime.

	  ecm_find_qmlmodule(<module_name> <version>...)

       Any  further  arguments	passed will be forwarded into a	find_package()
       call. See find_package()	documentation for more information.

       Usage example:

	  ecm_find_qmlmodule(org.kde.kirigami 2.1)

       Since 5.38.0.

   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.

       If  the	code  is  compiled against Qt 5.4 or later, by default it will
       only log	output	that  is  at  least  the  severity  specified  by  DE-
       FAULT_SEVERITY,	or aInfoa level	if DEFAULT_SEVERITY is not given. Note
       that, due to a bug in Qt	5.5, aInfoa may	be treated as more severe than
       aFatala.

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

       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.

   ECMSetupQtPluginMacroNames
       Instruct	 CMakeas  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>] )

       CMakeas 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 libaryas installed	CMake config file and that way
       will ensure that	in the 3rd-party pluginas 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 useras 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	CMakeas	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 fileas con-
       tents. It would then run	git update-index aassume-unchanged on them  to
       trick git.

       This is useful for projects like	abreeze-iconsa that contain many iden-
       tical icons implemented as symlinks.

       Since 5.28

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

COPYRIGHT
       KDE Developers

5.86				 Nov 04, 2021			ECM-MODULES(7)

NAME | INTRODUCTION | ALL MODULES | SEE ALSO | COPYRIGHT

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

home | help