[z.facultad/75.42/plaqui.git] / docs / manual_proyecto.lyx

#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass book
\language spanish
\inputencoding auto
\fontscheme default
\graphics default
\paperfontsize default
\spacing single 
\papersize Default
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Title

Manual del Proyecto
\newline 
PlaQui
\layout Author

Taller de Programación I
\newline 
Universidad de Buenos Aires
\layout Standard


\begin_inset LatexCommand \tableofcontents{}

\end_inset 


\layout Chapter

Integrantes.
\layout Itemize

Nicolás Dimov (77.624)
\layout Itemize

Leandro Lucarella (77.891)
\layout Itemize

Ricardo Markiewicz (78.226)
\layout Chapter

Programas de Prueba.
\layout Standard

Los programas de prueba se pueden encontrar en la carpeta 
\emph on 
tests
\emph default 
, allí se almacenaron los primeros ejecutables con los cuales se experimentó
 en temas que no se habían visto hasta el momento como 
\emph on 
drag&drop
\emph default 
, 
\emph on 
threads
\emph default 
 y 
\emph on 
sockets
\emph default 
.
\layout Standard

Con la ayuda de la herramienta subversion no fue necesario ir guardando
 versiones parciales del proyecto, ya que subversion guarda en un repositorio
 todas las versiones intermedias por nosotros, a las cuales se puede acceder
 en cualquier momento.
 Para obtener una versión particular del proyecto basta ejecutar:
\layout LyX-Code

svn co -r[rev|{fecha}] http://svn.llucax.hn.org/svn/plaqui/
\layout Standard

Donde 
\family typewriter 
-r
\family default 
 toma un parámetro que puede ser el número de revisión que se quiere obtener
 (
\family typewriter 
rev
\family default 
) o una fecha ingresada entre llaves (
\family typewriter 
{fecha}
\family default 
).
 Por ejemplo para obtener la revisión 1 se puede hacer:
\layout LyX-Code

svn co -r1 http://svn.llucax.hn.org/svn/plaqui/
\layout Standard

Y para obtener la versión de la fecha de la pre-entrega se puede hacer:
\layout LyX-Code

svn co -r'{2003-11-20 18:00}' http://svn.llucax.hn.org/svn/plaqui/
\layout Standard

Es por esto que nos pareció que no tenía mucho sentido acompañar este manual
 con una versión particular del repositorio en un momento dado.
\layout Chapter

Evolución del proyecto.
\layout Standard

La evolución del proyecto también se documentó a través del subversion,
 ya que a cada versión que se sube al servidor se la acompaña de un comentario
 sobre los avances realizados.
 Para ver el mensaje de cualquier cambio realizado en una revisión 
\family typewriter 
X
\family default 
 se puede hacer:
\layout LyX-Code

svn log -rX http://svn.llucax.hn.org/svn/plaqui/
\layout Standard

Para ver todos los mensajes basta con:
\layout LyX-Code

svn log -r0:HEAD http://svn.llucax.hn.org/svn/plaqui/
\layout Standard

Por conveniencia, en el directoria raíz del código fuente entregado en el
 CD se encuentra un archivo 
\family typewriter 
ChangeLog
\family default 
 con los mensajes de todas las revisiones del proyecto.
\layout Standard

A continuación se muestra una gráfica generada con un 
\emph on 
script
\emph default 
 hecho en Perl (
\family typewriter 
log_trace.pl
\family default 
, que se adjunta en el CD) que indica la cantidad de 
\emph on 
commits
\emph default 
 (cambios de versión) que se hicieron día a día, donde cada 
\family typewriter 
*
\family default 
 representa un 
\emph on 
commit
\emph default 
.
\layout LyX-Code

PlaQui - Grafica de Progreso SVN
\layout LyX-Code

--------------------------------
\layout LyX-Code

Fecha  Commits
\layout LyX-Code

2003-10-08     *(luca)
\layout LyX-Code

2003-10-12     *******(rmarkie)
\layout LyX-Code

2003-10-13     **(rmarkie|luca)
\layout LyX-Code

2003-10-15     *(rmarkie)
\layout LyX-Code

2003-10-16     *(rmarkie)
\layout LyX-Code

2003-10-17     ***(rmarkie)
\layout LyX-Code

2003-10-18     **(rmarkie)
\layout LyX-Code

2003-10-19     ***(luca)
\layout LyX-Code

2003-10-20     ***(rmarkie|luca)
\layout LyX-Code

2003-10-21     ***(rmarkie|luca)
\layout LyX-Code

2003-10-22     ****(luca)
\layout LyX-Code

2003-10-23     *****(rmarkie)
\layout LyX-Code

2003-10-24     *****(rmarkie|luca)
\layout LyX-Code

2003-10-26     *(luca)
\layout LyX-Code

2003-10-28     ***(sagar|rmarkie)
\layout LyX-Code

2003-11-06     ****(rmarkie)
\layout LyX-Code

2003-11-07     **(rmarkie)
\layout LyX-Code

2003-11-08     ****(rmarkie|sagar|luca)
\layout LyX-Code

2003-11-11     *****(rmarkie)
\layout LyX-Code

2003-11-12     ***(rmarkie|sagar|luca)
\layout LyX-Code

2003-11-13     *********(rmarkie|luca)
\layout LyX-Code

2003-11-15     *(rmarkie)
\layout LyX-Code

2003-11-16     *****(rmarkie|luca)
\layout LyX-Code

2003-11-17     *********(luca)
\layout LyX-Code

2003-11-18     **************(luca)
\layout LyX-Code

2003-11-19     *********(luca)
\layout LyX-Code

2003-11-20     ********************(rmarkie|sagar|luca)
\layout LyX-Code

2003-11-21     ***(luca)
\layout LyX-Code

2003-11-22     **(luca)
\layout LyX-Code

2003-11-23     ************(luca)
\layout LyX-Code

2003-11-24     ******(rmarkie|luca)
\layout LyX-Code

2003-11-25     ******(rmarkie|luca)
\layout LyX-Code

2003-11-26     ***(luca)
\layout LyX-Code

2003-11-27     ***(rmarkie)
\layout LyX-Code

2003-11-28     ***(luca)
\layout LyX-Code

2003-11-29     *****(luca)
\layout LyX-Code

2003-11-30     ***************(rmarkie|luca)
\layout LyX-Code

2003-12-01     ****************************************(luca)
\layout LyX-Code

2003-12-02     *********************************(luca)
\layout LyX-Code

( ) = Máximo Commiteador del Día
\layout LyX-Code

* == 1 Commit
\layout Standard

Los usuarios son:
\layout Description

sagar Nicolás Dimov
\layout Description

luca Leandro Lucarella
\layout Description

rmarkie Ricardo Markiewicz
\layout Standard

Vale la pena aclarar que en este gráfico no se muestran la cantidad de líneas
 modificadas, por lo que una gran cantidad de 
\emph on 
commits
\emph default 
 no significa necesariamente un gran cambio en el repositorio.
\layout Chapter

División de Tareas.
\layout Standard

A continuación se menciona, en términos generales la tarea que realizó cada
 integrante:
\layout Description

Leandro\SpecialChar ~
Lucarella PlaQui Server.
\layout Description

Ricardo\SpecialChar ~
Markiewicz PlaQui Model y PlaQui Client.
\layout Description

Nicolás\SpecialChar ~
Dimov PlaQui Constructor.
\layout Standard

Obviamente en algunas circunstancias algún integrante aporto al desarrollo
 de un módulo que no le estaba asignado.
 La documentación fue realizada y revisada entre todos los integrantes.
\layout Chapter

Inconvenientes Encontrados.
\layout Section

Servidor.
\layout Standard

El Servidor trajo varios problemas, en especial en cuanto al manejo de 
\emph on 
sockets
\emph default 
 y 
\emph on 
threads
\emph default 
.
 El uso de señales (para hacer el servidor orientado a eventos) dio también
 algunos problemas menores.
\layout Subsection


\emph on 
Threads
\emph default 
.
\layout Standard

El principal problema de los threads fue el no poder saber fácilmente donde
 se producía un error, en especial cuando el error venía por la falta de
 un 
\emph on 
mutex
\emph default 
.
 En términos generales, cada vez que el server tenía una violación de segmento
 se debía a la falta de un 
\emph on 
mutex
\emph default 
.
\layout Standard

Otro problema eran las excepciones no manejadas dentro del método 
\family typewriter 
real_run()
\family default 
 (que se ejecuta en su propio 
\emph on 
thread
\emph default 
).
 Aunque se incluía un bloque 
\family typewriter 
try ; catch
\family default 
 en el programa principal, al ocurrir una excepción en un 
\emph on 
thread
\emph default 
, dicha excepción no 
\emph on 
sube
\emph default 
 hasta el hilo padre y el programa sale con 
\family typewriter 
abort()
\family default 
.
 Es por esto que cada 
\family typewriter 
real_run()
\family default 
 tiene su propio bloque 
\family typewriter 
try ; catch
\family default 
 donde pueda surgir una excepción y se incluyó la 
\family typewriter 
signal_error()
\family default 
 en 
\family typewriter 
Runnable
\family default 
 para poder avisar de dicho error a quien lo necesite.
\layout Subsection


\emph on 
Sockets
\emph default 
.
\layout Standard

El principal problema con los 
\emph on 
sockets
\emph default 
 fue la imposibilidad (por enunciado) de usar 
\emph on 
sockets
\emph default 
 no bloqueantes.
 Esto tuvo particular repercusión en el 
\family typewriter 
TCPServer
\family default 
, ya que una vez llamado al 
\family typewriter 
accept()
\family default 
 para aceptar una nueva conexión, esta no retorna hasta que efectivamente
 se reciba una nueva conexión, haciendo imposible terminar el servidor de
 otra manera.
 Para resolver esto, al finalizar el 
\family typewriter 
TCPServer
\family default 
 se hace una 
\emph on 
conexión suicida
\emph default 
 para hacer que la llamada a 
\family typewriter 
accept()
\family default 
 retorne y el servidor pueda ser cerrado limpiamente.
\layout Subsection

Señales.
\layout Standard

La señales no dieron mayores problemas.
 El único inconveniente es que complican la depuración del programa, ya
 que uno no sabe de antemano quien las atenderá y se hace difícil seguir
 el flujo del mismo.
\layout Subsection

Falencias.
\layout Standard

El Server está preparado para servir (y simular) una cantidad indeterminada
 de plantas.
 Por problemas de tiempo esto no se llegó a implementar correctamente en
 el programa, en particular por la complicación que traería implementar
 dicha función en el cliente.
\layout Section

Constructor.
\layout Standard

A lo largo del desarrollo nos hemos encontrado con diferentes tipos de problemas
 los cuales pudieron ser solucionados, en su mayoría, de una forma aceptable.
 
\layout Standard

Al trabajar con imágenes independientes, las verificaciones sobre cada una
 de estas, dependen mucho de su posición en el área de trabajo y su orientación.
 Esto provoca que haya que realizar demasiadas validaciones para los diferentes
 tipos de verificaciones, y trae apareados problemas en la codificación
 por el uso de gran cantidad de coordenadas.
\layout Standard

Otro inconveniente no solucionado, fue que las imágenes de cada elemento
 que se coloca sobre la grilla se crean tantas veces como elementos de ese
 tipo haya.
 La idea en un principio fue crear todas estas imágenes estáticas, de modo
 que para un elemento de cuatro imágenes, se cargarían en memoria solamente
 esas cuatro imágenes y luego los elementos iguales apuntarían su imagen
 actual a la que corresponda.
 Esto no pudo ser solucionado pues no encontramos la forma de inicializar
 las imágenes de manera estática, se producían errores en el momento del
 linkeo.
\layout Standard

Por problemas de tiempo, hubo algunas implementaciones sobre el Constructor
 luego de cerrado el tema de la documentación, por ejemplo, el Constructor
 pregunta si quiere guardar el trabajo antes de salir del programa.
 Esto no fue documentado.
\layout Section

Cliente.
\layout Standard

El principal problema del cliente fueron los 
\emph on 
threads
\emph default 
.
 El asunto fue descubrir la forma de hacer que las actualizaciones de refresco
 de las propiedades y la creación dinámica de objetos sea 
\emph on 
thread-safe
\emph default 
 para garantizar a la Gtk+ cierta estabilidad.
 Luego de mucho leer se encontró el 
\family typewriter 
Glib::Distpatcher
\family default 
, que es un evento asíncrono especialmente diseñado para comunicación entre
 hilos.
\layout Section

Modelo.
\layout Standard

El Modelo tenía la complicación de la Union.
 Este elemento es complicado ya que para poder saber el estado a su salida
 se necesitaba saber el estado a sus 2 entradas, y esta información llegaba
 en forma asíncrona.
 Luego de mucho diseño, análisis de todas las combinaciones posibles entre
 las entradas se llego a un método que resulto exitoso en la mayoría de
 las pruebas y fue adoptado como definitivo.
\layout Standard

Otro inconveniente fue la suma de colores.
 El ejemplo dado en el enunciado no era para nada correcto.
 Para solucionar esto nos pusimos en contacto con Nicolás Reyna, estudiante
 de diseño industrial en la Universidad de La Plata, quien tiene un conocimiento
 mayor al nuestro acerca del comportamiento de los colores aditivos y su
 distribución RGB.
 En base a sus recomendaciones hicimos las sumas de colores en los distintos
 objetos.
\layout Standard

Por último, al verificarse la validez del conexionado de un archivo XML
 de planta en el Constructor, el Modelo no vuelve a realizar el chequeo,
 por lo que si se quiere levantar una planta desde un XML invalido los resultado
s son impredecibles.
\layout Chapter

Conclusiones.
\layout Standard

Se reforzaron los conocimientos en programación C++ y la programación orientada
 a objetos.
 El modelo utilizado aplica fuertemente estos conceptos, motivo por el cual
 no fue necesario utilizar un grafo para verificar los flujos por el circuito
 creado.
\layout Standard

El programa de desarrollo de interfaces Glade-2, y las bibliotecas Gtk+
 y Glademm facilitaron mucho la creación del Cliente y el Constructor, y
 nos hemos familiarizado con sus prestaciones, para crear aplicaciones visuales.
 
\layout Standard

Contamos con la ayuda del subversion y una lista de correos pudimos trabajar
 a distancia cómodamente, lo cual facilitó muchísimo las cosas y permitió
 que los tres integrantes del equipo pudiéramos contar con la totalidad
 del proyecto en todo momento, pudiendo conocer el trabajo de los demás
 y al mismo tiempo reportar 
\emph on 
bugs
\emph default 
 o complementar el trabajo de otro.
 En todo momento estuvimos actualizados sobre el desarrollo.
 Cabe mencionar que necesitamos juntarnos solamente una vez para distribuirnos
 las tareas.
 El resto del trabajo práctico se realizó a distancia.
\layout Standard

Nos ha parecido muy importante haber hecho todo el trabajo con ayuda de
 herramientas comunes de desarrollo de Software Libre, las cuales dejaron
 un producto final de una calidad igual o superior a cualquier otro entorno
 de desarrollo de aplicaciones, sobre todo las aplicaciones visuales que
 aprovechan un excelente trabajo de la GTK+ que suma un valor agregado como
 la posibilidad de cambiar la apariencia de la aplicación a través de 
\emph on 
themes
\emph default 
, sin costo alguno.
 Esto también nos permitió hacer un trabajo práctico usando 100% software
 legal, cosa que incluso grandes empresas no pueden realizar en muchos casos
 (ni hablar un estudiante).
\layout Standard

La documentación online generada con el Doxygen, si es bien utilizado, queda
 muy completa y es muy fácil realizar una búsqueda con la ayuda de un navegador.
 Esto puede comprobarse con la documentación online de la biblioteca Gtkmm
 (
\family typewriter 
www.gtkmm.org
\family default 
).
 La documentación en formato HTML del proyecto se encuentra en el CD y en
 
\family typewriter 
http://www.llucax.hn.org/plaqui/docs/html/
\family default 
.
\layout Standard

Hubo algunas ideas que no pudieron ser implementadas por cuestión de tiempo,
 y la documentación estaba programada para realizarse en cuatro días, pero
 tres días antes de la entrega nos enteramos que debíamos entregar el Martes,
 siendo que nosotros cursábamos los Jueves, lo que redujo el tiempo de documenta
ción a sólo dos días.
 Aún así creemos que se logró hacer un trabajo muy completo de documentación,
 en parte gracias a Doxygen (como se dijo antes) porque a medida que íbamos
 escribiendo el código lo íbamos documentando en línea.
\layout Standard

En general estamos muy conformes con el trabajo y la forma en la cuál fue
 realizado, cumplimos los requisitos pedidos por el enunciado y creemos
 que lo hicimos de una manera correcta.
\layout Standard

El proyecto completo es entregado en un CD que puede ser leído desde cualquier
 sistema operativo en cualquier tipo de lectora, pero también es un CD 
\emph on 
booteable
\emph default 
 con lo cual no es necesario ni siquiera tener un sistema operativo instalado
 o un disco rígido para poder operar el PlaQui.
 Basta activar la opción de 
\emph on 
booteo
\emph default 
 desde el CD en el 
\emph on 
BIOS
\emph default 
 y colocar el CD.
\the_end