Development/Tutorials/CMake (fi)

Development/Tutorials/CMake

Esipuhe

CMake tuottaa ohjaustiedostot järjestelmän omalle kääntäjälle omien komentotiedostojensa avulla. Se voi luoda GNU Makefilet, KDevelop-projektitiedostot, XCode-projektitiedostot, sekä Visual Studio-projektitiedostot.

CMake on vapaan lähdekoodin ohjelmisto joka on julkaistu BSD-tyylisen lisenssin alaisena. CMaken ylläpitäjä on Kitware Inc.

Näistä voit aloittaa CMaken perusteiden opiskelun (englanniksi):

Voit myös liittyä CMake postituslistalle.

Miksi käyttää CMakea ?

Maaliskuussa 2006 päätettiin valita CMake KDE 4 julkaisun viralliseksi työkaluksi, pääsääntöisesti sen teknisten ominaisuuksien vuoksi verrattuna vankempiin KDE työkaluihin kuten automake ja unsermake:

CMake on kehitetty KDE:stä riippumattomana, ja sitä voidaan käyttää myös muissa projekteissa
Käännösajat jäävät paljon pienemmiksi, pääosin koska libtoolia ei enää tarvita
Käännöstiedostot ovat helpompia kirjoittaa

KDE:n kääntäminen CMakea käyttäen

Lataa ja asenna CMake

Linux, BSD, sekä muut Unix Järjestelmät

Hae viimeisin vakaa versio CMakesta täältä.

Pura ja käännä:

$ mkdir cmake-build $ cd cmake-build $ ../bootstrap $ make $ make install

Oletuksena ylläoleva asentaa CMaken /usr/local, joten varmista että /usr/local/bin on määritelty polussa. Vaihtaaksesi asennushakemistoa (esim. /usr debianissa), lisää '--prefix=PATH' valitsin bootstrap komentoon. (Esim: $ ../bootstrap --prefix=/usr)

Jos haluat asentaa viimeisimmän kehitysversion, seuraa ohjeita täältä.

Windows

Hae viimeisin vakaa versio CMakesta täältä.

Ladattuasi, suorita cmake asennusohjelma.

Oletuksena CMake asennetaan C:\Program Files\CMake 2.4 - hakemistoon. Varmista että C:\Program Files\CMake 2.4\bin löytyy polkumuuttujasta.

Jos haluat asentaa viimeisimmän kehitysversion, seuraa ohjeita täältä.

CMaken käyttäminen

Linux, BSD, sekä muut Unix Järjestelmät

Luodaksesi järjestelmällesi käännöstiedostot(Makefile) tarvitsee sinun ajaa CMake. Molemmat, lähdekoodin seassa sekä lähdekoodin ulkopuolella käännökset, ovat CMaken puolelta tuettuja, mutta tällä hetkellä lähdekoodin seassa kääntäminen on estetty KDE:n toteutuksessa.

Esikerkiksi, jos kdelibs/ sijaitsee ~/src hakemistossa niin kääntäminen menee seuraavasti:

$ ls kdelibs/ $ mkdir kdelibs-build $ cd kdelibs-build $ cmake ../kdelibs

Ylläoleva tuottaa Makefilet kdelibs/ tiedostojen kääntämiseksi kdelibs-build/ hakemistoon.

Windows

Esikerkiksi, jos kdelibs/ sijaitsee c:\data\kde4 hakemistossa niin kääntäminen menee seuraavasti:

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

Ylläoleva tuottaa Makefilet kdelibs/ tiedostojen kääntämiseksi kdelibs-build/ hakemistoon. Lisätietoja KDE:n kääntämisestä Windows ympäristössä löytyy täältä.

KDevelop Project Files

Jos haluat luoda projektitiedostot KDevelopille(Makefile tiedostot sekä muutamia Kdevelopin vaatimia lisätiedostoja), suorita CMake seuraavasti:

$ cmake ../kdelibs -GKDevelop3

'cmake -h' näyttää muut CMakessa tuetut valitsimet.

CMake ja Qt4

Paikallistaakseen QT 4 kirjaston, CMake etsii qmakea polusta. CMake ei hyödynnä QTDIR ympäristömuuttujaa, joten varmista että oikea qmake löytyy ensimmäisenä polkumuuttujasta.

Lisää yksityiskohtia

Kun CMaken suoritus on valmis, on CMake luonut tiedoston nimeltä "CMakeCache.txt". Tämä tiedosto sisältää kaikki asetukset jotka CMake on tunnistanut järjestelmästäsi. Jos haluat suorittaa CMaken tuottaaksesi käännöstiedostot toiseen käännösympäristöön, tai haluat että asetukset tutkitaan uudelleen, poista tämä tiedosto.

Jos CMake ei löydä jotain, mutta olet varma että se on järjestelmässäsi, on mahdollista käsin kertoa CMakelle mistä etsiä. CMake käyttää apunaan muuttujia johon tämä tieto tallennetaan. Muuttujat on varastoitu "CMakeCache.txt" tiedostoon. Muuttujien määrittelemiseksi käsin on kolme vaihtoehtoa:

Komentoriviltä: cmake ../kdelibs -DMUUTTUJAN_NIMI=arvo
Merkkipohjainen ccmake käyttöliittymä (suorita: ccmake ../kdelibs)
Muokkaamalla CMakeCache.txt tiedostoa (ei suositeltava)

Kannattaa suorittaa "ccmake ../kdelibs" ainakin kerran jotta saat kokonaiskuvan kaikista niistä muuttujista jota CMake käyttää. Ohjelmassa, paina "T", nähdäksesi myös laajennetut muuttujat. Joten, jos CMake ei löydä jotain, käynnistä ccmake ja aseta se käsin.

Komentorivi Muuttujat

Muutamia cmake:n komentorivillä annettavia muuttujia joita saatat haluta muuttaa:

CMAKE_INSTALL_PREFIX: cmake ../kdelibs -DCMAKE_INSTALL_PREFIX=/opt/kde4 on vastaava ./configure --prefix=/opt/kde4
CMAKE_BUILD_TYPE: määrittelee käännöstyypin. Vaihtoehdot: "debugfull", "debug", "profile", "relwithdebinfo" ja "release". Oletuksena "relwithdebinfo" (-O2 -g). Katso lisätietoja: FindKDE4Internal.
KDE4_BUILD_TESTS=ON: Luo Makefilet testiohjelmien kanssa jotka myös tuottavat testi käännökset
KDE4_TEST_OUTPUT=xml: Luo yksikkötesteistä xml muotoiset lokitiedostot QTestLib:ä käyttäen.
KDE4_DISABLE_MULTIMEDIA=ON: Kääntää KDE:n ilman multimedia(ääni ja video) tukea.
RPATH_STYLE: Ei enään valittavissa. Oletuksena kaikki käännetään oikein asetetun RPATH:n kanssa. Jos et halua käyttää lainkaan RPATH:a, aseta CMAKE_SKIP_RPATH=TRUE.
BUILD_foo=OFF: Jättää 'foo' hakemiston kääntämättä.
WITH_foo: Tähän on useita vaihtoehtoja, esim: WITH_CUPS tai WITH_Jasper. Jos poissuljet(=OFF), cmake ei edes yritä etsiä näitä. Jos on valittu, cmake yrittää etsiä näitä. Jos haku epäonnistuu, voit silti määritellä sijainnin käsin kute aikaisemmin neuvottiin.

Ympäristömuuttujat

Jos sinulla on otsikkotiedostoja tai kirjastoja asennettuna epätavallisiin hakemistoihin, joista cmake ei niitä löydä, pitää asettaa seuraavat ympäristömuuttujat. Huolimatta samankaltaisesta nimeämistyylistä, näitä ei voi antaa cmakelle komentoriviltä.

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

Lisätietoja muuttujista, katso cmake.org wiki sivu.

Seuraavaksi

Jos cmake:n suoritus päättyy ilmoitukseen "Generating done", ei virheitä ilmentynyt. Nyt voit suorittaa käännöksen normaaliin tapaan(make, KDevelop, XCode tai MSVC). Käännöksen jälkeen asennus normaalisti esim "make install"

Jos suoritus päättyy ilmoitukseen "Configuring done", on ilmennyt joitain virheitä jotka pitää selvittää.

Jos sait virheilmoituksen jossa kerrotaan jotain seuraavaa 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)

, niin luultavammin jokin kirjastoa (tai muuta riippuvuutta) ei löytynyt. Selvittääksesi mikä kirjasto on kyseessä, etsi cmake/modules hakemistosta muuttujaa jota cmake ei löyänyt. Tässä esimerkissä se on

FIND_LIBRARY(X11_XTest_LIB Xtst ${X11_LIB_SEARCH_PATH})

Joten puuttuva tai epänormaaliin sijaintiin asennettu kirjasto on Xtst. Kirjaston asentamisen jälkeen suorita uudelleen cmake.

CMaken käyttö yksinkertaisessa sovelluksessa

Yksinkertsin toimiva CMakeLists.txt:

add_executable(hello main.cpp)

Tämä tuottaa main.cpp lähdekooditiedostosta suoritettavan ohjelman nimeltä "hello" (tai "hello.exe" Windowsissa). Voit käyttää samanaikaisesti sekä C attä C++ tiedostoja. Voit sijoittaa useampia suoritettavia binäärejä tai kirjastoja samaan CMakeLists.txt tiedostoon. Samaa lähdekooditiedostoa voidaan käyttää useamman binäärin kääntämiseen ja se käännetään jokaista binääriä kohden erikseen riippumatta muista binääreistä. Luultavammin tärkein osa cmaken komentokielessä ovat muuttujat:

SET( MY_SOURCES main.cpp widget.cpp) MESSAGE(STATUS "my sources: ${MY_SOURCES}")

SET() komennolla voit asettaa muuttujalle arvon. Jos asetat arvoksi useamman merkkijonon, muutujan tyypiksi tulee lista. Lista on puolipisteillä eroteltu merkkijonojen luettelo. Saadaksesi muuttujan arvon käytä $(MUUTTUJA). Listan voit iteroida seuraavasti: FOREACH():

FOREACH(next_ITEM ${MY_SOURCES})

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

ENDFOREACH(next_ITEM ${MY_SOURCES})

CMaken komennoissa, muuttujien nimissä ja muuttujien parametreissä on huomioitava kirjainkoko. (a != A)

Voit myös testata asioita:

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)

Jälkimmäisessä esimerkissä näytetään myös miten lisätä listaan merkkijono.

Suositeltavana lukemisena on cmake Wikissä perehdytys "Kuinka käännän KDE 4 ohjelmistoja".

CMaken käyttö KDE Projektissa

Seuraavana on perus CMakeList tiedosto jonlla voi kääntää KDE 4 projektin:

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

Muuttujat, makrot ja muuta KDE:ä koskevaa hyödyllistä tietoa löytyy Development/KDE and CMake Together - sivulta.

CMaken Laajentaminen

CMakea voi laajentaa käyttämällä cmake komentojonoja. CMaken mukana tulee useita valmiita komentojonoja. UNIX pohjaisissa järjestelmissä ne on asennettuna oletuksena /usr/local/share/CMake/Modules hakemistoon(riippuen CMaken asennushakemistosta). KDE kirjastot asentavat myös joukon cmake laajennuksia share/apps/cmake/modules/ hakemistoon. KDE:n hakemistossa sijaitsevat laajennukset ohittavat järjestelmänlaajuiset cmaken laajennukset. Ohjelmapakettien etsimistä varten täällä on FindFOO.cmake tiedostot, katso lisätietoja täältä. CMaken kanssa on myös mahdollista käyttää makroja, jotka ovat käyttökelpoisia useimpiin tilanteisiin joita ohjemien kääntämisessä tarvitaan.

autotools-pohjaisen KDE ohjelmiston kääntäminen CMakelle

Hakemistossa kdesdk/cmake/ on tiedosto nimeltään am2cmake. am2cmakea on ruby tiedosto, joten ruby tulee olla asennettu. Suorita am2cmake lähdekoodin päähakemistossa:

$ cd src/mykooltool/ $ am2cmake --kde4

Älä unohda "--kde4" - valitsinta, muuten am2cmake ei tuota KDE 4 ohjelmistoille sopivia tiedostoja. Käännetyt tiedostot 'voivat' toimia sellaisenaan kääntämisen jälkeen, mutta monimutkaisemmat projektit yleensä vaativat lisämuokkauksia.

Saatat joutua:

lisäämään sisällytettävia hakemistoja, käyttäen INCLUDE_DIRECTORIES()
lisäämään linkkejä kirjastoihin, käyttäen TARGET_LINK_LIBRARIES()
lisäämään joitain määrittelyjä kääntäjälle, käyttäen ADD_DEFINITIONS()
lisäämään tarkistuksia. Katso [Kuinka Tehdä Ympäristö Tarkistuksia sekä Kuinka Löytää Asennettuja Ohjelmia
huolehtimaan libtool-yhteensopivista kirjastoista. Ne eivät ole tuettuina cmakessa, sen sijaan on ConvenienceLibs.cmake. Tästä tiedostosta löydät jokaiselle yhteensopivuus kirjastolle muuttujan, joka sisältää kaikki kyseisen yhteensopivuustiedoston lähteet.
am2cmake luo tiedoston nimeltä AdditionalInfo.txt. Tässä tiedostossa on lueteltu kaikki *.in ja *.in.in tiedostot kyseisestä projektista. Näissä tiedostoissa olevat asiat pitää kääntää käsin CMakelle.

Usein Kysyttyjä Kysymyksiä

Kuinka voin opettaa käyttämälleni tekstieditorille CMaken syntaksin ja sisennykset ?

Katso CMake Winkin osiossa CMake Editors Support on ohjeet Emacs (myös XEmacs), VIM, Kate, KWrite, sekä KDevelop editoreille.

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.

I don't want to set the -DCMAKE_INSTALL_PREFIX command line option. Does cmake support the KDEDIR environment variable?

No. $KDEDIR is deprecated in KDE 4.

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.