@# @# 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(); }