Development/Tutorials/CMake (fr)

Development/Tutorials/CMake

Introduction

CMake lit des fichiers de script et produit des fichiers natifs pour la plateforme sur laquelle il a été lancé. Il peut créer des Makefile GNU, ou des projets KDevelop, XCode ou Visual Studio.

CMake est un logiciel libre sous license BSD. Il est développé par Kitware Inc..

Vosu trouverez plus d'informations relatives à CMake sur la page principale sur CMake de ce site.

Pourquoi utiliser CMake ?

CMake est un outil officiel de KDE 4, suite à un choix effectué en Mars 2006, principalement pour ses qualités techniques par rapport aux précédents outils de KDE, tels automake ou unsermake :

CMake est développé indépendemment de KDE , et peut être utilisé dans d'autres projets que celui-ci.
La durée de compilation est plus courte, notemment grâce à la non-utilisation de libtools
Le build des fichiers est plus facile à écrire

Comment compiler KDE avec CMake ?

Télécharger et installer CMake

Linux, BSD, et autres systèmes Unix

Cliquez ici pour télécharger la dernière version de CMake.

Une fois le téléchargement terminé, désarchivez et compilez-le : $ mkdir cmake-build $ cd cmake-build $ ../bootstrap $ make $ make install

Par défaut, CMake sera installé dans /usr/local, alors assurez-vous d'avoir /usr/local/bin dans votre répertoire d'exécution ($PATH). Pour changer ce répertoire (exemple : /usr sous Debian), ajoutez l'option '--prefix=PATH' à la commande boostrap.

Lisez ces instructions si vous voulez utiliser la version en cours de dévloppement.

Windows

Cliquez ici pour télécharger la dernière version de CMake.

Une fois téléchargé, lancez l'installeur de CMake.

Lisez ces instructions si vous voulez utiliser la version en cours de dévloppement.

Lancer CMake

Linux, BSD, et autres systèmes Unix

Vous devez lancer CMake pour générer les ficheirs de build pour votre système. Les builds in-source et out-of-source sont supportés par CMake, mais actuellement, les builds in-sources sont empêchés par l'implémentation de KDE.

En supposant que vous avez kdelibs/ dans ~/src/kdelibs/ (utilisez $ locate kdelibs/ au besoin), utilisez ces commandes : $ ls kdelibs/ $ mkdir kdelibs-build $ cd kdelibs-build $ cmake ../kdelibs Ceci générera les Makefiles pour construire kdelibs/ dans kdelibs-build/.

Windows

Vous devez lancer CMake pour générer les ficheirs de build pour votre système. Les builds in-source et out-of-source sont supportés par CMake, mais actuellement, les builds in-sources sont empêchés par l'implémentation de KDE.

En supposant que vous avez kdelibs\ dans c:\daten\kde4, utilisez ces commandes : So, let's say you have kdelibs\ in c:\daten\kde4, then do the following: c:\daten\kde4> cd kdelibs\win c:\daten\kde4> cmake c:\daten\kde4> make c:\daten\kde4> make install c:\daten\kde4> cd .. c:\daten\kde4> mkdir kdelibs-build c:\daten\kde4> cd kdelibs-build c:\daten\kde4\kdelibs-build> cmake ..\kdelibs

Ceci générera les Makefiles pour construire kdelibs\ dans kdelibs-build\. Lisez la page KDE sous Windows pour plus d'informations sur la compilation de KDE sous Windows.

Fichies de projet KDevelop 3

Si vous préférez utiliser des fichiers de projet pour KDevelop 3 (qui sont simplement des Makefiles accompagnés de quelques données pour KDevelop), lancez-le de cette façon : $ cmake ../kdelibs -GKDevelop3 Utilisez 'cmake -h' pour savoir quels générateurs CMake support ainsi que ses autres options.

CMake et Qt4

Pour trouver le réperoire de Qt4, CMake cherche qmake dans le répertoire d'exécution. CMake n'utilisez pas la variable d'environnement QTDIR. Assurez-vous d'abord que qmake se trouve dans le répertoire d'exécution qui vous utilisez.

More Details

When CMake has finished, it will have created a file called "CMakeCache.txt". This file contains all the settings CMake has detected on your system. If you want to run CMake with another generator or you want CMake to detect everything again, delete this file.

If CMake didn't find something, but you know it is somewere on your box, you can tell CMake manually where to find it. CMake uses variables to store this information. These variables are cached in the already mentioned file CMakeCache.txt. You have three options to adjust these variables manually:

tell CMake the correct value via the command line: cmake ../kdelibs -DNAME_OF_THE_VARIABLE=value
use ccmake, which provides a curses based GUI to adjust the CMake variables (run: ccmake ../kdelibs)
edit the file CMakeCache.txt directly (not recommended)

You should run "ccmake ../kdelibs" at least once so that you get an impression which variables CMake uses. Press "T" to see also the "advanced" variables. So, if CMake didn't find something, start ccmake and adjust it manually.

Command Line Variables

Some cmake command line variables you may want to set:

CMAKE_INSTALL_PREFIX: cmake ../kdelibs -DCMAKE_INSTALL_PREFIX=/opt/kde4 is the equivalent to ./configure --prefix=/opt/kde4
CMAKE_BUILD_TYPE: decide which type of build you want. You can choose between "debugfull", "Debug", "Profile", "RelWithDebInfo" and "Release". The default is "RelWithDebInfo". Please refer to page CMake Build Types for a more detailed explanation.
KDE4_BUILD_TESTS=ON: creates Makefiles with build test programs and also provides 'test' targets
KDE4_TEST_OUTPUT=xml: Unit tests using the QTestLib framework will create xml formatted logfiles.
KDE4_DISABLE_MULTIMEDIA=ON: Build KDE without any multimedia (audio and video) support.
BUILD_foo=OFF: disables the build for the project in subdirectory 'foo'.
WITH_foo: there are several options, e.g. WITH_CUPS or WITH_Jasper. If you disable them, cmake will not even try to find this package. If it is enabled, cmake will try to find it. If it fails with this, you can still adjust it manually as described above.

Environment Variables

If you have headers and libraries installed in non-standard locations that cmake cannot find (e.g., fink on Mac OSX installs to /sw), then set the following as environment variables. This can be also very useful e.g. if you install kdesupport to ~/install/kdesupport . Despite the similar naming convention, these will not work as arguments on the cmake command line:

CMAKE_INCLUDE_PATH, eg. export CMAKE_INCLUDE_PATH=/sw/include
CMAKE_LIBRARY_PATH, eg. export CMAKE_LIBRARY_PATH=/sw/lib
CMAKE_PROGRAM_PATH, eg. export CMAKE_LIBRARY_PATH=/sw/bin

With CMake 2.6.0 and above the same effect can be achieved by setting just one variable:

CMAKE_PREFIX_PATH, eg. export CMAKE_PREFIX_PATH=/sw

For more information on variables, see this cmake.org wiki page

Going Further

If cmake finishes with "Generating done" then there was no errors, but if it finishes with "Configuring done" then there was errors that you have to fix. Once cmake finishes successfully, run your buildtool (i.e. make, KDevelop, XCode or MSVC) and build and wait until it has finished. Then "make install".

If you got a failure that says something like CMake Error: This project requires some variables to be set, and cmake can not find them. Please set the following variables: X11_XTest_LIB (ADVANCED) then you may have a missing library (or other dependency). To find out which library, search in the cmake/modules directory for the variable that cmake can't find. In the example above, it is find_library(X11_XTest_LIB Xtst ${X11_LIB_SEARCH_PATH}) So the missing library is Xtst. You then need to find it (perhaps installing a libXtst-devel library) and re-run cmake.

Using CMake for a Simple Application

Here's the most simple CMakeLists.txt: add_executable(hello main.cpp) This will create an executable named "hello" (or "hello.exe" under Windows) from the source file main.cpp. You can mix C and C++ files as you want. You can have multiple executables and libraries in one CMakeLists.txt. The same source file can be used in multiple targets, it will be compiled for each target independently from the other targets. Probably the most important part of the cmake language are the variables: set( MY_SOURCES main.cpp widget.cpp) message(STATUS "my sources: ${MY_SOURCES}") So, use the SET() command to set the value of a variable. If you list more than one string, the variable will be a list. A list is a list of strings separated by semicolons. If you set it to only one item, it will have just that value. To get the value of a variable, use ${VAR}. You can iterate over a list using FOREACH(): foreach(next_ITEM ${MY_SOURCES})

  message(STATUS "next item: ${next_ITEM}")

endforeach(next_ITEM ${MY_SOURCES}) The commands in CMake are case-insensitive. Names of variables and names of parameter are case-sensitive.

You can also test for various things: if (UNIX)

  message(STATUS "This is UNIX (including OS X and CygWin)")

endif (UNIX)
if (MSVC)

  set(MY_SRCS ${MY_SRCS} winextra.cpp)

endif (MSVC) In this second example you can see also how to append items to a list.

In the cmake Wiki there is also a tutorial on using cmake to build KDE 4 software. It is recommended reading.

Using CMake for a KDE Project

Here's a basic CMakeList file that builds a small KDE 4 project: project( kde4project ) find_package( KDE4 REQUIRED ) include_directories( ${KDE4_INCLUDES} )

set( KDE4ProjectSources kde4mainapp.cpp someclass.cpp someotherclass.cpp )

kde4_add_executable( kde4project ${KDE4ProjectSources} )

target_link_libraries( kde4project ${KDE4_KDEUI_LIBS} ${KDE4_KPARTS_LIBS} )

install( TARGETS kde4project ${INSTALL_TARGETS_DEFAULT_ARGS} )

target_link_libraries contains the development libraries that are linked to your program. E.g. if you want to link to libtidy-devel, your library file name may be called /usr/local/lib/libtidy.a. You would then add -ltidy to a gcc call. Here, you add tidy to your target_link_libraries. If possible, use pre-defined variables or macros like ${KDE4_KDEUI_LIBS}.

install (TARGETS is where the target will finally be installed. If you do not have this line, make install will not be available.

Variables, macros and other useful information specific to KDE can be found at the CMake addons for KDE page.

Extending CMake

CMake can be extended using cmake scripts. CMake comes with a number of scripts; under UNIX they are by default installed to /usr/local/share/CMake/Modules/. The KDE libraries install also a set of cmake modules into share/apps/cmake/modules/. The files located there will be preferred over the ones in the system global cmake module path. For detecting software packages there are FindFOO.cmake files, see here for more information. You can also write macros in CMake. They are powerful enough to do most things you will need to build software, but they are not intended to be used as a general purpose programming language.

Converting autotools-based KDE software to CMake

In kdesdk/cmake/ you can find a script am2cmake . This is a ruby script, so you need to have ruby installed. Run am2cmake in the toplevel directory of your sources: $ cd src/mykooltool/ $ am2cmake --kde4 Don't forget the switch "--kde4", otherwise it won't generate files suitable for KDE 4 software. The converted files 'may' work as they are, but complicated projects will require some additional editing.

You may have to:

add more include direcories, using INCLUDE_DIRECTORIES()
add more link libraries, using TARGET_LINK_LIBRARIES()
add some compile switches, using ADD_DEFINITIONS()
add some "configure" checks, see How To Do Platform Checks and How To Find Installed Software
take special care of former libtool convenience libraries. They are not supported by cmake, instead there will be a file ConvenienceLibs.cmake created. In this file you will find for every convenience lib a variable, which contains all source files of this convenience lib. For the targets which linked to this convenience lib, just add the variable to the sources.
a file AdditionalInfo.txt will be created. There you will see all *.in and *.in.in files of your project. The stuff done in these files will have to be converted manually to cmake.