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

FreeBSD Manual Pages

  
 
  

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

NAME
       ecm-developer - ECM Developer Reference

WRITING	MODULES
       The  CMake 3 documentation (and cmake-developer(7) in particular) has a
       lot of useful information about	writing	 CMake	modules,  including  a
       large  section  devoted to find modules.	This guide will	only highlight
       things that are particular to the Extra CMake Modules project.

       Most of these are stylistic points. For example,	the license header for
       a module	in ECM should look like:

	  #=============================================================================
	  # Copyright 20XX Your	Name <your.email@example.com>
	  #
	  # Redistribution and use in source and binary	forms, with or without
	  # modification, are permitted	provided that the following conditions
	  # are	met:
	  #
	  # 1. Redistributions of source code must retain the copyright
	  #    notice, this list of conditions and the following disclaimer.
	  # 2. Redistributions in binary form must reproduce the copyright
	  #    notice, this list of conditions and the following disclaimer in the
	  #    documentation and/or other materials provided with the distribution.
	  # 3. The name	of the author may not be used to endorse or promote products
	  #    derived from this software without specific prior written permission.
	  #
	  # THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
	  # IMPLIED WARRANTIES,	INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	  # OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE	DISCLAIMED.
	  # IN NO EVENT	SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
	  # INCIDENTAL,	SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
	  # NOT	LIMITED	TO, PROCUREMENT	OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
	  # DATA, OR PROFITS; OR BUSINESS INTERRUPTION)	HOWEVER	CAUSED AND ON ANY
	  # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,	OR TORT
	  # (INCLUDING NEGLIGENCE OR OTHERWISE)	ARISING	IN ANY WAY OUT OF THE USE OF
	  # THIS SOFTWARE, EVEN	IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

       Functions  should be used instead of macros unless there	is a good rea-
       son not to (and that reason should be noted in a	comment),  and	lower-
       case should be used for macros, functions and commands.

       4  spaces  is the generally-recommended indent, although	there are sev-
       eral files that use 2 spaces; consistency within	a file is more	impor-
       tant than consistency across files.

       If in doubt, look at how	other modules in Extra CMake Modules are writ-
       ten, and	follow the same	pattern.

   Find	Modules
       A good template for find	module documentation is:

	  #.rst:
	  # FindFoo
	  # -------
	  #
	  # Finds the Foo library.
	  #
	  # This will define the following variables:
	  #
	  # ``Foo_FOUND``
	  #	True if	(the requested version of) Foo is available
	  # ``Foo_VERSION``
	  #	The version of Foo, if it is found
	  # ``Foo_LIBRARIES``
	  #	This can be passed to target_link_libraries() instead of the ``Foo::Foo``
	  #	target
	  # ``Foo_INCLUDE_DIRS``
	  #	This should be passed to target_include_directories() if the target is not
	  #	used for linking
	  # ``Foo_DEFINITIONS``
	  #	This should be passed to target_compile_options() if the target	is not
	  #	used for linking
	  #
	  # If ``Foo_FOUND`` is	TRUE, it will also define the following	imported target:
	  #
	  # ``Foo::Foo``
	  #	The Foo	library
	  #
	  # In general we recommend using the imported target, as it is	easier to use.
	  # Bear in mind, however, that	if the target is in the	link interface of an
	  # exported library, it must be made available	by the package config file.

       Note the	use of definition lists	for the	variables.

       Because of the ECMUseFindModules	module,	projects may easily make local
       copies  of  find	 modules,  and may install those copies	with their own
       CMake project config files. For this reason, find  modules  should  in-
       clude the full BSD 3-clause license:

	  #=============================================================================
	  # Copyright 20XX Your	Name <your.email@example.com>
	  #
	  # Redistribution and use in source and binary	forms, with or without
	  # modification, are permitted	provided that the following conditions
	  # are	met:
	  #
	  # 1. Redistributions of source code must retain the copyright
	  #    notice, this list of conditions and the following disclaimer.
	  # 2. Redistributions in binary form must reproduce the copyright
	  #    notice, this list of conditions and the following disclaimer in the
	  #    documentation and/or other materials provided with the distribution.
	  # 3. The name	of the author may not be used to endorse or promote products
	  #    derived from this software without specific prior written permission.
	  #
	  # THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
	  # IMPLIED WARRANTIES,	INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	  # OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE	DISCLAIMED.
	  # IN NO EVENT	SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
	  # INCIDENTAL,	SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
	  # NOT	LIMITED	TO, PROCUREMENT	OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
	  # DATA, OR PROFITS; OR BUSINESS INTERRUPTION)	HOWEVER	CAUSED AND ON ANY
	  # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,	OR TORT
	  # (INCLUDING NEGLIGENCE OR OTHERWISE)	ARISING	IN ANY WAY OUT OF THE USE OF
	  # THIS SOFTWARE, EVEN	IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	  #=============================================================================

       Find  modules should always provide imported targets in addition	to the
       traditional variables (like Foo_LIBRARIES, etc).

       Unlike find modules shipped with	CMake, if the module requires  a  spe-
       cific  CMake version it is not enough to	warn when the minimum required
       version is not high enough: you should also produce an error  when  the
       actual  CMake  version  being used is not high enough. This can be done
       with:

	  if(CMAKE_VERSION VERSION_LESS	2.8.12)
	      message(FATAL_ERROR "CMake 2.8.12	is required by FindFoo.cmake")
	  endif()
	  if(CMAKE_MINIMUM_REQUIRED_VERSION VERSION_LESS 2.8.12)
	      message(AUTHOR_WARNING "Your project should require at least CMake 2.8.12	to use FindFoo.cmake")
	  endif()

       The  ECMFindModuleHelpers  module  has  several	useful	functions  and
       macros.	For  example, it allows	you to replace the above version check
       with:

	  ecm_find_package_version_check(Foo)

   Components
       Using ECMFindModuleHelpers, creating a find module for a	 library  with
       several inter-dependent components is reasonably	straightforward. After
       the documentation, you need to include the module and do	the usual ver-
       sion check:

	  include(ECMFindModuleHelpers)
	  ecm_find_package_version_check(Foo)

       The   important	 macros	  are	ecm_find_package_parse_components  and
       ecm_find_package_handle_library_components.  These take a list of  com-
       ponents,	and query other	variables you provide to find out the informa-
       tion they require.  The documentation for ECMFindModuleHelpers provides
       more information, but a simple setup might look like:

	  set(Foo_known_components Bar Baz)
	  set(Foo_Bar_pkg_config "foo-bar")
	  set(Foo_Bar_lib "bar")
	  set(Foo_Bar_header "foo/bar.h")
	  set(Foo_Bar_pkg_config "foo-baz")
	  set(Foo_Baz_lib "baz")
	  set(Foo_Baz_header "foo/baz.h")

       If Baz depends on Bar, for example, you can specify this	with

	  set(Foo_Baz_component_deps "Bar")

       Then call the macros:

	  ecm_find_package_parse_components(Foo
	      RESULT_VAR Foo_components
	      KNOWN_COMPONENTS ${Foo_known_components}
	  )
	  ecm_find_package_handle_library_components(Foo
	      COMPONENTS ${Foo_components}
	  )

       Of  course,  if	your components	need unusual handling, you may want to
       replace ecm_find_package_handle_library_components with,	for example, a
       foreach	loop  over  the	components (the	body of	which should implement
       most of what a normal find module does, including  setting  Foo_<compo-
       nent>_FOUND).

       At  this	 point,	 you should set	Foo_VERSION using whatever information
       you have	available (such	as from	 parsing  header  files).   Note  that
       ecm_find_package_handle_library_components  will	 set it	to the version
       reported	by pkg-config of the first component found, but	 this  depends
       on the presence of pkg-config files, and	the version of a component may
       not be the same as the version of the whole package.  After that,  fin-
       ish off with

	  include(FindPackageHandleStandardArgs)
	  find_package_handle_standard_args(Foo
	      FOUND_VAR
		  Foo_FOUND
	      REQUIRED_VARS
		  Foo_LIBRARIES
	      VERSION_VAR
		  Foo_VERSION
	      HANDLE_COMPONENTS
	  )

	  include(FeatureSummary)
	  set_package_properties(Foo PROPERTIES
	      URL "https://www.foo.example.com/"
	      DESCRIPTION "A library for doing useful things")

SUBMITTING MODULES
       Proposed	new modules should be submitted	using the KDE Review Board in-
       stance, and  be	assigned  to  the  buildsystem	and  extracmakemodules
       groups.	You should be able to point to two separate projects that will
       make use	of the module.

       The	 mailing       list	  can	     be	       found	    at
       https://mail.kde.org/mailman/listinfo/kde-buildsystem.

COPYRIGHT
       KDE Developers

5.73				 Aug 27, 2020		      ECM-DEVELOPER(7)

NAME | WRITING MODULES | SUBMITTING MODULES | COPYRIGHT

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

home | help