Development/Tutorials/CMake (es)

Introducción

CMake lee los archivos de "script" y produce archivos de entrada para el sistema de construcción nativo de la plataforma en la que se ejecuta. Puede crear GNU Makefiles, archivos de projecto KDevelop, archivos de proyecto XCode y archivos de proyecto de Visual Studio.

CMake es software libre y lanzado bajo la licencia BSD. Es desarrollado por Kitware Inc.

Puedes encontrar más información relacionada a CMake en la página de CMake en esta misma TechBase.

¿Porqué usar CMake ?

CMake es la herramienta oficial de KDE 4, decidido en marzo del 2006, principalmente debido a los méritos técnicos en comparación con las anteriores herramientas utilizadas por KDE automake y unsermake:

• CMake se desarrolla de manera independiente de KDE, por lo que también es utilizado por otros proyectos.
• El tiempo de compilación es mucho más rápido, debido principalmente a que no utilizan libtool.
• Los archivos de creación son más fáciles de escribir.

Cómo compilar KDE usando CMake

Obtener e Instalar CMake

Linux, BSD y otros sistemas Unix

Obtener la última versión estable de CMake desde aquí.

Una vez descargado desempaquételo y compílelo:

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

Por defecto, se instala CMake en /usr/local, por defecto, se instalará CMake en /usr/local, así que asegúrese de que /usr/local/bin se encuentra en las rutas de ejecución. Para cambiar el prefijo de instalación (por ejemplo a /usr en debian), agregue la opción '--prefix=PATH' para el comando de arranque (bootstrap).

Por favor siga las instrucciones que se encuentran aquí si desea utilizar la versión en desarrollo.

Windows

Obtenga la última versión estable de CMake desde aquí.

Una vez descargado, ejecute el instalador de CMake.

Por defecto, se instalará en C:\Program Files\CMake 2.8, asegurese de que <installpath>\bin se encuentra en las rutas de ejecución.

Por favor siga las instrucciones que se encuentran aquí si desea utilizar la versión en desarrollo.

Ejecutar CMake

Linux, BSD y otros sistemas Unix

Ejecutar CMake para generar los archivos de construcción para su sistema. Son soportados las construcciones in-source y out-of-source, pero actualmente las in-source son evitadas por la implementación de KDE.

Por lo tanto, digamos que si se tiene kdelibs/ en ~/src/kdelibs/, entonces hacemos lo siguiente:

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

Esto generará los Makefiles para construir kdelibs/ en kdelibs-build/.

Windows

Ejecutar CMake para generar los archivos de construcción para su sistema. Son soportados las construcciones in-source y out-of-source, pero actualmente las in-source son evitadas por la implementación de KDE.

Por lo tanto, digamos que si se tiene kdelibs\ en c:\daten\kde4, entonces hacemos lo siguiente:

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

Esto generará los Makefiles para construir kdelibs\ en kdelibs-build\. Ver KDE en Windows para más información acerca de la compilación de KDE en Windows.

Archivos de Projecto de KDevelop 3

Si prefiere archivos de projecto para KDevelop 3 (son básicamente Makefiles con archivos extra para Kdevelop), ejecute algo como esto:

$ cmake ../kdelibs -GKDevelop3

Use 'cmake -h' para saber qué generadores soporta CMake y otras opciones.

CMake y Qt4

Para localizar Qt 4, CMake buscá a qmake en su ruta de ejecución. CMake no utiliza la variable de ambiente QTDIR. Así que asegurese de que qmake se encuentra en la ruta de ejecución que se desea utilizar.

Más Detalles

Cuando CMake ha finalizado, se crea un archivo llamado "CMakeCache.txt". Este archivo contiene todos los ajustes que CMake ha detectado en su sistema. Si desea ejecutar CMake con otro generador o si desea que CMake detecte todo de nuevo, borre este archivo.

Si CMake no encuentra algo, pero sabes que está en algún lugar, se le puede especificar manualmente a CMake dónde encontrarlo. CMake utiliza variables para almacenar esta información. Estas variables se almacenan en el archivo CMakeCache.txt ya mencionado. Hay tres opciones para ajustar estas variables de forma manual:

• Especificarle a CMake el valor correcto a través de la línea de comandos: cmake ../kdelibs -DNAME_OF_THE_VARIABLE=valor
• Usar ccmake, que proporciona una interfaz gráfica de usuario basada en 'curses' para ajustar las variables CMake (ejecutar: ccmake ../kdelibs)
• Editar el archivo directamente CMakeCache.txt (no recomendado)

Se debe ejecutar "ccmake ../kdelibs" al menos una vez para que usted obtenga una impresión de las variables que utiliza CMake. Pulse el botón "T" para ver las variables "avanzadas". Por lo tanto, si CMake no encuentra algo, ejecutar ccmake y ajustarlo de forma manual.

Variables de línea de Comandos

Algunas variables de linea de comandos para cmake que posiblemente quieras configurar:

• CMAKE_INSTALL_PREFIX: cmake ../kdelibs -DCMAKE_INSTALL_PREFIX=/opt/kde4 es el equivalente a ./configure --prefix=/opt/kde4
• CMAKE_BUILD_TYPE: decidir cual tipo de construcción a utilizar. Puedes escoger entre "DebugFull", "Debug", "Profile", "RelWithDebInfo" y "Release". Por defecto es "RelWithDebInfo". Consulte la página CMake Tipos de Construcción para una explicación más detallada.
• KDE4_BUILD_TESTS=ON: crear Makefiles con construccines de programas de prueba y también proporcionar objetivos de prueba
• KDE4_TEST_OUTPUT=xml: Pruebas unitarias usando el framework QTestLib que creará archivos de registro (logs) en formato xml.
• KDE4_DISABLE_MULTIMEDIA=ON: Construir KDE sin ningún soporte multimedia.
• BUILD_foo=OFF: desabilitar la construcción del projecto en el subdirectorio 'foo' .
• WITH_foo: hay varias opciones, por ejemplo WITH_CUPS o WITH_Jasper. Si está desactivada, cmake ni siquiera tratar de encontrar el paquete. Si está habilitada, cmake trata de encontrarlo. Si no lo consigue con esto, se puede ajustar de forma manual como se describió anteriormente.

Variables de Ambiente

Si tiene los 'headers' y las bibliotecas instaladas en ubicaciones no estándar que cmake no puede encontrar (por ejemplo, Fink en Mac OS X se instala en /sw), entonces rellene la CMAKE_PREFIX_PATH variable de entorno con una lista de rutas de acceso a esos lugares. Durante la búsqueda de headers, las bibliotecas y los archivos binarios, CMake buscará todos las rutas en CMAKE_PREFIX_PATH, así como en sus subdirectorios estándar ("lib" para las bibliotecas, "incluir" a los encabezados y los "bin" para los binarios). Esto también puede ser muy útil por ejemplo, si se instala a kdesupport en ~/install/kdesupport.

• CMAKE_PREFIX_PATH, ej. export CMAKE_PREFIX_PATH=/sw

Si es necesario ajustar aún más el comportamiento de búsqueda, tiene la posibilidad de establecer las siguientes variables de entorno con el fin de añadir una biblioteca, 'include' o directorio de binarios a la ruta de búsqueda:

• CMAKE_INCLUDE_PATH, eg. export CMAKE_PREFIX_PATH=/sw/include
• CMAKE_LIBRARY_PATH, eg. export CMAKE_LIBRARY_PATH=/sw/lib
• CMAKE_PROGRAM_PATH, eg. export CMAKE_PROGRAM_PATH=/sw/bin

Para más información en variables, ver la página de wiki de cmake.org

Profundizando

Si cmake termina con "Generating done" entonces no hubo errores, pero si se termina con "Configuring done" entonces hay errores que arreglar. Una vez que cmake termina correctamente, ejecute el buildtool (es decir, make, KDevelop, XCode o MSVC), construya y esperare hasta que haya terminado. Luego "make install".

Si tienes un fallo que dice algo así 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)

entonces puede hacer falta una biblioteca (u otra dependencia). Para saber en qué biblioteca, búsqueda en el cmake/modules por la variable que cmake no puede encontrar. En el ejemplo anterior, es

find_library(X11_XTest_LIB Xtst ${X11_LIB_SEARCH_PATH})

Por lo que la biblioteca que falta es Xtst. Entonces necesitas encontrarla (tal vez instalando una biblioteca libXtst-devel) y vuelva a ejecutar cmake.

Usando CMake para una aplicación simple

Aquí está el CMakeLists.txt más simple:

add_executable(hello main.cpp)

Esto creará un ejecutable llamado "hello" (o "hello.exe" en Windows) desde el archivo fuente el main.cpp. Usted puede mezclar los archivos C y C++ que quieras. Usted puede tener varios archivos ejecutables y bibliotecas en una CMakeLists.txt. El archivo de código fuente se puede utilizar con múltiples objetivos, se establecerán para cada objetivo independiente de los demás. Probablemente la parte más importante del lenguaje cmake son las variables:

set( MY_SOURCES main.cpp widget.cpp)
message(STATUS "my sources: ${MY_SOURCES}")

Por lo tanto, el uso de la SET() para establecer el valor de una variable. Si enlistas más de un 'string' (cadena), la variable será una lista. Una lista es una lista de strings separadas por punto y coma. Si se establece un solo ítem, solo tendrá ese valor. Para obtener el valor de una variable, use $ {VAR}. Se puede iterar sobre una lista usando FOREACH():

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

Los comandos en CMake son case-insensitive. Nombres de cariables y parámetros son case-sensitive. También puedes probar varias cosas:

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)

En este segundo ejemplo se puede ver también como añadir elementos a una lista. En el Wiki cmake también hay un tutorial sobre el uso de cmake para compilar KDE 4 software. Se recomienda leerlo.

Usando CMake para un Projecto KDE

Aquí hay un archivo CMakeList básico que construye un pequeño proyecto KDE 4:

project( kde4project )
find_package( KDE4 REQUIRED )
include(KDE4Defaults)

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" contiene las bibliotecas de desarrollo que están vinculados a su programa. Por ejemplo si desea crear un vínculo a libtidy-devel, el nombre del archivo biblioteca puede ser llamado /usr/local/lib/libtidy.a. A continuación, se añade -ltidy a una llamada de gcc. En este caso, se agrega "tidy" al target_link_libraries. Si es posible, utilizar variables predefinidas o macros como ${KDE4_KDEUI_LIBS}.

instalar (TARGETS es donde el objetivo será finalmente instalado. Si no tienes esta línea, make install no estará disponible.

Variables, macros y otros datos útiles específicos para KDE se puede encontrar en la página CMake addons para KDE.

Extendiendo CMake

CMake se puede extender usando cmake scripts. CMake viene con una serie de scripts, bajo UNIX son instalados por defecto en /usr/local/share/CMake/Modules/. Las bibliotecas de KDE también instalan un conjunto de módulos cmake en share/apps/cmake/modules/. Los archivos que se encuentran allí serán preferibles a los que están en la ruta global del sistema del módulo de cmake. Para la detección de paquetes de software hay archivos FindFOO.cmake, ver aquí para más información. También puede escribir macros en CMake. Son lo suficientemente poderosos para hacer la mayoría de cosas que se necesitan para construir software, pero no están destinados a ser utilizados como un lenguaje de programación de propósito general.

Convirtiendo software KDE basado en autotools a CMake

En kdesdk/cmake/ se encuentra un script am2cmake. Es un script en ruby, por lo que ruby necesita estar instalado. Run am2cmake en el nivel superior del directorio de los archivos fuentes (sources):

$ cd src/mykooltool/
$ am2cmake --kde4

No te olvides de cambiar el --kde4, de lo contrario no va a generar los archivos adecuados para KDE 4 software. Los archivos convertidos "puede" trabajar como lo son, pero los proyectos complicados requerirá algunas modificaciones adicionales.

Puede que tenga que:

• Agregar más directorios de "include", utilizando INCLUDE_DIRECTORIES()
• Agregar más librerías de enlace, utilizando TARGET_LINK_LIBRARIES()
• Añadir algunos conmutadores de compilación utilizando ADD_DEFINITIONS()
• Añadir algunos controles de "configuración", ver Cómo hacer Controles de Plataforma y Cómo encontrar el software instalado
• Tenga especial cuidado de las antiguas conveniencias de bibliotecas libtool. Ellos no son compatibles con cmake, en vez habrá un archivo ConvenienceLibs.cmake creado. En este archivo encontrará para cada conveniencia lib una variable, que contiene todos los archivos fuente de esta conveniencia lib. Para los objetivos(targets) que enlazaban a esta conveniencia lib, sólo tiene que añadir la variable a las fuentes.
• Un archivo AdditionalInfo.txt se creará. Allí usted podrá ver todos los archivos *.in y *. in.in de su proyecto. Las cosas realizadas en estos archivos se tienen que convertir manualmente a cmake.