Development/Tutorials/CMake (de)

Development/Tutorials/CMake

Zusammenfassung

CMake ist das Build-System, das KDE benutzt. Diese Anleitung beschreibt, wie man CMake benutzt und wie man die Projektdateien schreibt.

Einführung

CMake liest Script Dateien ein und gibt Eingabedateien für das native Buildsystem der Platform auf der es läuft aus. Es kann GNU Makefiles, KDevelop Projekt Dateien, XCode Projekt Dateien und Visual Studio Projekt Dateien ausgeben.

CMake ist freie Software, die unter einer BSD-artigen Lizenz veröffentlicht wird. Entwickelt wird es von Kitware Inc.

Hier einige Links, wo man etwas über CMake im Allgemeinen lernen kann (meist englisch):

Es gibt auch eine CMake Mailing List.

Warum CMake benutzen ?

CMake ist nach einer Entscheidung im März 2006 das offizielle Werkzeug von KDE 4, vorwiegend aus technischen Vorteilen gegenüber den älteren KDE Werkzeugen automake und unsermake:

CMake wird unabhänging von KDE entwickelt und kann auch von anderen Projekten benutzt werden.
Die Übersetzungszeit ist sehr viel kürzer, hauptsächlich weil die libtool nicht mehr benutzt wird.
Die CMake-Dateien sind einfacher zu schreiben.

Wie man KDE mit Hilfe von CMake übersetzt

CMake runterladen und installieren

Linux, BSD und andere Unix Systeme

Die neuste Version von CMake kann von [1] heruntergeladen werden.

Einmal heruntergeladen, muss es entpackt und übersetzt werden: $ mkdir cmake-build $ cd cmake-build $ ../bootstrap $ make $ make install

Standardmäßig wird CMake in /usr/local installiert, daher muss /usr/local/bin in Pfad für ausführbare Dateien stehen. Um das Installationspräfix zu ändern (z.B. in /usr in debian), muss die '--prefix=PATH' Option zum bootstrap Kommando hinzugefügt werden.

Möchte man die aktuelle Entwicklerversion von CMake benutzen, findet man hier eine Anleitung.

Windows

Neuste Version von CMake von hier herunterladen.

Dann den Cmake-installer aufrufen

Standardmäßig wird CMake in C:\$(Program Files)\CMake 2.4 installiert.

Möchte man die aktuelle Entwicklerversion von CMake benutzen, findet man hier eine Anleitung.

CMake ausführen

Linux, BSD, and other Unix Systems

Um die Build-Dateien für das System zu erzeugen, muss CMake aufgerufen werden. Sowohl Übersetzungsvorgänge innerhalb des Codes als auch in einem gesonderten werden von CMake unterstützt, wobei KDE derzeit einen Übersetzungsvorgang innerhalb des Quellcodes verbietet.

Hat man zum Beispiel kdelibs/ in ~/src/kdelibs/, dann ruft man folgende Befehle auf: $ ls kdelibs/ $ mkdir kdelibs-build $ cd kdelibs-build $ cmake ../kdelibs Das wird die Makefiles im Verzeichnis kdelibs-build erzeugen, die zum Übersetzen von kdelibs benötigt werden.

Windows

Hat man zum Beispiel kdelibs\ in c:\daten\kde4, dann ruft man folgende Befehle auf: 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

Dadurch werden die Makefiles, um kdelibs\ zu erzeugen in kdelibs-build angelegt. Siehe auch KDE On Windows für mehr Informationen über das Übersetzen von KDE unter Windows.

Projektdateien für KDevelop

Benötigen Sie Projektdateien für KDevelop (was einfache Makefile mit einigen zusätzlichen Extradateien für KDevelop sind), rufen Sie folgenden Befehl auf: $ cmake ../kdelibs -GKDevelop3 Mit 'cmake -h' kann man herausfinden, welche Generatoren CMake unterstützt und welche weiteren Optionen es gibt.

CMake und Qt4

Um Qt 4 zu finden sucht CMake nach qmake im Pfad für ausführbare Dateien. CMake benutzt nicht die QTDIR Umgebungsvariable. Daher müssen Sie sicherstellen, daß das erste qmake, welches im Pfad gefunden wird dasjenige ist, welches benutzt werden soll (also bei Parallelinstallationen von Qt3 und Qt4 entsprechend Qt4 zuerst gefunden wird).

Mehr Details

Wenn CMake seine Arbeit beendet hat, existiert eine Datei namens "CMakeCache.txt". Diese Datei enthält alle Einstellungen, die von CMake auf dem System entdeckt worden sind. Soll CMake mit einem anderen Generator aufgerufen werden oder das System neu untersucht werden, löschen Sie diese Datei. Wenn CMake etwas nicht findet, aber Sie wissen, dass es auf Ihrem System ist, können Sie CMake manuell mitteilen, wo man es findet. CMake benutzt Variablen um diese Information zu speichern und zwar in der eben erwähnten CMakeCache.txt Datei. Es gibt drei Möglichkeiten, diese Variablen manuell einzustellen:

CMake den korrekten Wert über die Kommandozeile mitteilen:

cmake ../kdelibs -DNAME_OF_THE_VARIABLE=value

ccmake benutzen, welches eine auf curses basierende GUI aufruft, um CMake Variablen zu setzen ((run: ccmake ../kdelibs)
Die Datei CMakeCache.txt direkt bearbeiten (wird nicht empfohlen)

Sie sollten "ccmake ../kdelibs" mindesten einmal aufrufen, so dass Sie einen Eindruck bekommen, welche Variable CMake benutzt. Drücken Sie "T" um die "fortgeschrittenen" Variablen zu sehen. Wenn also CMake etwas bestimmtes nicht von sich aus findet, rufen Sie ccmake auf und stellen Sie es von Hand ein.

Kommandozeilenvariablen

Folgende cmake Kommandozeilenvariablen könnten für Sie von Interesse sein:

CMAKE_INSTALL_PREFIX: cmake ../kdelibs -DCMAKE_INSTALL_PREFIX=/opt/kde4 entspricht dem früheren ./configure --prefix=/opt/kde4
CMAKE_BUILD_TYPE: Hier kann man sich aussuchen, welche Debug-Informationen erzeugt werden sollen. Folgende Möglichkkeiten gibt es:
- "debugfull"
- "debug"
- "profile"
- "relwithdebinfo"
- "release".

Voreinstellung ist "relwithdebinfo" (-O2 -g). Siehe auch FindKDE4Internal.cmake für weitere Details.

KDE4_BUILD_TESTS=ON: erzeugt Makefiles die zusätzliche Testprogramme erzeugen und auch das Ziel 'test' zur Verfügung stellen.
KDE4_TEST_OUTPUT=xml: Unit tests, die das QTestLib Framework benutzen werden xml-formatierte Logfiles erzeugen.
KDE4_DISABLE_MULTIMEDIA=ON: Erzeugt KDE ohne jegliche Multimediaunterstützung (Audio und Video)
RPATH_STYLE: Diese Kommandozeilenoption gibt es nicht mehr. Per Voreinstllung wird alles mit einem korrekten RPATH erzeugt. Möchten Sie RPATH nicht, setzten Sie CMAKE_SKIP_RPATH auf TRUE.
BUILD_foo=OFF: Schaltet die Erzeugung im Unterverzeichnis 'foo' ab.
WITH_foo: Hier gibt es mehrere Möglichkeiten, z.B. WITH_CUPS oder WITH_Jasper. Wenn Sie diese Punkte ausschalten, wird CMake nicht versuchen, die Pakete zu finden, ansonsten sucht CMake danach. Schlägt das Fehl, kann man wie oben beschrieben manuell nachhelfen.

Umgebungsvariablen

Wenn sich Header oder Bibliotheken an einem nicht-standarisierten Ort befinden, den CMake nicht findenkann (so wird zum Beispiel fink auf Mac OSX in /sw installiert), kann man folgendende Umgebungsvariablen setzen. Trotz der ähnlichen Namensgebung, funktionieren diese nicht als Kommandozeilenparameter für CMake:

CMAKE_INCLUDE_PATH, Beispiel: export CMAKE_INCLUDE_PATH=/sw/include
CMAKE_LIBRARY_PATH, Beispiel: export CMAKE_LIBRARY_PATH=/sw/lib

Mehr Informationen über Umgebungsvariablen hier

Nach dem Aufruf von CMake

Schließt cmake mit der Meldung "Generating done" ab, gab es keine Fehler. Schließt es jedoch mit "Configuring done" ab, gab es Fehler, die es zu beheben gilt. Wenn cmake erfolgreich durchgelaufen ist, rufen Sie das entsprechende Werkzeug zur weiteren Bearbeitung auf (z.B. make, KDevelop, XCode oder MSVC). Das Ziel wird erzeugt, warten Sie bis die Erzeugung abgeschlossen ist. Anschließend können Sie z.B. "make install" aufrufen.

Gibt es eine Fehlermeldung der Art 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) kann es an einer fehlenden Bibliothek oder anderen Abhängigkeit liegen. Um herauszufinden, welche Bibliothek, suchen Sie im Verzeichnis cmake/modules nach der Variable, die cmake nicht finden kann. Im obigen Beispiel ist das FIND_LIBRARY(X11_XTest_LIB Xtst ${X11_LIB_SEARCH_PATH}) Also fehlt die Biblothek Xtst. Diese muss ggf. nachinstalliert werden oder der Pfad dahin angegeben werden (s.o.). Anschließend rufen Sie cmake erneut auf.

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} )

Variables, macros and other useful information specific to KDE can be found at the Development/KDE and CMake Together 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.

Frequently Asked Questions

How can I teach my favorite editor about CMake syntax and indentation ?

Read the CMake Wiki section CMake Editors Support. It describes how to setup Emacs (XEmacs works too), VIM, Kate, KWrite, and KDevelop.

I need to generate some files during the build. How do I do this ?

Use ADD_CUSTOM_COMMAND(). It's explained here in the CMake wiki: How can I generate a source file during the build

I need to build an executable which is used later on during the build to generate files. How do I do this ?

Let's say the executable is called genembed. Then use KDE4_ADD_EXECUTABLE(foo RUN_UNINSTALLED ${fooSources})to create the executable. The RUN_UNINSTALLED option is important, because the executable has to run from the build dir and has to link to the libraries in the builddir. To achieve this, the executable is compiled with RPATH set accordingly and a wrapper shell script, named just like the executable but with the suffix ".sh" is created. This shell scripts sets up LD_LIBRARY_PATH and the calls the actual executable. Use this wrapper shell script in the ADD_CUSTOM_COMMAND() as described above. You can find out the name and exact location by querying the property WRAPPER_SCRIPT. Here's a full example taken from kdelibs/kstyles/keramik/ :

build the executable

KDE4_ADD_EXECUTABLE(genembed RUN_UNINSTALLED ${genembed_SRCS})

get the name of the generated wrapper script (which sets up LD_LIBRARY_PATH)

GET_TARGET_PROPERTY(GENEMBED_EXECUTABLE genembed WRAPPER_SCRIPT)

and the custom command

ADD_CUSTOM_COMMAND(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/keramikrc.h

 COMMAND ${GENEMBED_EXECUTABLE} --file ${CMAKE_CURRENT_BINARY_DIR}/keramikPics.txt > \
 ${CMAKE_CURRENT_BINARY_DIR}/pixmaps.keramik
 DEPENDS genembed ${keramikPics}

)

As you can see genembed is also listed as a dependency, this means cmake knows that it has to build the executable genembed before executing this rule.

Ich möchte statt der -DCMAKE_INSTALL_PREFIX Kommandozeilenoptionen lieber die KDEDIR Umgebungsvariable benutzen. Wird das von CMake unterstützt?

Nein. $KDEDIR ist in KDE4 veraltet.

Why do i get compile errors like /usr/lib/qt4/include/QtCore/qstring.h:536: undefined reference to `QString::fromLatin1_helper(char const*, int)'?

A: If you have an old Qt4 version in your qt/lib directory you must delete the old (4.0.1) files.

How do I tell cmake to create noisy makefiles? I want to see the exact commands that are run during the make process.

Pass the VERBOSE variable to make, i.e. % make VERBOSE=1 or % VERBOSE=1 make

For more details see the CMake wiki: Is there an option to produce more 'verbose' compiling?

There is no 'make distclean' target in the generated Makefiles. How do I clean up everything, including the cache files?

Simply remove the build directory, or just the contents of the build directory.