Verwendung von Build-Konfigurationseinstellungen

Build-Konfigurationseinstellungen können verwendet werden, um bestimmte Aspekte des Builds anzupassen. Eine Liste der von meson-python implementierten Einstellungen finden Sie im Nachschlagewerk für Build-Konfigurationseinstellungen.

Wie Build-Konfigurationseinstellungen angegeben werden, hängt vom verwendeten Python-Paket-Build-Frontend ab. Die beliebtesten Build-Frontends sind build und pip. Diese verwenden die lange Kommandozeilenoption --config-settings oder die kurze Kommandozeilenoption -C.

$ python -m build \
    -Csetup-args="-Doption=true" \
    -Csetup-args="-Dvalue=1" \
    -Ccompile-args="-j6"

$ python -m pip wheel . \
    --config-settings=setup-args="-Doption=disable" \
    --config-settings=compile-args="-j6"

Einzelheiten finden Sie in der Dokumentation von build und pip. Dieses Beispiel verwendet den Befehl python -m pip wheel, um ein Python-Wheel zu erstellen, das später installiert oder verteilt werden kann. Um ein Paket zu erstellen und sofort zu installieren, ersetzen Sie wheel durch install. Weitere Beispiele finden Sie im Leitfaden Argumente an Meson übergeben.

Mehrere Einstellungen übergeben

Bitte beachten Sie, dass pip vor Version 23.1 keine Möglichkeit bot, eine Build-Konfigurationseinstellung auf eine Liste von Zeichenketten zu setzen: spätere Werte für denselben Schlüssel, die an --config-settings übergeben werden, überschreiben frühere Werte, wodurch die Anzahl der Optionen, die an jeden Befehl übergeben werden können, die während des Build-Prozesses aufgerufen werden, effektiv auf eine beschränkt wird. Diese Einschränkung wurde in pip Release 23.1 aufgehoben.

Verwendung eines persistenten Build-Verzeichnisses

Standardmäßig verwendet meson-python ein temporäres Build-Verzeichnis, das nach Abschluss des Builds gelöscht wird. Ein persistentes Build-Verzeichnis ermöglicht schnellere inkrementelle Builds und den Zugriff auf Build-Protokolle und zwischengespeicherte Build-Artefakte. Die Konfigurationseinstellung build-dir weist meson-python an, ein vom Benutzer angegebenes Build-Verzeichnis zu verwenden, das nicht gelöscht wird. Zum Beispiel:

$ python -m build -Cbuild-dir=build

$ python -m pip install . -Cbuild-dir=build

Nachdem dieser Befehl ausgeführt wurde, enthält das Verzeichnis build alle Build-Artefakte und Unterstützungsdateien, die von meson, ninja und meson-python erstellt wurden. Dasselbe Build-Verzeichnis kann von nachfolgenden Aufrufen von meson-python verwendet werden, wodurch die Notwendigkeit entfällt, das gesamte Projekt neu zu erstellen, wenn Änderungen während der Entwicklung getestet werden.

Die Verwendung eines permanenten Build-Verzeichnisses hilft auch bei der Fehlersuche bei fehlerhaften Builds, indem es den Zugriff auf Build-Protokolle und zwischengespeicherte Build-Ausgaben ermöglicht, einschließlich der Meson-Introspektionsdateien und detaillierter Protokolle. Letztere werden in der Datei meson-logs/meson-log.txt im Build-Verzeichnis gespeichert und können nützlich sein, um zu diagnostizieren, warum ein Build im Projektkonfigurationsstadium fehlschlägt. Um beispielsweise zu verstehen, warum die Abhängigkeitserkennung fehlgeschlagen ist, ist es oft notwendig, die Ausgabe von pkg-config oder anderen Methoden zur Abhängigkeitserkennung zu überprüfen.

Der Zugriff auf detaillierte Protokolle und zwischengespeicherte Build-Ausgaben ist besonders hilfreich in CI-Umgebungen, in denen die Introspektion der Build-Umgebung in der Regel schwieriger ist als auf einem lokalen System. Daher kann es nützlich sein, die detaillierteren Protokolldateien anzuzeigen, wenn der CI-Build-Schritt fehlschlägt. Das folgende Code-Snippet einer GitHub Actions Workflow-Datei zeigt beispielsweise das detaillierte Meson-Setup-Protokoll, wenn der Build fehlschlägt.

- name: Build the package
  run: python -m build --wheel -Cbuild-dir=build
- name: Show meson-log.txt
  if: failure()
  run: cat build/meson-logs/meson-log.txt

Wenn failure() im obigen Code durch always() ersetzt wird, wird die Meson-Protokolldatei immer angezeigt. Weitere Einzelheiten finden Sie in der Dokumentation von GitHub Actions. Bitte beachten Sie, dass das Setup-Protokoll bei komplexen Projekten sehr lang werden kann und die Web-Oberfläche von GitHub Actions träge wird, wenn der laufende Job viele Ausgabenzeilen erzeugt.