guestfs-hacking - Online di Cloud

PROGRAM:

NAMA

guestfs-hacking - memperluas dan berkontribusi ke libguestfs

DESKRIPSI

Halaman manual ini untuk peretas yang ingin memperluas libguestfs itu sendiri.

GAMBARAN OF THE SOURCE KODE
Sumber Libguestfs terletak di repositori github
https://github.com/libguestfs/libguestfs

Sejumlah besar kode boilerplate di libguestfs (RPC, binding, dokumentasi) adalah
dihasilkan. Ini berarti bahwa banyak file sumber akan tampak hilang dari a
checkout git langsung. Anda harus menjalankan generator ("./autogen.sh && make -C
generator") untuk membuat file-file itu.

Libguestfs menggunakan sistem build berbasis autotools, dengan file utama adalah konfigurasi.ac
dan Makefile.am. itu generator subdirektori berisi generator, ditambah file yang menjelaskan
API. Itu src subdirektori berisi sumber untuk perpustakaan. Itu alat dan daemon
subdirektori berisi sumber untuk kode yang membangun alat, dan kode
yang berjalan di alat masing-masing. Direktori lain tercakup dalam bagian
"SUBDIRECTORIES KODE SUMBER" di bawah ini.

Terlepas dari kenyataan bahwa semua titik masuk API melalui beberapa kode yang dihasilkan, perpustakaan adalah
mudah. (Bahkan, bahkan kode yang dihasilkan dirancang agar dapat dibaca, dan harus
dibaca sebagai kode biasa). Beberapa tindakan dijalankan sepenuhnya di perpustakaan, dan ditulis sebagai C
fungsi dalam file di bawah src. Lainnya diteruskan ke daemon di mana (setelah beberapa
dihasilkan RPC marshalling) mereka muncul sebagai fungsi C dalam file di bawah daemon.

Untuk membangun dari sumber, pertama-tama baca file "README".

lokal* FILE
File di direktori sumber teratas yang dimulai dengan awalan lokal* diabaikan oleh git.
File-file ini dapat berisi konfigurasi lokal atau skrip yang Anda perlukan untuk membuat libguestfs.

Dengan konvensi, saya memiliki file bernama konfigurasi lokal yang merupakan pembungkus sederhana di sekitar
autogen.sh berisi penyesuaian konfigurasi lokal yang saya butuhkan:

. lokal
./autogen.sh \
--dengan-default-backend=libvirt \
--aktifkan-gcc-peringatan \
--aktifkan-gtk-doc \
-C \
"$@"

Jadi saya bisa menggunakan ini untuk membangun libguestfs:

./localconfigure && make

Jika ada file di direktori build teratas bernama lokal, maka itu akan bersumber dari
"membuat". File ini dapat berisi variabel lingkungan lokal yang diperlukan, mis. untuk melewatkan
tes:

# Gunakan biner python alternatif.
ekspor PYTHON=python3
# Lewati tes ini, ini rusak.
ekspor SKIP_TEST_BTRFS_FSCK=1

Perhatikan bahwa lokal disertakan oleh Makefile teratas (jadi ini adalah fragmen Makefile). Tapi jika
itu juga bersumber dari Anda konfigurasi lokal script kemudian digunakan sebagai skrip shell.

MENAMBAHKAN A BARU API AKSI
Karena sejumlah besar kode boilerplate di libguestfs dihasilkan, ini membuatnya mudah
untuk memperluas libguestfs API.

Untuk menambahkan tindakan API baru, ada dua perubahan:

1. Anda perlu menambahkan deskripsi panggilan (nama, parameter, tipe pengembalian, tes,
dokumentasi) untuk generator/tindakan.ml.

Ada dua jenis tindakan API, tergantung pada apakah panggilan masuk ke
daemon di alat, atau dilayani sepenuhnya oleh perpustakaan (lihat "ARSITEKTUR" di
guestfs-internal(3)). "guestfs_sync" di tamu(3) adalah contoh dari yang pertama,
karena sinkronisasi dilakukan di alat. "guestfs_set_trace" di tamu(3) adalah sebuah
contoh yang terakhir, karena bendera jejak dipertahankan di pegangan dan semua pelacakan
dilakukan di sisi perpustakaan.

Sebagian besar tindakan baru adalah dari jenis pertama, dan ditambahkan ke daftar "daemon_functions".
Setiap fungsi memiliki nomor prosedur unik yang digunakan dalam protokol RPC yang ditetapkan
untuk tindakan itu ketika kami menerbitkan libguestfs dan tidak dapat digunakan kembali. Ambil yang terbaru
nomor prosedur dan menambahnya.

Untuk tindakan perpustakaan-saja dari jenis kedua, tambahkan ke daftar "non_daemon_functions".
Karena fungsi-fungsi ini dilayani oleh perpustakaan dan tidak melewati RPC
mekanisme ke daemon, fungsi-fungsi ini tidak memerlukan nomor prosedur, sehingga
nomor prosedur diatur ke "-1".

2. Terapkan tindakan (dalam C):

Untuk aksi daemon, implementasikan fungsi "do_ " di direktori "daemon/".

Untuk tindakan perpustakaan, implementasikan fungsi "guestfs_impl_ " di "src/"
direktori.

Dalam kedua kasus, gunakan fungsi lain sebagai contoh apa yang harus dilakukan.

Setelah membuat perubahan ini, gunakan "make" untuk mengkompilasi.

Perhatikan bahwa Anda tidak perlu mengimplementasikan RPC, binding bahasa, halaman manual, atau apa pun
kalau tidak. Semuanya dibuat secara otomatis dari deskripsi OCaml.

MENAMBAHKAN UJI UNTUK AN API AKSI
Anda dapat menyediakan nol atau sebanyak tes yang Anda inginkan per panggilan API. Tes bisa berupa
ditambahkan sebagai bagian dari deskripsi API (generator/tindakan.ml), atau dalam beberapa kasus yang lebih jarang Anda
mungkin ingin memasukkan skrip ke "tests/*/". Perhatikan bahwa menambahkan skrip ke "tests/*/" adalah
lebih lambat, jadi jika memungkinkan gunakan cara pertama.

Berikut ini menjelaskan lingkungan pengujian yang digunakan saat Anda menambahkan pengujian API di tindakan.ml.

Lingkungan pengujian memiliki 4 perangkat blok:

/ Dev / sda 500MB
Perangkat blok umum untuk pengujian.

/ dev / sdb 500MB
/ dev / sdb1 adalah sistem file ext2 yang digunakan untuk menguji operasi penulisan sistem file.

/ dev / sdc 10MB
Digunakan dalam beberapa tes di mana dua perangkat blok diperlukan.

/ dev / sdd
ISO dengan konten tetap (lihat gambar/tes.iso).

Untuk dapat menjalankan pengujian dalam waktu yang wajar, alat libguestfs dan
perangkat blok digunakan kembali di antara pengujian. Jadi jangan coba menguji "guestfs_kill_subprocess" di
tamu(3) :-x

Setiap pengujian dimulai dengan skenario awal, dipilih menggunakan salah satu ekspresi "Init*",
dijelaskan dalam generator/types.ml. Ini menginisialisasi disk yang disebutkan di atas dalam a
cara tertentu seperti yang didokumentasikan dalam jenis.ml. Anda seharusnya tidak berasumsi apa pun tentang
isi sebelumnya dari disk lain yang tidak diinisialisasi.

Anda dapat menambahkan klausa prasyarat ke tes individual apa pun. Ini adalah pemeriksaan run-time,
yang, jika gagal, menyebabkan tes dilewati. Berguna jika menguji perintah yang
mungkin tidak berfungsi pada semua variasi build libguestfs. Sebuah tes yang memiliki prasyarat
"Selalu" berarti berlari tanpa syarat.

Selain itu, pembuat paket dapat melewati pengujian individual dengan mengatur variabel lingkungan sebelumnya
menjalankan "melakukan pemeriksaan".

SKIP_TEST_ _ =1

misalnya: "SKIP_TEST_COMMAND_3=1" melewatkan tes #3 dari "guestfs_command" di tamu(3).

atau:

SKIP_TEST_ =1

misalnya: "SKIP_TEST_ZEROFREE=1" melewatkan semua "guestfs_zerofree" di tamu(3) tes.

Pembuat paket hanya dapat menjalankan tes tertentu dengan mengatur misalnya:

TEST_ONLY="vfs_type zerofree"

Lihat tes/c-api/tes.c untuk detail lebih lanjut tentang cara kerja variabel lingkungan ini.

DEBUGING BARU API TINDAKAN
Uji tindakan baru yang berfungsi sebelum mengirimkannya.

Anda dapat menggunakan guestfish untuk mencoba perintah baru.

Men-debug daemon adalah masalah karena berjalan di dalam lingkungan minimal. Namun
Anda dapat mem-fprintf pesan di daemon ke stderr, dan mereka akan muncul jika Anda menggunakan
"ikan tamu -v".

MENAMBAHKAN A BARU BAHASA MENGIKAT
Semua ikatan bahasa harus dibuat oleh generator (lihat bagian generator subdirektori).

Belum ada dokumentasi untuk ini. Kami menyarankan Anda melihat ikatan yang ada, mis.
generator/ocaml.ml or generator/perl.ml.

MENAMBAHKAN UJI UNTUK BAHASA PENGIKAT
Ikatan bahasa harus disertai dengan tes. Pengujian binding bahasa sebelumnya adalah
agak ad-hoc, tetapi kami telah mencoba memformalkan serangkaian tes yang setiap bahasa
mengikat harus digunakan.

Saat ini hanya binding OCaml dan Perl yang benar-benar mengimplementasikan set lengkap pengujian, dan
binding OCaml bersifat kanonik, jadi Anda harus meniru apa yang dilakukan tes OCaml.

Ini adalah skema penomoran yang digunakan oleh tes:

- 000+ tes dasar:

010 memuat perpustakaan
020 buat
030 buat-bendera
040 buat banyak pegangan
050 pengaturan pengujian dan mendapatkan properti konfigurasi
060 eksplisit dekat
065 tutup implisit (dalam bahasa GC)
070 optarg

- 100 peluncuran, buat partisi dan LV dan sistem file

- 400+ acara:

410 tutup acara
420 pesan log
430 pesan kemajuan

- 800+ tes regresi (khusus untuk bahasa)

- 900+ tes khusus lainnya untuk bahasa tersebut

Untuk menghemat waktu saat menjalankan tes, hanya 100, 430, 800+, 900+ yang harus meluncurkan pegangan.

FORMAT KODE
Kode sumber C kami umumnya mematuhi beberapa konvensi pemformatan kode dasar. Itu
basis kode yang ada tidak sepenuhnya konsisten di bagian depan ini, tetapi kami lebih suka itu
kode kontribusi diformat dengan cara yang sama. Singkatnya, gunakan spasi-bukan-TAB untuk indentasi,
gunakan 2 spasi untuk setiap level indentasi, dan selain itu, ikuti gaya K&R.

Jika Anda menggunakan Emacs, tambahkan berikut ini ke salah satu file awal Anda (mis. ~/.emacs),
untuk membantu memastikan bahwa Anda mendapatkan lekukan yang benar:

;;; Di libguestfs, indentasi dengan spasi di mana-mana (bukan TAB).
;;; Pengecualian: mode Makefile dan ChangeLog.
(tambahkan-kait 'temukan-file-kait
'(lambda () (jika (dan nama-file buffer
(pencocokan string "/ libguestfs\\>"
(nama-file-buffer))
(bukan (nama mode sama string "Ubah Log"))
(bukan (nama mode sama string "Makefile")))
(setq indent-tabs-mode nihil))))

;;; Saat mengedit sumber C di libguestfs, gunakan gaya ini.
(defun libguestfs-c-mode ()
"Mode C dengan default yang disesuaikan untuk digunakan dengan libguestfs."
(interaktif)
(c-set-style "K&R")
(setq c-inden-tingkat 2)
(setq c-dasar-offset 2))
(tambahkan-kait 'c-mode-kait
'(lambda () (jika (pencocokan string "/libguestfs\\>"
(nama-file-buffer))
(libguestfs-c-mode))))

PENGUJIAN ANDA PERUBAHAN
Aktifkan peringatan saat kompilasi (dan perbaiki masalah yang ditemukan):

./configure --enable-gcc-warnings

Target yang berguna adalah:

"periksa"
Menjalankan rangkaian pengujian reguler.

Ini diimplementasikan menggunakan target "TES" automake biasa. Lihat pembuat mobilnya
dokumentasi untuk rincian.

"membuat cek-valgrind"
Menjalankan subset dari test suite di bawah valgrind.

Apa saja Makefile.am di pohon yang memiliki target "check-valgrind:" akan dijalankan oleh ini
aturan.

"buat check-valgrind-lokal-tamu"
Menjalankan subset suite pengujian di bawah valgrind menggunakan tamu libvirt yang diinstal secara lokal
(hanya baca).

"buat cek langsung"
Menjalankan semua pengujian menggunakan back-end alat default. Ini hanya memiliki efek jika non-
backend default dipilih menggunakan "./configure --with-default-backend=..."

"buat cek-valgrind-langsung"
Jalankan subset suite pengujian di bawah valgrind menggunakan back-end alat default.

"buat cek-uml"
Menjalankan semua pengujian menggunakan backend Linux User-Mode.

Karena tidak ada lokasi standar untuk kernel Linux User-Mode, Anda memiliki untuk mengatur
"LIBGUESTFS_HV" untuk menunjuk ke gambar kernel, misalnya:

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

"buat cek-valgrind-uml"
Jalankan semua pengujian menggunakan backend User-Mode Linux, di bawah valgrind.

Seperti di atas, Anda harus mengatur "LIBGUESTFS_HV" untuk menunjuk ke kernel.

"buat cek-dengan-upstream-qemu"
Menjalankan semua pengujian menggunakan biner qemu lokal. Itu mencari biner qemu di QEMUDIR
(default ke $HOME/h/qemu), tetapi Anda dapat mengatur ini ke direktori lain dengan perintah
garis, misalnya:

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

"buat cek-dengan-upstream-libvirt"
Jalankan semua tes menggunakan libvirt lokal. Ini hanya berpengaruh jika libvirt backend
dipilih menggunakan "./configure --with-default-backend=libvirt"

Itu mencari libvirt di LIBVIRTDIR (default ke $HOME/h/libvirt), tetapi Anda dapat mengatur ini
ke direktori lain pada baris perintah, misalnya:

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

"buat cek-lambat"
Menjalankan beberapa tes yang lambat/berjalan lama yang tidak dijalankan secara default.

Apa saja Makefile.am di pohon yang memiliki target "check-slow:" akan dijalankan oleh aturan ini.

"buat cek semua"
Setara dengan menjalankan semua aturan "make check*".

"buat cek-rilis"
Menjalankan subset dari aturan "make check*" yang harus dilewati sebelum tarball dapat
dilepaskan. Saat ini adalah:

· memeriksa

· cek-valgrind

· cek langsung

· cek-valgrind-langsung

· periksa-lambat

"buat cek instal"
Jalankan "make check" pada salinan libguestfs yang diinstal.

Versi libguestfs yang diinstal sedang diuji, dan versi libguestfs
pohon sumber harus sama.

Do:

./autogen.sh
bersihkan ||:
membuat
buat cek instal

DAEMON KUSTOM CETAK FORMATTER
Dalam kode daemon kami telah membuat formatter printf kustom %Q dan %R, yang digunakan untuk
melakukan shell quoting.

%Q String kutipan shell sederhana. Setiap spasi atau karakter shell lainnya diloloskan untuk Anda.

%R Sama seperti %Q kecuali string diperlakukan sebagai jalur yang diawali oleh sysroot.

Sebagai contoh:

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

akan menghasilkan "cat /sysroot/some\ path\ dengan\ spasi"

Catatan: Do tidak gunakan ini saat Anda meneruskan parameter ke "command{,r,v,rv}()"
fungsi. Parameter ini TIDAK perlu dikutip karena tidak diteruskan melalui
shell (sebagai gantinya, langsung ke exec). Anda mungkin ingin menggunakan fungsi "sysroot_path()"
namun.

PENGIRIMAN ANDA BARU API TINDAKAN
Kirim patch ke milis: http://www.redhat.com/mailman/listinfo/libguestfs dan
CC ke [email dilindungi].

PENGINTERNASIONALAN (I18N) TEKNIS
Kami mendukung i18n (gettext bagaimanapun) di perpustakaan.

Bagaimanapun banyak pesan datang dari daemon, dan kami tidak menerjemahkannya saat ini.
Salah satu alasannya adalah bahwa alat umumnya menghapus semua file lokal darinya, karena
mereka mengambil banyak ruang. Jadi kami harus membaca beberapa di antaranya, serta menyalin
file PO ke dalam alat.

Pesan debug tidak pernah diterjemahkan, karena ditujukan untuk pemrogram.

SOURCE KODE SUBDIREKTORI
meluruskan
pemindaian-penyelarasan-virt(1) perintah dan dokumentasi.

alat
Alat libguestfs, skrip build, dan sebagainya.

menampar
Skrip penyelesaian tab Bash.

build-aux
Berbagai skrip build yang digunakan oleh autotools.

pembangun
pembuat virt(1) perintah dan dokumentasi.

kucing The kucing-virt(1) virt-filesystem(1) log-virt(1) dan virt-ls(1) perintah dan
dokumentasi.

contrib
Kontribusi luar, bagian eksperimental.

menyesuaikan
virt-menyesuaikan(1) perintah dan dokumentasi.

daemon
Daemon yang berjalan di dalam alat libguestfs dan melakukan tindakan.

df kebajikan-df(1) perintah dan dokumentasi.

dib virt-dib(1) perintah dan dokumentasi.

diff
perbedaan-kebajikan(1) perintah dan dokumentasi.

dermaga Berbagai halaman manual.

mengedit
edit-virt(1) perintah dan dokumentasi.

contoh
Kode contoh C API.

ikan
ikan tamu(1), shell baris perintah, dan berbagai skrip shell yang dibangun di atas seperti
salinan-virt(1) salinan-kebaikan(1) virt-tar-in(1) kebajikan-tar-keluar(1).

format
format-virt(1) perintah dan dokumentasi.

sekering
gunung tamu(1), FUSE (sistem file ruang pengguna) dibangun di atas libguestfs.

generator
Generator yang sangat penting, digunakan untuk secara otomatis menghasilkan sejumlah besar
kode boilerplate C untuk hal-hal seperti RPC dan binding.

dapatkan-kernel
kernel-virt-get(1) perintah dan dokumentasi.

gnuli
Gnulib digunakan sebagai perpustakaan portabilitas. Salinan gnulib disertakan di sini.

inspektur
virt-inspektur(1), inspektur gambar mesin virtual.

logo
Logo yang digunakan pada website. Ikan itu disebut Arthur.

m4 Makro M4 digunakan oleh autoconf.

make-fs
kebajikan-membuat-fs(1) perintah dan dokumentasi.

mllib
Berbagai perpustakaan dan kode umum yang digunakan oleh virt-mengubah ukuran(1) dan alat-alat lain yang
ditulis dalam OCaml.

p2v virt-p2v(1) perintah, dokumentasi, dan skrip untuk membangun ISO atau disk virt-p2v
gambar.

po Terjemahan string gettext sederhana.

po-dokumen
Membangun infrastruktur dan file PO untuk terjemahan halaman manual dan file POD.
Akhirnya ini akan digabungkan dengan po direktori, tapi itu agak
rumit.

menyelamatkan
virt-penyelamatan(1) perintah dan dokumentasi.

mengubah ukuran
virt-mengubah ukuran(1) perintah dan dokumentasi.

sparify
virt-sparsify(1) perintah dan dokumentasi.

src Kode sumber ke pustaka C.

Sysprep
virt-sysprep(1) perintah dan dokumentasi.

tes
Tes.

data-tes
File dan data pengujian lainnya yang digunakan oleh pengujian.

alat tes
Alat uji untuk pengguna akhir untuk menguji apakah kombinasi qemu/kernel mereka akan bekerja dengan
libguestfs.

tmp Digunakan untuk file sementara saat menjalankan tes (bukan / Tmp dll). Alasannya adalah
sehingga Anda dapat menjalankan beberapa pengujian paralel libguestfs tanpa memiliki satu set
tes menimpa alat yang dibuat oleh yang lain.

alat
Alat baris perintah yang ditulis dalam Perl (virt-win-reg(1) dan banyak lainnya).

v2v virt-v2v(1) perintah dan dokumentasi.

situs web
The http://libguestfs.org file situs web.

csharp
diperoleh
objek gobjek
golang
Haskell
Jawa
bulan
ocaml
php
perl
ular sanca
rubi
Ikatan bahasa.

PEMBUATAN A STABIL RELEASE
Saat kami membuat rilis stabil, ada beberapa langkah yang didokumentasikan di sini. Lihat "LIBGUESTFS
NOMOR VERSI" di tamu(3) untuk informasi umum tentang kebijakan cabang stabil.

· Centang "make && make check" bekerja setidaknya di Fedora, Debian dan Ubuntu.

· Centang "./configure --without-libvirt" berfungsi.

· Selesaikan guestfs-catatan-rilis.pod

· Dorong dan tarik dari Zanata.

Menjalankan:

dorongan zanata

untuk mendorong file POT terbaru ke Zanata. Lalu lari:

./zanata-pull.sh

yang merupakan pembungkus untuk menarik terjemahan terbaru *.po file.

· Pertimbangkan untuk memperbarui gnulib ke versi upstream terbaru.

· Buat direktori stabil dan pengembangan baru di bawah http://libguestfs.org/download.

· Sunting situs web/index.html.in.

· Atur versi (dalam konfigurasi.ac) ke yang baru stabil versi, mis. 1.XX.0, dan komit
itu:

./konfigurasi lokal
buat distclean -k
./konfigurasi lokal
membuat && membuat perbedaan
buat komitmen pemelihara
buat tag pemelihara

· Buat cabang stabil di git:

cabang git stable-1.XX
git Push Origin stable-1.XX

· Lakukan rilis penuh dari cabang stabil.

· Atur versi ke versi pengembangan berikutnya dan lakukan itu. Opsional lakukan penuh
pelepasan cabang pengembangan.

Gunakan guestfs-hacking online menggunakan layanan onworks.net