Provided by: extra-cmake-modules_5.62.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

   ECMAddAppIcon
       Add icons to executable files and packages.

          ecm_add_app_icon(<sources_var>
                           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 to the executable target whose sources are  specified  by  <sources_var>  on
       platforms that support it (Windows and Mac OS X).  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.

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

              · One  of  the  tools  png2ico  (See  FindPng2Ico)  or 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. ksvg2icns handles this internally.

              · 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>]
              [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.

       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.

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

   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.

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

   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 "<dep> [<dep> [...]]"]
                                [FILENAME_VAR <filename_variable>]
                                [INCLUDE_INSTALL_DIR <dir>]
                                [LIB_INSTALL_DIR <dir>]
                                [DEFINES -D<variable=value>...]
                                [DESCRIPTION <library description>] # since 5.41.0
                                [INSTALL])

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

       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.

       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 (only
       available since CMake 3.0) 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>
                                [DEPS "<dep> [<dep> [...]]"]
                                [FILENAME_VAR <filename_variable>]
                                [INCLUDE_INSTALL_DIR <dir>]
                                [LIB_INSTALL_DIR <dir>])

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

       ecm_generate_pri_file()   generates   just    such    a    file.     It    requires    the
       PROJECT_VERSION_STRING  variable  to  be  set.   This is typically set by ECMSetupVersion,
       although the project() command in CMake 3.0.0 and later can also set this.

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

       Example usage:

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

       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(<source_files_var> <catalog_name>)

       Generates C++ code which ensures translations are automatically  loaded  at  startup.  The
       generated files are appended to <source_files_var>.

       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 mylib)
          add_library(mylib ${mylib_SRCS})

          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.

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

   ECMQtDeclareLoggingCategory
       Generate declarations for logging categories in Qt5.

          ecm_qt_declare_logging_category(<sources_var>
                                          HEADER <filename>
                                          IDENTIFIER <identifier>
                                          CATEGORY_NAME <category_name>
                                          [DEFAULT_SEVERITY
                                               <Debug|Info|Warning|
                                                Critical|Fatal>])

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

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

       Since 5.14.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>_VERSION_STRING - <version> (for compatibility: use <prefix>_VERSION instead)
          <prefix>_SOVERSION      - <soversion>, or <major> if SOVERSION was not given

       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>
          PROJECT_VERSION_STRING  - <version> (for compatibility: 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.

   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

SEE ALSO

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

COPYRIGHT

       KDE Developers