Development/CMake KDE 4 2: Difference between revisions

    From KDE TechBase
    Line 41: Line 41:


    ===New: The reduced link interface===
    ===New: The reduced link interface===
    ===How to install libraries correctly now===
    If a project installs a library, and creates an exported target for it, which can be imported by other projects then, two things have to be done additionally:
    # Set the link interface
    # Export the target
    ====Setting the link interface====
    This defines against which libraries a package which links to this library will be linked additionally automatically. By default the link interface is empty. This is only the case for libraries created using KDE4_ADD_LIBRARY(), if a library is created using the standard ADD_LIBRARY() the link interface is "full" by default.
    Put those libraries in the link interface from which symbols are used in the public interface of your library. If e.g. a QWidget appears in your public headers, but nothing from zlib, put QT_QTGUI_LIBRARY in the link interface:
    <pre>
    kde4_add_library(kfoo ${kfooSrcs})
    target_link_libraries(kfoo ${ZLIB_LIBRARIES} ${QT_QTGUI_LIBRARY})
    target_link_libraries(kfoo LINK_INTERFACE ${QT_QTGUI_LIBRARY})
    </pre>


    ===Misc. new CMake features===
    ===Misc. new CMake features===

    Revision as of 00:05, 11 January 2009

    Changes in the buildsystem from KDE 4.0/4.1 to KDE 4.2

    Starting with KDE 4.0.0 source compatibility is guaranteed, this doesn't apply only to the C++ sources, but also to the CMake interface.

    Incompatible Changes

    1. The reduced link interface, details see below. It may be possible that an application which linked against KDE 4.0/4.1 now fails due to unresolved symbols. In this case the libraries which provide these symbols have to be added to the TARGET_LINK_LIBRARIES() calls. This happens only if symbols are used but the library is not linked again. This can be considered a bug in the cmake files of these applications. Applications which explicitely link against all libraries they use will build successfully with KDE 4.2.


    Other Changes

    Required CMake Version

    At least version 2.6.2 of CMake is required now. With KDE 4.0 and 4.1 version 2.4.5 was required.

    Removed option KDE4_ENABLE_EXPERIMENTAL_LIB_EXPORT

    The option KDE4_ENABLE_EXPERIMENTAL_LIB_EXPORT was new in KDE 4.1 and enabled the reduced link interface. This is now always the case, so the option became unnecessary.

    Removed option KDE4_USE_ALWAYS_FULL_RPATH

    KDE4_USE_ALWAYS_FULL_RPATH was by default on. In this case executables, libraries and plugins where linked with RPATH. This caused relinking of these binaries during make install, which takes some time. If it was off, only executables where linked with RPATH, and their RPATH had to be sufficient also for the shared libraries and plugins. This can be the case, but doesn't have to. Applications which were not marked as RUN_UNINSTALLED where built directly with their install RPATH. This saved a lot of time during make install but the resulting install might not get the correct libraries. Since version 2.6 CMake can now edit the RPATH inside binaries, which compared to relinking takes no time.

    That's why this option is not necessary anymore, and now all executables, libraries and plugins are always built with their build tree RPATH and then installed with their install tree RPATH, so they always get their correct libraries, both when executed from the build tree as well as when executed from the install tree.

    So, if you set this option somewhere, this is no problem with KDE 4.2, it now always does the right thing.

    New option KDE4_USE_COMMON_CMAKE_PACKAGE_CONFIG_DIR

    With KDE 4.2 and the required CMake 2.6.2 the FIND_PACKAGE() command now supports finding installed configuration files of packages. If the package is named <package>, their configuration file is named <package>Config.cmake. CMake 2.6.2 supports searching these files in lib/<package>/cmake/, a version number may also be included in the directory name: lib/<package>-x.y.z/cmake/. Starting with version 2.6.3 of CMake (soon to be released as of January 2009), it also supports searching these configuration files in lib/cmake/<package>/ (also with optional version number). This may be preferred by packagers. If a KDE package installs such a configuration file it should check this option, and if enabled install its <package>Config.cmake file to lib/cmake/<package>/ instead of lib/<package>/cmake/. More at http://www.cmake.org/Wiki/CMake_2.6_Notes#Packages .

    This option is only available with CMake >= 2.6.3, in this case it is ON by default. Otherwise it is OFF.

    If a package has been installed with this option enabled (which can only be the case with CMake >= 2.6.3), at least CMake 2.6.3 is also required for building packages which use this package. CMake < 2.6.3 will not find their installed <package>Config.cmake files.

    Currently only kdepimlibs/ and kdebase/workspace/ install such configuration files.

    New: Exporting and importing targets

    More details at http://www.cmake.org/Wiki/CMake_2.6_Notes#Exporting_and_Importing_Targets .

    New: The reduced link interface

    How to install libraries correctly now

    If a project installs a library, and creates an exported target for it, which can be imported by other projects then, two things have to be done additionally:

    1. Set the link interface
    2. Export the target

    Setting the link interface

    This defines against which libraries a package which links to this library will be linked additionally automatically. By default the link interface is empty. This is only the case for libraries created using KDE4_ADD_LIBRARY(), if a library is created using the standard ADD_LIBRARY() the link interface is "full" by default. Put those libraries in the link interface from which symbols are used in the public interface of your library. If e.g. a QWidget appears in your public headers, but nothing from zlib, put QT_QTGUI_LIBRARY in the link interface:

    kde4_add_library(kfoo ${kfooSrcs})
    target_link_libraries(kfoo ${ZLIB_LIBRARIES} ${QT_QTGUI_LIBRARY})
    target_link_libraries(kfoo LINK_INTERFACE ${QT_QTGUI_LIBRARY})
    

    Misc. new CMake features

    Finding installed packages

    Starting with CMake 2.6 the FIND_XXX() commands now search by default the respective subdirectories under the current CMAKE_INSTALL_PREFIX and the install prefix of CMake itself.

    Additionally now the environment variable CMAKE_PREFIX_PATH is supported. This is a list of directories which are searched by the FIND_XXX() commands with the respective subdirectories appended, i.e. include/ for FIND_PATH() and FIND_FILE(), lib/ for FIND_LIBRARY() and bin/ for FIND_PROGRAM(). These directories are searched before all other directories, so this can be used to make CMake find the versions of packages you want it to find.

    E.g. the following can be used to make CMake find required packages in the given directories instead of e.g. a Qt4 installed in /usr/lib :

    $ export CMAKE_PREFIX_PATH=/opt/qt-copy:/opt/kdesupport:/opt/kdelibs:/opt/kde4
    $ cmake args...
    

    Comparing version strings

    CMake now supports comparing version strings consisting of version 1 to 4 version components:

    • if(<str> VERSION_GREATER "1.2.3")
    • if(<str> VERSION_LESS "1.2.3")

    Functions

    CMake now has a FUNCTION() and an ENDFUNCTION() commands. They can be used similar to MACRO()/ENDMACRO(), but variables created (i.e. SET() ) inside them stay local. To modify a variable outside the function, e.g. as return value, do the following:

    function(foo)
       set(var1 "hello")
       set(var2 "world" PARENT_SCOPE)
    endfunction(foo)
    
    foo()
    message(STATUS "${var1} ${var2}")
    

    This will print only "world", since var1 is local to the function.

    Return()

    CMake now has a return(), which can be used to return from function()s and also from processed files. See the man page for details.

    cmake-gui

    cmake-gui is a Qt4 based GUI to CMake. It makes running CMake, setting options, checking results and selecting the generator easier.

    http://www.neundorf.net/pics/cmake-gui-kdelibs.png .

    CMake policies

    More details at http://www.cmake.org/Wiki/CMake_Policies .