Guestfs-hacking - Online w chmurze

PROGRAM:

IMIĘ

Guestfs-hacking - rozszerzanie i współtworzenie libguestfs

OPIS

Ta strona podręcznika jest przeznaczona dla hakerów, którzy chcą rozszerzyć samą bibliotekę libguestfs.

INFORMACJE OGÓLNE OF THE ŹRÓDŁO KOD
Źródło Libguestfs znajduje się w repozytorium github
https://github.com/libguestfs/libguestfs

Duża ilość standardowego kodu w libguestfs (RPC, powiązania, dokumentacja) to:
wygenerowane. Oznacza to, że w pliku będzie brakować wielu plików źródłowych
proste sprawdzenie git. Musisz uruchomić generator („./autogen.sh && make -C
generator”) w celu utworzenia tych plików.

Libguestfs korzysta z systemu kompilacji opartego na narzędziach automatycznych, w którym głównymi plikami są konfiguracja.ac
i Makefile.am, generator podkatalog zawiera generator oraz pliki opisujące
API. The src podkatalog zawiera źródło biblioteki. The urządzenie i Demon
podkatalogi zawierają źródło kodu budującego urządzenie oraz kod
które działają odpowiednio w urządzeniu. Inne katalogi są omówione w tej sekcji
„PODKATALOGI KODU ŹRÓDŁOWEGO” poniżej.

Oprócz tego, że wszystkie punkty wejścia API przechodzą przez wygenerowany kod, biblioteka tak
prosty. (W rzeczywistości nawet wygenerowany kod został zaprojektowany tak, aby był czytelny i powinien
być odczytywane jako zwykły kod). Niektóre akcje działają w całości w bibliotece i są zapisane jako C
funkcje w plikach pod src. Inne są przekazywane do demona, gdzie (po pewnym czasie
wygenerowane zestawianie RPC) pojawiają się jako funkcje C w plikach poniżej Demon.

Aby zbudować ze źródła, najpierw przeczytaj plik „README”.

lokalny* AKTA
Pliki w najwyższym katalogu źródłowym zaczynające się od przedrostka lokalny* są ignorowane przez git.
Pliki te mogą zawierać lokalną konfigurację lub skrypty potrzebne do zbudowania biblioteki libguestfs.

Zgodnie z konwencją mam plik o nazwie konfiguracja lokalna co jest prostym opakowaniem
autogen.sh zawierający lokalne dostosowania konfiguracji, których potrzebuję:

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

Mogę więc użyć tego do zbudowania libguestfs:

./localconfigure && make

Jeśli w górnym katalogu kompilacji znajduje się plik o nazwie localenv, wówczas będzie pochodzić z
"robić". Plik ten może zawierać wszelkie potrzebne lokalne zmienne środowiskowe, np. za pomijanie
testy:

# Użyj alternatywnego pliku binarnego Pythona.
eksportuj PYTHON=python3
# Pomiń ten test, jest uszkodzony.
eksport SKIP_TEST_BTRFS_FSCK=1

Należy pamiętać, że localenv jest zawarty w górnym pliku Makefile (więc jest to fragment Makefile). Ale jeśli
pochodzi również z twojego konfiguracja lokalna skrypt, wówczas jest on używany jako skrypt powłoki.

DODAWANIE A NOWOŚĆ API ACTION
Ponieważ w libguestfs generowane są duże ilości standardowego kodu, ułatwia to pracę
aby rozszerzyć API libguestfs.

Aby dodać nową akcję API, należy wprowadzić dwie zmiany:

1. Należy dodać opis wywołania (nazwa, parametry, typ powrotu, testy,
dokumentacja) do generator/akcje.ml.

Istnieją dwa rodzaje akcji API, w zależności od tego, czy połączenie przechodzi do
demon w urządzeniu lub jest w całości obsługiwany przez bibliotekę (patrz „ARCHITEKTURA” w
gościefs-wewnętrzni(3)). „guestfs_sync” w goście(3) jest przykładem pierwszego,
ponieważ synchronizacja odbywa się w urządzeniu. „guestfs_set_trace” w goście(3) jest
przykład tego ostatniego, ponieważ flaga śledzenia jest utrzymywana w uchwycie i całym śledzeniu
odbywa się po stronie biblioteki.

Większość nowych akcji jest pierwszego typu i jest dodawana do listy „daemon_functions”.
Każda funkcja ma przypisany unikalny numer procedury używany w protokole RPC
do tej akcji, gdy publikujemy libguestfs i nie można ich ponownie wykorzystać. Weź najnowsze
numer procedury i zwiększ go.

W przypadku akcji drugiego typu dostępnych wyłącznie w bibliotece dodaj do listy „non_daemon_functions”.
Ponieważ te funkcje są obsługiwane przez bibliotekę i nie są przesyłane przez RPC
mechanizmu do demona, funkcje te nie wymagają numeru procedury, a zatem plik
numer procedury jest ustawiony na „-1”.

2. Zaimplementuj akcję (w C):

W przypadku akcji demona zaimplementuj funkcję „do_ " w katalogu "demon/".

W przypadku akcji bibliotecznych zaimplementuj funkcję „guestfs_impl_ " w "źródle/"
katalogiem.

W obu przypadkach użyj innej funkcji jako przykładu tego, co należy zrobić.

Po dokonaniu tych zmian użyj polecenia „make” do kompilacji.

Pamiętaj, że nie musisz implementować RPC, powiązań językowych, stron podręcznika ani niczego
w przeciwnym razie. Wszystko jest generowane automatycznie na podstawie opisu OCaml.

DODAWANIE TESTY DLA AN API ACTION
Możesz dostarczyć zero lub dowolną liczbę testów na wywołanie API. Testy mogą być
dodany jako część opisu API (generator/akcje.ml) lub, w rzadszych przypadkach, Ciebie
może zechcesz wrzucić skrypt do „tests/*/”. Pamiętaj, że dodanie skryptu do „tests/*/” to
wolniej, więc jeśli to możliwe, użyj pierwszej metody.

Poniżej opisano środowisko testowe używane podczas dodawania testu API działania.ml.

Środowisko testowe składa się z 4 urządzeń blokowych:

/ Dev / sda 500MB
Ogólne urządzenie blokowe do testowania.

/ dev / sdb 500MB
/ dev / sdb1 to system plików ext2 używany do testowania operacji zapisu w systemie plików.

/ dev / sdc 10MB
Używany w kilku testach, gdzie potrzebne są dwa urządzenia blokowe.

/ dev / sdd
ISO ze stałą zawartością (patrz obrazy/test.iso).

Aby móc przeprowadzić testy w rozsądnym czasie, urządzenie libguestfs i
urządzenia blokowe są ponownie wykorzystywane pomiędzy testami. Więc nie próbuj testować „guestfs_kill_subprocess” w
goście(3) :-x

Każdy test rozpoczyna się od scenariusza początkowego, wybranego za pomocą jednego z wyrażeń „Init*”,
opisane w generator/types.ml. Inicjują one dyski wspomniane powyżej w pliku a
określony sposób, jak udokumentowano w typy.ml. Nie należy zakładać niczego na temat
poprzednia zawartość innych dysków, które nie zostały zainicjowane.

Do dowolnego pojedynczego testu można dodać klauzulę wymagań wstępnych. To jest kontrola w czasie wykonywania,
co w przypadku niepowodzenia powoduje pominięcie testu. Przydatne podczas testowania polecenia które
może nie działać we wszystkich odmianach kompilacji libguestfs. Test, który ma warunek wstępny
„Zawsze” oznacza działanie bezwarunkowe.

Ponadto osoby pakujące mogą pominąć poszczególne testy, ustawiając wcześniej zmienne środowiskowe
uruchomienie „sprawdź”.

POMIŃ_TEST_ _ =1

np.: „SKIP_TEST_COMMAND_3=1” pomija test nr 3 „guestfs_command” w goście(3).

lub:

POMIŃ_TEST_ =1

np.: „SKIP_TEST_ZEROFREE=1” pomija wszystkie „guestfs_zerofree” w goście(3) testy.

Osoby pakujące mogą uruchamiać tylko niektóre testy, ustawiając na przykład:

TEST_ONLY="vfs_type zerofree"

See testy/c-api/testy.c aby uzyskać więcej informacji na temat działania tych zmiennych środowiskowych.

DEBUGOWANIE NOWOŚĆ API DZIAŁANIA
Przetestuj działanie nowych działań przed ich przesłaniem.

Możesz użyć gościa, aby wypróbować nowe polecenia.

Debugowanie demona stanowi problem, ponieważ działa on w minimalnym środowisku. Jednakże
możesz fprintf wiadomości w demonie na stderr i pojawią się, jeśli użyjesz
„gość -v”.

DODAWANIE A NOWOŚĆ JĘZYK WIĄŻĄCY
Wszystkie powiązania językowe muszą zostać wygenerowane przez generator (patrz plik generator podkatalogu).

Nie ma jeszcze na to dokumentacji. Sugerujemy sprawdzenie istniejącego wiązania, np.
generator/ocaml.ml or generator/perl.ml.

DODAWANIE TESTY DLA JĘZYK WIĄZANIA
Powiązania językowe powinny być dostarczane z testami. Wcześniej testowano powiązania językowe
raczej ad hoc, ale staramy się sformalizować zestaw testów dla każdego języka
należy użyć wiązania.

Obecnie tylko powiązania OCaml i Perl faktycznie implementują pełny zestaw testów i
powiązania OCaml są kanoniczne, więc powinieneś emulować to, co robią testy OCaml.

Oto schemat numeracji używany w testach:

- 000+ podstawowych testów:

010 załaduj bibliotekę
020 utwórz
030 utwórz flagi
040 utwórz wiele uchwytów
050 ustawienie testowe i uzyskiwanie właściwości konfiguracyjnych
060 wyraźne zamknięcie
065 ukryte zamknięcie (w językach GC)
070 opcji

- 100 uruchomień, utwórz partycje, LV i systemy plików

- Ponad 400 wydarzeń:

410 zamknięcie wydarzenia
420 komunikatów dziennika
430 komunikatów o postępie

- Ponad 800 testów regresyjnych (specyficznych dla języka)

- Ponad 900 innych niestandardowych testów dla języka

Aby zaoszczędzić czas podczas przeprowadzania testów, tylko 100, 430, 800+, 900+ powinno uruchomić uchwyt.

FORMATOWANIE KOD
Nasz kod źródłowy C ogólnie jest zgodny z pewnymi podstawowymi konwencjami formatowania kodu. The
istniejąca baza kodu nie jest pod tym względem całkowicie spójna, ale my tak wolimy
wniesiony kod powinien być sformatowany w podobny sposób. Krótko mówiąc, do wcięć używaj spacji, a nie tabulatorów,
używaj 2 spacji na każdy poziom wcięcia, a poza tym postępuj zgodnie ze stylem K&R.

Jeśli używasz Emacsa, dodaj następujący tekst do jednego z plików startowych (np. ~/.emacs),
aby zapewnić prawidłowe wcięcie:

;;; W libguestfs wciskaj wszędzie spacje (nie TAB).
;;; Wyjątki: tryby Makefile i ChangeLog.
(add-hook „znajdź-file-hook
'(lambda () (if (i nazwa-pliku-bufora
(dopasowanie ciągu „/libguestfs\\>”
(nazwa pliku-bufora))
(not (ciąg znaków równy nazwie trybu „Dziennik zmian”))
(not (ciąg znaków równy nazwie trybu „Makefile”)))
(setq tryb wcięcia-tabulacji zero))))

;;; Edytując źródła C w libguestfs, użyj tego stylu.
(zdefiniuj tryb libguestfs-c ()
„Tryb C ze skorygowanymi ustawieniami domyślnymi do użytku z libguestfs.”
(interaktywny)
(w stylu c-set „K&R”)
(setq poziom wcięcia c 2)
(setq c-podstawowe przesunięcie 2))
(add-hook „c-mode-hook
'(lambda () (if (dopasowanie ciągu "/libguestfs\\>"
(nazwa pliku-bufora))
(tryb libguestfs-c))))

BADANIE TWÓJ ZMIANY
Włącz ostrzeżenia podczas kompilacji (i napraw wszelkie wykryte problemy):

./configure --enable-gcc-ostrzeżenia

Przydatnymi celami są:

„sprawdź”
Uruchamia zwykły zestaw testów.

Jest to realizowane przy użyciu zwykłego celu „TESTS” automatycznego tworzenia. Zobacz automake
dokumentacja, aby uzyskać szczegółowe informacje.

„zrób check-valgrind”
Uruchamia podzbiór zestawu testów w valgrind.

Każdy Makefile.am w drzewie, które ma element docelowy „check-valgrind:”, zostanie przez to uruchomiony
reguła.

„zrób check-valgrind-local-guests”
Uruchamia podzbiór zestawu testów w systemie valgrind, korzystając z lokalnie zainstalowanych gości libvirt
(tylko czytać).

„zrób czek bezpośrednio”
Uruchamia wszystkie testy przy użyciu domyślnego zaplecza urządzenia. Ma to jakikolwiek skutek tylko wtedy, gdy nie-
wybrano domyślny backend za pomocą „./configure --with-default-backend=…”

„ustaw check-valgrind-direct”
Uruchom podzbiór zestawu testów w systemie valgrind, korzystając z domyślnego zaplecza urządzenia.

„sprawdź-uml”
Uruchamia wszystkie testy przy użyciu zaplecza systemu Linux w trybie użytkownika.

Ponieważ nie ma standardowej lokalizacji jądra systemu Linux w trybie użytkownika, you mieć ustawić
„LIBGUESTFS_HV”, aby wskazać obraz jądra, np.:

wykonaj check-uml LIBGUESTFS_HV=~/d/linux-um/vmlinux

„zrób check-valgrind-uml”
Uruchamia wszystkie testy przy użyciu backendu Linux w trybie użytkownika w valgrind.

Jak wyżej, musisz ustawić "LIBGUESTFS_HV", aby wskazywało jądro.

„sprawdź za pomocą-upstream-qemu”
Uruchamia wszystkie testy przy użyciu lokalnego pliku binarnego qemu. Szuka pliku binarnego qemu w QEMUDIR
(domyślnie $HOME/d/qemu), ale możesz ustawić to w poleceniu na inny katalog
linia, np.:

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

„sprawdź za pomocą-upstream-libvirt”
Uruchamia wszystkie testy przy użyciu lokalnej biblioteki libvirt. Ma to jakikolwiek skutek tylko wtedy, gdy backend libvirt
został wybrany przy użyciu „./configure --with-default-backend=libvirt”

Szuka libvirt w LIBVIRTDIR (domyślnie $HOME/d/libvirt), ale możesz to ustawić
do innego katalogu w wierszu poleceń, np.:

sprawdź za pomocą-upstream-libvirt LIBVIRTDIR=/usr/src/libvirt

„sprawdź, czy sprawdzanie jest powolne”
Uruchamia niektóre powolne/długo działające testy, które nie są uruchamiane domyślnie.

Każdy Makefile.am w drzewie, które ma element docelowy „check-slow:”, zostanie uruchomiony zgodnie z tą regułą.

„sprawdź wszystko”
Równoważne uruchamianiu wszystkich reguł „sprawdź*”.

„zrób zwolnienie czeku”
Uruchamia podzbiór reguł „make check*”, które muszą zostać spełnione, zanim będzie można umieścić plik tar
wydany. Obecnie jest to:

· sprawdzać

· sprawdź-valgrind

· sprawdź bezpośrednio

· sprawdź-valgrind-bezpośrednio

· sprawdź wolno

„wykonaj kontrolę instalacji”
Uruchom „make check” na zainstalowanej kopii libguestfs.

Wersja testowanej zainstalowanej biblioteki libguestfs i wersja biblioteki libguestfs
drzewo źródłowe musi być takie samo.

Zrobić:

./autogen.sh
oczyścić ||:
robić
sprawdź instalację

DEMON ZWYCZAJ DRUKUJ FORMATYRZY
W kodzie demona utworzyliśmy niestandardowe formatery printf %Q i %R, do których jesteśmy przyzwyczajeni
cytuj Shella.

%Q Prosty ciąg znaków w cudzysłowie powłoki. Wszelkie spacje lub inne znaki powłoki zostaną dla Ciebie zmienione.

%R To samo co %Q, z tą różnicą, że ciąg znaków jest traktowany jako ścieżka poprzedzona katalogiem sysroot.

Na przykład:

asprintf (&cmd, "kot%R", ścieżka);

spowodowałoby wygenerowanie „cat /sysroot/jakaś ścieżka\ ze spacjami”

Uwaga: Do nie użyj ich, przekazując parametry do „polecenie{,r,v,rv}()”
Funkcje. Parametry te NIE muszą być cytowane, ponieważ nie są przekazywane przez
powłoki (zamiast tego bezpośrednio do exec). Prawdopodobnie chcesz użyć funkcji „sysroot_path()”.
jednak.

PRZEDKŁADAJĄCY TWÓJ NOWOŚĆ API DZIAŁANIA
Prześlij poprawki na listę mailingową: http://www.redhat.com/mailman/listinfo/libguestfs i
CC do [email chroniony].

UMIĘDZYNARODOWIENIE (I18N) WSPIERAJ
W bibliotece obsługujemy i18n (w każdym razie gettext).

Jednak wiele wiadomości pochodzi od demona i w tej chwili ich nie tłumaczymy.
Jednym z powodów jest to, że z urządzenia zazwyczaj usuwane są wszystkie pliki ustawień regionalnych, ponieważ
zajmują dużo miejsca. Musielibyśmy więc przeczytać niektóre z nich, a także skopiować nasze
PO do urządzenia.

Komunikaty debugowania nigdy nie są tłumaczone, ponieważ są przeznaczone dla programistów.

ŹRÓDŁO KOD PODKATALOGI
wyrównać
skanowanie-wyrównania virt(1) polecenie i dokumentacja.

urządzenie
Urządzenie libguestfs, tworzenie skryptów i tak dalej.

bash
Skrypty uzupełniania kart Bash.

budowa-pomoc
Różne skrypty kompilacji używane przez autotools.

budowniczy
virt-budowniczy(1) polecenie i dokumentacja.

jak Połączenia Virt-cat(1) wirtualne systemy plików(1) log-virt(1) i virt-ls(1) polecenia i
dokumentacja.

contrib
Wkład zewnętrzny, części eksperymentalne.

dostosować
Wirtualne dostosowywanie(1) polecenie i dokumentacja.

Demon
Demon działający wewnątrz urządzenia libguestfs i wykonujący akcje.

df virt-df(1) polecenie i dokumentacja.

wym virt-dib(1) polecenie i dokumentacja.

diff
Wirtualna różnica(1) polecenie i dokumentacja.

doc Różne strony podręcznika.

edit
wirtualna edycja(1) polecenie i dokumentacja.

przykłady
Przykładowy kod API języka C.

ryba
gość(1), powłoka wiersza poleceń i różne skrypty powłoki zbudowane na wierzchu, takie jak
wirtualna kopia(1) Wirtualne kopiowanie(1) virt-tar-in(1) wirt-tar-out(1).

format
format virt(1) polecenie i dokumentacja.

bezpiecznik
gość(1), FUSE (system plików przestrzeni użytkownika) zbudowany na bazie libguestfs.

generator
Niezwykle ważny generator, służący do automatycznego generowania dużych ilości
standardowy kod C dla takich rzeczy jak RPC i powiązania.

pobierz jądro
virt-get-jądro(1) polecenie i dokumentacja.

gnulib
Gnulib jest używany jako biblioteka przenośności. Kopia gnulib jest dołączona poniżej.

inspektor
wirtualny inspektor(1), inspektor obrazu maszyny wirtualnej.

logo
Logo użyte na stronie. Nawiasem mówiąc, ryba nazywa się Artur.

m4 Makra M4 używane przez autoconf.

make-fs
virt-make-fs(1) polecenie i dokumentacja.

mllib
Różne biblioteki i wspólny kod używany przez Wirtualna zmiana rozmiaru(1) i inne narzędzia, które są
napisany w OCaml.

p2v virt-p2v(1) polecenie, dokumentacja i skrypty do budowy ISO lub dysku virt-p2v
obraz.

po Tłumaczenia prostych ciągów gettext.

po-dokumenty
Infrastruktura kompilacji i pliki PO do tłumaczeń stron podręcznika i plików POD.
Docelowo zostanie to połączone z po katalog, ale to raczej
skomplikowane.

ratowanie
ratownictwo wirtualne(1) polecenie i dokumentacja.

rozmiar
Wirtualna zmiana rozmiaru(1) polecenie i dokumentacja.

sparsyfikować
wirt-sparsify(1) polecenie i dokumentacja.

src Kod źródłowy biblioteki C.

sysprep
virt-sysprep(1) polecenie i dokumentacja.

Testy
Testy.

dane testowe
Pliki i inne dane testowe wykorzystywane w testach.

narzędzie testowe
Narzędzie testowe dla użytkowników końcowych, umożliwiające sprawdzenie, czy ich kombinacja qemu/jądro będzie działać
libguestfs.

tmp Używane do plików tymczasowych podczas uruchamiania testów (zamiast / Tmp itp). Powodem jest
dzięki czemu można uruchomić wiele równoległych testów libguestfs bez posiadania jednego zestawu
testy nadpisujące urządzenie utworzone przez inne.

narzędzia
Narzędzia wiersza poleceń napisane w języku Perl (virt-win-reg(1) i wiele innych).

v2v virt-v2v(1) polecenie i dokumentacja.


Połączenia http://libguestfs.org pliki strony internetowej.

csharp
Erlang
przedmiot
golang
Haskell
Jawa
Lua
ocaml
php
Perl
pyton
rubin
Powiązania językowe.

ZROBIENIE A STABILNY ZWOLNIENIE
Kiedy tworzymy stabilną wersję, tutaj udokumentowanych jest kilka kroków. Zobacz „LIBGUESTFS
NUMERY WERSJI” w goście(3) ogólne informacje na temat polityki stabilnego oddziału.

· Sprawdź, czy „make && make check” działa przynajmniej na Fedorze, Debianie i Ubuntu.

· Sprawdź, czy „./configure --without-libvirt” działa.

· Sfinalizuj Guestfs-release-notes.pod

· Pchnij i pociągnij Zanatę.

Biegać:

pchnięcie Zanaty

aby przesłać najnowsze pliki POT do Zanaty. Następnie uruchomić:

./zanata-pull.sh

który jest opakowaniem do pobrania najnowszego przetłumaczonego pliku *.po akta.

· Rozważ aktualizację gnulib do najnowszej wersji.

· Utwórz nowe katalogi stabilne i rozwojowe w ramach http://libguestfs.org/download.

· Edytować strona internetowa/index.html.in.

· Ustaw wersję (w konfiguracja.ac) do nowego stabilny wersja, tj. 1.XX.0 i zatwierdź
to:

./lokalna konfiguracja
zrób wyczyść -k
./lokalna konfiguracja
make && make dist
wykonaj zatwierdzenie konserwatora
utwórz tag konserwatora

· Utwórz stabilną gałąź w git:

git oddział stabilny-1.XX
git push Origin stable-1.XX

· Wykonaj pełne wydanie stabilnej gałęzi.

· Ustaw wersję na następną wersję rozwojową i zatwierdź ją. Opcjonalnie wykonaj pełne
wydanie gałęzi rozwojowej.

Skorzystaj z hackowania gościnnego online, korzystając z usług onworks.net