Difference between revisions of "Development/Tutorials/CMake (pt BR)"

Revision as of 21:50, 29 June 2011

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( MY_SOURCES main.cpp widget.cpp)
message(STATUS "my sources: ${MY_SOURCES}")

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. Uma lista é uma lista de strings separada por pontos-e-vírgulas. Se você definí-la para apenas um item, ela terá apenas um valor. Para pegar o valor da variável, use ${VAR}. Você pode realizar iterações na lista usando FOREACH():

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

Os comandos do CMake são sensíveis à caixa, assim como nomes de variáveis de de parâmetros.

Você também pode testar várias coisas:

if (UNIX)
   message(STATUS "Isto é UNIX (incluindo OS X e CygWin)")
endif (UNIX)
 
if (MSVC)
   set(MY_SRCS ${MY_SRCS} winextra.cpp)
endif (MSVC)

Neste segundo exemplo você pode ver também como anexar ítens a uma lista.

Na Wiki do CMake também há um tutorial (em inglês) sobre como usar o CMake para compilar software para o KDE 4. É uma leitura recomendada.

Usando o CMake para um projeto KDE

A seguir, uma CMakeList básica que compila um projeto KDE 4 pequeno:

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 contém as bibliotecas de desenvolvimento que estão ligadas ao seu programa. Por exemplo, se você quiser ligar a libtidy-devel, o nome do arquivo da sua biblioteca deve ser /usr/local/lib/libtidy.a. Você deve, então, adicionar -ltidy numa chamada do gcc. Aqui, você adicona tidy ao seu target_link_libraries. Se possível, use variáveis pré-definidas ou macros como ${KDE4_KDEUI_LIBS}.

install (TARGETS é onde o alvo será instalado. Se você não tiver essa linha, make install não funcionará.

Variáveis, macros e outras informações úteis específicas do KDE podem ser encontradas na página addons do CMake para o KDE.

Estendendo o CMake

O CMake pode ser estendido usando scripts cmake. O CMake vem com uma certa quantidade de scripts; no UNIX, eles são instalados por padrão em /usr/local/share/CMake/Modules/. As bibliotecas do KDE também instalam um conjunto de módulos cmake em share/apps/cmake/modules/. Os arquivos que estão ali serão preferidos em vez dos que estão no path global do sistema de módulos cmake. Para detectar pacotes de software que são arquivos FindFOO.cmake, veja aqui para mais informações. Você também pode escrever macros em CMake. Elas são poderosas o suficiente para fazer a maior parte das coisas que você precisará para compilar software, mas elas não são destinadas a serem usadas como uma linguagem de programação de propósito geral.

Convertendo software do KDE baseado em autotools em CMake

Em kdesdk/cmake/ você pode encontrar um script chamado am2cmake. É um script em ruby, logo, você precisa do ruby instalado. Rode am2cmake no diretório de maior nível dos seus fontes:

$ cd src/mykooltool/
$ am2cmake --kde4

Não esqueça de pôr "--kde4", senão ele não gerará arquivos adequados para software KDE 4. Os arquivos convertidos devem funcionar como estão, mas projetos complexos podem precisar de edição adicionar.

Você pode precisar:

• adicionar mais diretórios de includes, usando INCLUDE_DIRECTORIES()
• adicionar mais bibliotecas que serão ligadas, usando TARGET_LINK_LIBRARIES()
• adicionar algumas definições de compilação, usando ADD_DEFINITIONS()
• adicionar algumas checagens de configuração (veja como fazer checagens de plataforma e como encontrar software instalado)
• tomar cuidados especiais bibliotecas de conveniência antigas do libtool. Elas não são suportadas pelo CMake. Em vez delas, haverá um arquivo ConvenienceLibs.cmake criado. Nesse arquivo você encontrará uma variável para cada biblioteca de conveniência, que contém todos os fontes dessa biblioteca de conveniência. Para os alvos que estão ligados a esta biblioteca de conveniência, simplesmente adicione a variável aos fontes.
• Um arquivo AdditionalInfo.txt será criado. Lá você verá todos os arquivos *.in e *.in.in do seu projeto. As coisas feitas nesses arquivos terão de ser manualmente convertidas para CMake.