Difference between revisions of "Policies/CMake Coding Style"

Jump to: navigation, search
Line 1: Line 1:
 
This document describes the recommended coding style for CMake files in KDE, i.e. CMakeLists.txt files and *.cmake files.
 
This document describes the recommended coding style for CMake files in KDE, i.e. CMakeLists.txt files and *.cmake files.
 +
 +
=General=
 +
 +
To put in in one sentence: be as careful when writing the CMake files as when you are writing C++ code.
  
 
==Indentation==
 
==Indentation==
Line 44: Line 48:
 
<syntaxhighlight lang="cmake">
 
<syntaxhighlight lang="cmake">
 
if(FOOVAR)
 
if(FOOVAR)
some_command(...)
+
  some_command(...)
 
else()
 
else()
another_command(...)
+
  another_command(...)
 
endif()
 
endif()
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 53: Line 57:
 
<pre>
 
<pre>
 
if(BARVAR)
 
if(BARVAR)
  some_other_command(...)
+
  some_other_command(...)
 
endif(BARVAR)
 
endif(BARVAR)
 
</pre>
 
</pre>
 +
 +
=Writing CMake Find-modules=
  
 
==(Not) Using pkg-config==
 
==(Not) Using pkg-config==
Line 66: Line 72:
 
* 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.
 
* 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 CMake's readme.txt==
  
* 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.
+
==Use FindPackageHandleStandardArgs.cmake==
 +
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
+
==Avoid Micro-Optimzations==
 +
Micro-optimizations like
 
<pre>
 
<pre>
 
if(FOO_LIBRARY AND FOO_INCLUDE_DIR)
 
if(FOO_LIBRARY AND FOO_INCLUDE_DIR)

Revision as of 14:32, 15 January 2012

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

Contents

General

To put in in one sentence: be as careful when writing the CMake files as when you are writing C++ code.

Indentation

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

  • if/else/endif
  • foreach/endforeach
  • while/endwhile
  • macro/endmacro
  • function/endfunction

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. Do not use tabs.

Upper/lower casing

Most important: use consistent upper- or lowercasing within one file !

In general, in KDE the all-lowercase style is preferred.

So, this is recommended:

add_executable(foo foo.c)

This is also acceptable:

ADD_EXECUTABLE(bar bar.c)

Mixed casing as shown below works too, but should not be done within KDE:

Add_Executable(hello hello.c)
aDd_ExEcUtAbLe(blub blub.c)

End commands

To make the code easier to read, use empty commands for endforeach(), endif(), endfunction(), endmacro() and endwhile(). Also, use empty else() commands.

For example, do this:

if(FOOVAR)
  some_command(...)
else()
  another_command(...)
endif()

and not this:

if(BARVAR)
   some_other_command(...)
endif(BARVAR)

Writing CMake Find-modules

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

Follow CMake's readme.txt

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

Use FindPackageHandleStandardArgs.cmake

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.

Avoid Micro-Optimzations

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.


KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal