Creación de complementos. Paso 3: empaquetado

Llegamos al últimos de esta serie de posts destinado a mostrar cómo se arman complementos para ZinjaI basados en bibliotecas externas. Vamos a ver a hora cómo utilizar la herramienta que empaqueta los archivos y genera el .zpc que después podemos instalar fácilmente en cualquier ZinjaI. Resumiendo mucho, los pasos que necesarios para llegar hasta aquí fueron:

1. Obtener los archivos necesarios para compilar un programa cliente de la biblioteca con MinGW. Esto incluye cabeceras, objetos y dlls. Lograr compilar y ejecutar un ejemplo con estos archivos. Más...
2. Armar una carpeta con lo mínimo necesario y modificar la configuración del proyecto para que busque esa carpeta en un ruta relativa a la instalación de ZinjaI. Más...
3. Generar el índice de autocompletado, configurarlo en el proyecto, agregar un botón para acceder fácilmente a la referencia, y guardar todo eso como template de proyecto. Más...

Resta juntar todo lo que tenemos, acomodarlo para el generador de complementos, y obtener finalmente el archivo .zcp. Veamos cómo.

Lo primero es crear en algún lado una carpeta para poner junto todo lo que necesita el complemento. En esa carpeta vamos a reproducir la estructura de directorios de una instalación de ZinjaI. Siguiendo con el ejemplo de OpenCV, sería:

1. Crear una carpeta "OpenCV" en algún lado, por ejemplo el escritorio.
2. Copiar los archivos de la biblioteca que vayamos a necesitar (binarios, cabeceras, documentación, etc). Para esto, creamos una subcarpeta "MinGW", y allí copiamos la subcarpeta OpenCV que habíamos creado antes en el MinGW de ZinjaI (probablemente esté en "C:\archivos de programa (x86)\zinjai\MinGW\OpenCV").
3. Copiar el índice de autompletado. Para esto creamos una carpeta "autocomp" y copiamos allí el archivo del índice. El índice que generamos antes estará en una carpeta llamada "zinjai" (o ".zinjai" en MacOS y GNU/Linux) que se crea en el home del usuario. Por ejemplo, si estamos en Windows 7 y el usuario se llama Zaskar, estará probablemente en "C:\users\zaskar\zinjai". Allí, entre archivos de configuración y temporales habrá una subcarpeta "autocomp" con los índices que hallamos generado.
4. Copiar el template de proyecto. Para eso creamos una subcarpeta "templates".  Las plantillas de proyecto están en la misma carpeta "zinjai" que los índices de autocompletado, pero en una subcarpeta llamada (cómo no) "templates". Si son plantillas de proyecto serán una carpeta cada una, si son plantillas de programa simple serán solo un archivo de extensión .tpl (sería buen detalle si se animan crear también el template de programa simple).

Eso es todo lo necesario para que funcione, pero falta algo importante, que debí mencionar antes. Tenemos que tener en cuenta la licencia de la biblioteca, para saber si podemos o no distribuir esos archivos, y qué otros archivos estamos obligados a incluir. En general, cuando las bibliotecas tienen licencias libres no muy restrictivas, lo que hago es agregar dentro de la carpeta de la biblioteca en ZinjaI ("MinGW\OpenCV" en este caso), un archivo de texto que indique de dónde obtuvimos los archivos que estamos distribuyendo, indicando exáctamente qué versiones utilizamos, cómo los compilamos si lo hicimos, etc, proporcionando enlaces al sitio oficial (y al sitio de donde lo descargamos si no fuera el mismo), y explicitando cuál es la licencia (incluyendo también otro txt u html con el texto completo de la misma si es posible) y quienes son los autores. La idea es que quede claro que software de terceros con licencia propia, que no es nuestro pero sí es libre, y que sea fácil rastrear los fuentes, la licencia, o cualquier otra cosa que no hayamos incluido. Esta información es fundamental (aunque a veces la licencia de la biblioteca no nos obligue a incluirla) si vamos a querer distribuir públicamente el complemento.

Ahora vamos a la carpeta donde instalamos ZinjaI y buscamos un programa llamado "complement.exe". Al abrirlo, veremos una ventana que nos pide algunos pocos campos:

• Directory with files to be included: El directorio que acabamos de crear y que tiene todo lo necesario.
• Complement's description: hay dos campos para descripciones, una en español y una en inglés. Esta es la descripción que aparece cuando desde ZinjaI iniciamos la instalación del complemento.
• Required ZinjaI version: qué versión mínima de ZinjaI debe tener el usuario para poder utilizar el complemento. Pueden abrir los archivos de proyecto con algún editor de texto y buscar el número donde diga "version_required=....". Ése número va allí. No podrán instalar el complemento quienes tengan versiones anteriores de ZinjaI. En este caso, por ejemplo, la mínima versión será al menos 20131122, ya que las versiones anteriores no soportaban el campo de variables de entorno en las opciones de ejecución del proyecto.
• Requires closing ZinjaI for correct instalation: si se necesita cerrar ZinjaI durante la instalación. Generalmente no, solo será necesario si reemplazamos archivos de ZinjaI, pero estos complementos usualmente agregan, no reemplazan. Ese campo estaba pensado para distribuir como complementos las versiones de prueba de ZinjaI y/o actualizaciones.
• Requires restarting Zinjai after installation: Si se activa, le avisará al usuario que deberá reiniciar ZinjaI luego de la instalación. En general es buena idea, ya que puede que ZinjaI no reconozca la nueva plantilla hasta que no se reinicie.
• Ouput file: el nombre del archivo de complemento que generará. Mi nomenclatura suele ser: "zinjai-add-XXX-YYY-ZZZ.zcp", donde XXXX será el nombre de la biblioteca en minúsculas, YYY será la abreviación de tres letras del sistema operativo para el cual está pensado, y ZZZ será la versión del mismo. Por ejemplo, en este caso podría ser "zinjai-add-opencv2-w32-20131123.zcp".

Si todo está listo, click en "Generate..." y en unos segundos tendremos el complemento empaquetado para llevar. Suelo generar por cada biblioteca al menos dos versiones, una con todos los archivos para compilar en Windows (el directorio MinGW), y otra sin ellos, para utilizar en Linux o Mac. Si se animan a hacer complementos y quieren compartirlos (obviamente de cosas que tengan permisos para distribuir) pueden enviármelos para que los publique en la sección de descargas del sitio de ZinjaI, con la debida mención al autor. Y si no, no importa, igual pueden hacerlos para uso personal y consultarme en los comentarios si algo no sale como se esperaba.

Este post es continuación de Creación de complementos. Paso 2: extras.