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

Revision as of 07:43, 27 February 2009

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

  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. 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.