Development/Tutorials/CMake (pt BR)

Development/Tutorials/CMake

Introdução

O CMake lê arquivos de script e produz arquivos de entrada para o sistema de compilação nativo da plataforma que ele roda. Ele pode criar GNU Makefiles, arquivos de projeto do KDevelop, arquivos de projeto do XCode e arquivos de projeto do Visual Studio.

O CMake é software livre e liberado sob a licença BSD. É desenvolvido pela Kitware Inc.

Você pode encontrar mais informação relacionada ao CMake na página principal do CMake aqui no TechBase.

Por que usar CMake?

CMake é a ferramenta oficial do KDE 4, decidida em Março de 2006, primeiramente graças aos seus méritos técnicos quando comparada com automake e unsermake, as antigas ferramentas do KDE:

CMake é desenvolvido independentemente do KDE, e pode ser usado por outros projetos, portanto.
O tempo de compilação é muito menor, principalmente por não usar mais o libtool
É mais fácil escrever arquivos de compilação

Como compilar o KDE usando CMake

Baixe e instale o CMake

Linux, BSD e outros sistemas Unix-like

Baixe a última versão estável do CMake em [1].

Depois de baixar, descompacte e compile: $ mkdir cmake-build $ cd cmake-build $ ../bootstrap $ make $ make install

Por padrão, isso instalará o CMake em /usr/local, então tenha certeza de pôr /usr/local/bin no seu path de execução. Para mudar o prefixo de instalação (para /usr no Debian, por exemplo), adicione a opção '--prefix=PATH' à linha de comando.

Siga as instruções que se encontram aqui se quiser usar a versão de desenvolvimento.

Windows

Baixe a última versão estável do CMake em [2].

Depois de baixar, execute o instalador do CMake.

Por padrão, ele instalará o CMake em C:\Program Files\CMake 2.4, então tenha certeza de ter <installpath>\bin no seu path de execução.

Siga as instruções que se encontram aqui se quiser usar a versão de desenvolvimento.

Executar o CMake

Linux, BSD e outros sistemas Unix-like

Você tem que rodar o CMake para que ele gere os arquivos para seu sistema. Tanto compilações dentro dos códigos fontes (in-source builds) quando fora deles (out-of-source builds) são suportadas pelo CMake, mas in-source builds são prevenidos pela implementação atual do KDE.

Supondo que você tenha o diretório kdelibs/ em ~/src/kdelibs/, faça o seguinte: $ ls kdelibs/ $ mkdir kdelibs-build $ cd kdelibs-build $ cmake ../kdelibs Isso gerará os Makefiles para compilar kdelibs/ em kdelibs-build/.

Windows

Você tem que rodar o CMake para que ele gere os arquivos para seu sistema. Tanto compilações dentro dos códigos fontes (in-source builds) quando fora deles (out-of-source builds) são suportadas pelo CMake, mas in-source builds são prevenidos pela implementação atual do KDE.

Supondo que você tenha o diretório kdelibs\ em c:\daten\kde4, faça o seguinte: 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

Isso gerará os Makefiles para compilar kdelibs\ em kdelibs-build\. Veja KDE no Windows para mais informações sobre como compilar o KDE no Windows.

Arquivos de projeto do KDevelop 3

Se você prefere arquivos de projeto para o KDevelop 3 (que serão basicamente Makefiles acompanhados de alguns arquivos extra para o KDevelop), rode-o desta forma: $ cmake ../kdelibs -GKDevelop3 Use 'cmake -h' para descobrir que geradores o CMake suporta e outras opções.

CMake e Qt4

Para localizar o Qt 4, o CMake procura por qmake no seu path de execução. CMake não usa a variável de ambiente QTDIR. Então esteja certo que o primeiro qmake encontrado no path de execução é o que você deve usar.

Mais detalhes

Quando CMake finalizar, ele terá criado um arquivo chamado "CMakeCache.txt". Esse arquivo contem todas as configurações que o CMake detectou em seu sistema. Se você quiser executar o CMake com outro gerador ou se você quer que o CMake detecte tudo novamente, exclua esse arquivo.

Se o CMake não encontrar alguma coisa, mas você sabe que está em algum lugar, você pode dizer manualmente ao CMake onde encontrá-la. O CMake usa variáveis para guardar essas informações. Essas variáveis são armazenadas no já mencionado arquivo CMakeCache.txt. Você tem três opções para ajustá-las manualmente:

informe ao CMake o valor correto pela linha de comando: cmake ../kdelibs -DNOME_DA_VARIAVEL=valor
use ccmake, que provê uma GUI baseada em curses para ajustar as variáveis do CMake (rode: ccmake ../kdelibs)
modifique CMakeCache.txt diretamente (não recomendado)

Você deve rodar "ccmake ../kdelibs" ao menos uma vez para que você tenha uma ideia de que variáveis o CMake usa. Pressione "T" para ver também as variáveis "avançadas". Então, se o CMake não encontrar alguma coisa, inicie ccmake e ajuste-o manualmente.

Variáveis de linha de comando

Algumas variáveis de linha de comando do CMake que você deve querer configurar:

CMAKE_INSTALL_PREFIX: cmake ../kdelibs -DCMAKE_INSTALL_PREFIX=/opt/kde4 é equivalente a ./configure --prefix=/opt/kde4
CMAKE_BUILD_TYPE: decide que tipo de compilação você quer. Você pode escolher entre "debugfull", "debug", "profile", "relwithdebinfo" e "release". O padrão é "relwithdebinfo". Vá à página Tipos de compilação do CMake para uma explicação mais detalhada.
KDE4_BUILD_TESTS=ON: cria Makefiles com programas de teste de compilação e provê alvos 'test'.
KDE4_TEST_OUTPUT=xml: Testes unitários usando o framework QTestLib criará arquivos de log formatados em xml.
KDE4_DISABLE_MULTIMEDIA=ON: Compila o KDE sem nenhum suporte a multimídia (áudio e vídeo).
BUILD_foo=OFF: desativa a compilação para o prjeto no subdiretório 'foo'.
WITH_foo: há várias opções - por exemplo, WITH_CUPS ou WITH_Jasper. Se você desativá-las, o CMake não irá nem mesmo tentar procurar por esse pacote. Se estiver ativado, o CMake tentará encontrá-lo. Se falhar com isso, você pode ajustar manualmente, como descrito acima.

Variáveis de ambiente

Se você tem cabeçalhos e bibliotecas instalados em localizações fora do padrão que o CMake não pode encontrar, então configure as seguintes variáveis de ambiente. Isso pode ser bastante útil se, por exemplo você instalar kdesupport em ~/install/kdesupport . Apesar da nomeação similar, essas variáveis não funcionam se passadas por linha de comando:

CMAKE_INCLUDE_PATH, por exemplo, export CMAKE_INCLUDE_PATH=/sw/include
CMAKE_LIBRARY_PATH, por exemplo, export CMAKE_LIBRARY_PATH=/sw/lib
CMAKE_PROGRAM_PATH, por exemplo, export CMAKE_PROGRAM_PATH=/sw/bin

A partir do CMake 2.6.0, o mesmo efeito das variáveis acima pode ser atingido com apenas um comando:

CMAKE_PREFIX_PATH, por exemplo, export CMAKE_PREFIX_PATH=/sw

Para mais informações sobre variáveis, veja esta página do wiki cmake.org

Indo além

Se o CMake finalizar com "Generating done", não houve erros. Mas, se finalizar com "Configuring done", então há erros para você consertar. Se o CMake finalizar com sucesso, rode sua ferramenta de compilação (por exemplo: make, KDevelop, XCode ou MSVC), compile e espere que a compilação termine. Então rode "make install" como root.

Se houve uma falha que diz algo como: 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) então está faltando uma biblioteca (ou outra dependência). Para descobrir qual biblioteca é, procure no diretório pela variável que o CMake não pôde encontrar no diretório cmake/modules. No exemplo acima, ela é find_library(X11_XTest_LIB Xtst ${X11_LIB_SEARCH_PATH}) Logo, a biblioteca que está faltando é Xtst. Então você deve encontrá-la (provavelmente instalando libXtst-devel) e rodar cmake novamente.

Usando o CMake para uma aplicação simples

Aqui está o CMakeLists.txt mais simples possível: add_executable(hello main.cpp) Isso criará um executável chamado "hello" (ou "hello.exe" no Windows) do arquivo de código fonte main.cpp. Você pode misturar arquivos C e C++ se você quiser. Você pode ter múltiplos executáveis e bibliotecas num CMakeLists.txt. O mesmo arquivo de código fonte pode ser usado em vários alvos: ele será compilado para cada um, independentemente dos outros. Provavelmente, a parte mais importante da linguagem CMake são as variáveis: set( MEUS_FONTES main.cpp widget.cpp) message(STATUS "meus fontes: ${MEUS_FONTES}") Então, use o comando SET() para definir o valor de uma variável. Se você listar mais de uma string, a variável será uma lista. 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.