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

FreeBSD Manual Pages

  
 
  

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

NAME
       ecm-modules - ECM Modules Reference

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

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

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

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

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

ALL MODULES
   ECMAddAppIcon
       Add icons to executable files and packages.

	  ecm_add_app_icon(<sources_var>
			   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).
       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.

       Windows notes

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

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

	      o	The tool png2ico is required. See FindPng2Ico.

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

       Mac OS X	notes

	      o	The  executable	 target	 must  have the	MACOSX_BUNDLE property
		set.

	      o	Icons are added	to the bundle.

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

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

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

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

	      o	Larger	sizes are automatically	used to	substitute for smaller
		sizes on "Retina" (high-resolution) displays. For  example,  a
		32px  icon,  if	provided, will be used as a 32px icon on stan-
		dard-resolution	displays, and as a 16px-equivalent icon	 (with
		an  "@2x"  tag)	on high-resolution displays. ksvg2icns handles
		this internally.

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

       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_LI-
       BRARIES.	Each executable	will be	added as a test	with the same name.

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

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

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

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

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

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

       Since pre-1.0.0.

   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	ECMPo-
	  QmTools instead.

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

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

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

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

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

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

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

	  po/
	      es.po
	      fr.po

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

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

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

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

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

       ecm_create_qm_from_po_files() creates a "translation" target. This tar-
       get builds all .po files	into .qm files.

	  ecm_create_qm_loader(<source_files_var> <catalog_name>)

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

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

       This generates a	C++ file which loads "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:

       o Address Sanitizer

       o Memory	Sanitizer

       o Thread	Sanitizer

       o Leak Sanitizer

       o Undefined Behaviour Sanitizer

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

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

   Usage
       Simply add:

	  include(ECMEnableSanitizers)

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

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

       o address

       o memory

       o thread

       o leak

       o undefined

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

       "leak" requires the  "address" sanitizer.

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

   Example
       This is an example of usage:

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

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

	      -DCMAKE_CXX_COMPILER=clang++

       Since 1.3.0.

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

	  ecm_find_package_version_check(<name>)

       Prints  warnings	 if  the CMake version or the 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	compo-
       nents.	If  <component>	 is listed in <name>_FIND_COMPONENTS, then all
       its (transitive)	dependencies will also be added	to <variable>.

	  ecm_find_package_handle_library_components(<name>
	      COMPONENTS <component> [<component> [...]]
	      [SKIP_DEPENDENCY_HANDLING])
	      [SKIP_PKG_CONFIG])

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

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

       Additional variables can	be used	to provide additional information:

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

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

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

       The following variables will be set:

       <name>_TARGETS
	      the imported targets

       <name>_LIBRARIES
	      the found	libraries

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

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

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

       Note  that  these  variables  are  never	 cleared, so if	ecm_find_pack-
       age_handle_library_components() is called multiple times	with different
       components  (typically  because	of multiple find_package() calls) then
       <name>_TARGETS, for example, will contain all the targets found in  any
       call (although no duplicates).

       Since pre-1.0.0.

   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	camel-
       case 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: low-
       ercased 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, gen-
       erate   forwarding   headers   based   on   the	original  names	 (e.g.
       kparts/part.h).	This allows includes like  "#include  <kparts/part.h>"
       to  be used before installation,	as long	as the include_directories are
       set appropriately.

       OUTPUT_DIR specifies where the files will be generated; this should  be
       within  the  build  directory.  By default, ${CMAKE_CURRENT_BINARY_DIR}
       will be used.  This option can be used to avoid file conflicts.

       REQUIRED_HEADERS	specifies an output variable name where	 all  the  re-
       quired  headers will be appended	so that	they can be installed together
       with the	generated ones.	 This is mostly	intended as a  convenience  so
       that  adding  a	new  header  to	a project only requires	specifying the
       CamelCase variant in the	CMakeLists.txt file; the original variant will
       then be added to	this variable.

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

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

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

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

       Example usage (without PREFIX):

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

       Example usage (with PREFIX):

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

       Since pre-1.0.0.

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

	  ecm_generate_pkgconfig_file(BASE_NAME	<baseName>
				[LIB_NAME <libName>]
				[DEPS "<dep> [<dep> [...]]"]
				[FILENAME_VAR <filename_variable>]
				[INCLUDE_INSTALL_DIR <dir>]
				[LIB_INSTALL_DIR <dir>]
				[DEFINES -D<variable=value>...]
				[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 unde-
       fined, it will default to the BASE_NAME.	That means the	LIB_NAME  will
       be set as the name field	as well	as the library to link to.

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

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

       LIB_INSTALL_DIR specifies where the library is being installed. If 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	subdi-
       rectory	of LIB_INSTALL_DIR, unless the ECM_PKGCONFIG_INSTALL_DIR cache
       variable	is set to something different. Note that  the  first  call  to
       ecm_generate_pkgconfig_file   with  the	INSTALL	 argument  will	 cause
       ECM_PKGCONFIG_INSTALL_DIR to be set to the cache, and will be  used  in
       any subsequent calls.

       To  properly  use this macro a version needs to be set. To retrieve it,
       ECM_PKGCONFIG_INSTALL_DIR uses PROJECT_VERSION.	To  set	 it,  use  the
       project()   command   (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 ei-
       ther the	default	qmake mkspecs directory	or of a	directory that will be
       in the $QMAKEPATH environment variable when qmake is run.

	  ecm_generate_pri_file(BASE_NAME <baseName>
				LIB_NAME <libName>
				[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 ac-
       tual library to link to (ie:  the  first	 argument  to  add_library()).
       DEPS  is	 a  space-separated  list of the base names of other libraries
       (for Qt libraries, use the same names you use with the QT variable in a
       qmake project file, such	as "core" for QtCore).	FILENAME_VAR specifies
       the name	of a variable to store the path	to the generated file in.

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

       Example usage:

	  ecm_generate_pri_file(
	      BASE_NAME	KArchive
	      LIB_NAME KF5KArchive
	      DEPS "core"
	      FILENAME_VAR pri_filename
	  )
	  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 ac-
       cording to the FreeDesktop.org icon naming scheme. By default, they are
       installed  to  the  "hicolor"  theme, but this can be changed using the
       THEME argument.	If the icons are localized, the	LANG argument  can  be
       used to install them in a locale-specific directory.

       <size>  is  a  numeric pixel size (typically 16,	22, 32,	48, 64,	128 or
       256) or sc for scalable (SVG) files, <group> is	one  of	 the  standard
       FreeDesktop.org icon groups (actions, animations, apps, categories, de-
       vices, emblems, emotes, intl, mimetypes,	places,	status)	and  <ext>  is
       one of .png, .mng or .svgz.

       The typical installation	directory is share/icons.

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

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

       Users of	 the  KDEInstallDirs  module  would  normally  use  ${ICON_IN-
       STALL_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 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.

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

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

	  cmake	-DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_foo=TRUE myproject

       Since pre-1.0.0.

   ECMPackageConfigHelpers
       Helper macros for generating CMake package config files.

       write_basic_package_version_file() is the same as the one  provided  by
       the  CMakePackageConfigHelpers module in	CMake; see that	module's docu-
       mentation for more information.

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

       This behaves in the same	way  as	 configure_package_config_file()  from
       CMake  2.8.12,  except  that it adds an extra helper macro: find_depen-
       dency().	It is highly recommended that you read the  documentation  for
       CMakePackageConfigHelpers  for  more information, particularly with re-
       gard to the PATH_VARS argument.

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

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

   Additional Config File Macros
	  find_dependency(<dep>	[<version> [EXACT]])

       find_dependency()  should  be  used  instead  of	find_package() to find
       package dependencies.  It forwards the correct  parameters  for	EXACT,
       QUIET  and  REQUIRED  which  were passed	to the original	find_package()
       call.  It also sets an informative diagnostic message if	the dependency
       could not be found.

       Since pre-1.0.0.

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

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

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

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

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

       Since pre-1.0.0.

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

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

	  <prefix>_VERSION_MAJOR  - <major> as an integer
	  <prefix>_VERSION_MINOR  - <minor> as an integer
	  <prefix>_VERSION_PATCH  - <patch> as an integer
	  <prefix>_VERSION_STRING - <version> as a C string
	  <prefix>_VERSION	  - the	version	as an integer

       <prefix>_VERSION	 has <patch> in	the bottom 8 bits, <minor> in the next
       8 bits and <major> in the remaining bits.  Note that <patch>  and  <mi-
       nor> must be less than 256.

       If the PACKAGE_VERSION_FILE option is used, a simple CMake package ver-
       sion file is created using the write_basic_package_version_file() macro
       provided	 by  CMake. It should be installed in the same location	as the
       Config.cmake file of the	library	so that	it can be found	by  find_pack-
       age().	If the filename	is a relative path, it is interpreted as rela-
       tive to CMAKE_CURRENT_BINARY_DIR. The optional COMPATIBILITY option  is
       forwarded   to	write_basic_package_version_file(),  and  defaults  to
       AnyNewerVersion.

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

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

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

       Since pre-1.0.0.

       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_de-
       pendency	to make	the uninstall target depend on it:

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

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

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

       Since 1.7.0.

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

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

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

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

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

       Since pre-1.0.0.

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

COPYRIGHT
       KDE Developers

5.35				 Jul 02, 2017			ECM-MODULES(7)

NAME | INTRODUCTION | ALL MODULES | SEE ALSO | COPYRIGHT

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

home | help