guestfs-hacking - Online nel cloud

PROGRAMMA:

NOME

guestfs-hacking - estendere e contribuire a libguestfs

DESCRIZIONE

Questa pagina di manuale è per gli hacker che vogliono estendere libguestfs stesso.

OVERVIEW OF LA FONTE CODICE
Il sorgente Libguestfs si trova nel repository github
https://github.com/libguestfs/libguestfs

Grandi quantità di codice standard in libguestfs (RPC, associazioni, documentazione) sono
generato. Ciò significa che molti file sorgente sembreranno mancare da a
checkout git semplice. Devi eseguire il generatore ("./autogen.sh && make -C
generatore") per creare quei file.

Libguestfs utilizza un sistema di compilazione basato su autotools, con i file principali che sono configurare.ac
ed Makefile.am. generatore la sottodirectory contiene il generatore, più i file che descrivono
l'API. Il src la sottodirectory contiene l'origine per la libreria. Il apparecchio ed demone
le sottodirectory contengono l'origine del codice che costruisce l'appliance e il codice
che viene eseguito rispettivamente nell'apparecchio. Altre directory sono trattate nella sezione
"SOTTODIRECTORY CODICE SORGENTE" di seguito.

A parte il fatto che tutti i punti di ingresso dell'API passano attraverso un codice generato, la libreria è
semplice. (In effetti, anche il codice generato è progettato per essere leggibile e dovrebbe
essere letto come codice ordinario). Alcune azioni vengono eseguite interamente nella libreria e sono scritte come C
funzioni nei file sotto src. Altri vengono inoltrati al demone dove (dopo alcuni
marshalling RPC generato) appaiono come funzioni C nei file sotto demone.

Per compilare dal sorgente, leggi prima il file "README".

Locale* FILE
File nella directory principale dei sorgenti che iniziano con il prefisso Locale* vengono ignorati da git.
Questi file possono contenere la configurazione locale o gli script necessari per compilare libguestfs.

Per convenzione, ho un file chiamato configurazione locale che è un semplice involucro intorno
autogen.sh contenente le personalizzazioni di configurazione locali di cui ho bisogno:

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

Quindi posso usarlo per creare libguestfs:

./localconfigure && make

Se c'è un file nella directory di build superiore chiamato localenv, quindi verrà fornito da
"fare". Questo file può contenere qualsiasi variabile di ambiente locale necessaria, ad es. per aver saltato
test:

# Usa un binario Python alternativo.
esporta PYTHON=python3
# Salta questo test, è rotto.
esporta SKIP_TEST_BTRFS_FSCK=1

Si noti che localenv è incluso dal Makefile in alto (quindi è un frammento di Makefile). Ma se
è anche di provenienza tua configurazione locale script quindi viene utilizzato come script di shell.

AGGIUNTA A NUOVA API AZIONE
Poiché vengono generate grandi quantità di codice standard in libguestfs, questo lo rende facile
per estendere l'API libguestfs.

Per aggiungere una nuova azione API ci sono due modifiche:

1. È necessario aggiungere una descrizione della chiamata (nome, parametri, tipo restituito, test,
documentazione) a generatore/azioni.ml.

Esistono due tipi di azioni API, a seconda che la chiamata passi attraverso il
demone nell'appliance, o è servito interamente dalla libreria (vedi "ARCHITETTURA" in
guestfs-interni(3)). "guestfs_sync" in ospiti(3) è un esempio del primo,
poiché la sincronizzazione viene eseguita nell'apparecchio. "guestfs_set_trace" in ospiti(3) è un
esempio di quest'ultimo, poiché viene mantenuto un flag di traccia nell'handle e in tutti i tracing
è fatto dal lato della biblioteca.

La maggior parte delle nuove azioni sono del primo tipo e vengono aggiunte all'elenco "daemon_functions".
Ogni funzione ha un numero di procedura univoco utilizzato nel protocollo RPC che viene assegnato
a quell'azione quando pubblichiamo libguestfs e non può essere riutilizzato. Prendi l'ultima
numero di procedura e incrementarlo.

Per le azioni di sola libreria del secondo tipo, aggiungere all'elenco "non_daemon_functions".
Poiché queste funzioni sono gestite dalla libreria e non viaggiano sull'RPC
meccanismo al demone, queste funzioni non necessitano di un numero di procedura, quindi
numero di procedura è impostato su "-1".

2. Implementare l'azione (in C):

Per le azioni del demone, implementa la funzione "do_ " nella directory "daemon/".

Per le azioni della libreria, implementa la funzione "guestfs_impl_ " nella "src/"
directory.

In entrambi i casi, usa un'altra funzione come esempio di cosa fare.

Dopo aver apportato queste modifiche, usa "make" per compilare.

Nota che non è necessario implementare l'RPC, i vincoli di lingua, le pagine di manuale o altro
altro. È tutto generato automaticamente dalla descrizione di OCaml.

AGGIUNTA PROVE PER AN API AZIONE
Puoi fornire zero o tutti i test che desideri per chiamata API. I test possono essere
aggiunto come parte della descrizione dell'API (generatore/azioni.ml), o in alcuni casi più rari tu
potrebbe voler rilasciare uno script in "tests/*/". Nota che aggiungere uno script a "tests/*/" è
più lento, quindi se possibile usa il primo metodo.

Quanto segue descrive l'ambiente di test utilizzato quando si aggiunge un test API in azioni.ml.

L'ambiente di test ha 4 dispositivi a blocchi:

/ dev / sda 500MB
Dispositivo di blocco generale per il test.

/ Dev / sdb 500MB
/ dev / sdb1 è un filesystem ext2 utilizzato per testare le operazioni di scrittura del filesystem.

/ Dev / sdc 10MB
Utilizzato in alcuni test in cui sono necessari due dispositivi a blocchi.

/ Dev / sdd
ISO con contenuto fisso (vedi immagini/test.iso).

Per poter eseguire i test in un ragionevole lasso di tempo, l'appliance libguestfs e
i dispositivi a blocchi vengono riutilizzati tra i test. Quindi non provare a testare "guestfs_kill_subprocess" in
ospiti(3) :-x

Ogni test inizia con uno scenario iniziale, selezionato utilizzando una delle espressioni "Init*",
descritto in generatore/tipi.ml. Questi inizializzano i dischi menzionati sopra in a
modo particolare come documentato in tipi.ml. Non dovresti dare per scontato nulla sul
contenuto precedente di altri dischi non inizializzati.

È possibile aggiungere una clausola di prerequisito a qualsiasi singolo test. Questo è un controllo in fase di esecuzione,
che, se fallisce, fa saltare il test. Utile se si prova un comando che
potrebbe non funzionare su tutte le varianti delle build di libguestfs. Un test che ha prerequisito di
"Sempre" significa correre incondizionatamente.

Inoltre, i confezionatori possono saltare i singoli test impostando prima le variabili di ambiente
eseguendo "verifica".

SALTA_TEST_ _ =1

ad esempio: "SKIP_TEST_COMMAND_3=1" salta il test n. 3 di "guestfs_command" in ospiti(3).

o:

SALTA_TEST_ =1

ad esempio: "SKIP_TEST_ZEROFREE=1" salta tutti i "guestfs_zerofree" in ospiti(3) prove.

I packager possono eseguire solo determinati test impostando ad esempio:

TEST_ONLY="vfs_type zerofree"

See test/c-api/test.c per maggiori dettagli su come funzionano queste variabili di ambiente.

DEBUG NUOVA API AZIONI
Testare il funzionamento delle nuove azioni prima di inviarle.

Puoi usare guestfish per provare nuovi comandi.

Il debug del demone è un problema perché viene eseguito all'interno di un ambiente minimo. però
puoi inviare messaggi fprintf nel demone a stderr e verranno visualizzati se usi
"pesce ospite -v".

AGGIUNTA A NUOVA LINGUA RILEGATURA
Tutti i collegamenti linguistici devono essere generati dal generatore (vedi il generatore sottocartella).

Non c'è ancora documentazione per questo. Ti suggeriamo di guardare un'associazione esistente, ad es.
generatore/ocaml.ml or generatore/perl.ml.

AGGIUNTA PROVE PER LINGUA ATTACCHI
Le associazioni linguistiche dovrebbero venire con i test. In precedenza il test delle associazioni linguistiche era
piuttosto ad-hoc, ma abbiamo cercato di formalizzare l'insieme di test che ogni lingua
vincolante dovrebbe usare.

Attualmente solo i collegamenti OCaml e Perl implementano effettivamente l'intero set di test e
i collegamenti OCaml sono canonici, quindi dovresti emulare ciò che fanno i test OCaml.

Questo lo schema di numerazione utilizzato dai test:

- 000+ test di base:

010 carica la libreria
020 crea
030 crea-flag
040 crea più maniglie
050 test setting e ottenimento delle proprietà di configurazione
060 chiusura esplicita
065 chiusura implicita (nei linguaggi di GC)
070 optarg

- 100 avvia, crea partizioni e LV e filesystem

- 400+ eventi:

410 Chiudi evento
420 messaggi di registro
430 messaggi di avanzamento

- 800+ test di regressione (specifici per la lingua)

- 900+ eventuali altri test personalizzati per la lingua

Per risparmiare tempo durante l'esecuzione dei test, solo 100, 430, 800+, 900+ dovrebbero avviare la maniglia.

FORMATTAZIONE CODICE
Il nostro codice sorgente C generalmente aderisce ad alcune convenzioni di formattazione del codice di base. Il
la base di codice esistente non è del tutto coerente su questo fronte, ma preferiamo che
codice contribuito essere formattato in modo simile. In breve, usa spazi-non-TAB per il rientro,
usa 2 spazi per ogni livello di rientro e, a parte questo, segui lo stile K&R.

Se usi Emacs, aggiungi quanto segue a uno dei tuoi file di avvio (ad es. ~/.emacs),
per aiutarti a ottenere il rientro corretto:

;;; In libguestfs, rientra con spazi ovunque (non TAB).
;;; Eccezioni: modalità Makefile e ChangeLog.
(add-hook 'trova-file-hook
'(lambda() (if (e nome-file-buffer)
(corrispondenza stringa "/libguestfs\\>"
(nome-file-buffer))
(not (nome della modalità uguale a stringa "Change Log"))
(not (nome della modalità uguale a stringa "Makefile")))
(setq indent-tabs-mode nil))))

;;; Quando modifichi i sorgenti C in libguestfs, usa questo stile.
(defun libguestfs-c-mode()
"Modalità C con impostazioni predefinite modificate per l'uso con libguestfs."
(interattivo)
(stile c-set "K&R")
(setq c-indent-livello 2)
(setq c-base-offset 2))
(aggiungi hook 'c-mode-hook
'(lambda() (if (string-match "/libguestfs\\>"
(nome-file-buffer))
(libguestfs-c-mode))))

TEST AL VOSTRO MODIFICHE
Abilita gli avvisi durante la compilazione (e risolvi eventuali problemi riscontrati):

./configure --enable-gcc-avvisi

Obiettivi utili sono:

"verificare"
Esegue la normale suite di test.

Questo è implementato usando il normale target "TEST" di automake. Guarda l'automake
documentazione per i dettagli.

"fare check-valgrind"
Esegue un sottoinsieme della suite di test sotto valgrind.

Qualsiasi Makefile.am nell'albero che ha un target "check-valgrind:" verrà eseguito da questo
regola.

"fare check-valgrind-local-ospiti"
Esegue un sottoinsieme della suite di test sotto valgrind utilizzando guest libvirt installati localmente
(sola lettura).

"fare assegno diretto"
Esegue tutti i test utilizzando il back-end dell'appliance predefinito. Questo ha effetto solo se un
il backend predefinito è stato selezionato utilizzando "./configure --with-default-backend=..."

"fare check-valgrind-direct"
Esegui un sottoinsieme della suite di test in valgrind utilizzando il back-end dell'appliance predefinito.

"fare check-uml"
Esegue tutti i test utilizzando il backend Linux in modalità utente.

Poiché non esiste una posizione standard per il kernel Linux in modalità utente, avere per impostare
"LIBGUESTFS_HV" per puntare all'immagine del kernel, ad esempio:

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

"fare check-valgrind-uml"
Esegue tutti i test utilizzando il backend Linux in modalità utente, sotto valgrind.

Come sopra, devi impostare "LIBGUESTFS_HV" in modo che punti al kernel.

"fare il check-con-upstream-qemu"
Esegue tutti i test utilizzando un binario qemu locale. Cerca il binario qemu in QEMUDIR
(predefinito su $HOME/g/qemu), ma puoi impostarlo in un'altra directory con il comando
riga, ad esempio:

fare il check-with-upstream-qemu QEMUDIR=/usr/src/qemu

"fare il check-with-upstream-libvirt"
Esegue tutti i test utilizzando una libvirt locale. Questo ha effetto solo se il backend libvirt
è stato selezionato usando "./configure --with-default-backend=libvirt"

Cerca libvirt in LIBVIRTDIR (predefinito su $HOME/d/libvirt), ma puoi impostare questo
in un'altra directory sulla riga di comando, ad esempio:

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

"fare il check-lento"
Esegue alcuni test lenti/di lunga durata che non vengono eseguiti per impostazione predefinita.

Qualsiasi Makefile.am nell'albero che ha un target "check-slow:" verrà eseguito da questa regola.

"fare il check-all"
Equivalente all'esecuzione di tutte le regole "make check*".

"fare assegno di rilascio"
Esegue un sottoinsieme di regole "make check*" che devono essere superate prima che un tarball possa essere
rilasciato. Attualmente questo è:

· dai un'occhiata

· controlla-valgrind

· check-diretto

· check-valgrind-diretto

· check-lento

"fare installcheck"
Esegui "make check" sulla copia installata di libguestfs.

La versione di libguestfs installata in fase di test e la versione di libguestfs
l'albero di origine deve essere lo stesso.

Do:

./autogen.sh
pulisci ||:
make
fare installcheck

DEMONE CUSTOM STAMPA FORMATORI
Nel codice del demone abbiamo creato formattatori printf personalizzati %Q e %R, che sono usati per
fare la citazione della shell.

%Q Semplice stringa tra virgolette della shell. Eventuali spazi o altri caratteri di shell vengono sfuggiti per te.

%R Uguale a %Q eccetto che la stringa è trattata come un percorso preceduto da sysroot.

Per esempio:

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

produrrebbe "cat /sysroot/some\path\ with\spaces"

Nota: Do non usa questi quando stai passando parametri al "command{,r,v,rv}()"
funzioni. Questi parametri NON devono essere quotati perché non vengono passati tramite il
shell (invece, direttamente a exec). Probabilmente vorrai usare la funzione "sysroot_path()"
tuttavia.

PRESENTAZIONE AL VOSTRO NUOVA API AZIONI
Invia le patch alla mailing list: http://www.redhat.com/mailman/listinfo/libguestfs ed
CC a [email protected].

INTERNAZIONALIZZAZIONE (I18N) SUPPORTO
Supportiamo i18n (gettext comunque) nella libreria.

Tuttavia, molti messaggi provengono dal demone e al momento non li traduciamo.
Una ragione è che l'appliance in genere ha tutti i file locali rimossi da essa, perché
occupano molto spazio. Quindi dovremmo leggerne alcuni, oltre a copiare il nostro
file PO nell'appliance.

I messaggi di debug non vengono mai tradotti, poiché sono destinati ai programmatori.

FONTE CODICE SOTTODIRECTORY
allineare
virt-allineamento-scansione(1) comando e documentazione.

apparecchio
L'appliance libguestfs, gli script di compilazione e così via.

bash
Script di completamento della scheda Bash.

build-aux
Vari script di build utilizzati da autotools.

costruttore
costruttore di virtù(1) comando e documentazione.

gatto I virt-gatto(1) filesystem-virt(1) registro virtuale(1) e virt-ls(1) comandi e
documentazione.

contrib
Contributi esterni, parti sperimentali.

personalizzare
virt-personalizzare(1) comando e documentazione.

demone
Il demone che viene eseguito all'interno dell'appliance libguestfs ed esegue azioni.

df virt-df(1) comando e documentazione.

ancora virt-dib(1) comando e documentazione.

diff
virt-diff(1) comando e documentazione.

doc Varie pagine di manuale.

edit
virt-modifica(1) comando e documentazione.

Esempi
Codice di esempio API C.

pesce
pesce ospite(1), la shell della riga di comando e vari script di shell costruiti sopra come
copia-virtù(1) copia-virtù(1) virt-tar-in(1) virt-tar-out(1).

formato
formato-virt(1) comando e documentazione.

fusibile
ospite(1), FUSE (filesystem in spazio utente) costruito su libguestfs.

generatore
Il generatore di cruciale importanza, utilizzato per generare automaticamente grandi quantità di
codice C standard per cose come RPC e associazioni.

get-kernel
virt-get-kernel(1) comando e documentazione.

gnulib
Gnulib è usato come libreria di portabilità. Una copia di gnulib è inclusa qui sotto.

ispettore
ispettore-virt(1), l'ispettore dell'immagine della macchina virtuale.

logo
Logo utilizzato nel sito web. A proposito, il pesce si chiama Arthur.

m4 Macro M4 utilizzate da autoconf.

make-fs
virt-make-fs(1) comando e documentazione.

mllib
Varie librerie e codice comune utilizzato da ridimensionamento virtuale(1) e gli altri strumenti che sono
scritto in OCaml.

p2v virt-p2v(1) comando, documentazione e script per creare l'ISO o il disco virt-p2v
immagine.

po Traduzioni di semplici stringhe gettext.

po-docs
L'infrastruttura di compilazione e i file PO per la traduzione di manpage e file POD.
Alla fine questo sarà combinato con il po directory, ma questo è piuttosto
complicato.

salvataggio
virt-salvataggio(1) comando e documentazione.

ridimensionare
ridimensionamento virtuale(1) comando e documentazione.

sparsificare
virt-sparsificare(1) comando e documentazione.

src Codice sorgente per la libreria C.

sysprep
virt-sysprep(1) comando e documentazione.

test
Test.

dati di test
File e altri dati di test utilizzati dai test.

strumento di prova
Strumento di test per gli utenti finali per verificare se la loro combinazione qemu/kernel funzionerà con
libguestfs.

tmp Usato per i file temporanei durante l'esecuzione dei test (invece di / Tmp eccetera). Il motivo è
in modo da poter eseguire più test paralleli di libguestfs senza avere un set di
test sovrascrivendo l'appliance creata da un altro.

strumenti
Strumenti da riga di comando scritti in Perl (virt-win-reg(1) e molti altri).

v2v virt-v2v(1) comando e documentazione.

sito web
I http://libguestfs.org file del sito web.

nitido
Erlang
oggetto
golang
Haskell
Giava
luna
ocam
php
perl
python
rubino
Legami linguistici.

MAKING A STABILE STAMPA
Quando facciamo una versione stabile, ci sono diversi passaggi documentati qui. Vedere "LIBGUESTFS
NUMERI VERSIONE" in ospiti(3) per informazioni generali sulla politica del ramo stabile.

· Controllare che "make && make check" funzioni almeno su Fedora, Debian e Ubuntu.

· Controllare che "./configure --with-libvirt" funzioni.

· Finalizzare guestfs-note-di-rilascio.pod

· Spingi e tira da Zanata.

Esegui:

spinta zanata

per inviare gli ultimi file POT a Zanata. Quindi eseguire:

./zanata-pull.sh

che è un wrapper per tirare l'ultimo tradotto *.po File.

· Considerare l'aggiornamento di gnulib all'ultima versione upstream.

· Creare nuove directory stabili e di sviluppo sotto http://libguestfs.org/download.

· Modificare sito web/index.html.in.

· Impostare la versione (in configurare.ac) al nuovo stabile versione, es. 1.XX.0 e commit
esso:

./localconfig
rendere distclean -k
./localconfig
crea && crea dist
fare commit-manutentore
fai il tag del manutentore

· Crea il ramo stabile in git:

ramo git stable-1.XX
git push origine stable-1.XX

· Eseguire un rilascio completo del ramo stabile.

· Imposta la versione alla prossima versione di sviluppo e confermala. Facoltativamente fai un pieno
rilascio del ramo di sviluppo.

Usa guestfs-hacking online usando i servizi onworks.net