Policies/CMake Coding Style: Difference between revisions

From KDE Community Wiki
(→‎Upper/lower casing: update to new syntaxhighlighter)
No edit summary
Line 34: Line 34:
* use only FIND_PACKAGE(PkgConfig), don't use INCLUDE(UsePkgConfig), this one is deprecated
* use only FIND_PACKAGE(PkgConfig), don't use INCLUDE(UsePkgConfig), this one is deprecated
* make sure the variables created by PKG_CHECK_MODULES() are all prefixed with "PC_", so they don't mix up with other variables, e.g. set via FIND_PATH() etc.
* make sure the variables created by PKG_CHECK_MODULES() are all prefixed with "PC_", so they don't mix up with other variables, e.g. set via FIND_PATH() etc.
 
* FindLibXml2.cmake as shipped with CMake 2.8.5 is a good example how pkg-config should be handled
* putting something like if(NOT WIN32) around the pkg-config stuff is not necessary (and should be removed if it is somewhere). If pkg-config is not found, e.g. on Windows, the macros simply do nothing.


==Writing CMake Find-modules==
==Writing CMake Find-modules==


Follow the style guide from CMake when writing some FindFoo.cmake module:  
* Follow the style guide from CMake when writing some FindFoo.cmake module:  
[http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup readme.txt]
[http://www.cmake.org/cgi-bin/viewcvs.cgi/Modules/readme.txt?root=CMake&view=markup readme.txt]
* For checking the results inside the Find-module, the macro find_package_handle_standard_args() (coming with CMake) should be used, using the new extended syntax, which supports also version checking.
* Micro-optimizations like
<pre>
if(FOO_LIBRARY AND FOO_INCLUDE_DIR)
  set(FOO_FOUND TRUE)
else()
  ... execute the whole find-logic
endif()
</pre>
should be removed, the find-logic should be executed always. These shortcuts can cause problems e.g. when the same file is used from multiple directories but e.g. with different required versions or components etc.

Revision as of 23:19, 22 August 2011

This document describes the recommended coding style for CMake files in KDE, i.e. CMakeLists.txt files and *.cmake files.

Indentation

Indent all code correctly, i.e. the body of

  • IF/ELSE/ENDIF
  • FOREACH/ENDFOREACH
  • WHILE/ENDWHILE
  • MACRO/ENDMACRO
  • FUNCTION/ENDFUNCTION (CMake 2.6)

Use spaces for indenting, 2, 3 or 4 spaces preferably. Use the same amount of spaces for indenting as is used in the rest of the file.

Upper/lower casing

CMake commands are case-insensitive (only the commands, not the arguments or variable names). So all the following versions work:

add_executable(foo foo.c)
ADD_EXECUTABLE(bar bar.c)
Add_Executable(hello hello.c)
aDd_ExEcUtAbLe(blub blub.c)

But this would be ugly.

In KDE the all-lowercase style is preferred. The all-uppercase style is also ok. Mixing upper- and lowercase should not be done in KDE CMake files. Although all-lowercase is preferred, if a file is apparently in all-uppercase style, then stay consistent and also use all-uppercase in this file.

(Not) Using pkg-config

You are free to use pkg-config in FindXXX.cmake modules, as long as the following conditions are met:

  • the FindXXX.cmake must also work without pkg-config, as long as the package is either installed to one of the default locations (as /usr or /usr/local) or if CMAKE_PREFIX_PATH is set accordingly
  • use only FIND_PACKAGE(PkgConfig), don't use INCLUDE(UsePkgConfig), this one is deprecated
  • make sure the variables created by PKG_CHECK_MODULES() are all prefixed with "PC_", so they don't mix up with other variables, e.g. set via FIND_PATH() etc.
  • FindLibXml2.cmake as shipped with CMake 2.8.5 is a good example how pkg-config should be handled
  • putting something like if(NOT WIN32) around the pkg-config stuff is not necessary (and should be removed if it is somewhere). If pkg-config is not found, e.g. on Windows, the macros simply do nothing.

Writing CMake Find-modules

  • Follow the style guide from CMake when writing some FindFoo.cmake module:

readme.txt

  • For checking the results inside the Find-module, the macro find_package_handle_standard_args() (coming with CMake) should be used, using the new extended syntax, which supports also version checking.
  • Micro-optimizations like
if(FOO_LIBRARY AND FOO_INCLUDE_DIR)
  set(FOO_FOUND TRUE)
else()
  ... execute the whole find-logic
endif()

should be removed, the find-logic should be executed always. These shortcuts can cause problems e.g. when the same file is used from multiple directories but e.g. with different required versions or components etc.