Guía de reporte de fallos Gentoo

1.  Introducción

Prefacio

Uno de los factores que puede retrasar la solución a un problema con algún programa, es la forma en que se informa acerca del mismo. Creando esta guía pretendemos mejorar la comunicación entre los desarrolladores y los usuarios para facilitar la resolución de dichos problemas. Que los fallos o errores se arreglen es una parte muy importante, si no crucial, de la calidad de cualquier proyecto y esperemos que esta guía contribuya al éxito en dicha labor.

¡¡¡¡Fallos (Bugs)!!!!

Se está haciendo emerge a un paquete o trabajando con un programa y de repente ocurre lo peor. Se encuentra un fallo. Los fallos pueden presentarse como problemas con emerge o errores de segmentación (violación de segmento). Cualquiera que sea la causa, el caso es que el error ha de resolverse. Vamos a mostrar algunos ejemplos de fallos:

$ ./bad_code `perl -e 'print "A"x100'`
Segmentation fault (Violación de segmento)

/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.2/include/g++-v3/backward/backward_warning.h:32:2:
warning: #warning This file includes at least one deprecated or antiquated
header. Please consider using one of the 32 headers found in section 17.4.1.2 of
the C++ standard. Examples include substituting the <X> header for the <X.h>
header for C++ includes, or <sstream> instead of the deprecated header
<strstream.h>. To disable this warning use -Wno-deprecated.
In file included from main.cc:40:
menudef.h:55: error: brace-enclosed initializer used to initialize `
OXPopupMenu*'
menudef.h:62: error: brace-enclosed initializer used to initialize `
OXPopupMenu*'
menudef.h:70: error: brace-enclosed initializer used to initialize `
OXPopupMenu*'
menudef.h:78: error: brace-enclosed initializer used to initialize `
OXPopupMenu*'
main.cc: In member function `void OXMain::DoOpen()':
main.cc:323: warning: unused variable `FILE*fp'
main.cc: In member function `void OXMain::DoSave(char*)':
main.cc:337: warning: unused variable `FILE*fp'
make[1]: *** [main.o] Error 1
make[1]: Leaving directory
`/var/tmp/portage/xclass-0.7.4/work/xclass-0.7.4/example-app'
make: *** [shared] Error 2

!!! ERROR: x11-libs/xclass-0.7.4 failed.
!!! Function src_compile, Line 29, Exitcode 2
!!! 'emake shared' failed

Estos errores pueden ser muy problemáticos. De cualquier forma, una vez que se encuentran, ¿qué se puede hacer? Las siguientes secciones muestran dos herramientas muy importantes para los errores en tiempo de ejecución. Después de esto echaremos un vistazo a los errores de compilación y cómo manejarlos. Empecemos con la primera herramienta para corregir errores en tiempo de ejecución: gdb.

2.  Depurar usando GDB

Introducción

GDB, o (G)NU (D)e(B)ugger [Depurador GNU], es un programa usado para encontrar errores en tiempo de ejecución en programas que involucran corrupción en la memoria. Antes de nada, veamos lo que implica la depuración. Una de las cosas principales que se han de hacer para depurar un programa es emerge programa con FEATURES="nostrip". Esto previene que el programa omita los símbolos de depuración. ¿Por qué los programas usan strip por defecto? La razón es la misma por la que se tienen páginas de manual comprimidas con gzip -- conservar espacio. He aquí cómo el tamaño de un programa varía con o sin símbolos de depuración.

(quitando los símbolos de depuración)
-rwxr-xr-x  1 chris users 3140  6/28 13:11 bad_code
(con todos los símbolos de depuración)
-rwxr-xr-x  1 chris users 6374  6/28 13:10 bad_code

Sólo como referencia, bad_code es el programa que vamos a depurar con gdb después. Como puede verse, el programa sin símbolos de depuración ocupa 3140 bytes, mientras que con ellos ocupa 6374 bytes. ¡Casi duplica su tamaño! Pueden hacerse otras dos cosas más para llevar a cabo la depuración. La primera es añadir ggdb a su CFLAGS y CXXFLAGS. Con este parámetro se añade mucha más información de depuración de la que normalmente se incluye. Veremos lo que significa más tarde. Así es como /etc/portage/make.conf debería aparecer con los nuevos parámetros añadidos.

CFLAGS="-O1 -pipe -ggdb"
CXXFLAGS="${CFLAGS}"

Finalmente, se puede también añadir "debug" a los parámetros USE del paquete. Ésto puede hacerse con el archivo package.use.

# echo "categoría/paquete debug" >> /etc/portage/package.use

Ahora volvemos a emerger el paquete con las modificaciones que hemos hecho, tal y como se muestra:

# FEATURES="nostrip" emerge package

Ahora que los símbolos de depuración se han añadido, podemos continuar depurando el programa.

Ejecutando el programa con GDB

Vamos a pensar que tenemos un programa que se llama "bad_code". Alguna persona manifiesta que el programa no funciona y proporciona un ejemplo. Vamos adelante y lo comprobamos:

$ ./bad_code `perl -e 'print "A"x100'`
Segmentation fault ( Violación de segmento )

Parece que esta persona estaba en lo cierto. Desde que el programa no funciona adecuadamente, tenemos un fallo (bug) en las manos. Ahora es el momento de usar gdb para ayudar a resolver este problema. Primero ejecutamos gdb con --args, y después le damos el programa con sus argumentos como se muestra:

$ gdb --args ./bad_code `perl -e 'print "A"x100'`
GNU gdb 6.3
Copyright 2004 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "i686-pc-linux-gnu"...Using host libthread_db library "/lib/libthread_db.so.1".

Debería verse un símbolo de espera de órdenes que indica "(gdb)" que está aguardando una entrada. Primero, tenemos que ejecutar el programa. Tecleamos run y muestra lo siguiente:

(gdb) run
Starting program: /home/chris/bad_code

Program received signal SIGSEGV, Segmentation fault.
0xb7ec6dc0 in strcpy () from /lib/libc.so.6

Aquí podemos ver que el programa se inicia, junto con una notificación de SIGSEGV, o violación de segmento. Este es GDB diciéndonos que el programa ha fallado, también nos muestra la última función que se ha ejecutado cuando el programa falla. De cualquier forma no es demasiado útil, dado que pueden haber múltiples strcpy en el programa, haciendo muy difícil a los desarrolladores saber cuál ha sido la que ha causado el fallo en concreto. Para ayudarles hacemos lo que se denomina un "backtrace", que consiste en un trazado inverso de todas las funciones ejecutadas por el programa, hasta llegar a la función que plantea el problema. Las funciones ejecutadas (sin plantear ningún problema) no se mostrarán en el "backtrace". Para obtenerlo, en la línea de espera (gdb), tecleamos bt. Veremos algo así:

(gdb) bt
#0  0xb7ec6dc0 in strcpy () from /lib/libc.so.6
#1  0x0804838c in run_it ()
#2  0x080483ba in main ()

Se puede notar el patrón de trazado claramente. Primero se llama a main(), seguido de run_it(), y en alguna parte del run_it() es donde se encuentra el fallo en strcpy(). Cosas como ésta, son las que ayudan a los desarrolladores a trazar el problema. Hay algunas excepciones a la salida. La primera de ellas es haber olvidado añadir los símbolos de depuración con FEATURES="nostrip". Si quitamos los símbolos de depuración, la salida sería algo como:

(gdb) bt
#0  0xb7e2cdc0 in strcpy () from /lib/libc.so.6
#1  0x0804838c in ?? ()
#2  0xbfd19510 in ?? ()
#3  0x00000000 in ?? ()
#4  0x00000000 in ?? ()
#5  0xb7eef148 in libgcc_s_personality () from /lib/libc.so.6
#6  0x080482ed in ?? ()
#7  0x080495b0 in ?? ()
#8  0xbfd19528 in ?? ()
#9  0xb7dd73b8 in __guard_setup () from /lib/libc.so.6
#10 0xb7dd742d in __guard_setup () from /lib/libc.so.6
#11 0x00000006 in ?? ()
#12 0xbfd19548 in ?? ()
#13 0x080483ba in ?? ()
#14 0x00000000 in ?? ()
#15 0x00000000 in ?? ()
#16 0xb7deebcc in __new_exitfn () from /lib/libc.so.6
#17 0x00000000 in ?? ()
#18 0xbfd19560 in ?? ()
#19 0xb7ef017c in nullserv () from /lib/libc.so.6
#20 0xb7dd6f37 in __libc_start_main () from /lib/libc.so.6
#21 0x00000001 in ?? ()
#22 0xbfd195d4 in ?? ()
#23 0xbfd195dc in ?? ()
#24 0x08048201 in ?? ()

Este backtrace contiene muchos símbolos de interrogación ??. Esto es porque sin los símbolos de depuración, gdb no sabe cómo se ha ejecutado el programa. Por lo tanto es crucial que los símbolos de depuración no se omitan. Ahora recordemos el parámetro -ggdb. Veamos la salida que nos muestra con este parámetro habilitado:

(gdb) bt
#0  0xb7e4bdc0 in strcpy () from /lib/libc.so.6
#1  0x0804838c in run_it (input=0x0) at bad_code.c:7
#2  0x080483ba in main (argc=1, argv=0xbfd3a434) at bad_code.c:12

Aquí vemos que se muestra mucha más información que podemos proporcionar a los desarrolladores. No sólo se muestra la información de la función ejecutada sino que además se añade el número de línea exacto de los archivos de código fuente. Este método es el preferido si se puede usar todo el espacio requerido. He aquí una comparación de los tamaños de archivo sin símbolos de depuración, con ellos y con -ggdb habilitado:

(omitidos los símbolos de depuración)
-rwxr-xr-x  1 chris users 3140  6/28 13:11 bad_code
(habilitados los símbolos de depuración)
-rwxr-xr-x  1 chris users 6374  6/28 13:10 bad_code
(parámetro -ggdb habilitado)
-rwxr-xr-x  1 chris users 19552  6/28 13:11 bad_code

Como puede verse, -ggdb añade 13178 bytes más al tamaño del archivo con símbolos de depuración. Sin embargo, este incremento en el tamaño del archivo puede merecer la pena si muestra información adicional a los desarrolladores. El backtrace puede guardarse en un archivo copiando y pegando desde la terminal (si se trata de una terminal sin X, siempre puede usarse gpm. Para mantener este documento simple, recomiendo leer la documentación de gpm para ver cómo copiar y pegar con él). Ahora que hemos terminado con gdb, podemos quitarlo.

(gdb) quit
The program is running. Exit anyway? (y or n) y
$

Esto termina con nuestra visita a gdb. Usando gdb, esperamos que se puedan dar mejores informes de fallos. De cualquier forma, hay otros tipos de error que pueden causar que un programa falle en tiempo de ejecución. Uno de estos tipos es causado por un acceso indebido a archivos. Podemos encontrar estos errores con una pequeña gran utilidad llamada strace.

3.  Encontrando los errores accediendo a archivos usando strace

Introducción

Los programas a menudo usan archivos para comprobar su configuración, acceder a dispositivos o escribir su bitácora. A veces, un programa intenta llegar a dichos dispositivos de forma incorrecta. Una herramienta llamada strace fue creada para tratar de ayudar con respecto a este problema. La orden strace traza las llamadas del sistema (de ahí su nombre) que incluyen llamadas que usan la memoria y los archivos. Para nuestro ejemplo, vamos a tomar el programa foobar2. Es una versión actualizada de foobar. De cualquier forma, durante el cambio a foobar2 notamos que perdemos todas nuestras configuraciones. En foobar versión 1, nuestra configuración le indicaba que dijese "foo", pero ahora muestra por defecto "bar".

$ ./foobar2
Configuration says: bar

Nuestra configuración anterior le decía que mostrase foo, así que vamos a usar strace para ver qué está pasando.

Usando strace para hacer averiguaciones

Vamos a hacer que strace genere un registro de los resultados de las llamadas al sistema. Para hacer esto, ejecutamos strace con el argumento -o[archivo]. Vamos a usarlo con foobar2 como se muestra.

# strace -ostrace.log ./foobar2

Esto crea un archivo llamado strace.log en el directorio actual. Comprobamos el archivo y vemos las partes relevantes del mismo.

open(".foobar2/config", O_RDONLY)       = 3
read(3, "bar", 3)                       = 3

¡Ajá! He aquí el problema. Alguien ha movido el directorio de configuración a .foobar2 en lugar de .foobar. También vemos que el programa está leyendo "bar" tal y como debe hacer. En este caso, debemos recomendar al mantenedor del ebuild que ponga un aviso sobre ello. Por ahora, podemos copiar el archivo desde .foobar y modificarlo para que produzca los resultados deseados.

Conclusión

Hasta ahora nos hemos preocupado de los errores en tiempo de ejecución. Estos errores son problemáticos cuando se trata de ejecutar los programas. De cualquier forma estos errores nos traerán sin cuidado si lo que falla es la compilación del mismo. Vamos a echar un vistazo a los errores de compilación con emerge.

4.  Manejando los errores con emerge

Introducción

Los errores con emerge, como el mencionado anteriormente, pueden ser frustrantes para los usuarios. Informar sobre estos fallos se considera crucial para poder mantener la salud de Gentoo. Vamos a ver un ebuild de ejemplo, foobar2, que contiene algunos errores de compilación.

Evaluando errores emerge

Vamos a mirar este error muy simple emerge:

gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod \
 -c -o foobar2-7.o foobar2-7.c
gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod \
 -c -o foobar2-8.o foobar2-8.c
gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod \
 -c -o foobar2-9.o foobar2-9.c
gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod \
 -c -o foobar2.o foobar2.c
foobar2.c:1:17: ogg.h: No such file or directory
make: *** [foobar2.o] Error 1

!!! ERROR: sys-apps/foobar2-1.0 failed.
!!! Function src_compile, Line 19, Exitcode 2
!!! Make failed!
!!! If you need support, post the topmost build error, NOT this status message

El programa está compilando normalmente, cuando de repente para y muestra este error. Este mensaje en particular puede dividirse en tres secciones diferentes: los mensajes de compilación, el error de construcción del programa y el error mostrado por emerge, tal y como se muestran a continuación:

(Mensajes de compilación)
gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod \
 -c -o foobar2-7.o foobar2-7.c
gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod \
 -c -o foobar2-8.o foobar2-8.c
gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod \
 -c -o foobar2-9.o foobar2-9.c
gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod \
 -c -o foobar2.o foobar2.c

(Error de construcción)
foobar2.c:1:17: ogg.h: No such file or directory
make: *** [foobar2.o] Error 1

(Error emerge)
!!! ERROR: sys-apps/foobar2-1.0 failed.
!!! Function src_compile, Line 19, Exitcode 2
!!! Make failed!
!!! If you need support, post the topmost build error, NOT this status message

Los mensajes de compilación son los que conducen al error. A menudo, es bueno añadir como mínimo unas 10 líneas de dicha información, para que el desarrollador sepa dónde se encontraba la compilación cuando se produjo el error.

Por favor, asegúrese de que siempre incluye los mensajes de error en inglés incluso cuando el lenguaje de su sistema esté configurado en algún otro. Puede, temporalmente, cambiar a la localización inglesa anteponiendo LC_ALL=C al comando emerge, de este modo:

# LC_ALL=C emerge sys-apps/foobar2

Los errores de make son el error actual y la información que el desarrollador necesita. Cuando vemos "make: ***", es a menudo dónde el error se produjo. Normalmente, se pueden copiar y pegar las diez líneas superiores a este mensaje y el desarrollador sabrá cómo redireccionar el problema. De cualquier forma, ésto no siempre funciona y veremos otra alternativa en breve.

El error de emerge es lo que emerge muestra como mensaje. A veces, puede contener información importante. A menudo, la gente comete el error de enviar únicamente este error. Lo cual no tiene ninguna utilidad, pero con el error make y los mensajes de compilación un desarrollador puede saber la versión y el paquete que están fallando. Como nota adicional, make se usa para construir los programas (pero no siempre). Si no se puede encontrar ningún error "make: ***" por ninguna parte, entonces hay que copiar unas 20 líneas por encima del error emerge. Con esto debe ser suficiente para la mayoría de los errores de "construcción" en el sistema. Ahora digamos que los errores parecen demasiado largos, 10 líneas no serán suficientes para capturarlo todo, aquí es donde PORT_LOGDIR entra en juego.

emerge y PORT_LOGDIR

PORT_LOGDIR es una variable de portage que configura el directorio para las diferentes bitácoras de emerge. Vamos a comprobarlo y a ver lo que implica. Primero ejecutamos emerge con la localización preferida para su bitácora en PORT_LOGDIR. Digamos que se configura para que use /var/log/portage. Usaremos esta ruta para que sea la bitácora de nuestro sistema:

# PORT_LOGDIR=/var/log/portage emerge cate-gory/foobar2

Ahora, emerge falla de nuevo. De cualquier forma ahora disponemos de una bitácora con la que podremos trabajar, y podemos añadirlo al informe de fallo posteriormente. Vamos a echar un vistazo a nuestro directorio bitácora.

# ls -la /var/log/portage
total 16
drwxrws---   2 root root 4096 Jun 30 10:08 .
drwxr-xr-x  15 root root 4096 Jun 30 10:08 ..
-rw-r--r--   1 root root 7390 Jun 30 10:09 cate-gory:foobar2-1.0:20090110-213217.log

Los archivos de log tienen el formato [categoría]:[nombre del paquete]-[versión]:[fecha].log. Un vistazo rápido al fichero de log mostrará el proceso de emerge completo. Éste puede ser adjuntado como veremos más tarde en la sección acerca del informe de fallos. Ahora que hemos obtenido de forma segura la información que necesitamos para informar del fallo, podemos proceder a hacerlo. Sin embargo, antes de hacerlo, necesitamos asegurarnos de que nadie más ha informado de la misma cuestión. Echemos un vistazo a la búsqueda de informes de fallos.

5.  Búsqueda usando Bugzilla

Introducción

Bugzilla es lo que usamos en Gentoo para manejar los fallos. Al Bugzilla de Gentoo puede accederse mediante HTTPS y HTTP. HTTPS está disponible para aquellos en redes inseguras o símplemente paranoicos :). Para mayor consistencia usaremos HTTPS en los ejemplos a continuación. Echemos un vistazo a Gentoo Bugs para ver cómo es.

Una de las cosas más frustrantes para los desarrolladores y los encargados de los fallos es encontrar informes de fallo duplicados. Cuestan un tiempo que podrían dedicar a resolver otros errores más importantes. A menudo, esto puede evitarse con unos simples métodos de búsqueda. Así que vamos a ver cómo buscar fallos y ver si hay alguno similar al nuestro. Para este ejemplo vamos a usar el mismo error de emerge en la xclass que vimos antes.

/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.2/include/g++-v3/backward/backward_warning.h:32:2:
warning: #warning This file includes at least one deprecated or antiquated
header. Please consider using one of the 32 headers found in section 17.4.1.2 of
the C++ standard. Examples include substituting the <X> header for the <X.h>
header for C++ includes, or <sstream> instead of the deprecated header
<strstream.h>. To disable this warning use -Wno-deprecated.
In file included from main.cc:40:
menudef.h:55: error: brace-enclosed initializer used to initialize `
OXPopupMenu*'
menudef.h:62: error: brace-enclosed initializer used to initialize `
OXPopupMenu*'
menudef.h:70: error: brace-enclosed initializer used to initialize `
OXPopupMenu*'
menudef.h:78: error: brace-enclosed initializer used to initialize `
OXPopupMenu*'
main.cc: In member function `void OXMain::DoOpen()':
main.cc:323: warning: unused variable `FILE*fp'
main.cc: In member function `void OXMain::DoSave(char*)':
main.cc:337: warning: unused variable `FILE*fp'
make[1]: *** [main.o] Error 1
make[1]: Leaving directory
`/var/tmp/portage/xclass-0.7.4/work/xclass-0.7.4/example-app'
make: *** [shared] Error 2

!!! ERROR: x11-libs/xclass-0.7.4 failed.
!!! Function src_compile, Line 29, Exitcode 2
!!! 'emake shared' failed

Para empezar a buscar, vamos a la página de Bugzilla.

Ilustración 5.1: Bugzilla

Hacemos click en "Query Existing bug reports". La razón por la que elegimos este método en lugar de la búsqueda de errores básica es porque no suele dar buenos resultados, presenta demasiada información y puede impedir a los usuarios encontrar un informe de fallo duplicado. Una vez se ha hecho click en la pantalla "query", llegamos a la siguiente página:

Ilustración 5.2: Página de búsqueda Bugzilla

Procedemos haciendo click en "Advanced Search" para acceder a la página de búsqueda avanzada.

Ilustración 5.3: Página de búsqueda avanzada

Así es como la página de búsqueda avanzada se muestra. Al principio puede parecer aplastante, pero vamos a ver ciertas áreas para que los resultados de las búsquedas no sean tan poco productivos.

Ilustración 5.4: Contenido

El primer campo es el sumario del fallo. Aquí sencillamente pondremos el nombre del paquete con problemas. Si "bugzie" no devuelve resultados, tendremos que intentar quitar el nombre del paquete, por si acaso alguien no lo ha puesto en el sumario (no es lo más normal, pero hemos visto informes de fallos muy extraños...).

El producto, el componente y la versión deben indicarse por defecto. Esto previene que seamos demasiado específicos y que perdamos muchos informes de fallos.

El comentario ("comment") es la parte más importante. Usaremos el campo de comentario para proporcionar todo aquello que parezca una instancia específica del error. Básicamente no se debe usar el principio del error de construcción, hay que encontrar la línea en la que el error se muestra. También, tendremos que evitar la puntuación para evitar que Bugzilla interprete los resultados del comentario de forma errónea. Ejemplo con el error emerge de xclass:

menudef.h:78: error: brace-enclosed initializer used to initialize `OXPopupMenu'
(Hay que eliminar las comillas ' ')
menudef.h 78 error brace-enclosed initializer used to initialize OXPopupMenu

El ejemplo anterior es lo suficientemente específico como para evitar que andemos buscando otros candidatos a errores de compilación de xclass.

Los campos URI, Whiteboard, y Keywords pueden obviarse. La información que hemos introducido debe ser suficiente para encontrar nuestro error. Vamos a echar un vistazo a la información que hemos introducido.

Ilustración 5.5: Formulario de búsqueda completada

Ahora hacemos click en el botón de búsqueda ("Search") y estos son los resultados ...

Ilustración 5.6: Resultados de la búsqueda

¡Sólo 2 fallos! Así es mucho más fácil de manejar. Hacemos click en el primero de ellos para comprobar y asegurarnos de que es el que estábamos buscando.

Ilustración 5.7: Fallo localizado

No sólo es el que queremos, sino que también ha sido resuelto. Comprobando el último comentario vemos la solución y qué debemos hacer para solucionarlo. Veamos lo que hubiera ocurrido si no hubiésemos empleado la búsqueda avanzada.

Ilustración 5.8: Resultados de búsqueda básica

¡4 fallos más a los que enfrentarnos! Suele ser mucho peor con paquetes mucho más grandes. De cualquier forma, con estas simples herramientas seremos capaces de hacer mucho más sencilla la búsqueda para localizar un fallo en concreto.

Conclusión

Digamos que aunque se ha buscado y buscado, somos incapaces de encontrar el fallo. Entonces se ha encontrado un nuevo fallo. Veamos cómo se han de introducir nuevos informes de fallos.

6.  Informando sobre fallos

Introducción

En este capítulo veremos como usar Bugzilla para enviar un informe de fallo nuevo. Vamos a Gentoo Bugs y ...

Ilustración 6.1: Bugzilla

Hacemos click en "Report a Bug - Using the guided format".

Ilustración 6.2: Selección de producto

Como puede verse, se ha puesto el mayor énfasis en colocar el informe de fallo en el lugar adecuado. La mayoría de informes de fallo van a Gentoo Linux.

A pesar de ello, algunos usarán desarrollo portage para enviar informes de fallos en ebuilds (asumiendo que el equipo portage maneja el árbol portage) o infra (asumiendo que infra tiene acceso directo a las réplicas y a rsync y pueden solucionarlo directamente). Así no funcionan las cosas, sencillamente.

Otro error muy común ocurre con nuestros fallos de Documentación. Por ejemplo, un usuario encuentra un fallo en los Docs Catalyst. La tendencia general es rellenar un informe de fallo bajo la categoría Docs-user, que se asigna a GDP, cuando en realidad debería asignarse a un miembro del equipo Release Engineering. Como regla práctica, sólo la documentación bajo http://www.gentoo.org/doc/* está bajo la responsabilidad de GDP, y aquella bajo http://www.gentoo.org/proj/* está bajo la responsabilidad de sus respectivos equipos.

Nuestro bug está destinado a Gentoo Linux dado que es un error de un ebuild. Accedemos a la página y se nos presenta la forma guiada en múltiples pasos. Vamos a proceder con el primer paso ...

Ilustración 6.3: Paso 1 en la forma guiada

El primer paso aquí es realmente importante (como indica el texto en rojo). Aquí es dónde uno busca si alguien ha informado del mismo error o fallo que el nuestro. Si se evita este paso y un fallo como el nuestro ya existe, será marcado como duplicado (DUPLICATE) desperdiciando mucho tiempo y esfuerzos del equipo QA. Para proporcionar una idea, los números de errores que han emprendido el camino de resolución son errores duplicados. Ahora viene el paso 2 donde proporcionamos la información.

Información requerida

Ilustración 6.4: Información básica

Vamos a mirar detenidamente en qué consiste.

• Primero, está el producto. El producto enmarcará el error en un área específica de Gentoo como Bugzilla (para fallos relacionados con bugs.gentoo.org), Docs-user (para la documentación de usuario) o Gentoo Linux (para ebuilds y cosas así).
• El componente es exactamente donde el problema ocurre, más específicamente la parte del producto donde el error se muestra. Ésto hace la clasificación mucho más sencilla.
• La plataforma de hardware es la arquitectura en la que se presenta. Si se está utilizando un SPARC, evidentemente deberá seleccionarse SPARC.
• El sistema operativo es el que se está usando. Dado que Gentoo se considera una "meta-distribución", puede ejecutarse en otros sistemas operativos que no sean Linux.

Así que, para nuestro error de ejemplo, tenemos:

• Product - Gentoo Linux (Dado que es un problema con un ebuild)
• Component - Application (Es una aplicación la que falla, foobar2)
• Hardware Platform - All (Este error puede ocurrir en todas las arquitecturas)
• Operation System - All (Puede ocurrir en todo tipo de sistemas)

Ilustración 6.5: Información básica completada

• El identificador de construcción es sencillamente el agente del usuario que el navegador está empleando (para propósitos de bitácora). Se puede dejar tal y como aparece.
• El URL es opcional y se usa para apuntar a información relevante en otro sitio (sitio de bugzilla, notas del lanzamiento en la página del paquete, etc.). No debería usar URL para indicar sitios de tipo pastebin donde se encuentren mensajes de error, registros, información producida por emerge --info, capturas de pantalla o similares. Estos debería siempre ser adjuntados al bug.
• En el Sumario, se ha de añadir la categoría del paquete, nombre y número.

Realmente, no incluir la categoría en el sumario no es tan malo, aunque se recomienda hacerlo. Si no se incluye el nombre del paquete, sencillamente, no sabremos de qué se está enviando un informe de fallo, y tendremos que preguntarlo. El número de versión es muy importante para la gente que busca fallos. Si 20 personas han rellenado un informe de fallo y nadie ha indicado la versión, ¿cómo podría la gente que está buscando errores similares notar que ya se ha informado acerca del mismo? Deberían buscar en todos los informes de fallos, lo cual no es muy difícil, siempre y cuando no haya más de 200 errores acerca de un paquete. Después de incluir toda la información, se debe incluir una pequeña descripción del incidente. Aquí mostramos un ejemplo:

Ilustración 6.6: Sumario

Estas sencillas normas pueden hacer que manejar errores sea mucho más sencillo. Ahora vienen los detalles. Vamos a mostrarlo con un ejemplo:

Ilustración 6.7: Detalles

Ahora el desarrollador sabe por qué estamos rellenando el informe de fallo. Entonces pueden intentar reproducirlo. Poder reproducirlo nos muestra con cuánta frecuencia puede ocurrir el problema. En este ejemplo, podemos reproducirlo cada vez que ejecutamos foobar2. Vamos a añadir esta información.

Ilustración 6.8: Reproducción

Hemos explicado cómo hemos encontrado el error. El siguiente paso es explicar los resultados que obtenemos y los resultados que deberíamos obtener.

Ilustración 6.9: Resultados

Podemos proporcionar información adicional. Que podrían ser trazados de pila, secciones (dado que la bitácora completa es normalmente muy grande y de no demasiada utilidad) de las bitácoras strace, pero mucho más importante es el emerge --info. He aquí un ejemplo:

Ilustración 6.10: Información adicional

Finalmente elegimos la categoría (severity) del fallo. Por favor, hay que mirar esto con muchísimo detenimiento. En la mayoría de ocasiones está bien dejarlo tal cual está y alguien subirá o rebajará la categoría del mismo. De cualquier forma, si se especifica la categoría del fallo, hay que asegurarse de no estar cometiendo un error. Proporcionamos una descripción de todos los niveles a continuación.

• Blocker - El programa sencillamente no quiere emerger o es un grave problema para el sistema. Por ejemplo, un problema con baselayout que impide que el sistema se inicie, sería un seguro candidato a etiquetarse como blocker.
• Critical - El programa pierde datos o tiene problemas con la memoria en tiempo de ejecución. De nuevo, un programa importante como net-tools que no puede compilarse debe etiquetarse como crítico. No evitará que el sistema se inicie, pero impedirá el correcto funcionamiento diario del sistema.
• Major - El programa falla, pero nada causa al sistema daños serios o pérdida de información.
• Minor - El programa falla aquí y allí, pero hay formas de solucionarlo.
• Normal - El nivel por defecto. Si no se está seguro, hay que dejarlo así a no ser que se trate de una nueva construcción o cambio cosmético, entonces hay que seguir leyendo para mayor información.
• Trivial - Cosas como un error tipográfico o limpieza de espacios.
• Enhancement - Una petición para habilitar una nueva característica a un programa, o más específicamente nuevos ebuilds.

Ilustración 6.11: Categoría

Aquí, la dejaremos como Normal.

Ahora podremos informar sobre el fallo pulsando en "Submit Bug Report". Puede verse cómo aparece el fallo. Veamos Bug 97561 y sus resultados. ¡Hemos informado acerca de nuestro fallo! Veamos cómo se maneja.

Peticiones de actualización el día del lanzamiento (zero-day)

Hasta acá, hemos visto qué hacer para reportar un "bug". Ahora veamos que no hacer.

Supongamos que ha estado ávidamente siguiendo el progreso de un proyecto y al revisar su página web, ¿adivinen qué? Acaban de lanzar una versión nueva ¡hace apenas unos minutos! La mayoría de los usuarios volarán al bugzilla de Gentoo para reportar la disponibilidad de la nueva versión: pidiendo por favor actualizar la versión existente y agregarla a Portage, etc. Sin embargo, esto es exactamente lo que no debemos hacer. Este tipo de petición se llaman (en inglés) peticiones de actualización zero-day (ó 0-day), ya que se hacen el mismo día del lanzamiento de la nueva versión.

¿Porqué esperar? Primero, es algo grosero demandar que los desarrolladores Gentoo dejen todo lo que están haciendo para agregar un lanzamiento hecho hace 15 minutos. Su reporte podrá ser marcado como inválido (INVALID) o para procesamiento posterior (LATER), ya que los desarrolladores tienen bastantes asuntos urgentes para mantenerlos ocupados. Segundo, los desarrolladores usualmente están al tanto de los lanzamientos nuevos, aún más que muchos usuarios, ya que siguen de cerca los desarrollos "upstream". Ellos están enterados que vienen nuevas versiones. En muchos casos, ya habrán reportado un "bug", o incluso haberlo agregado a Portage como un paquete enmascarado.

Sea inteligente al probar y pedir nuevas versiones de paquetes. Haga un rastreo en bugzilla antes de reportar su petición de actualización -- ¿habrá ya un reporte? ¿Ha sincronizado Portage últimamente? ¿Estará ya en Portage? ¿Realmente ha sido lanzado por sus desarrolladores? El sentido común básico lo ayudará mucho y será agradecido por los desarrolladores que ya tienen demasiado que hacer. Si han pasado varios días desde el lanzamiento y está seguro que no existen peticiones de actualización abiertas (y que no está en el árbol Portage), entonces reporte un "bug" nuevo. Asegúrese de mencionar que compila y ejecuta bien en su plataforma. Cualquier otra información que proporcione será bienvenida.

¿Desea ver la versión más reciente de su paquete favorito en Portage? Reporte "bugs" inteligentemente.

7.  Trabajando con nuestro error

Mirando el error, vemos la información que hemos proporcionado anteriormente. Como puede verse el informe ha sido asignado a bug-wranglers@gentoo.org. Ésta es la asignación por defecto de los componentes de aplicaciones.

Ilustración 7.1: Información básica nueva del error

Los detalles que hemos introducido acerca del error están disponibles también.

Ilustración 7.2: Nuevos detalles del error

De cualquier forma, bug-wranglers (normalmente) nunca resuelven nuestros informes de error, así que podemos reasignarlo a alguien que pueda hacerlo (o bien dejar que bug-wranglers se encarguen de reasignarlo por nosotros). Para esto, empleamos la metadata.xml del paquete. Puede encontrarse en /usr/portage/categoría/paquete/metadata.xml. Aquí hay una que hemos realizado para el paquete foobar2.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
<pkgmetadata>
<herd>chriswhite</herd>
<maintainer>
<email>chriswhite@gentoo.org</email>
<name>Chris White</name>
</maintainer>
<longdescription lang="en">
Foobar2 is a package that uses a configuration file to display a word.
</longdescription>
</pkgmetadata>

Hay que fijarse en la sección del mantenedor (maintainer). Ésta muestra quien se encarga del paquete, en este caso soy yo mismo, Chris White. La dirección de correo electrónico que se muestra es chriswhite@gentoo.org. La usaremos para reasignar el informe de fallo a la persona adecuada. Para hacerlo, pulsamos en "Reassign bug to" y añadimos dicha dirección de correo electrónico.

Ilustración 7.3: Reasignación del error

Pulsamos en el botón "Commit" para que los cambios surtan efecto. El error ha sido reasignado a mí mismo. Brevemente, se recibirá (por correo electrónico normalmente) la noticia de que se ha respondido al informe de fallo proporcionado. Se ha pedido que se muestre el trazado de strace, para mostrar cómo el programa está intentando acceder a nuestro archivo de configuración. Así pues, tendremos que añadirlo al informe de fallo. Para hacer esto, pulsamos en "añadir un accesorio" (Create A New Attachment).

Ilustración 7.4: Añadir un accesorio

Ahora debemos añadir la bitácora. Vamos a ello paso por paso.

• File - Esta es la localización del archivo en nuestra máquina. En este ejemplo, la localización de strace.log. Se puede usar el botón "Navegar ..." (Browse ...) para seleccionar el archivo, o bien entrar la ruta directamente en el campo de texto.
• Description - Una breve descripción en una línea o en pocas palabras del archivo añadido. Sencillamente, pondremos strace.log dado que el contenido queda claro.
• Content Type - Este es el tipo de archivo que estamos añadiendo al informe.
• Obsoletes - Si había bitácoras obsoletas que habíamos añadido al error antes de añadir la actual, tenemos la opción de declararlas obsoletas por nosotros mismos. Dado que no habíamos añadido otras al informe de error, no necesitamos molestarnos.
• Comment - Añadir comentarios que podrán verse junto con el archivo añadido. Si se necesita, pueden explicarse cosas acerca del mismo.

Con respecto al tipo de contenido (Content Type), vamos a dar algunos detalles más. Podemos seleccionar la casilla parche (patch) si estamos enviando un parche. De otra forma podemos dejar que Bugzilla auto-detecte el tipo de archivo (no es muy recomendable). Las otras opciones son "Seleccionar desde una lista", que es la que se usa normalmente. Se debe usar texto plano (plain text) para la mayoría de los archivos que añadimos exceptuando archivos binarios como imágenes (en cuyo caso puede usarse image/gif, image/jpeg ó image/png dependiendo del tipo) o archivos comprimidos como los .tar.bz2 que usarán application/octet-stream como tipo de contenido.

Ilustración 7.5: Nuevo accesorio añadido

Añadimos strace.log y se muestra en el informe de fallo.

Ilustración 7.6: strace log añadido

Hemos mencionado anteriormente que a veces los ebuilds pueden solicitar que se añada un archivo en el error. Veamos un ejemplo.

configure: error: PNG support requires ZLIB. Use --with-zlib-dir=<DIR>

!!! Please attach the config.log to your bug report:
!!! /var/tmp/portage/php-5.0.3-r1/work/php-5.0.3/config.log

!!! ERROR: dev-php/php-5.0.3-r1 failed.
!!! Function econf, Line 485, Exitcode 0
!!! econf failed
!!! If you need support, post the topmost build error, NOT this status message.

Hay que añadir en el informe de fallo cualquier archivo que se mencione en el error, en este caso "config.log".

A veces un desarrollador podrá pedirle que adjunte un diff o parche para un archivo. Los archivos diff estandard se pueden obtener de la siguiente manera:

$ cp file file.old
$ nano file
$ diff -u file.old file

Para los archivos fuente de C/C++, agregamos el parámetro -p para mostrar cuál función llama el diff al cual aplica:

$ cp file.c file.c.old
$ nano file.c
$ diff -up file.c.old file.c

El equipo de documentación necesitará la combinación de parámetros -Nt al igual que -u. Esto tiene que ver con la expansión de tabuladores. Un archivo diff con estas características se puede obtener con:

$ cp file.xml file.xml.old
$ nano file.xml
$ diff -Nut file.xml.old file.xml

Así creamos los archivos diff. Mientras estamos haciendo esto, supongamos que alguien encuentra nuestro informe de fallo a través de Bugzilla y quiere permanecer informado acerca del mismo, pueden hacerlo si añaden su dirección de correo electrónico en el campo "Add CC" del error como veremos a continuación. Podemos estar informados acerca de otros errores siguiendo el mismo procedimiento.

Ilustración 7.7: Añadiendo un correo a CC:

Después de todo este trabajo, el informe de fallo puede obtener distintas calificaciones. Ésto suelen hacerlo los desarrolladores Gentoo y, a veces, quien informa del fallo. Las siguientes son las calificaciones que el informe de fallo puede tener durante su periodo de duración.

• UNCONFIRMED - No veremos esta muy a menudo. Significa que quien informa del fallo ha empleado el método avanzado y no está muy seguro de si es un error actual o no.
• NEW - Los errores de los que se informa por primera vez se consideran nuevos.
• ASSIGNED - Cuando la persona a la que se ha asignado el error acepta el mismo, recibirá a menudo la calificación de ASSIGNED mientras se figuran el problema. Esto permite hacernos saber que han aceptado el informe de fallo como un fallo real.
• REOPENED - Alguien ha resuelto el error, pero pensamos que la solución no se puede llevar a cabo, dado que el problema sigue estando presente. En este punto, podemos re-abrir el error. Por favor, no debe abusarse de ésto. Si un desarrollador cierra el error por segunda o tercera vez, lo más probable es que el error se cierre (closed).
• RESOLVED - Se ha tomado una decisión firme acerca del fallo. Normalmente pasa a estar FIXED para indicar que el fallo se ha resuelto, aunque sea posible solucionarlo de muchas otras maneras. Veremos ésto con más detenimiento en breve.
• VERIFIED - Los pasos seguidos para trabajar con el fallo son correctos. Esto es cosa del equipo QA normalmente.
• CLOSED - Básicamente significa que el informe ha sido definitivamente cerrado.

A continuación, veremos el error en la bitácora strace y arreglaremos el error y lo calificaremos de RESOLVED FIXED, mencionando que ha habido un cambio en la ubicación de los archivos de configuración. Se modificará el ebuild para que muestre una advertencia acerca de ello. El fallo queda resuelto y se nos muestra lo siguiente:

Ilustración 7.8: Error resuelto

A continuación, veremos ésto:

Ilustración 7.9: Opciones del error

Esto nos proporciona la opción de re-abrir el error si se desea (por ejemplo, si el desarrollador piensa que se ha resuelto, pero la solución no nos parece adecuada). ¡Nuestro error se ha resuelto! De cualquier forma, la lista de resoluciones posible es la siguiente:

• FIXED - El error se ha resuelto, hay que seguir las instrucciones para resolver nuestro problema.
• INVALID - Se hizo algo que no estaba documentado, causando el error.
• DUPLICATE - No se han seguido los pasos de esta guía y se ha enviado un informe de fallo duplicado.
• WORKSFORME - El desarrollador o la persona encargada del error es incapaz de reproducir el error.
• CANTFIX - El error no puede solucionarse debido a ciertas circunstancias. Dichas circunstancias serán expuestas por la persona encargada del informe de fallo.
• WONTFIX - Se aplica generalmente a nuevos ebuilds o a peticiones de mejoras. Básicamente el desarrollador considera que no necesita añadir cierta "mejora" dado que no es necesaria, existe una alternativa mejor, o sencillamente no funcionará. A veces, se nos puede dar una solución para resolver el problema.
• UPSTREAM - El error no puede ser resuelto por el equipo de desarrollo de Gentoo, y se solicita que se lleve el informe de fallo a las personas que han elaborado el programa, para que lo revisen. Los desarrolladores del programa tienen varias formas de manejar fallos, incluyendo listas de correo, canales de IRC e incluso páginas similares a nuestro Bugzilla. Si no se está seguro de cómo poder contactar con ellos, lo preguntamos en el informe de fallo y alguien nos orientará en la dirección adecuada.

A veces, antes de que el fallo pueda resolverse, un desarrollador puede solicitarnos que comprobemos un ebuild actualizado. Vamos a ver los pasos a seguir en el siguiente capítulo.

8.  Comprobación de ebuilds

Obtener los archivos

Digamos que hemos informado del fallo de compilación de foobar2 anterior. Ahora los desarrolladores pueden haber encontrado el problema y pueden solicitarnos que comprobemos un nuevo ebuild, para verificar que también funciona para nosotros:

Ilustración 8.1: Solicitud de comprobación de ebuild

Aquí se usa un vocabulario bastante confuso. Primero vamos a ver en lo que consiste un revestimiento (overlay). Un revestimiento es un directorio especial como /usr/portage, la diferencia de nuestro revestimiento es que cuando hagamos emerge sync, los archivos no se borrarán del mismo. Creamos una ruta especial para ello, /usr/local/portage. Vamos a configurar nuestro revestimiento en /etc/portage/make.conf. Lo abrimos con nuestro editor preferido y añadimos lo siguiente al final del archivo.

PORTDIR_OVERLAY="/usr/local/portage"

Ahora tendremos que crear los directorios apropiados para poner los archivos de nuestro ebuild de comprobación en ellos. En este caso, se supone que debemos ponerlos en sys-apps/foobar2. Observamos que el segundo comentario solicita un directorio files para el parche. El directorio files contiene los condensados (md5sums de los archivos de una versión en particular del programa) y otros archivos requeridos que no se encuentran en el archivo de código fuente (parches, macros init.d, etc.). Vamos a crear los directorios:

# mkdir -p /usr/local/portage/sys-apps/foobar2/files

Ahora, podremos descargar los archivos, colocaremos el ebuild en /usr/local/portage/sys-apps/foobar2, y después pondremos el parche en /usr/local/portage/sys-apps/foobar2/files. Ahora que tenemos los archivos podemos comprobar el ebuild.

Comprobar el ebuild

El proceso para crear un ebuild que pueda ser usado por emerge es muy sencillo. Tenemos que crear los archivos Manifest para el ebuild. Lo cual puede hacerse usando el comando ebuild tal así:

# ebuild foobar2-1.0.ebuild manifest
>>> Creating Manifest for /usr/local/portage/sys-apps/foobar2

Ahora veamos si funciona como debería.

# emerge -pv foobar2

These are the packages that I would merge, in order:

Calculating dependencies ...done!
[ebuild  N    ] sys-apps/foobar2-1.0  0 kB [1]

Total size of downloads: 0 kB
Portage overlays:
 [1] /usr/local/portage

¡Parece que ha funcionado! Se habrá notado el [1] en la línea [ebuild]. Éste apunta a /usr/local/portage, que es el revestimiento que creamos antes. Vamos adelante y emergemos el paquete.

# emerge foobar2
 Calculating dependencies ...done!
(se omite la información de compilación)
>>> Unpacking foobar2-1.0.tar.bz2 to /var/tmp/portage/foobar2-1.0/work
 * Applying foobar2-1.0-Makefile.patch ...                                    [ ok ]
(se omite la información de compilación)
>>> Merging sys-apps/foobar2-1.0 to /
>>> chris +sandbox(preinst)
--- /usr/
--- /usr/bin/
>>> /usr/bin/foobar2

En la primera sección vemos que emerge ha empezado tal y como debía. La segunda sección muestra como se aplica el parche satisfactoriamente con el mensaje de estado "[ ok ]" a la derecha. La última sección nos muestra que el programa se ha compilado correctamente. Podemos informar ahora al desarrollador que el parche funciona bien y que pueden incluir el cambio en portage.

Conclusión

Con esto concluimos nuestra guía acerca de cómo trabajar con Bugzilla. Espero que se encuentre útil. Si se tienen preguntas, ideas o comentarios con respecto a esta guía, pueden enviarse a Chris White. Gracias especiales a moreon por sus notas con respecto al parámetro -g y los errores de compilación, a la gente de #gentoo-bugs por la ayuda proporcionada con respecto a bug-wrangling, Griffon26 por sus notas en cuanto a maintainer-needed, robbat2 por sus sugerencias generales y a fox2mike por corregir el documento y añadir contenidos siempre que fue necesario.

El contenido de este documento, a no ser que se especifique expresamente, está registrado bajo los términos de la licencia CC-BY-SA-2.5. Se aplican las Pautas de Utilización del logotipo y nombre de Gentoo.