Creación de complementos. Paso 2: extras

Ya tenemos un proyecto que anda, y configurado de forma que solo copiando un par de carpetas de un ZinjaI a otro podemos replicarlo. En esta tercera parte vamos a pulir algunos detallecitos y a generar el bendito índice de autocompletado que hará que ZinjaI nos ayude a utilizar las clases y funciones de la biblioteca mientras escribimos el programa cliente.

Empecemos por generar el índice. Lo vamos a hacer automáticamente a partir de las cabeceras (los .h y .hpp). Esto no siempre es lo mejor, porque a veces tienen definidas cosas demás, que no nos interesan para el autocompletado (como las guardas), o porque a veces no se condicen con la documentación. Digamos por ejemplo que para una clase Ventana la documentación dice que va "#include <Ventana.h>", pero en realidad Ventana.h no tiene la clase sino un montón de #ifs que según el sistema operativo hacen un #include diferente con la versión de la clase para cada sistema operativo. El parseo automático dirá por ejemplo que Ventana está en <Win32/Ventana.h> mientras que lo correcto es poner solo <Ventana.h> o de lo contrario no compilará en otro sistema. Como este hay muchos casos, y por eso los índices de wxWidgets y SFML-1 se generaron parseando los archivos de la referencia HTML y no las cabeceras. Pero este parseo es ad-hoc y requiere mucho trabajo (y programar), así que vamos por la forma fácil y esperemos que no traiga demasiados problemas.

Para ello, tenemos que abrir en un ZinjaI, sin utilizar un proyecto, todos los .h que tengan definidas las cosas de la biblioteca que vamos a utilizar. Y nada más, no debe haber otro archivo abierto. Una forma de hacerlo es utilizar el "Explorador de Archivos" de ZinjaI (Ctrl+E, o menú Ver). Allí buscan la carpeta de OpenCV (con Backspace suben, con Enter eligen), y luego por cada carpeta y subcarpeta que vean hacen click con el botón derecho y eligen "Abrir todos los fuentes".

La explicación es simple: ZinjaI para autocompletar utiliza información que recopila de dos fuentes: desde los índices de autocompletado (los que vienen con ZinjaI, que se configuran desde la pestaña Asistencias de las Preferencias), y de analizar los archivos que uno tenga abiertos o asociados al proyecto si se trata de un proyecto. Si abrimos todos los archivos .h, ZinjaI los analizará y aprenderá momentáneamente qué es lo que hay definido en ellos.

El árbol de símbolo (F2 o menú Ver) muestra sólo los símbolos de los archivos o del proyecto abierto, pero no los que cargó desde índices de autocompletado prefabricados. Entonces si vamos al árbol de símbolos veremos todo ese "conocimiento" nuevo. Ahora, podemos pedirle a Zinjai que guarde ese conocimiento generando un nuevo índice, para que no tengamos que volver a abrir todos esos archivos a cada rato ni asociarlos al proyecto. Para ello, simplemente hacemos click derecho en el árbol de símbolos (en cualquier parte), y elegimos "Generar índice para autocompletado...". Nos pedirá un nombre (que cumple con las reglas de un nombre de archivo, pero sin extensión), y luego un directorio. El directorio sirve para que ZinjaI sepa cómo agregar los #includes cuando apretemos Ctrl+H sobre una clase de la biblioteca. Supongamos que un .h está en "C:\OpenCV\build\include\OpenCV\OpenCV2\highgui\highgui.hpp". El include no puede decir "#include <C:\OpenCV\build\include\OpenCV\OpenCV2\highgui\highgui.hpp>", sino que debería decir simplemente "#include <OpenCV2\highgui\highgui.hpp>". El directorio base entonces que nos pide ZinjaI es el que corresponde a la parte del path que no debe colocar en el #include, es "C:\OpenCV\build\include\OpenCV\".

Ahora podremos ver y activar el nuevo índice en el cuadro de preferencias (Archivo->Preferencias...->Asistencias). Pero mejor que tenerlo activado todo el tiempo será activarlo sólo para el proyecto que utiliza OpenCV. Entonces, podemos ir al cuadro de Configuración General del proyecto, que no es el que habíamos usado para la compilación y el enlazado, sino el que se accede desde el ítem "Configuración General del Proyecto..." del menú Archivo. Allí tenemos un campo para elegir índices de autocompletado que sólo se activen para ese proyecto. El índice no se copia con el proyecto, solo se guarda su nombre. Por eso debe estar presente en la instalación de ZinjaI para poder utilizarlo, pero al abrir el proyecto se activa si no lo estaba antes, y al cerrarlo vuelve a desactivarse.

Ya que estamos en ese cuadro de diálogo, hay dos cosas más que serán útiles. Una es ponerle un nombre adecuado al proyecto, en el primer campo. Ese nombre será el que se muestre en la barra de título de ZinjaI. Algo como "Proyecto OpenCV" estaría bien. La otra, más interesante, es la posibilidad de tener siempre a mano la ayuda o referencia de la biblioteca. En ese cuadro hay un botón "Herramientas Personalizadas..." que nos permitirá agregar botones a la barra de herramientas de ZinjaI solo para ese proyecto. La idea es agregar un botón que permita acceder entonces a la documentación. Para el caso de OpenCV, ya comenté que lo mejor que encontré fue una referencia online. Entonces, podemos hacer un botón que nos abra un navegador y nos lleve directo a esa referencia:

1. Abrir el cuadro de "Configuración del Proyecto" desde el menú Archivo.
2. Hacer click en "Herramientas Personalizables..." para abrir un nuevo cuadro de diálogo.
3. Configurar la primer herramienta:
• En "Nombre", colocamos por ejemplo "Referencia OpenCV".
• En "Comando" colocamos "${BROWSER} http://docs.opencv.org/modules/refman.html". Este es el comando que ejecuta ZinjaI al hacer click en la nueva herramienta, reemplazando "${BROWSER}" por la llamada al navegador por defecto del sistema, o al que hayan configurado en las preferencias. Pueden usar el botón de los tres puntos (...) para insertar este tipo de variables si no saben cuales son.
• Luego activan el checkbox que dice "Mostrar en la barra de herramientas" y click en "Ejecutar".
• Si el navegador se abrió correctamente, le dan "Aceptar" al cuadro de configuración de la herramienta y ven aparecer su ícono en la barra de ZinjaI (aparecerán al final, a la derecha, será un martillo con un 0 azul).

Si la referencia se pudiese descargar en HTML sería mejor incluirla en el complemento en la carpeta "MinGW/OpenCV/doc" para tenerla disponible sin depender de la conexión a Internet. En ese caso, conviene colocar en el comando junto a "${BROWSER}" solo el nombre del archivo html que hace de índice, y la ubicación del mismo como ruta de trabajo usando la variable "${MINGW_DIR}". Aún en GNU/Linux esta variable existe (apunta siempre a zinjai/MinGW), y permite utilizar de esta forma la misma configuración de herramienta que en Windows. Y el hecho de poner el path como directorio de trabajo en lugar de poner la ruta completa en el comando, es porque ZinjaI adecua el formato del directorio de trabajo al sistema operativo automáticamente, intercambiando las barras ('/' y '\') según corresponda.

Un último detalle recomendable sería agregar al proyecto un nuevo archivo de texto Readme.txt o similiar con una pequeña descripción del mismo, aclarando qué se incluye, qué faltaría configurar (por ejemplo, si se pudiera modificar el perfil de compilación fácilmente para compilar estáticamente, o si no todas las partes de la biblioteca estuvieran enlazadas por defecto en el proyecto). Pueden ver ejemplos de esto en las plantillas de proyecto que incluye ZinjaI por defecto. Si piensan distribuirlo, también sería genial que la descripción esté en español y en inglés. Nada de esto es necesario para que el programa funcione, pero todo suma.

Finalmente, tenemos el proyecto listo. Compila, no depende de rutas fijas, ejecuta un ejemplo sin problemas, autocompleta, nos da un botón para ir a consultar al sitio web, etc. Lo único que resta es convertir todo este trabajo en plantilla de proyecto para que la próxima vez podamos crear un proyecto nuevo desde el asistente y tener todo listo sin hacer nada más que elegir "Proyecto OpenCV" en la lista de plantillas. Para eso, vamos al menú Herramientas y elegimos "Guardar como nueva plantilla...". Allí les pedirá dos nombres. El "nombre para mostrar" será el que aparecerá en la lista de plantillas del asistente de proyecto, mientras que el "nombre de archivo" será el nombre de la subcarpeta de esa plantilla y del archivo .zpr del mismo. En este ejemplo ponemos "Proyecto OpenCV" para el primero y simplemente "OpenCV" para el segundo. Dependiendo de la versión de ZinjaI, tal vez deban reiniciar ZinjaI para verlo en la lista del asistente.

Ahora sí, está todo lo necesario para el complemento ya generado. En la próxima y última parte solo veremos como utilizar la herramienta que empaqueta los complementos para armar el archivo .zcp que luego podremos distribuir e instalar con tres clicks.

Este post es continuación de Creación de complementos. Paso 1: relatividad y sigue en Creación de complementos. Paso 3: empaquetado.