CMake Modul

Hinweis: Die Funktionalität dieses Moduls wird durch Mesons Regeln zur Vermischung von Build-Systemen bestimmt.

Dieses Modul bietet Hilfswerkzeuge zur Generierung von CMake-Paketdateien. Es unterstützt auch die Verwendung von CMake-basierten Subprojekten, ähnlich den normalen Meson-Subprojekten.

Verwendung

Um dieses Modul zu verwenden, machen Sie einfach: cmake = import('cmake'). Die folgenden Funktionen sind dann als Methoden des Objekts mit dem Namen cmake verfügbar. Sie können den Namen cmake natürlich durch einen beliebigen anderen ersetzen.

Es wird generell empfohlen, die neueste Meson-Version und CMake >=3.17 für beste Kompatibilität zu verwenden. CMake-Subprojekte funktionieren in der Regel auch mit älteren CMake-Versionen. Dies kann jedoch in seltenen Fällen zu unerwarteten Problemen führen.

CMake Subprojekte

Die Verwendung von CMake-Subprojekten ähnelt der Verwendung der "normalen" Meson-Subprojekte. Sie müssen sich ebenfalls im Verzeichnis subprojects befinden.

Beispiel

add_library(cm_lib SHARED ${SOURCES})

cmake = import('cmake')

# Configure the CMake project
sub_proj = cmake.subproject('libsimple_cmake')

# Fetch the dependency object
cm_lib = sub_proj.dependency('cm_lib')

executable('exe1', ['sources'], dependencies: [cm_lib])

Die Methode subproject ist fast identisch mit der normalen Meson-Funktion subproject(). Der einzige Unterschied besteht darin, dass ein CMake-Projekt anstelle eines Meson-Projekts konfiguriert wird.

Das zurückgegebene sub_proj unterstützt dieselben Optionen wie ein "normales" Subprojekt. Meson erkennt automatisch CMake-Build-Ziele, auf die mit den unten aufgeführten Methoden zugegriffen werden kann weiter unten.

Normalerweise reicht es aus, das von der Methode dependency() zurückgegebene Abhängigkeitsobjekt in den Build-Zielen zu verwenden. Dies ist fast identisch mit der Verwendung des Objekts declare_dependency() aus einem normalen Meson-Subprojekt.

Es ist auch möglich, in einem CMake-Projekt definierte ausführbare Dateien als Code-Generatoren mit der Methode target() zu verwenden

add_executable(cm_exe ${EXE_SRC})

cmake = import('cmake')

# Subproject with the "code generator"
sub_pro = cmake.subproject('cmCodeGen')

# Fetch the code generator exe
sub_exe = sub_pro.target('cm_exe')

# Use the code generator
generated = custom_target(
  'cmake-generated',
  input: [],
  output: ['test.cpp'],
  command: [sub_exe, '@OUTPUT@']
)

Es ist zu beachten, dass nicht alle Projekte garantiert funktionieren. Der sicherste Ansatz wäre immer noch, für die betreffenden Subprojekte eine meson.build zu erstellen.

Konfigurationsoptionen

Neu in Meson 0.55.0

Meson unterstützt auch die Übergabe von Konfigurationsoptionen an CMake und das Überschreiben bestimmter Build-Details, die aus dem CMake-Subprojekt extrahiert wurden.

cmake   = import('cmake')
opt_var = cmake.subproject_options()

# Call CMake with `-DSOME_OTHER_VAR=ON`
opt_var.add_cmake_defines({'SOME_OTHER_VAR': true})

# Globally override the C++ standard to c++11
opt_var.set_override_option('cpp_std', 'c++11')

# Override the previous global C++ standard
# with c++14 only for the CMake target someLib
opt_var.set_override_option('cpp_std', 'c++14', target: 'someLib')

sub_pro = cmake.subproject('someLibProject', options: opt_var)

# Further changes to opt_var have no effect

Siehe das CMake-Options-Objekt für eine vollständige Referenz aller unterstützten Funktionen.

Das CMake-Konfigurations-Options-Objekt ähnelt stark dem Objekt cfg_data, das von configuration_data() zurückgegeben wird. Es wird durch die Methode subproject_options generiert.

Alle Konfigurationsoptionen müssen gesetzt werden, bevor das Subprojekt konfiguriert wird, und müssen über den Schlüssel options an die Methode subproject übergeben werden. Änderungen am Konfigurationsobjekt haben keine Auswirkungen auf frühere cmake.subproject-Aufrufe.

In früheren Meson-Versionen konnten CMake-Kommandozeilenparameter mit dem Kwarg cmake_options gesetzt werden. Dieses Feature ist jedoch seit 0.55.0 veraltet und wird nur noch aus Kompatibilitätsgründen beibehalten. Es funktioniert nicht zusammen mit dem Kwarg options.

subproject Objekt

Dieses Objekt wird von der oben beschriebenen Methode subproject zurückgegeben und unterstützt die folgenden Methoden

  • dependency(target) gibt ein Abhängigkeitsobjekt für jedes CMake-Ziel zurück. Das Kwarg include_type (neu in 0.56.0) steuert den Include-Typ des zurückgegebenen Abhängigkeitsobjekts ähnlich wie das gleiche Kwarg in der Funktion dependency().
  • include_directories(target) gibt ein Meson inc Objekt für das angegebene Ziel zurück. Die Verwendung dieser Methode ist nicht notwendig, wenn das Abhängigkeitsobjekt verwendet wird.
  • target(target) gibt das rohe Build-Ziel zurück.
  • target_type(target) gibt den Typ des Ziels als String zurück
  • target_list() gibt eine Liste aller Ziel-Namen zurück.
  • get_variable(name) ruft die angegebene Variable aus dem Subprojekt ab. Normalerweise sollten dependency() oder target() bevorzugt werden, um Build-Ziele zu extrahieren.
  • found gibt true zurück, wenn das Subprojekt verfügbar ist, andernfalls false neu in Meson 0.53.2

cmake options Objekt

Dieses Objekt wird von der Methode subproject_options() zurückgegeben und vom Kwarg options der Methode subproject konsumiert. Die folgenden Methoden werden unterstützt

  • add_cmake_defines({'opt1': val1, ...}) zusätzliche CMake-Kommandozeilen-Defines hinzufügen
  • set_override_option(opt, val) spezifische Build-Optionen für Ziele setzen. Dies fügt effektiv opt=val zum Array override_options des build_target() hinzu
  • set_install(bool) überschreiben, ob Ziele installiert werden sollen oder nicht
  • append_compile_args(lang, arg1, ...) Compile-Flags für eine bestimmte Sprache zu den Zielen hinzufügen
  • append_link_args(arg1, ...) Linker-Argumente zu den Zielen hinzufügen
  • clear() alle Daten im cmake options Objekt zurücksetzen

Die Methoden set_override_option, set_install, append_compile_args und append_link_args unterstützen das optionale Kwarg target. Wenn angegeben, wirken sich die gesetzten Optionen auf das spezifische Ziel aus. Ansonsten ist die Auswirkung der Option global für das Subprojekt.

Wenn beispielsweise opt_var.set_install(false) aufgerufen wird, wird kein Ziel installiert, unabhängig davon, was von CMake gesetzt wird. Es ist jedoch immer noch möglich, spezifische Ziele (hier foo) zu installieren, indem das Kwarg target gesetzt wird: opt_var.set_install(true, target: 'foo')

Optionen, die nicht gesetzt sind, beeinflussen das generierte Subprojekt nicht. Wenn beispielsweise set_install nicht aufgerufen wurde, werden die aus CMake extrahierten Werte verwendet.

Cross-Kompilierung

Neu in 0.56.0

Meson versucht, die meisten erforderlichen CMake-Toolchain-Variablen automatisch aus vorhandenen Einträgen in den Cross- und Native-Dateien zu erraten. Diese Variablen werden in einer automatisch generierten CMake-Toolchain-Datei im Build-Verzeichnis gespeichert. Die verbleibenden Variablen, die nicht erraten werden können, können vom Benutzer im Abschnitt [cmake] der Cross-/Native-Datei hinzugefügt werden (neu in 0.56.0).

Das Hinzufügen einer manuellen CMake-Toolchain-Datei wird auch mit der Einstellung cmake_toolchain_file im Abschnitt [properties] unterstützt. Das direkte Setzen einer CMake-Toolchain-Datei mit -DCMAKE_TOOLCHAIN_FILE=/path/to/some/Toolchain.cmake in der meson.build wird nicht unterstützt, da die automatisch generierte Toolchain-Datei auch von Meson verwendet wird, um beliebigen Code in CMake einzuschleusen, um die CMake-Subprojekt-Unterstützung zu aktivieren.

Die Konfiguration, die der Verwendung einer manuellen CMake-Toolchain-Datei am nächsten kommt, wäre das Setzen dieser Optionen in der Maschinendatei

[properties]

cmake_toolchain_file = '/path/to/some/Toolchain.cmake'
cmake_defaults       = false

[cmake]

# No entries in this section

Dies führt zu einer Toolchain-Datei mit dem absoluten Minimum, um die CMake-Subprojekt-Unterstützung zu aktivieren, und include() die cmake_toolchain_file als letzte Anweisung.

Weitere Informationen finden Sie in der Spezifikation für Cross- und Native-Dateien.

CMake Konfigurationsdateien

cmake.write_basic_package_version_file()

Diese Methode ist das Äquivalent der entsprechenden CMake-Funktion; sie generiert eine Paketversionsdatei mit dem Namen name.

  • name: der Name des Pakets.
  • version: die Version der generierten Paketdatei.
  • compatibility: ein String, der die Art der Kompatibilität angibt. Akzeptierte Werte sind AnyNewerVersion, SameMajorVersion, SameMinorVersion oder ExactVersion. Standardmäßig ist AnyNewerVersion. Je nach Ihrer CMake-Installation sind möglicherweise einige Arten von Kompatibilität nicht verfügbar.
  • arch_independent: neu in 0.62.0, wenn true, überspringt die generierte Paketdatei Architekturprüfungen. Nützlich für Header-only-Bibliotheken.
  • install_dir: optionales Installationsverzeichnis, standardmäßig $(libdir)/cmake/$(name)

Beispiel

cmake = import('cmake')

cmake.write_basic_package_version_file(name: 'myProject', version: '1.0.0')

cmake.configure_package_config_file()

Diese Methode ist das Äquivalent der entsprechenden CMake-Funktion; sie generiert eine Paketkonfigurationsdatei mit dem Namen name aus der Eingabe-Template-Datei input. Genau wie die CMake-Funktion wird in dieser Datei die Anweisung @PACKAGE_INIT@ durch den entsprechenden CMake-Code ersetzt. Das äquivalente Argument PATH_VARS wird über den Parameter configuration bereitgestellt.

  • name: der Name des Pakets.
  • input: die Template-Datei, die auf Variablensubstitutionen in configuration geprüft wird.
  • install_dir: optionales Installationsverzeichnis, standardmäßig $(libdir)/cmake/$(name).
  • configuration: ein configuration_data-Objekt, das für die Variablensubstitution in der Template-Datei verwendet wird. Seit 0.62.0 kann es stattdessen ein Dictionary akzeptieren.

Beispiel

meson.build

cmake = import('cmake')

conf = configuration_data()
conf.set_quoted('VAR', 'variable value')

cmake.configure_package_config_file(
    name: 'myProject',
    input: 'myProject.cmake.in',
    configuration: conf
)

myProject.cmake.in

@PACKAGE_INIT@

set(MYVAR VAR)

Die Ergebnisse der Suche sind