Rendre une bibliothèque "consommable"

L'utilisation de la bibliothèque par un projet indépendant (sans que le projet bibliothèque soit englobé dans l'autre projet) nécessite une préparation. Il faut créer un fichier <packageName>Config.cmake :

  • <packageName> est le nom sous lequel la bibliothèque sera cherchée par le projet consommateur. En général, on choisit le nom du projet bibliothèque.
  • Le fichier contient les propriétés d'interface de la bibliothèque.

Création du fichier config, cas sans dépendances, sans installation

Dans le cas simple où la bibliothèque ne dépend pas elle-même d'autres bibliothèques, et où on ne veut pas installer la bibliothèque (voir plus loin pour la notion d'installation), le fichier peut être créé par la commande suivante, à ajouter dans CMakeLists.txt :

export(TARGETS <cible bibliothèque> FILE ${PROJECT_NAME}Config.cmake)

Création du fichier config, cas avec dépendances, sans installation

Si la bibliothèque A dépend elle-même d'autres bibliothèques, le fichier AConfig.cmake doit vérifier la disponibilité de ces bibliothèques.

Ajouter la commande dans CMakeLists.txt :

export(TARGETS A FILE ${PROJECT_NAME}Targets.cmake)

Noter la différence avec :

FILE ${PROJECT_NAME}Config.cmake

qui crée directement le fichier ${PROJECT_NAME}Config.cmake dans le cas sans dépendances. Ici, nous allons inclure ${PROJECT_NAME}Targets.cmake dans ${PROJECT_NAME}Config.cmake.

Créer manuellement un fichier AConfig.cmake.in avec le contenu :

include(CMakeFindDependencyMacro)
find_dependency(B)
find_dependency(C)
...
include(${CMAKE_CURRENT_LIST_DIR}/@PROJECT_NAME@Targets.cmake)

Ajouter dans CMakeLists.txt la commande :

configure_file(${PROJECT_NAME}Config.cmake.in ${PROJECT_NAME}Config.cmake @ONLY)

qui copie le fichier dans le répertoire de compilation en remplaçant les chaînes de caractères entre @.

Utilisation d'une bibliothèque extérieure au projet

Ajouter dans CMakeLists.txt du projet utilisateur :

find_package(<PackageName> CONFIG REQUIRED)

À l'exécution de cmake ou cmake-gui, si la bibliothèque utilisée n'est pas trouvée automatiquement, donner le chemin du répertoire parent de son répertoire de compilation avec la variable de cache CMAKE_PREFIX_PATH. Nota bene :

  • Lui donner le type PATH.

  • CMAKE_PREFIX_PATH est interprété comme une liste : vous pouvez donner plusieurs chemins (en général pour plusieurs bibliothèques) séparés par des points-virgules.

  • Donner des chemins absolus.

Manipulation 25

  • Compiler NR_util et Jumble avec deux projets indépendants. À la configuration de Jumble, utilisez NR_util que vous venez de compiler et non la version installée dans ~/.local.
  • Préparer aussi la consommation de Jumble même si vous ne l'utilisez pas tout de suite.

Namespace

Conseil : ajouter une option NAMESPACE à la commande export :

export(TARGETS <cible> NAMESPACE <namespace> FILE ${PROJECT_NAME}....cmake)

L'effet est de préfixer le nom de la cible avec namespace dans ${PROJECT_NAME}....cmake. Les projets consommateurs devront faire référence à la cible préfixée avec namespace.

Terminer namespace par ::. Typiquement, on choisit pour namespace : ${PROJECT_NAME}::.

Namespace : exemple

Dans le CMakeLists.txt de NR_util :

export(TARGETS nr_util NAMESPACE ${PROJECT_NAME}:: FILE ${PROJECT_NAME}Config.cmake)

et dans le CMakeLists.txt d'un projet consommateur de NR_util :

find_package(NR_util CONFIG REQUIRED)
target_link_libraries(Jumble PRIVATE NR_util::nr_util)

Intérêts de namespace

Intérêt principal : si un nom contient :: alors CMake le traite comme le nom d'une cible importée (typiquement avec find_package) ou d'un alias (cf. plus loin). Si find_package a été oublié ou s'il y a une faute de frappe dans le nom, une erreur est signalée à la génération. Si le nom ne contient pas ::, CMake admet la possibilité que ce soit le nom d'une bibliothèque à trouver dans les répertoires du système, au moment de la compilation.

Exemple :

target_link_libraries(Jumble PRIVATE nr_util)

et on a oublié find_package. CMake ajoute juste -lnr_util dans les options d'édition de liens et l'erreur n'apparaîtra qu'à la compilation.

Autre exemple, on n'a pas oublié find_package mais on a une faute de frappe dans le nom de la cible consommée :

target_link_libraries(Jumble PRIVATE NR_util)

Là encore, l'erreur n'apparaîtra qu'à la compilation.

Intérêt secondaire de namespace : éviter une collision entre cibles consommées de noms identiques, venant de différents projets.

Laisser le choix entre englober le projet ou non : le problème de find_package

Si les projets A et B sont englobés alors la commande :

find_package(A CONFIG REQUIRED)

depuis B :

  • d'une part est inutile, puisque la cible A est définie dans une partie du projet global ;
  • d'autre part échoue (le fichier AConfig.cmake n'est pas encore créé au moment de la configuration).

Il faut d'une façon ou d'une autre tester l'opportunité de l'appel à find_package.

Première méthode :

if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
    find_package(A CONFIG REQUIRED)
endif()

Inconvénient : suppose que le projet englobant B englobe aussi A. Ou, en d'autres termes, que tout projet englobant B, englobera logiquement aussi A.

Seconde méthode :

if(NOT TARGET A)
    find_package(A CONFIG REQUIRED)
endif()

Plus robuste. Le projet englobant B peut ne pas englober A. Inconvénient : il faut faire attention à l'ordre des appels à add_subdirectory dans le projet englobant, add_subdirectory(A) doit être avant add_subdirectory(B).

Laisser le choix entre englober le projet ou non : le problème du namespace

Supposons que A soit utilisé par B :

target_link(B ... Project_A::A)

et que A et B soient englobés. Le namespace Projet_A:: n'est ajouté que dans le fichier AConfig.cmake, à l'intention seule de find_package. Pour que la commande target_link ci-dessus n'échoue pas, il faut ajouter un alias dans le projet A :

add_library(PROJECT_A::A ALIAS A)

Manipulation 26

Modifier les CMakeLists.txt de NR_util, Jumble, Numer_Rec_95 et Coriolis pour que ces codes puissent être compilés aussi bien indépendamment qu'englobés dans un super-projet. Penser à mettre des namespaces. Tester.