guestfs-hacking: en línea en la nube

PROGRAMA:

NOMBRE

guestfs-hacking: ampliar y contribuir a libguestfs

DESCRIPCIÓN

Esta página de manual está destinada a los piratas informáticos que desean ampliar libguestfs.

Descripción OF EL FUENTE CÓDIGO
La fuente de libguestfs se encuentra en el repositorio de github
https://github.com/libguestfs/libguestfs

Grandes cantidades de código repetitivo en libguestfs (RPC, enlaces, documentación) son
generado. Esto significa que parecerá que faltan muchos archivos de origen en un
pago sencillo de git. Tienes que ejecutar el generador ("./autogen.sh && make -C
generador ") para crear esos archivos.

Libguestfs utiliza un sistema de compilación basado en autotools, con los archivos principales configurar.ac
y Makefile.am. generador subdirectorio contiene el generador, más archivos que describen
la API. los src El subdirectorio contiene la fuente de la biblioteca. los aparato y demonio
Los subdirectorios contienen la fuente del código que compila el dispositivo y el código
que se ejecuta en el aparato respectivamente. Otros directorios se tratan en la sección
"SUBDIRECTORIOS DE CÓDIGO FUENTE" a continuación.

Aparte del hecho de que todos los puntos de entrada de la API pasan por algún código generado, la biblioteca es
simple. (De hecho, incluso el código generado está diseñado para ser legible y debería
leerse como código ordinario). Algunas acciones se ejecutan completamente en la biblioteca y están escritas como C
funciones en archivos bajo src. Otros se reenvían al demonio donde (después de algunos
cálculo de referencias RPC generado) aparecen como funciones C en archivos bajo demonio.

Para compilar desde el código fuente, primero lea el archivo "README".

local* ARCHIVOS
Archivos en el directorio de origen superior que comienzan con el prefijo local* son ignorados por git.
Estos archivos pueden contener la configuración local o los scripts que necesita para construir libguestfs.

Por convención, tengo un archivo llamado configuración local que es un envoltorio simple alrededor
autogen.sh que contiene las personalizaciones de configuración local que necesito:

. localenv
./autogen.sh\
--with-default-backend = libvirt \
--enable-gcc-advertencias \
--enable-gtk-doc \
-C \
PS

Entonces puedo usar esto para construir libguestfs:

./localconfigure && hacer

Si hay un archivo en el directorio de compilación superior llamado localenv, entonces será obtenido por
"fabricar". Este archivo puede contener cualquier variable de entorno local necesaria, por ejemplo. por saltar
pruebas:

# Utilice un binario de Python alternativo.
exportar PYTHON = python3
# Omita esta prueba, está roto.
exportar SKIP_TEST_BTRFS_FSCK = 1

Tenga en cuenta que localenv está incluido en el Makefile superior (por lo que es un fragmento de Makefile). Pero si
también lo obtiene su configuración local script, entonces se utiliza como script de shell.

AGREGANDO A NUEVO API ACCIÓN
Debido a que se generan grandes cantidades de código repetitivo en libguestfs, esto facilita
para ampliar la API libguestfs.

Para agregar una nueva acción de API, hay dos cambios:

1. Debe agregar una descripción de la llamada (nombre, parámetros, tipo de retorno, pruebas,
documentación) a generador / actions.ml.

Hay dos tipos de acciones de API, dependiendo de si la llamada pasa al
daemon en el dispositivo, o es atendido por completo por la biblioteca (ver "ARQUITECTURA" en
guestfs-internos(3)). "guestfs_sync" en invitados(3) es un ejemplo del primero,
ya que la sincronización se realiza en el dispositivo. "guestfs_set_trace" en invitados(3) es un
ejemplo de lo último, ya que se mantiene una bandera de seguimiento en el identificador y todo el seguimiento
se hace en el lado de la biblioteca.

La mayoría de las acciones nuevas son del primer tipo y se agregan a la lista "daemon_functions".
Cada función tiene un número de procedimiento único utilizado en el protocolo RPC que se asigna
a esa acción cuando publicamos libguestfs y no se puede reutilizar. Toma lo último
número de procedimiento e increméntelo.

Para las acciones de biblioteca del segundo tipo, agregue a la lista "non_daemon_functions".
Dado que estas funciones son atendidas por la biblioteca y no viajan por el RPC
mecanismo para el demonio, estas funciones no necesitan un número de procedimiento, por lo que el
el número de procedimiento se establece en "-1".

2. Implementar la acción (en C):

Para acciones de demonio, implemente la función "do_ "en el directorio" daemon / ".

Para las acciones de la biblioteca, implemente la función "guestfs_impl_ "en el" src / "
directorio.

En cualquier caso, utilice otra función como ejemplo de qué hacer.

Después de realizar estos cambios, use "make" para compilar.

Tenga en cuenta que no necesita implementar el RPC, los enlaces de idioma, las páginas del manual ni nada
demás. Todo se genera automáticamente a partir de la descripción de OCaml.

AGREGANDO TESTS PARA AN API ACCIÓN
Puede proporcionar cero o tantas pruebas como desee por llamada a la API. Las pruebas pueden ser
agregado como parte de la descripción de la API (generador / actions.ml), o en algunos casos más raros
es posible que desee colocar un script en "tests / * /". Tenga en cuenta que agregar un script a "tests / * /" es
más lento, así que, si es posible, utilice el primer método.

A continuación se describe el entorno de prueba que se utiliza cuando agrega una prueba de API en acciones.ml.

El entorno de prueba tiene 4 dispositivos de bloque:

/ Dev / sda 500MB
Dispositivo de bloqueo general para pruebas.

/ dev / sdb 500MB
/ dev / sdb1 es un sistema de archivos ext2 utilizado para probar las operaciones de escritura del sistema de archivos.

/ dev / sdc 10MB
Se utiliza en algunas pruebas en las que se necesitan dos dispositivos de bloque.

/ dev / sdd
ISO con contenido fijo (ver images / test.iso).

Para poder ejecutar las pruebas en un período de tiempo razonable, el dispositivo libguestfs y
los dispositivos de bloque se reutilizan entre pruebas. No intente probar "guestfs_kill_subprocess" en
invitados(3): -x

Cada prueba comienza con un escenario inicial, seleccionado mediante una de las expresiones "Init *",
descrita en generador / tipos.ml. Estos inicializan los discos mencionados anteriormente en un
forma particular como se documenta en tipos.ml. No debe asumir nada sobre el
contenido anterior de otros discos que no están inicializados.

Puede agregar una cláusula de requisito previo a cualquier prueba individual. Esta es una verificación en tiempo de ejecución,
que, si falla, hace que se omita la prueba. Útil si se prueba un comando que
puede que no funcione en todas las variaciones de las compilaciones de libguestfs. Una prueba que tiene el requisito previo de
"Siempre" significa correr incondicionalmente.

Además, los empaquetadores pueden omitir pruebas individuales configurando variables de entorno antes
ejecutando "hacer cheque".

SKIP_TEST_ _ = 1

por ejemplo: "SKIP_TEST_COMMAND_3 = 1" omite la prueba n. ° 3 de "guestfs_command" en invitados(3).

o bien:

SKIP_TEST_ = 1

por ejemplo: "SKIP_TEST_ZEROFREE = 1" omite todo "guestfs_zerofree" en invitados(3) pruebas.

Los empaquetadores pueden ejecutar solo ciertas pruebas configurando, por ejemplo:

TEST_ONLY = "vfs_type zerofree"

See tests / c-api / tests.c para obtener más detalles sobre cómo funcionan estas variables de entorno.

DEPURACIÓN NUEVO API ACCIONES
Pruebe el funcionamiento de nuevas acciones antes de enviarlas.

Puede utilizar guestfish para probar nuevos comandos.

La depuración del demonio es un problema porque se ejecuta dentro de un entorno mínimo. Sin embargo
puede enviar mensajes fprintf en el demonio a stderr, y aparecerán si usa
"pez invitado -v".

AGREGANDO A NUEVO IDIOMA UNIÓN
Todos los enlaces de idioma deben ser generados por el generador (consulte el generador subdirectorio).

Aún no hay documentación para esto. Le sugerimos que consulte una encuadernación existente, por ejemplo.
generador / ocaml.ml or generador / perl.ml.

AGREGANDO TESTS PARA IDIOMA ENLACES
Los enlaces de idioma deben venir con las pruebas. Anteriormente, la prueba de las vinculaciones de idiomas era
más bien ad-hoc, pero hemos estado tratando de formalizar el conjunto de pruebas que cada idioma
la encuadernación debe usar.

Actualmente, solo los enlaces OCaml y Perl realmente implementan el conjunto completo de pruebas, y
los enlaces OCaml son canónicos, por lo que debe emular lo que hacen las pruebas OCaml.

Este es el esquema de numeración utilizado por las pruebas:

- Más de 000 pruebas básicas:

010 cargar la biblioteca
020 crear
030 crear banderas
040 crear varios identificadores
050 configuración de prueba y obtención de propiedades de configuración
060 cierre explícito
065 cierre implícito (en lenguajes GC)
070 optar

- 100 lanzamientos, creación de particiones y LV y sistemas de archivos

- 400+ eventos:

410 evento cerrado
420 mensajes de registro
430 mensajes de progreso

- Más de 800 pruebas de regresión (específicas del idioma)

- Más de 900 pruebas personalizadas para el idioma.

Para ahorrar tiempo al ejecutar las pruebas, solo 100, 430, 800+, 900+ deberían iniciar el mango.

FORMATEAR CÓDIGO
Nuestro código fuente C generalmente se adhiere a algunas convenciones básicas de formato de código. los
La base de código existente no es totalmente consistente en este frente, pero preferimos que
el código contribuido tenga un formato similar. En resumen, use espacios en lugar de TAB para la sangría,
use 2 espacios para cada nivel de sangría, y aparte de eso, siga el estilo K&R.

Si usa Emacs, agregue lo siguiente a uno de sus archivos de inicio (por ejemplo, ~ / .emacs),
para ayudar a asegurarse de obtener la sangría correcta:

;;; En libguestfs, sangra con espacios en todas partes (no TAB).
;;; Excepciones: modos Makefile y ChangeLog.
(agregar-gancho 'buscar-archivo-gancho
'(lambda () (if (y buffer-file-name
(coincidencia de cadena "/ libguestfs \\>"
(nombre-archivo-búfer))
(no (string-equal mode-name "Change Log"))
(no (nombre de modo igual a cadena "Makefile")))
(setq sangría-pestañas-modo nulo))))

;;; Cuando edite fuentes C en libguestfs, use este estilo.
(defun libguestfs-c-mode()
"Modo C con valores predeterminados ajustados para usar con libguestfs".
(interactivo)
(estilo c-set "K&R")
(setq c-sangría-nivel 2)
(setq c-desplazamiento-básico 2))
(add-hook 'c-mode-hook
'(lambda () (if (string-match "/ libguestfs \\>"
(nombre-archivo-búfer))
(modo libguestfs-c))))

Servicios TU CAMBIOS
Habilite las advertencias al compilar (y solucione cualquier problema que encuentre):

./configure --enable-gcc-advertencias

Los objetivos útiles son:

"hacer el cheque"
Ejecuta el conjunto de pruebas normal.

Esto se implementa utilizando el objetivo "TESTS" habitual de automake. Ver el automake
documentación para más detalles.

"hacer check-valgrind"
Ejecuta un subconjunto del conjunto de pruebas bajo valgrind.

Alquiler y venta Makefile.am en el árbol que tiene un "check-valgrind:" el objetivo será ejecutado por este
regla.

"hacer check-valgrind-locales-invitados"
Ejecuta un subconjunto del conjunto de pruebas en valgrind utilizando invitados libvirt instalados localmente
(solo lectura).

"hacer cheque directo"
Ejecuta todas las pruebas utilizando el back-end del dispositivo predeterminado. Esto solo tiene algún efecto si un
El backend predeterminado se seleccionó usando "./configure --with-default-backend = ..."

"hacer check-valgrind-direct"
Ejecute un subconjunto del conjunto de pruebas en valgrind utilizando el back-end del dispositivo predeterminado.

"hacer check-uml"
Ejecuta todas las pruebas utilizando el backend de Linux en modo de usuario.

Como no existe una ubicación estándar para el kernel de Linux en modo de usuario, have para establecer
"LIBGUESTFS_HV" para apuntar a la imagen del kernel, por ejemplo:

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

"hacer check-valgrind-uml"
Ejecuta todas las pruebas utilizando el backend de Linux en modo de usuario, en valgrind.

Como se indicó anteriormente, debe configurar "LIBGUESTFS_HV" para que apunte al kernel.

"hacer check-with-upstream-qemu"
Ejecuta todas las pruebas utilizando un binario qemu local. Busca el binario qemu en QEMUDIR
(predeterminado en $ HOME / d / qemu), pero puede configurarlo en otro directorio con el comando
línea, por ejemplo:

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

"hacer check-with-upstream-libvirt"
Ejecuta todas las pruebas usando un libvirt local. Esto solo tiene algún efecto si el backend libvirt
fue seleccionado usando "./configure --with-default-backend = libvirt"

Busca libvirt en LIBVIRTDIR (por defecto es $ HOME / d / libvirt), pero puede configurar esto
a otro directorio en la línea de comando, por ejemplo:

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

"hacer el cheque lento"
Ejecuta algunas pruebas de ejecución lenta / prolongada que no se ejecutan de forma predeterminada.

Alquiler y venta Makefile.am en el árbol que tiene un objetivo "check-slow:" se ejecutará según esta regla.

"hacer check-all"
Equivalente a ejecutar todas las reglas de "verificación *".

"hacer check-release"
Ejecuta un subconjunto de reglas "make check *" que deben aprobarse antes de que se pueda ejecutar un tarball.
liberado. Actualmente esto es:

· cheque

· Cheque-valgrind

· Comprobar-directo

· Comprobar-valgrind-directo

· Comprobar lento

"hacer installcheck"
Ejecute "make check" en la copia instalada de libguestfs.

La versión de libguestfs instalada que se está probando y la versión de libguestfs
el árbol de origen debe ser el mismo.

Que Hacer:

./autogen.sh
hacer limpio ||:
make
hacer installcheck

DEMONIO PERSONALIZADO IMPRIMIR Formateadores
En el código del demonio hemos creado los formateadores de printf personalizados% Q y% R, que se utilizan para
hacer cotizaciones de shell.

% Q Cadena entre comillas de shell simple. Cualquier espacio u otro carácter de shell se le escapan.

% R Igual que% Q excepto que la cadena se trata como una ruta prefijada por la raíz del sistema.

Por ejemplo:

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

produciría "cat / sysroot / some \ path \ with \ spaces"

Nota: Do no utilícelos cuando esté pasando parámetros al "comando {, r, v, rv} ()"
funciones. Estos parámetros NO necesitan ser citados porque no se pasan a través del
shell (en su lugar, directamente al ejecutivo). Probablemente quieras usar la función "sysroot_path ()"
sin embargo.

SUMISIÓN TU NUEVO API ACCIONES
Envíe los parches a la lista de correo: http://www.redhat.com/mailman/listinfo/libguestfs y
CC a [email protected].

INTERNACIONALIZACION (I18N) APOYAR
Admitimos i18n (gettext de todos modos) en la biblioteca.

Sin embargo, muchos mensajes provienen del demonio y no los traducimos en este momento.
Una razón es que el dispositivo generalmente tiene todos los archivos de configuración regional eliminados, porque
ocupan mucho espacio. Así que tendríamos que leer algunos de ellos, además de copiar nuestro
PO archivos en el dispositivo.

Los mensajes de depuración nunca se traducen, ya que están destinados a los programadores.

FUENTE CÓDIGO SUBDIRECTORIOS
alinear
virt-alineación-escaneo(1) comando y documentación.

aparato
El dispositivo libguestfs, crea scripts, etc.

golpear
Scripts de finalización de tabulación Bash.

construir-aux
Varios scripts de compilación utilizados por autotools.

constructor
constructor de virtudes(1) comando y documentación.

gato El sistema virt-gato(1) sistemas de archivos virt(1) registro virt(1) y virt-ls(1) comandos y
documentación.

Contrib
Contribuciones externas, partes experimentales.

personalizan
virt-personalizar(1) comando y documentación.

demonio
El demonio que se ejecuta dentro del dispositivo libguestfs y realiza acciones.

df virt-df(1) comando y documentación.

DIB virt-dib(1) comando y documentación.

diff
diferencia virtual(1) comando y documentación.

doc Páginas de manual misceláneas.

editar
virt-editar(1) comando y documentación.

ejemplos
Código de ejemplo de API de C.

Pescado
pez invitado(1), el shell de la línea de comandos y varios scripts de shell construidos en la parte superior, como
virt-copia-en(1) copia-virtual(1) virt-tar-en(1) virt-tar-fuera(1).

formato
formato virt(1) comando y documentación.

fusible
Guestmount(1), FUSE (sistema de archivos de espacio de usuario) construido sobre libguestfs.

generador
El generador de importancia crucial, que se utiliza para generar automáticamente grandes cantidades de
código C repetitivo para cosas como RPC y enlaces.

obtener-kernel
virt-get-kernel(1) comando y documentación.

gnulib
Gnulib se utiliza como biblioteca de portabilidad. Aquí se incluye una copia de gnulib.

inspector
virt-inspector(1), el inspector de imágenes de la máquina virtual.

logo
Logotipo utilizado en el sitio web. Por cierto, el pez se llama Arthur.

m4 Macros M4 utilizadas por autoconf.

hacer-fs
virt-make-fs(1) comando y documentación.

mllib
Varias bibliotecas y código común utilizado por virt-cambiar tamaño(1) y las otras herramientas que son
escrito en OCaml.

p2v virt-p2v(1) comando, documentación y scripts para construir el disco o la ISO virt-p2v
imagen.

po Traducciones de cadenas gettext simples.

po-docs
La infraestructura de compilación y los archivos PO para la traducción de páginas de manual y archivos POD.
Eventualmente esto se combinará con el po directorio, pero eso es más bien
Complicado.

rescatar
virt-rescate(1) comando y documentación.

cambiar el tamaño
virt-cambiar tamaño(1) comando y documentación.

esparcir
virt-esparsificar(1) comando y documentación.

src Código fuente de la biblioteca C.

sysprep
virt-sysprep(1) comando y documentación.

pruebas
Pruebas

datos de prueba
Archivos y otros datos de prueba utilizados por las pruebas.

herramienta de prueba
Herramienta de prueba para que los usuarios finales prueben si su combinación qemu / kernel funcionará con
libguestfs.

tmp Se utiliza para archivos temporales al ejecutar las pruebas (en lugar de / Tmp etc). La razón es
para que pueda ejecutar varias pruebas paralelas de libguestfs sin tener un conjunto de
pruebas que sobrescriben el dispositivo creado por otro.


Herramientas de línea de comandos escritas en Perl (virt-ganar-reg(1) y muchos otros).

v2v virt-v2v(1) comando y documentación.

sitio web
El sistema http://libguestfs.org archivos del sitio web.

CSharp
Erlang
gobjeto
Golang
haskell
Java
luna
ocaml
php
perl
pitón
rubí
Vinculaciones de idioma.

HACIENDO A ESTABLE LIBERAR
Cuando hacemos una versión estable, hay varios pasos documentados aquí. Ver "LIBGUESTFS
NÚMEROS DE VERSIÓN "en invitados(3) para obtener información general sobre la política de sucursales estable.

· Comprobar que "make && make check" funciona al menos en Fedora, Debian y Ubuntu.

· Compruebe que funciona "./configure --without-libvirt".

· Finalizar guestfs-notas-de-lanzamiento.pod

· Empujar y tirar de Zanata.

Ejecutar:

empujar zanata

para enviar los últimos archivos POT a Zanata. Entonces corre:

./zanata-pull.sh

que es un contenedor para extraer la última traducción *.correos archivos.

· Considere actualizar gnulib a la última versión ascendente.

· Cree nuevos directorios estables y de desarrollo en http://libguestfs.org/download.

· Editar sitio web / index.html.in.

· Establecer la versión (en configurar.ac) a lo nuevo estable versión, es decir. 1.XX.0 y confirmar
ella:

./localconfigure
hacer distclean -k
./localconfigure
hacer && hacer dist
hacer que el mantenedor se comprometa
hacer etiqueta de mantenedor

· Crea la rama estable en git:

git branch estable-1.XX
git push origin estable-1.XX

· Realice una liberación completa de la rama estable.

· Configure la versión para la siguiente versión de desarrollo y confírmela. Opcionalmente, haz un
lanzamiento de la rama de desarrollo.

Utilice guestfs-hacking en línea utilizando los servicios de onworks.net