@#
@# This is the source for the how-to-get-help file, in a weird custom format.
@# Read makedoc.c for a description of what is going on...
@#
@document_title=Qué hacer cuando su programa con Allegro no funciona
@!html
@!rtf
____ _ _ _ _ _ _
/ ___| ___| |_| |_(_)_ __ __ _ | | | | ___| |_ __
| | _ / _ \ __| __| | '_ \ / _` | | |_| |/ _ \ | '_ \
| |_| | __/ |_| |_| | | | | (_| | | _ | __/ | |_) |
\____|\___|\__|\__|_|_| |_|\__, | |_| |_|\___|_| .__/
|___/ |_|
@html
@rtf
@!text
Qué hacer cuando su programa con Allegro no funciona
@text
@!text
@heading
Contenido
@shortcontents
@text
@heading
Introducción
Cuando las cosas van mal, a menudo parece buena idea pedir a otras
personas ayuda. Afortunadamente para las personas en esta situación, hay
muchas personas (tanto desarrolladores de Allegro como usuarios) que
están dispuestas a responder preguntas de este tipo, pero hay varias
cosas que puede hacer para que este proceso sea más eficiente. Este
documento describe algunos pasos que debe tomar cuando tiene un problema
con un programa que use Allegro, sugiriendo modos de solucionar el
problema usted mismo, y enseñando trucos sobre cuándo y/o cómo pedir
ayuda. El seguir estas reglas hará la vida más sencilla para el que le
ayude (porque toda la información relevante será presentada de modo
conciso y útil), y para el ayudado (porque así será más probable que
reciba una respuesta rápida y precisa).
@heading
Parte 1 - ¿quién es el culpable?
¿Es un problema de Allegro, o de su código? Para descubrirlo, pruebe
ejecutar los programas test de Allegro, en particular test.exe (si tiene
problemas con los gráficos), play.exe (problemas de sonido), y el
contenido completo del directorio examples (para cualquier cosa que vaya
mal). Si no puede reproducir el problema con uno de éstos, entonces
probablemente es un fallo suyo, por lo que salte a la parte 3 más abajo.
Si el problema está relacionado con los modos gráficos del DOS, debería
empezar por conseguir una copia del programa Display Doctor de
http://www.scitechsoft.com/.
Si esto soluciona el problema, significa con toda seguridad que su driver
VESA original estaba estropeado de alguna manera.
No estoy interesado en leer mensajes sobre problemas de este tipo: no hay
nada que pueda hacer para corregirlos, por lo que me temo que su única
opción es conseguir un driver VESA mejor, ya sea solicitando al fabricante
de su tarjeta que solucione sus errores, comprando Display Doctor, o
escribiendo un driver FreeBE/AF para su tarjeta (mire en
http://www.talula.demon.co.uk/freebe/).
Si el problema tiene que ver con los modos gráficos, debería conseguir
una copia de UniVBE de http://www.scitechsoft.com/. Si esto soluciona
el problema, significa que su driver VESA original estaba estropeado de
alguna manera. No estoy interesado en oír problemas de este tipo: no hay
nada que pueda hacer para solucionarlos, me temo que su única opción es
conseguir un driver VESA mejor, obligando al fabricante de tu tarjeta a
que solucione los fallos, comprando UniVBE, o escribiendo un driver
FreeBE/AF para su tarjeta (mire en http://www.talula.demon.co.uk/freebe/).
@heading
Parte 2 - cuando Allegro falla
Si sigue creyendo que el problema es de Allegro, mande un mensaje con una
descripción sobre su sistema y el problema, indique la versión de Allegro
y su plataforma, su configuración de hardware, y una lista exacta de los
programas que pueden reproducir su problema (es importante saber qué
programas no funcionan, y cuales sí, en caso de que funcione alguno).
Si el problema está relacionado con modos gráficos del DOS, también
debería mandar los resultados producidos por los programas afinfo y
vesainfo (la versión reducida es suficiente a no ser que se le indique
específicamente usar el parámetro -v: esos datos extra no son necesarios
normalmente). Pruebe ejecutar el programa test.exe con varios drivers de
Allegro (otros drivers nativos que crea puedan funcionar con su tarjeta,
el driver VESA 1.x y VESA 2.0), en varios modos de vídeo, y describa
exáctamente qué resoluciones causan problemas. Si es capaz de ejecutar los
programas en resoluciones SVGA, ejecute test.exe con la opción Autodetect
e indique el texto completo que aparece en el medio de la pantalla.
Si el problema está relacionado con el sistema de sonido del DOS, pruebe
usar el programa setup para configurar manualmente su tarjeta. Quizás
tenga que introducir manualmente los parámetros del hardware, y si se
trata de una tarjeta clon de la SB, pruebe seleccionar una versión
anterior a la que está siendo autodetectada (SB Pro, SB 2.0, o SB 1.0). Si
sigue sin conseguir que funcione, su mensaje de ayuda debería incluir el
nombre y descripción de los drivers que estén siendo autodetectados (ésta
información es mostrada por el programa play.exe).
@heading
Parte 3 - cuando su programa falla
Cuando un programa djgpp falla, normalmente volcará el contenido de la
pila que parecerá algo como esto:
Exiting due to signal SIGSEGV
General Protection Fault at eip=00001eca
[corte]
Call frame traceback EIPs:
0x00001eca
0x00001590
0x00001aea
Esta información le indica exactamente dónde ocurrió el fallo. Para que
estos datos tengan sentido, debe compilar su programa con información de
depurado (usando el parámetro -g), y ejecutar "symify programa.exe" cuando
esté viendo el contenido de la pila en pantalla. Eso cambiará los datos
a algo parecido a esto:
Call frame traceback EIPs:
0x00001eca _strcpy+14
0x00001590 _main+56, line 7 of t.c
0x00001aea ___crt1_startup+138
En este caso, puede ver que el bloqueo ocurrió en la función strcpy(),
que fue llamada en la línea 7 de la función main() del fichero fuente
t.c. Ahora sólo tienes que ir a esa línea, mirar lo que esté haciendo
allí, y corregirlo :-)
Nota: si el bloqueo ocurre dentro de una función de Allegro, el mensaje
de error puede no ser muy útil. Cuando esto ocurra puede recompilar
Allegro con información de depuración (lea el fichero readme), y enlazar
su programa con esta versión de la biblioteca de funciones.
Nota 2: incluso cuando el traceback apunta a una función de Allegro, no
significa que sea fallo de una rutina de Allegro. Cualquier rutina
fallará si le pasa parámetros inválidos, por lo que a no ser que pueda
duplicar el problema con uno de los programas de ejemplo de Allegro,
debería asumir que es un caso de error de operador y chequear dos veces
qué valores le está pasando a la función de Allegro.
@heading
Parte 4 - lo que la gente no hace (pero debería)
Uno de los errores más comunes cometidos por los programadores es ignorar
el valor de retorno de una función que puede fallar. Tal error
normalmente llevará a otros errores inusuales e inesperados, convirtiendo
la depuración en una pesadilla. Hay muchas funciones dentro y fuera de
Allegro que pueden funcionar o no dependiendo de las circunstancias. Sin
embargo le harán saber si funcionaron o no gracias a los valores de
retorno documentados.
Siempre que llame a una función que puede fallar (sobre todo
set_gfx_mode(), install_sound(), y cualquier cosa que carga datos del
disco), es _esencial_ que chequee el valor devuelto por la función, y
actúe en consecuencia.
Otra herramienta importante comúnmente olvidada es usar las opciones que
activan los mensajes de aviso del compilador más estrictos (gcc usa
-Wall), cuando compile su código. Cualquier mensaje de aviso que de el
compilador con ésta opción representará casi con toda seguridad un error
en su programa, y debería ser corregido antes de hacer nada. Si usa gcc,
un truco útil es compilar además con el parámetro -O, porque esto fuerza
al compilador a examinar las acciones del programa con más detalle,
activando comprobaciones más útiles. Sin embargo debería desactivar las
optimizaciones mientras depura su programa. A pesar de ofrecer mejores
mensajes de aviso, posiblemente moleste más tarde a las herramientas de
depuración que vaya a usar.
@heading
Parte 5 - pidiendo ayuda
Bueno, así que ha probado todo lo descrito arriba y su programa sigue sin
funcionar. No tiene ni idea de qué hacer ahora, por lo que es tiempo de
aventurarse en las entrañas de la red, con la esperanza de encontrar
algún hombre sabio, adivino u oráculo que tenga la respuesta a su
pregunta...
El mejor lugar donde puede preguntar es probablemente la lista de correo
de Allegro: más detalles en el fichero readme.txt. Sin embargo, recuerde
que esta lista es específica de Allegro. Los problemas relacionados con
el lenguaje C o el compilador djgpp pertenecen a otros forums
(comp.lang.c y comp.os.msdos.djgpp respectivamente).
Tanto la lista de emails de Allegro como la de djgpp son archivadas, y
puede ojear los mensajes desde sus páginas web respectivas. Es muy
probable que encuentre una solución a su problema mirando las respuestas
a preguntas previas, lo que le evitará hacer la pregunta.
Según la netiqueta usual, se asume que cuando hace una pregunta en
cualquier forum de Internet al menos ya ha consultado primero la
documentación relevante, leyéndola por completo. Si el problema que tiene
merece ser planteado a cientos de personas para que lo resuelvan,
seguramente merecerá la pena tomarse unos minutos extra para solucionar
el problema usted mismo. Allegro está documentado extensivamente y se
considera un prerequisito para hacer una pregunta no sólo el haber leído
la documentación, sino también haber examinado los programas de ejemplo.
@heading
Parte 6 - aprenda de mis fallos
Qué no hacer, Primera Parte:
"Mi programa se bloquea. Por favor, dime porqué."
Si, a veces recibo preguntas como ésta :-) A pesar de años de práctica,
todavía no soy capaz de leer el pensamiento, por lo que es inútil este
tipo de pregunta. Para conseguir ayuda con un problema debe describirlo
con suficiente detalle como para que otras personas lo entiendan y puedan
reproducirlo: esto normalmente significa mandar parte de su código.
Qué no hacer, Segunda Parte:
"Tengo un problema con mi programa. Junto con este email mando un
fichero zip de 500k que contiene diez mil líneas de código y todos los
gráficos y sonidos necesarios: ¿por favor, puedes depurarlo y decirme
cual es el problema?"
Después de desperdiciar tiempo y facturas de teléfono para recibir un
fichero tan grande, es poco probable que nadie _quiera_ ayudarle, sin
olvidar el tiempo que se necesitaría para leer y entender tal enorme
cantidad de información. Tiene que aislar una parte más pequeña de código
que demuestre el problema: cuanto más corto sea, más probable será que
alguien le ayude. Recuerde que está pidiendo a otros que le hagan un
favor, por lo que es su responsabilidad hacerles este proceso tan
sencillo como pueda.
@heading
Parte 7 - escribiendo su petición
La cosa más importante es incluir código que puede ser compilado y
comprobado por la persona que lee su mensaje. No mande simplemente todo
su programa: extraiga una sección pequeña que incluya las líneas
específicas que causan su problema, o reproduzca el problema de forma más
simple (a menudo descubrirá que puede encontrar el error usted mismo al
hacer una versión simplificada de su programa, por lo que es un buen
ejercicio que puede hacer). Este código debería ser un programa pequeño
pero completo que puede ser compilado y ejecutado, ya que es muy difícil
depurar fragmentos incompletos de código.
Es mejor incluir el código directamente en el texto de su email, porque
a la gente le resultará más sencillo leer esto que si tuviesen que extraer
el código de un attachment.
Idealmente su ejemplo debería evitar el uso de gráficos externos y
ficheros de datos. Está bien incluir un pequeño zip (máx 2k) que contiene
información, o si no puede hacerlo, de una descripción de qué ficheros
necesita (ej: "pon un fichero .pcx de 32x32 llamado "tile.pcx" en el
mismo directorio que el programa). Si no hay modo alguno de simplificar
las cosas, debería copiar su programa y sus datos a una página web, y
entonces dar la URL del fichero zip en su mensaje.
Debería decir que línea de comando gcc ha usado para crear el programa,
y ésta debería incluir el parámetro -Wall.
Describa qué es lo que intenta hacer el programa (puede no ser obvio
instantáneamente para otras personas), y también qué es lo que hace
realmente cuando lo ejecuta. Normalmente no hace falta indicar el
traceback de su programa cuando se bloquea (otras personas pueden
duplicarlo por sí mismas siempre y cuando consigan compilar su código),
pero debería indicar si aparece este traceback, o se bloquea el
programa, o si devuelve resultados incorrectos (si es así, en qué
difieren estos de los que esperaba). Es útil marcar su código con
comentarios para indicar a qué línea apunta el traceback del programa.
Otra información que pueda añadir puede ser útil. Lo más importante es
una descripción corta de su hardware, información relevante de sus
controladores, y la versión de Allegro que está usando (por favor no diga
"WIP" a secas, sino la fecha exacta si está usando una versión que no sea
oficial).
@heading
Parte 8 - un modelo de perfección
Como referencia, aquí tiene un ejemplo de lo que yo consideraría un
mensaje ideal:
Estoy teniendo algunos problemas al intentar usar modos hicolor en mi
programa, a pesar de que estos modos funcionen bien con los programas test
de Allegro. Estoy usando Allegro 3.0 con djgpp 2.02 (versión gcc 2.8.1) en
un p166, ejecutando el programa bajo win95 y usando el driver VESA 2.0
incluido por defecto, descrito por el programa vesainfo como "Matrox
Graphics Inc.".
Este programa debería seleccionar una resolución 640x480 de 16 bits,
dibujar un rectángulo azul cerca de la esquina superior izquierda de la
pantalla, y entonces esperar la pulsación de una tecla antes de salir,
pero simplemente recibo un General Protection Fault cuando lo ejecuto.
Lo compilo usando "gcc -Wall t.c -o t.exe -lalleg", y no obtengo ningún
mensaje de error.
--- corta aquí, t.c ---
#include <stdio.h>
#include <allegro.h>
void main()
{
BITMAP *bmp = screen;
install_keyboard();
if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0) {
printf("Error seleccionando modo de vídeo\n");
return;
}
set_color_depth(16);
/* ¡ se bloquea cuando llama rectfill ! */
rectfill(bmp, 32, 32, 64, 64, 0x001F);
readkey();
}