GuestFS-Hacking – Online in der Cloud

PROGRAMM:

NAME/FUNKTION

Guestfs-Hacking – Erweiterung und Beitrag zu libguestfs

BESCHREIBUNG

Diese Handbuchseite richtet sich an Hacker, die libguestfs selbst erweitern möchten.

Überblick OF SOURCE CODE
Die Libguestfs-Quelle befindet sich im Github-Repository
https://github.com/libguestfs/libguestfs

Große Mengen an Boilerplate-Code in libguestfs (RPC, Bindungen, Dokumentation) sind
generiert. Dies bedeutet, dass viele Quelldateien in einem zu fehlen scheinen
unkomplizierter Git-Checkout. Sie müssen den Generator ausführen ("./autogen.sh && make -C
Generator"), um diese Dateien zu erstellen.

Libguestfs verwendet ein auf Autotools basierendes Build-System, wobei die Hauptdateien sind konfigurieren.ac
und Makefile.amdem „Vermischten Geschmack“. Seine Generator Das Unterverzeichnis enthält den Generator sowie beschreibende Dateien
die API. Der src Das Unterverzeichnis enthält die Quelle für die Bibliothek. Der Gerät und Daemon
Unterverzeichnisse enthalten die Quelle für den Code, der die Appliance erstellt, und den Code
das jeweils im Gerät läuft. Weitere Verzeichnisse werden in diesem Abschnitt behandelt
„QUELLCODE-UNTERVERZEICHNISSE“ unten.

Abgesehen von der Tatsache, dass alle API-Einstiegspunkte über einen generierten Code laufen, ist dies bei der Bibliothek der Fall
einfach. (Tatsächlich ist sogar der generierte Code so konzipiert, dass er lesbar ist, und das sollte auch so sein
als gewöhnlicher Code gelesen werden). Einige Aktionen laufen vollständig in der Bibliothek und sind als C geschrieben
Funktionen in Dateien unter src. Andere werden an den Daemon weitergeleitet, wo (nach einigen
(generiertes RPC-Marshalling) erscheinen sie als C-Funktionen in den Dateien darunter Daemon.

Um aus dem Quellcode zu erstellen, lesen Sie zunächst die Datei „README“.

lokal* DATEIEN
Dateien im obersten Quellverzeichnis, die mit dem Präfix beginnen lokal* werden von Git ignoriert.
Diese Dateien können lokale Konfigurationen oder Skripte enthalten, die Sie zum Erstellen von libguestfs benötigen.

Konventionell habe ich eine Datei namens localconfigure Das ist ein einfacher Wrapper
autogen.sh Enthält lokale Konfigurationsanpassungen, die ich benötige:

. localenv
./autogen.sh \
--with-default-backend=libvirt \
--enable-gcc-warnings \
--enable-gtk-doc \
-C \
"$@"

Damit ich Folgendes verwenden kann, um libguestfs zu erstellen:

./localconfigure && make

Wenn sich im obersten Build-Verzeichnis eine Datei mit dem Namen befindet localenv, dann wird es bezogen von
"machen". Diese Datei kann alle benötigten lokalen Umgebungsvariablen enthalten, z. zum Überspringen
Tests:

# Verwenden Sie eine alternative Python-Binärdatei.
export PYTHON=python3
# Überspringen Sie diesen Test, er ist kaputt.
Export SKIP_TEST_BTRFS_FSCK=1

Beachten Sie, dass localenv ist im obersten Makefile enthalten (es handelt sich also um ein Makefile-Fragment). Aber falls
Es stammt auch von Ihnen localconfigure Skript, dann wird es als Shell-Skript verwendet.

HINZUFÜGEN A NEU API AKTION
Da große Mengen an Boilerplate-Code in libguestfs generiert werden, ist dies einfacher
um die libguestfs-API zu erweitern.

Um eine neue API-Aktion hinzuzufügen, gibt es zwei Änderungen:

1. Sie müssen eine Beschreibung des Aufrufs hinzufügen (Name, Parameter, Rückgabetyp, Tests,
Dokumentation) an generator/actions.ml.

Es gibt zwei Arten von API-Aktionen, je nachdem, ob der Aufruf an die weitergeleitet wird
Daemon in der Appliance oder wird vollständig von der Bibliothek bedient (siehe „ARCHITEKTUR“ in
gastfs-internals(3)). „guestfs_sync“ in Gastfs(3) ist ein Beispiel für Ersteres,
da die Synchronisierung in der Appliance erfolgt. „guestfs_set_trace“ in Gastfs(3) ist ein
Beispiel für Letzteres, da im Handle und bei der gesamten Ablaufverfolgung ein Ablaufverfolgungsflag beibehalten wird
erfolgt auf der Bibliotheksseite.

Die meisten neuen Aktionen sind vom ersten Typ und werden zur Liste „daemon_functions“ hinzugefügt.
Jeder Funktion ist eine eindeutige Prozedurnummer zugewiesen, die im RPC-Protokoll verwendet wird
zu dieser Aktion, wenn wir libguestfs veröffentlichen und nicht wiederverwendet werden können. Nehmen Sie das Neueste
Prozedurnummer eingeben und erhöhen.

Für reine Bibliotheksaktionen des zweiten Typs fügen Sie sie zur Liste „non_daemon_functions“ hinzu.
Da diese Funktionen von der Bibliothek bedient werden und nicht über den RPC laufen
Mechanismus zum Daemon benötigen diese Funktionen keine Prozedurnummer und daher die
Prozedurnummer ist auf „-1“ gesetzt.

2. Implementieren Sie die Aktion (in C):

Implementieren Sie für Daemon-Aktionen die Funktion „do_ " im Verzeichnis „daemon/“.

Implementieren Sie für Bibliotheksaktionen die Funktion „guestfs_impl_“ " im "src/"
Verzeichnis.

Verwenden Sie in jedem Fall eine andere Funktion als Beispiel für die Vorgehensweise.

Nachdem Sie diese Änderungen vorgenommen haben, kompilieren Sie mit „make“.

Beachten Sie, dass Sie weder RPC noch Sprachbindungen, Handbuchseiten oder ähnliches implementieren müssen
anders. Es wird alles automatisch aus der OCaml-Beschreibung generiert.

HINZUFÜGEN TESTS FÜR AN API AKTION
Sie können pro API-Aufruf null oder so viele Tests bereitstellen, wie Sie möchten. Die Tests können entweder sein
als Teil der API-Beschreibung hinzugefügt (generator/actions.ml) oder in einigen selteneren Fällen Sie
Möglicherweise möchten Sie ein Skript in „tests/*/“ ablegen. Beachten Sie, dass das Hinzufügen eines Skripts zu „tests/*/“ erforderlich ist
langsamer, also wenn möglich die erste Methode verwenden.

Im Folgenden wird die Testumgebung beschrieben, die beim Hinzufügen eines API-Tests verwendet wird Aktionen.ml.

Die Testumgebung verfügt über 4 Blockgeräte:

/ Dev / sda 500MB
Allgemeines Blockgerät zum Testen.

/ dev / sdb 500MB
/ dev / sdb1 ist ein ext2-Dateisystem, das zum Testen von Dateisystem-Schreibvorgängen verwendet wird.

/ dev / sdc 10MB
Wird in einigen Tests verwendet, bei denen zwei Blockgeräte benötigt werden.

/ dev / sdd
ISO mit festem Inhalt (siehe images/test.iso).

Um die Tests in angemessener Zeit ausführen zu können, sind die libguestfs-Appliance und
Blockgeräte werden zwischen Tests wiederverwendet. Versuchen Sie also nicht, „guestfs_kill_subprocess“ zu testen
Gastfs(3) :-x

Jeder Test beginnt mit einem anfänglichen Szenario, das mithilfe eines der „Init*“-Ausdrücke ausgewählt wird.
beschrieben in generator/types.ml. Diese initialisieren die oben genannten Festplatten in a
bestimmte Art und Weise, wie in dokumentiert Typen.ml. Sie sollten sich darüber keine Gedanken machen
vorherige Inhalte anderer Festplatten, die nicht initialisiert sind.

Sie können jedem einzelnen Test eine Voraussetzungsklausel hinzufügen. Dies ist eine Laufzeitprüfung,
Wenn der Test fehlschlägt, wird der Test übersprungen. Nützlich, wenn Sie einen Befehl testen, der
Funktioniert möglicherweise nicht bei allen Variationen von libguestfs-Builds. Ein Test, der die Voraussetzung hat
„Immer“ bedeutet bedingungslos laufen.

Darüber hinaus können Paketierer einzelne Tests überspringen, indem sie vorher Umgebungsvariablen setzen
Ausführen von „make check“.

SKIP_TEST_ _ =1

Beispiel: „SKIP_TEST_COMMAND_3=1“ überspringt Test Nr. 3 von „guestfs_command“ in Gastfs(3).

oder:

SKIP_TEST_ =1

Beispiel: „SKIP_TEST_ZEROFREE=1“ überspringt alle „guestfs_zerofree“ in Gastfs(3) Tests.

Packager können nur bestimmte Tests ausführen, indem sie beispielsweise Folgendes festlegen:

TEST_ONLY="vfs_type nullfrei"

Weitere Informationen finden Sie auch in den tests/c-api/tests.c Weitere Informationen zur Funktionsweise dieser Umgebungsvariablen finden Sie hier.

FEHLERBEHEBUNG NEU API MASSNAHMEN
Testen Sie neue Aktionen, bevor Sie sie einreichen.

Mit Guestfish können Sie neue Befehle ausprobieren.

Das Debuggen des Daemons stellt ein Problem dar, da er in einer minimalen Umgebung ausgeführt wird. Jedoch
Sie können Nachrichten im Daemon an stderr fprinten, und sie werden angezeigt, wenn Sie sie verwenden
„guestfish -v“.

HINZUFÜGEN A NEU SPRACHE BINDUNG
Alle Sprachbindungen müssen vom Generator generiert werden (siehe Generator Unterverzeichnis).

Hierzu gibt es noch keine Dokumentation. Wir empfehlen Ihnen, sich eine vorhandene Bindung anzusehen, z.
generator/ocaml.ml or Generator/perl.ml.

HINZUFÜGEN TESTS FÜR SPRACHE BINDUNGEN
Sprachbindungen sollten mit Tests geliefert werden. Zuvor war das Testen von Sprachbindungen
eher ad hoc, aber wir haben versucht, die Testreihe für jede Sprache zu formalisieren
Bindung verwenden sollte.

Derzeit implementieren nur die OCaml- und Perl-Bindungen tatsächlich den gesamten Testsatz
Die OCaml-Bindungen sind kanonisch, daher sollten Sie nachahmen, was die OCaml-Tests tun.

Dies ist das von den Tests verwendete Nummerierungsschema:

- Über 000 Basistests:

010 Laden Sie die Bibliothek
020 erstellen
030 Flags erstellen
040 mehrere Griffe erstellen
050-Testeinstellung und Abrufen von Konfigurationseigenschaften
060 explizites Schließen
065 implizites Schließen (in GC-Sprachen)
070 Optargs

- 100 starten, Partitionen und LVs und Dateisysteme erstellen

- Über 400 Veranstaltungen:

410 Abschlussereignis
420 Protokollmeldungen
430 Fortschrittsmeldungen

- Über 800 Regressionstests (spezifisch für die Sprache)

- Über 900 weitere benutzerdefinierte Tests für die Sprache

Um beim Ausführen der Tests Zeit zu sparen, sollte das Handle nur bei 100, 430, 800+, 900+ gestartet werden.

FORMATIERUNG CODE
Unser C-Quellcode hält sich im Allgemeinen an einige grundlegende Codeformatierungskonventionen. Der
Die bestehende Codebasis ist in dieser Hinsicht nicht völlig konsistent, aber wir bevorzugen das
Der beigesteuerte Code muss ähnlich formatiert sein. Kurz gesagt: Verwenden Sie zum Einrücken Leerzeichen und keine Tabulatoren.
Verwenden Sie für jede Einrückungsebene zwei Leerzeichen und folgen Sie ansonsten dem K&R-Stil.

Wenn Sie Emacs verwenden, fügen Sie Folgendes zu einer Ihrer Startdateien hinzu (z. B. ~/.emacs),
um sicherzustellen, dass Sie die Einrückung richtig machen:

;;; In libguestfs überall mit Leerzeichen einrücken (nicht mit TABs).
;;; Ausnahmen: Makefile- und ChangeLog-Modi.
(add-hook 'find-file-hook
'(lambda () (if (und Pufferdateiname
(string-match „/libguestfs\\>“
(Pufferdateiname))
(nicht (string-equal mode-name „Change Log“))
(nicht (string-gleicher Modusname „Makefile“)))
(setq indent-tabs-mode nil))))

;;; Verwenden Sie diesen Stil, wenn Sie C-Quellen in libguestfs bearbeiten.
(defun libguestfs-c-mode ()
„C-Modus mit angepassten Standardeinstellungen für die Verwendung mit libguestfs.“
(interaktiv)
(C-Set-Stil „K&R“)
(setq c-indent-level 2)
(setq c-basic-offset 2))
(add-hook 'c-mode-hook
'(lambda () (if (string-match "/libguestfs\\>"
(Pufferdateiname))
(libguestfs-c-mode))))

PRÜFUNG DEINER ÄNDERUNGEN
Aktivieren Sie Warnungen beim Kompilieren (und beheben Sie alle dabei gefundenen Probleme):

./configure --enable-gcc-warnings

Nützliche Ziele sind:

„Scheck machen“
Führt die reguläre Testsuite aus.

Dies wird mithilfe des regulären Automake-Ziels „TESTS“ implementiert. Sehen Sie sich die Automarke an
Dokumentation für Details.

„make check-valgrind“
Führt eine Teilmenge der Testsuite unter Valgrind aus.

Jedes Makefile.am in dem Baum, der ein „check-valgrind:“-Ziel hat, wird dadurch ausgeführt
Regel.

„make check-valgrind-local-guests“
Führt eine Teilmenge der Testsuite unter Valgrind unter Verwendung lokal installierter libvirt-Gäste aus
(schreibgeschützt).

„Scheck direkt durchführen“
Führt alle Tests mit dem Standard-Appliance-Back-End aus. Dies hat nur dann eine Auswirkung, wenn ein Nicht-
Das Standard-Backend wurde mit „./configure --with-default-backend=…“ ausgewählt.

„make check-valgrind-direct“
Führen Sie eine Teilmenge der Testsuite unter Valgrind mit dem Standard-Appliance-Backend aus.

„check-uml erstellen“
Führt alle Tests mit dem User-Mode-Linux-Backend aus.

Da es keinen Standardspeicherort für den User-Mode-Linux-Kernel gibt, müssen Sie haben um
„LIBGUESTFS_HV“, um auf das Kernel-Image zu verweisen, z. B.:

Machen Sie die Check-UML LIBGUESTFS_HV=~/d/linux-um/vmlinux

„make check-valgrind-uml“
Führt alle Tests mit dem User-Mode-Linux-Backend unter valgrind aus.

Wie oben müssen Sie „LIBGUESTFS_HV“ so einstellen, dass es auf den Kernel verweist.

„check-with-upstream-qemu durchführen“
Führt alle Tests mit einer lokalen qemu-Binärdatei aus. Es sucht nach der qemu-Binärdatei in QEMUDIR
(standardmäßig $HOME/d/qemu), aber Sie können dies im Befehl auf ein anderes Verzeichnis festlegen
Zeile, z.B.:

make check-with-upstream-qemu QEMUDIR=/usr/src/qemu

„mit-upstream-libvirt prüfen“
Führt alle Tests mit einer lokalen libvirt aus. Dies hat nur Auswirkungen, wenn das libvirt-Backend
wurde mit „./configure --with-default-backend=libvirt“ ausgewählt

Es sucht nach libvirt in LIBVIRTDIR (standardmäßig). $HOME/d/libvirt), aber Sie können dies einstellen
in ein anderes Verzeichnis auf der Befehlszeile, z. B.:

make check-with-upstream-libvirt LIBVIRTDIR=/usr/src/libvirt

„Check-langsam machen“
Führt einige langsame/lang laufende Tests aus, die nicht standardmäßig ausgeführt werden.

Jedes Makefile.am im Baum, der ein „check-slow:“-Ziel hat, wird von dieser Regel ausgeführt.

„Alles überprüfen“
Entspricht der Ausführung aller „make check*“-Regeln.

„Scheck-Freigabe machen“
Führt eine Teilmenge der „make check*“-Regeln aus, die erfüllt sein müssen, bevor ein Tarball erstellt werden kann
freigegeben. Derzeit ist dies:

· überprüfen

· check-valgrind

· check-direct

· check-valgrind-direct

· Check-Slow

„make installcheck“
Führen Sie „make check“ für die installierte Kopie von libguestfs aus.

Die Version der installierten libguestfs, die getestet wird, und die Version der libguestfs
Der Quellbaum muss identisch sein.

Folgende Hinweise sollten Sie beachten:

./autogen.sh
sauber machen ||:
um
installcheck durchführen

DÄMON KUNDENSPEZIFISCH DRUCKF FORMATIERER
Im Daemon-Code haben wir benutzerdefinierte printf-Formatierer %Q und %R erstellt, die daran gewöhnt sind
Zitieren Sie Shell.

%Q Einfache Shell-Zeichenfolge in Anführungszeichen. Leerzeichen oder andere Shell-Zeichen werden für Sie maskiert.

%R Identisch mit %Q, außer dass die Zeichenfolge als Pfad behandelt wird, dem das Sysroot-System vorangestellt ist.

Beispielsweise:

asprintf (&cmd, "cat %R", Pfad);

würde „cat /sysroot/some\ path\ with\ Leerzeichen“ erzeugen

Hinweis: Do nicht Verwenden Sie diese, wenn Sie Parameter an „command{,r,v,rv}()“ übergeben.
Funktionen. Diese Parameter müssen NICHT in Anführungszeichen gesetzt werden, da sie nicht über übergeben werden
Shell (stattdessen direkt zur Exec). Sie möchten wahrscheinlich die Funktion „sysroot_path()“ verwenden
aber.

EINREICHEN DEINER NEU API MASSNAHMEN
Senden Sie Patches an die Mailingliste: http://www.redhat.com/mailman/listinfo/libguestfs und
CC zu [E-Mail geschützt] .

INTERNATIONALISIERUNG (I18N) SUPPORT
Wir unterstützen i18n (jedenfalls gettext) in der Bibliothek.

Allerdings kommen viele Nachrichten vom Daemon und wir übersetzen diese derzeit nicht.
Ein Grund dafür ist, dass von der Appliance im Allgemeinen alle Gebietsschemadateien entfernt wurden, weil
Sie nehmen viel Platz ein. Wir müssten also einige davon lesen und unsere kopieren
PO-Dateien in die Appliance.

Debug-Meldungen werden nie übersetzt, da sie für die Programmierer bestimmt sind.

SOURCE CODE UNTERVERZEICHNISSE
ausrichten
Virt-Alignment-Scan(1) Befehl und Dokumentation.

Gerät
Die libguestfs-Appliance, Build-Skripte usw.

bash
Bash-Tab-Vervollständigungsskripte.

Build-Aux
Verschiedene von Autotools verwendete Build-Skripte.

Baumeister
Virt-Builder(1) Befehl und Dokumentation.

Katze Die Virt-Katze(1) virt-Dateisysteme(1) Virt-Log(1) und Virt-ls(1) Befehle und
Dokumentation.

Beitrag
Fremdbeiträge, experimentelle Teile.

anpassen
virt-anpassen(1) Befehl und Dokumentation.

Daemon
Der Daemon, der innerhalb der libguestfs-Appliance ausgeführt wird und Aktionen ausführt.

df virt-df(1) Befehl und Dokumentation.

dib virt-dib(1) Befehl und Dokumentation.

diff
Virt-Diff(1) Befehl und Dokumentation.

Dock Verschiedene Handbuchseiten.

bearbeiten
virt-edit(1) Befehl und Dokumentation.

Beispiele
C-API-Beispielcode.

Fisch
Gastfisch(1), die Befehlszeilen-Shell und verschiedene darauf aufbauende Shell-Skripte, wie z
Virt-Copy-In(1) virtuelles Kopieren(1) virt-tar-in(1) Virt-Tar-Out(1).

Format
Virt-Format(1) Befehl und Dokumentation.

Sicherung
Gastberg(1), FUSE (Userspace-Dateisystem) basiert auf libguestfs.

Generator
Der äußerst wichtige Generator, mit dem automatisch große Mengen erzeugt werden
Boilerplate-C-Code für Dinge wie RPC und Bindungen.

get-kernel
virt-get-kernel(1) Befehl und Dokumentation.

Gnulib
Gnulib wird als Portabilitätsbibliothek verwendet. Eine Kopie von Gnulib ist hier enthalten.

Inspektor
Virt-Inspektor(1), der Bildinspektor für virtuelle Maschinen.

Logo
Auf der Website verwendetes Logo. Der Fisch heißt übrigens Arthur.

m4 Von autoconf verwendete M4-Makros.

make-fs
virt-make-fs(1) Befehl und Dokumentation.

mllib
Verschiedene Bibliotheken und allgemeiner Code, der von verwendet wird virtuelle Größenänderung(1) und die anderen Werkzeuge, die es gibt
geschrieben in OCaml.

p2v virt-p2v(1) Befehl, Dokumentation und Skripte zum Erstellen der virt-p2v-ISO oder -Festplatte
Bild.

po Übersetzungen einfacher Gettext-Strings.

po-docs
Die Build-Infrastruktur und PO-Dateien für Übersetzungen von Manpages und POD-Dateien.
Irgendwann wird dies mit dem kombiniert po Verzeichnis, aber das ist eher
kompliziert.

retten
virt-rettung(1) Befehl und Dokumentation.

Größe
virtuelle Größenänderung(1) Befehl und Dokumentation.

spärlich machen
virt-sparsifizieren(1) Befehl und Dokumentation.

src Quellcode zur C-Bibliothek.

sysprep
virt-sysprep(1) Befehl und Dokumentation.

Tests
Prüfungen.

Testdaten
Von den Tests verwendete Dateien und andere Testdaten.

Test-Tool
Testtool für Endbenutzer, um zu testen, ob ihre QEMU/Kernel-Kombination damit funktioniert
libguestfs.

tmp Wird für temporäre Dateien beim Ausführen der Tests verwendet (anstelle von / Tmp usw). Der Grund ist
sodass Sie mehrere parallele Tests von libguestfs ausführen können, ohne einen Satz davon zu haben
Tests überschreiben die von einer anderen erstellte Appliance.

Werkzeuge
In Perl geschriebene Befehlszeilentools (virt-win-reg(1) und viele andere).

v2v virt-v2v(1) Befehl und Dokumentation.

Website
Die http://libguestfs.org Website-Dateien.

scharf
erlang erhalten
Objekt
golang
haskell
Java
Mond
ocaml
php
perl
python
Rubin
Sprachbindungen.

MACHEN A STABIL Loslassen
Wenn wir eine stabile Version erstellen, sind hier mehrere Schritte dokumentiert. Siehe „LIBGUESTFS
VERSIONSNUMMERN" in Gastfs(3) für allgemeine Informationen zur Stable-Branch-Richtlinie.

· Überprüfen Sie, ob „make && make check“ mindestens auf Fedora, Debian und Ubuntu funktioniert.

· Überprüfen Sie, ob „./configure --without-libvirt“ funktioniert.

· Abschließen Guestfs-Release-Notes.pod

· Drücken und Ziehen von Zanata.

Run:

Zanata Push

um die neuesten POT-Dateien an Zanata zu übertragen. Dann renne:

./zanata-pull.sh

Dies ist ein Wrapper zum Abrufen der neuesten Übersetzung *.po Dateien.

· Erwägen Sie, Gnulib auf die neueste Upstream-Version zu aktualisieren.

· Erstellen Sie unter neue stabile und Entwicklungsverzeichnisse http://libguestfs.org/download.

· Bearbeiten website/index.html.in.

· Legen Sie die Version fest (in konfigurieren.ac) zum neuen stabil Version, d.h. 1.XX.0 und commit
es:

./localconfigure
Machen Sie distclean -k
./localconfigure
make && make dist
Machen Sie Maintainer-Commit
Erstelle ein Maintainer-Tag

· Erstellen Sie den Stable-Zweig in Git:

Git Branch Stable-1.XX
Git Push Origin Stable-1.XX

· Führen Sie eine vollständige Veröffentlichung des stabilen Zweigs durch.

· Stellen Sie die Version auf die nächste Entwicklungsversion ein und übernehmen Sie diese. Führen Sie optional einen vollständigen aus
Veröffentlichung des Entwicklungszweigs.

Nutzen Sie GuestFS-Hacking online über die Dienste von onworks.net