Provided by: extra-cmake-modules_5.92.0-0ubuntu1_amd64 bug

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 modules that can be used from CMake scripts:
       those  that  extend  the  functionality  of  the  find_package  command  are documented in
       ecm-find-modules(7); those that provide standard settings for software produced by the KDE
       community are documented in ecm-kde-modules(7).  The rest provide macros and functions for
       general use by CMake scripts and are documented here.

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

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

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

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

ALL MODULES

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

       Since 5.75.0.

   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 others the call has  no
       effect and is ignored.

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

       SIDEBAR_ICONS can be used to add Mac OS X sidebar icons to the generated iconset. They are
       used  when  a  folder monitored by the application is dragged into Finder’s 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 don’t specify it, it defaults to <sources_var_name>.<ext>. Since 5.49.

       Windows notes

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

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

              • Icotool (see FindIcoTool) is required.

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

       Mac OS X notes

              • The executable target must have the MACOSX_BUNDLE property set.

              • Icons are added to the bundle.

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

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

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

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

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

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

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

       Since 1.7.0.

   ECMAddQch
       This module provides the ecm_add_qch function for generating API  documentation  files  in
       the  QCH  format,  and  the  ecm_install_qch_export function for generating and installing
       exported CMake targets for such generated 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 corresponding doxygen  tag  file,  which  enables  creating  links  from  other
       documentation 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_NAMESPACE,
       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 existing, 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 documentation 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  relative  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_TEMPLATE 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 included 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  included  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 install rules  for  the
       generated QCH file and tag file are associated.

       NAMESPACE can be used to set a custom namespace <namespace> of the generated QCH file. The
       namepspace    is    used     as     the     unique     id     by     QHelpEngine     (cmp.
       https://doc.qt.io/qt-5/qthelpproject.html#namespace).     The    default    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 libraries.  For each target  <qch>  in
       the   list   these   target  properties  are  expected  to  be  defined:  DOXYGEN_TAGFILE,
       QHP_NAMESPACE and QHP_VIRTUALFOLDER.  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 handled 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 ignored 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_DOXYGEN_QHELPGENERATOR_EXECUTABLE  -  ECM_QCH_DOXYGEN_FILEPATH,
       ECM_QCH_DOXYGEN_TAGFILE    The    following    CMake    variables    can    be   used:   -
       ECM_QCH_DOXYGEN_PROJECTNAME          -          ECM_QCH_DOXYGEN_PROJECTVERSION           -
       ECM_QCH_DOXYGEN_VIRTUALFOLDER - ECM_QCH_DOXYGEN_FULLNAMESPACE - ECM_QCH_DOXYGEN_TAGFILES -
       ECM_QCH_DOXYGEN_WARN_LOGFILE - ECM_QCH_DOXYGEN_QUIET There is no guarantue that the  other
       CMake  variables  currently  used in the default config file template will also be present
       with the same semantics in future 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_DOXYGEN   when    run    (since    v5.67.0).    For
       backward-compatibility  also the definition 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  install  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 generating 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  default  is
       <target_name>.

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

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

       INSTALL_DESTINATION specifies where the generated plugin binary will be installed.

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

       DEFAULT_GROUP specifies the default group in Qt Designer where the widgets will be placed.
       The default is “Custom”.

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

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

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

       INCLUDE_FILES  specifies  additional  include  files  to include with the generated source
       file. This can be needed for custom code used in initializing 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 creating widgets.

       COMPONENT  specifies  the installation component name with which the install 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 namespaces.  The  default  is
       “<widgetid>”.

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

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

       ICON  specifies  the  icon  file  to  use  as  symbol  for  this  widget.   The default is
       “{lowercased  <class_name>}.png”  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 “<class_name>
       Widget”.

       WHATSTHIS specifies the What’s-This text to use for this widget.  Defaults 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(QWidget* parent).  The default is “return new
       <impl_class_name><constructor_args_code>;”.

       INITIALIZE_CODE_FROM_VARIABLE specifies the variable to get from the C++ code to use  with
       the  override  of QDesignerCustomWidgetInterface::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 QDesignerCustomWidgetInterface::domXml().  Default does not override.

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

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

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

       Example usage:

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

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

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

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

       Since 5.62.0.

   ECMAddTests
       Convenience functions for adding tests.

          ecm_add_tests(<sources> 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_LIBRARIES. 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   (regardless   of   the   value   of
       CMAKE_WIN32_EXECUTABLE  or CMAKE_MACOSX_BUNDLE). Be aware that this changes the executable
       entry point on Windows (although some frameworks, such as  Qt,  abstract  this  difference
       away).

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

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

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

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

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

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

       Preconditions for using this module:

              • All tested input source files must contain the SPDX-License-Identifier tag.

              • Python3 must be available.

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

       When this module is included, a SKIP_LICENSE_TESTS option is added (default 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  of  the
              source code files shall be tested..INDENT 7.0

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

              • MIT

              • BSD-2-Clause

              • BSD-3-Clause

              • LGPL-2.0-only

              • LGPL-2.1-only

              • LGPL-3.0-only

              • GPL-2.0-only

              • GPL-3.0-only

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

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

       WILL_FAIL
              Optional  parameter  that  inverts  the test result. This parameter is usually only
              used for tests of the module.
   ECMConfiguredInstall
       Takes a list of files, runs configure_file on each and installs the  resultant  configured
       files in the given location.

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

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

       Example usage:

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

       This will install the file as foo.txt with any cmake variable replacements 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 GCC’s 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 ECMPoQmTools instead.

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

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

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

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

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

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

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

          po/
              es.po
              fr.po

       Without setting CATALOG_NAME, those .po will be turned into .qm and installed as:

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

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

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

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

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

          ecm_create_qm_loader(<source_files_var> <catalog_name>)

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

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

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

       Since pre-1.0.0.

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

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

       This module provides the following function:

          ecm_set_disabled_deprecation_versions(
              [SHOW_DEPRECATIONS]
              [<identifier> <deprecation_version>]
              [<identifier2> <deprecation_version2>]
          )

       SHOW_DEPRECATIONS  if  this  option  is  used,  deprecation warnings for the current major
       version are emitted.

       Example usage:

          set(QT_MIN_VERSION "5.15.0")
          set(KF5_MIN_VERSION "5.90")

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

       Since 5.91

   ECMEnableSanitizers
       Enable compiler sanitizer flags.

       The following sanitizers are supported:

       • Address Sanitizer

       • Memory Sanitizer

       • Thread Sanitizer

       • Leak Sanitizer

       • Undefined Behaviour Sanitizer

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

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

   Usage
       Simply add:

          include(ECMEnableSanitizers)

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

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

       • address

       • memory

       • thread

       • leak

       • undefined

       • fuzzer

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

       “leak” requires the  “address” sanitizer.

       NOTE:
          To reduce the overhead induced by the instrumentation of the sanitizers, 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_library_components().

          ecm_find_package_version_check(<name>)

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

          ecm_find_package_parse_components(<name>
              RESULT_VAR <variable>
              KNOWN_COMPONENTS <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   components.    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  library,  and
       <name>_<component>_header variable should contain the name of  a  header  file  associated
       with    it    (whatever    relative    path    is    normally   passed   to   ‘#include’).
       <name>_<component>_header_subdir variable can be used to specify which subdirectory of the
       include path the headers will be found in.  ecm_find_package_components() will then search
       for the library and include directory (creating appropriate cache variables) and create an
       imported library target named <name>::<component>.

       Additional variables can be used to provide additional information:

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

       Note that if version information is found via pkg-config,  <name>_<component>_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>_<component>_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>_component_deps to be listed before
       <component> in the COMPONENTS argument.

       The following variables will be set:

       <name>_TARGETS
              the imported targets

       <name>_LIBRARIES
              the found libraries

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

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

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

       Note      that      these      variables      are      never      cleared,      so      if
       ecm_find_package_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.

   ECMFindQmlModule
       Find  QML  import  modules  through  a  find_qmlmodule()  call.  It uses the qmlplugindump
       application to find the plugins and sets them up as runtime 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 application 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.

   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 installed in the
       relevant D-Bus config location. This filename can be customized with RENAME.

       <executable> must be an absolute path to the installed service executable. 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 <executable> 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  corresponding  systemd
       service instead of the <executable> if the D-Bus daemon 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 generating export macros
       for libraries with version-based control over visibility  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
       “<major>.<minor>.<patchlevel>”.

       GROUP_BASE_NAME specifies the name to use for the macros defining  library  group  default
       values.       If       set,       this       will       generate      code      supporting
       <group_base_name>_NO_DEPRECATED_WARNINGS,
       <group_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT,
       <group_base_name>_DEPRECATED_WARNINGS_SINCE   and   <group_base_name>_NO_DEPRECATED   (see
       below).  If not set, the generated code will ignore any such macros.

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

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

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

       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_BEFORE_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><uppercase_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_BEFORE_AND_AT, so e.g. test and examples part of
       the project automatically 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 library 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><uppercase_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><uppercase_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 &
              minor 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><uppercase_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_BELATED(major,     minor,
       textmajor, textminor, text)
              to  use  to conditionally set a <prefix_name><uppercase_base_name>_DEPRECATED macro
              for an enumerator, depending on the warnings macro  flags  set  (see  below),  with
              major  &  minor  applied  for  the logic and textmajor & textminor for the warnings
              message.  In builds using C++14 standard or earlier,  where  enumerator  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, minor)
              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 visibility requested.

       <prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)
              evaluates    to    TRUE    or    FALSE    depending     on     the     value     of
              EXCLUDE_DEPRECATED_BEFORE_AND_AT.  To  be  used  mainly  with  #if/#endif  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   notation
              (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_DEPRECATED_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  notation
              (0x<major><minor><patchlevel>). Warnings will be only activated for API  deprecated
              up         to         and         including         the         version.         If
              <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_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>_DEPRECATED_WARNINGS_SINCE to “0”.  If  both  are
              set, this flag overrules.

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

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

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

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

       In  such  cases  the  API  can  be  only “hidden” at build time of the library, itself, by
       generated          hard          coded           macro           settings,           using
       <prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor).

       Examples:

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

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

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

          #include <foo_export.h>

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

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

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

          add_definitions(-DFOO_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)

       Or using the macro variable of the group:

          add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)

       If both are specified, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT will take precedence.

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

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

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

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

          #include <foo_export.h>

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

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

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

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

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

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

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

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

       When using the NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE  and  the  project  for  the  “Foo”
       library  includes also tests and examples linking against the library and using deprecated
       API     (like     tests     covering     it),     one     better      explicitly      sets
       FOO_DISABLE_DEPRECATED_BEFORE_AND_AT  for those targets to the version before and at which
       all deprecated API has been excluded from the build.   Even  more  when  building  against
       other  libraries  from  the  same  group  “Bar” 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_export_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
       redirects 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:  lowercased  or  also
       camelcased.  The default is LOWERCASE. Since 1.8.0.

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

       PREFIX places the generated headers in subdirectories.  This should be  a  CamelCase  name
       like  KParts, which will cause the CamelCase forwarding headers to be placed in the KParts
       directory (e.g. KParts/Part).  It will also, for the convenience of  code  in  the  source
       distribution,   generate   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 required headers will be
       appended so that they can be installed together with the generated ones.  This  is  mostly
       intended  as  a  convenience  so  that  adding  a  new  header  to a project only requires
       specifying the CamelCase variant in the CMakeLists.txt file;  the  original  variant  will
       then be added to this variable.

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

       The RELATIVE argument indicates where the  original  headers  can  be  found  relative  to
       CMAKE_CURRENT_SOURCE_DIR.   It  does  not affect the generated CamelCase forwarding files,
       but ecm_generate_headers() uses it when checking that the original header exists,  and  to
       generate originally named forwarding headers when PREFIX is set.

       To  allow  other parts of the source distribution (eg: tests) to use the generated headers
       before installation, it may be desirable to set the INCLUDE_DIRECTORIES property  for  the
       library target to output_dir.  For example, if OUTPUT_DIR is CMAKE_CURRENT_BINARY_DIR (the
       default), you could do

          target_include_directories(MyLib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>")

       Example usage (without PREFIX):

          ecm_generate_headers(
              MyLib_FORWARDING_HEADERS
              HEADERS
                  MLFoo
                  MLBar
                  # etc
              REQUIRED_HEADERS MyLib_HEADERS
              COMMON_HEADER MLGeneral
          )
          install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS}
                  DESTINATION ${CMAKE_INSTALL_PREFIX}/include
                  COMPONENT Devel)

       Example usage (with PREFIX):

          ecm_generate_headers(
              MyLib_FORWARDING_HEADERS
              HEADERS
                  Foo
                  # several classes are contained in bar.h, so generate
                  # additional files
                  Bar,BarList
                  # etc
              PREFIX MyLib
              REQUIRED_HEADERS MyLib_HEADERS
          )
          install(FILES ${MyLib_FORWARDING_HEADERS}
                  DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib
                  COMPONENT Devel)
          install(FILES ${MyLib_HEADERS}
                  DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib
                  COMPONENT Devel)

       Since pre-1.0.0.

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

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

       BASE_NAME is the name of the module. It’s the name projects will use to find the module.

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

       DEPS is the list of libraries required by this library. Libraries that are not exposed  to
       applications should be marked with PRIVATE. The default is PUBLIC, but note that according
       to the  Guide  to  pkg-config  <https://people.freedesktop.org/~dbn/pkg-config-guide.html>
       marking  dependencies as private is usually preferred. The PUBLIC and PRIVATE keywords are
       supported since 5.89.0.

       FILENAME_VAR is specified with a variable name. This variable will receive 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 it’s not specified,
       it will default to INSTALL_INCLUDEDIR, CMAKE_INSTALL_INCLUDEDIR or just “include/” in case
       they are specified, with the BASE_NAME postfixed.

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

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

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

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

       INSTALL  will  cause  the  module  to  be  installed  to  the  pkgconfig  subdirectory  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 either the default qmake
       mkspecs  directory  or  of a directory that will be in the $QMAKEPATH environment variable
       when qmake is run.

          ecm_generate_pri_file(BASE_NAME <baseName>
                                LIB_NAME <libName>
                                [VERSION <version>] # since 5.83
                                [DEPS "<dep> [<dep> [...]]"]
                                [FILENAME_VAR <filename_variable>]
                                [INCLUDE_INSTALL_DIRS <dir> [<dir> [...]]]  # since 5.92
                                [INCLUDE_INSTALL_DIR <dir>] # deprecated since 5.92
                                [LIB_INSTALL_DIR <dir>])

       If your CMake project produces a Qt-based library, you may expect there to be applications
       that  wish  to  use it that use a qmake-based build system, rather than a CMake-based one.
       Creating a .pri file will make use of your library convenient for them, in much  the  same
       way  that  CMake  config  files  make  things  convenient  for  CMake-based  applications.
       ecm_generate_pri_file() generates just such a file.

       VERSION specifies the version of the library the .pri file  describes.  If  not  set,  the
       value is taken from the context variable PROJECT_VERSION.  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_VERSION_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 actual library to link to (ie: the first
       argument to add_library()).  DEPS is a space-separated list of the  base  names  of  other
       libraries  (for  Qt  libraries, use the same names you use with the QT variable in a qmake
       project file, such as “core” for QtCore).  FILENAME_VAR specifies the name of  a  variable
       to store the path to the generated file in.

       INCLUDE_INSTALL_DIRS  are  the paths (relative to CMAKE_INSTALL_PREFIX) that include files
       will  be  installed  to.  It  defaults   to   ${INCLUDE_INSTALL_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  operates  similarly  for  the  installation  location  for  libraries; it
       defaults to ${LIB_INSTALL_DIR}, ${CMAKE_INSTALL_LIBDIR} or lib, in that order.

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

       Example usage:

          ecm_generate_pri_file(
              BASE_NAME KArchive
              LIB_NAME KF5KArchive
              DEPS "core"
              FILENAME_VAR pri_filename
              VERSION 4.2.0
          )
          install(FILES ${pri_filename} DESTINATION ${ECM_MKSPECS_INSTALL_DIR})

       A qmake-based project that wished to use this would then do:

          QT += KArchive

       in their .pro file.

       Since pre-1.0.0.

   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 plugins 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 doesn’t 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  according to the
       FreeDesktop.org icon naming scheme. By default, they are installed to the “hicolor” theme,
       but  this  can  be changed using the THEME argument.  If the icons are localized, the LANG
       argument can be used to install them in a locale-specific directory.

       <size> is a numeric pixel size (typically 16, 22, 32, 48,  64,  128  or  256)  or  sc  for
       scalable (SVG) files, <group> is one of the standard FreeDesktop.org icon groups (actions,
       animations, apps, categories, devices, 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_INSTALL_ICONDIR}  as  the
       DESTINATION,     while     users    of    the    GNUInstallDirs    module    should    use
       ${CMAKE_INSTALL_DATAROOTDIR}/icons.

       An old form of arguments will also be accepted:

          ecm_install_icons(<icon_install_dir> [<l10n_code>])

       This matches files named like:

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

       where <theme> is one of

       • hi for hicolor

       • lo for locolor

       • cr for the Crystal icon theme

       • ox for the Oxygen icon theme

       • br for the Breeze icon theme

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

       Since pre-1.0.0.

   ECMMarkAsTest
       Marks a target as only being required for tests.

          ecm_mark_as_test(<target1> [<target2> [...]])

       This  will  cause the specified targets to not be built unless either BUILD_TESTING is set
       to ON or the user invokes the buildtests target.

       BUILD_TESTING  is  created  as  a  cache  variable  by  the  CTest  module  and   by   the
       KDECMakeSettings module.

       Since pre-1.0.0.

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

          ecm_mark_nongui_executable(<target1> [<target2> [...]])

       This  will  indicate  to  CMake  that  the  specified  targets should not be included in a
       MACOSX_BUNDLE and should not be WIN32_EXECUTABLEs.  On platforms other  than  MacOS  X  or
       Windows, this will have no effect.

       Since pre-1.0.0.

   ECMOptionalAddSubdirectory
       Make subdirectories optional.

          ecm_optional_add_subdirectory(<dir>)

       This  behaves  like  add_subdirectory(), except that it does not complain if the directory
       does not exist.  Additionally, if the directory does exist, it creates an option to  allow
       the user to skip it. The option will be named BUILD_<dir>.

       This is useful for “meta-projects” that combine several mostly-independent sub-projects.

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

          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  module’s  documentation for more
       information.

          ecm_configure_package_config_file(<input> <output>
              INSTALL_DESTINATION <path>
              [PATH_VARS <var1> [<var2> [...]]
              [NO_SET_AND_CHECK_MACRO]
              [NO_CHECK_REQUIRED_COMPONENTS_MACRO])

       This behaves in the same way as configure_package_config_file() from CMake 2.8.12,  except
       that  it  adds an extra helper macro: find_dependency(). It is highly recommended that you
       read the documentation for CMakePackageConfigHelpers for  more  information,  particularly
       with regard 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_package_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 config 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_install_po_files_as_qm
       functions  for  generating QTranslator (.qm) catalogs 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
       <install_destination>/<lang>/LC_MESSAGES.  Typically,  <install_destination>  is  set   to
       share/locale.

       ecm_process_po_files_as_qm  creates  a  “translations”  target. This target builds all .po
       files into .qm files.  If ALL is specified, these rules are added to the “all” target (and
       so the .qm files will be built by 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  installs  it  in
       <install_destination>/fr/LC_MESSAGES.        <install_destination>       defaults       to
       ${LOCALE_INSTALL_DIR}  if defined, otherwise it uses ${CMAKE_INSTALL_LOCALEDIR} if that is
       defined, otherwise it uses share/locale.

       Since pre-1.0.0.

   ECMQmlModule
       This file contains helper functions to make it easier to create QML modules. It takes care
       of  a  number  of  things  that  often  need to be repeated. It also takes care of special
       handling of QML modules between shared and static builds. When building a  static  version
       of  a  QML module, the relevant QML source files are bundled into the static library. When
       using a shared build, the QML plugin and relevant QML files are  copied  to  the  target’s
       RUNTIME_OUTPUT_DIRECTORY  to  make  it  easier  to  run  things  directly  from  the build
       directory.

       Example usage:

          ecm_add_qml_module(ExampleModule URI "org.example.Example" VERSION 1.4)

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

          ecm_target_qml_sources(ExampleModule SOURCES ExampleItem.qml)
          ecm_target_qml_sources(ExampleModule SOURCES AnotherExampleItem.qml VERSION 1.5)

          ecm_finalize_qml_module(ExampleModule DESTINATION ${KDE_INSTALL_QMLDIR})

          ecm_add_qml_module(<target name> URI <module uri> [VERSION <module version>] [NO_PLUGIN] [CLASSNAME <class name>])

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

       If the VERSION argument is specified, it is used to initialize the default version that is
       used  by  ecm_target_qml_sources when adding QML files. If it is not specified, a  default
       of 1.0 is used. Additionally, if a version greater than or equal to 2.0 is specified,  the
       major version is appended to the installation path of the module.

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

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

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

       Since 5.91.0

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

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

       Since 5.91.0

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

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

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

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

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

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

       Since 5.91.0

          ecm_finalize_qml_module(<target> DESTINATION <QML install destination>)

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

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

       • If  BUILD_SHARED_LIBS  is  off,  a QRC file is generated from the QML files added to the
         target. This QRC file will be included when compiling the  C++  QML  module.  The  built
         static  library  will  be  installed  in  a subdirection of DESTINATION based on the QML
         module’s uri. Note that if NO_PLUGIN is set, a C++  QML  plugin  will  be  generated  to
         include the QRC files.

       • If  BUILD_SHARED_LIBS in on, all generated files, QML sources and the C++ plugin will be
         installed in a subdirectory of DESTINATION based upon the QML module’s uri. In addition,
         these  files  will  also be copied to the target’s RUNTIME_OUTPUT_DIRECTORY in a similar
         subdirectory.

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

       Since 5.91.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 installing 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 manually defined also  a  function
       ecm_qt_export_logging_category is provided.

          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 configuration 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  DEFAULT_SEVERITY,  or  “Info”  level  if
       DEFAULT_SEVERITY is not given. Note that, due to a bug in Qt 5.5, “Info” may be treated as
       more severe than “Fatal”.

       <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 generated in a file and installed  by  that
       group   id   with  the  ecm_qt_install_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 declared 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 registered.  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_logging_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_category call which uses
       the same <exportid>. This can be in the same directory,  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 install rules for the
       generated file are associated.

       Since 5.85.0 this is a no-op when building for Android, as KDebugSettings 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 CMake’s 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>] )

       CMake’s  automoc  needs  some  support when parsing C++ source files to detect whether moc
       should be run on those files and if there are also dependencies 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 developer 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 plugins which do not
       refer to external files with the plugin metadata.

       JSON_ARG1 lists the names of C++ preprocessor macros for Qt-style plugins 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 object:

          #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  additional  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.  MyProjectConfig.cmake.in)  for  the
       libary’s  installed  CMake  config  file  and  that  way will ensure that in the 3rd-party
       plugin’s buildsystem automoc is instructed 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 minimum 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   interpreted   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 <minor> must be less than 256.

       If the PACKAGE_VERSION_FILE option is used, a simple CMake package version file is created
       using  the  write_basic_package_version_file()  macro  provided  by  CMake.  It  should be
       installed in the same location as the Config.cmake file of the library so that it  can  be
       found  by  find_package().   If  the  filename  is  a  relative path, it is interpreted as
       relative to CMAKE_CURRENT_BINARY_DIR. 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_dependency 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 important files from a user’s computer. Use
          with caution.

       Since 1.7.0.

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

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

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

       This  allows  selective  use  of  the find modules provided by ECM, including deferring to
       CMake’s  versions   of   those   modules   if   it   has   them.    Rather   than   adding
       ${ECM_FIND_MODULE_DIR}  to  CMAKE_MODULE_PATH,  you use ecm_use_find_modules() to copy the
       modules you want to a local (build) directory, and add that to CMAKE_MODULE_PATH.

       The find modules given to MODULES will be copied to the  directory  given  by  DIR  (which
       should  be located in ${CMAKE_BINARY_DIR} and added to CMAKE_MODULE_PATH).  If NO_OVERRIDE
       is given, only modules not also provided by CMake will be copied.

       Example:

          find_package(ECM REQUIRED)
          ecm_use_find_modules(
              DIR ${CMAKE_BINARY_DIR}/cmake
              MODULES FindEGL.cmake
              NO_OVERRIDE
          )
          set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake)

       This example will make FindEGL.cmake available in your project, but only as long as it  is
       not yet part of CMake. Calls to find_package(EGL) will then make use of this copied module
       (or the CMake module if it exists).

       Another possible use for this macro is  to  take  copies  of  find  modules  that  can  be
       installed  along  with  config files if they are required as a dependency (for example, if
       targets provided by the find module are in the link interface of a library).

       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 directory and replace pseudo-symlinks  with  corresponding
       real  file’s  contents.  It  would  then run git update-index –assume-unchanged on them to
       trick git.

       This is useful  for  projects  like  “breeze-icons”  that  contain  many  identical  icons
       implemented as symlinks.

       Since 5.28

   QtVersionOption
       Adds  a build option to select the major Qt version if necessary, that is, if the major Qt
       version has not yet been determined otherwise  (e.g.  by  a  corresponding  find_package()
       call).

       This  module is typically included by other modules requiring knowledge about the major Qt
       version.

       QT_MAJOR_VERSION is defined to either be “5” or “6”.

       Since 5.82.0.

SEE ALSO

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

COPYRIGHT

       KDE Developers