Provided by: extra-cmake-modules_5.18.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> [...]])

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

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

       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.

              · The tool png2ico is required. See FindPng2Ico.

              · Supported sizes: 16, 32, 48, 64, 128.

       Mac OS X notes

              · The executable target must have the MACOSX_BUNDLE property set.

              · Icons are added to the bundle.

              · The tool iconutil (provided by Apple) is required.

              · Supported sizes: 16, 32, 64, 128, 256, 512, 1024.

              · At least a 128x128px 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.

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

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

       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').
       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>]
              [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 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.

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

       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.

   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  ${ICON_INSTALL_DIR}  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 subdiretories 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.

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

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

       Starting  with Frameworks 5.18, the generated header also includes the <QDebug> header, so
       you don't have to put extra #include <QDebug> anymore in your code.

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

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

SEE ALSO

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

COPYRIGHT

       KDE Developers