.. warning::

   Este documento es una copia de un documento de trabajo.
   No tiene por que contener toda la informacion necesaria para poder
   realizar un instalable, pero consideramos que puede llegar a ser
   de interes a la comunidad por eso lo exponemos tal como lo tenemos.

   Partes de este documento han quedado obsoletas.

   La informacion mas reciente relacionada con el nombrado de los ficheros utilizados
   para la distribucion de binarios, documentacion y fuentes puede encontrarla en
   `Nombrado de binarios para un plugin de gvSIG`_.

   La informacion mas reciente relacionada con como nombrar y gestionar el numero
   de version puede encontrarla en `Interpretacion del numero de version en gvSIG`_.

.. _`Nombrado de binarios para un plugin de gvSIG` : https://gvsig.org/web/reference_catalog/lookupObject?uuid=ab2213e3b42ff25300be00b564b05c63
.. _`Interpretacion del numero de version en gvSIG` : https://gvsig.org/web/reference_catalog/lookupObject?uuid=99467e3828f3fe1a25ef5b6c96d17a13


.. contents:: Contenidos


Cómo se genera un instalable para un Plugin de gvSIG
=======================================================

Informacion previa
-------------------

Antes de generar un instalable para una extensión de gvSIG deberemos disponer
de la siguiente informacion:

* nombre o identificador de la extensión, extname: 
  Toda extensión en gvSIG deberá tener un nombre o identificado que la diferencie de las demas extensiones.

  Para los desarrollos oficiales se consultará con el responsable
  de desarrollo para obtener el nombre de la extensión.

* versión de la extensión, extversion: 
  Cuando una extensión se vaya a distribuir de forma independiente a gvSIG esta deberá disponer de un número de versión. 

  Para los desarrollos oficiales, la obtención
  de un número de versión adecuado se realizará enviando la petición al
  responsable de desarrollo de gvSIG, quien o bien asignará un número
  de versión o delegará en quien corresponda para que le sea asignado
  un número de versión a esa extensión.

* número de build de la extensión, extbn: 
  Se trata de un número interno que garantize que no existirán
  entregables distintos con el mismo nombre.
  Se espera que el número de versión mas el número de build de
  una extensión identifica de forma única a un entregable.
  Normalmente este número se genera de forma automática cuando
  se genera el empaquetado.

* nombre en codigo, extcodename:
  Se trata de una combinación de nombre, versión y número de build
  de la extensión. Su formato será::

    extname-extversion-extbn


Número de  build
-------------------

Un plugin debe añadir un panel (al que se accede en gvSIG por "ayuda->acerca de") en el
que figure su nombre en código, *extcodename*.

Para poder añadir dicho panel se seguirán los siguientes pasos:

* En la carpeta config del plugin, se tiene que crear un fichero **"about.htm"**. 
  Este fichero además de contener información sobre los desarrolladores de la extensión 
  tendrá que tener las siguientes líneas:

  .. code-block:: html

     



      Code name: extname-extversion-#build.number#
     

  Donde deberá sustituir manualmente los valores de *extbame* y *extversion*.

* Dentro de nuestro plugin, hay que crear en el build.xml un target ****, que se 
  encargará de aumentar el build number:

  .. code-block:: xml

      
      
        
      
      
    

  **Nota**: Existe un *task* para el ant que hace una función parecida, el problema es que funciona de forma distinta
  a la que nosotros trabajamos (*Deja el siguiente número de build en el fichero, en vez del actual*).

* El fichero **"about.htm"** se tiene que copiar en una carpeta temporal y hacer el remplazo del #build.number# (el about.htm que se copiará en gvsig será el que está en dicha carpeta temporal). Aquí un ejemplo (extraído del *extExpressionField/build.xml*):
    
  .. code-block:: xml

    
		
		
		   
		
						 
		
			
		
		
			
		
    

* De nuevo en el build.xml de nuestro plugin, hay que crear un target ****, que llama al target ** y luego al target por defecto. Este target por lo tanto hará lo mismo que el target por defecto con la única diferencia de aumentar el buildnumber del plugin.

* En los fuentes del plugin hay que crear una extensión (si ya la tenemos simplemente añadiremos dentro de ella) para registrar el panel de about.htm, un ejemplo sería:

  .. code-block:: java

	public class AboutMyextensionNameextension extends extension {
	
		public void initialize() {
			// TODO Auto-generated method stub

		}

		public void postInitialize() {
			About about=(About)PluginServices.getextension(About.class);
			FPanelAbout panelAbout=about.getAboutPanel();
			java.net.URL aboutURL = this.getClass().getResource(
		        "/about.htm");
		        panelAbout.addAboutUrl(PluginServices.getText(this,"MyextensionName"),aboutURL);
		}
        }

* Para acabar, hay que añadir en el fichero config/config.xml de nuestro plugin la extensión que acabamos de crear (en caso de que no existiera):
	
  .. code-block:: xml

	 class-name="com.iver.cit.gvsig.AboutMyextensionNameextension"
			description="extension to add about panel."
			active="true"
			priority="1"
	    
  


Nombrado de los binarios y del empaquetado de fuentes
-------------------------------------------------------


El nombre de los ficheros debe ir todo en *minúsculas*. Para los ficheros 
binarios de estos deberán tener el siguiente formato::

  gvsig_-.

Donde *extplatform* es:

* *windows-i586_j1_5*, para los binarios para *MS Windows* compilados
  para la máquina virtual de java version 1.5.X que no incluyan
  una distribución de la máquina virtual de java.

* *windows-i586-withjre_j1_5*, para los binarios para *MS Windows* compilados
  para la máquina virtual de java versión 1.5.X que incluyan
  una distribución de la máquina virtual de java.

* *linux-i586_j1_5*, para los binarios para *linux* compilados
  para la máquina virtual de java versión 1.5.X que no incluyan
  una distribución de la máquina virtual de java.

* *linux-i586-withjre_j1_5*, para los binarios para *linux* compilados
  para la máquina virtual de java versión 1.5.X que incluyan
  una distribución de la máquina virtual de java.

* *mac-10_4*, para los binarios para *Mac OS* versión 10.4 compilados
  para la máquina virtual de java que incluye de base esa versión
  de Mac.


En lo que respecta a las extensiones, estas serán:

* *exe* para los instalables de *MS Windows*.
* *bin* para los instalables de Linux.
* *zip* para los instalables de Mac.



Para las distribuciones de fuentes el formato será::

  gvsig_-src.zip

Se hace notar que en la distribución de fuentes no se hace distinción
entre plataformas.

  FIXME:

  Falta por especificar cómo se deben llamar los binarios
  cuando se trata de una actualización.


Generación del instalable
-----------------------------

Vamos a describir los pasos que se siguen actualmente para generar una distribución de binarios de una extensión para gvSIG.
Antes de empezar, hay que asegurarse de que en nuestro Workspace disponemos de la carpeta **"install"** y de la carpeta **"binaries"**, ya que estas dos carpetas son imprescindibles para generar los binarios.

Hay que descomprimir el fichero **"install/pluginInstallTemplate/install.zip**" dentro de nuestro proyecto. Este zip también se puede bajar de:

+ Si se está trabajando sobre el branch: `install_branch.zip `_   
+ Si se está trabajando sobre el trunk: `install_trunk.zip `_ 

Una vez descomprimido ya tenemos lo necesario (en forma de plantilla) para generar los binarios de cualquier extensión, y sólo se deberán hacer algunos pequeños cambios para adaptarla a cada extensión.

Primero tenemos que modificar el fichero build.properties. Este fichero contiene el nombre de algunas variables y de la extensión. Tal y como está comentado en el propio fichero, hay que indicar el directorio de nuestra extensión en **MAIN_INSTALL_PLUGIN**, verificar que los números de versión sean los correctos, indicar el nombre del plugin (extensión) en **APPNAME**, y finalmente indicarle el directorio en el que se dejarán los binarios en **OUTPUT_DIR**.

El siguiente fichero a modificar será install.xml. Este fichero sirve de guía para el IzPAck a la hora de generar el instalable. Al principio del fichero se debe indicar el nombre del plugin en **" "**.
Luego habrá que situarse en el final del fichero, en la zona ****. En esta parte se definen qué ficheros tendrán que añadirse sobre la instalación de gvSIG ya existente. En **"name"** se indica el nombre del paquete tal y como se mostrará a la hora de la selección de paquetes durante la instalación, y en **"descripcion"** se indica la descripción que aparecerá al seleccionar dicha extensión. Posteriormente se definen los ficheros a añadir. Para ello disponemos de dos *tasks*:

+ ****: copia un fichero o directorio. Tiene tres atributos a especificar:
    - **targetdir**: Para especificar el destino de los ficheros que se copiarán.

    - **src**: Para especificar el fichero/directorio que se copiará.

    - **override**: Para especificar si se sobreescriben los ficheros a copiar en caso de que existan. Generalmente será **true**.

* ****: copia un conjunto de fichero o directorios. Tiene los siguientes campos:
    -  **targetdir**: Para especificar el destino, de igual manera que .

    - ** dir**: El directorio desde el cuál se copiarán los ficheros.

    - **includes**: Los ficheros a incluir en la copia. Lo interesante de este campo es que se pueden introducir patrones (como * o ?).

    - **excludes**: Semejante a includes, sólo que aquí se especifican los ficheros que **no** se desean copiar.

    - **override**: igual que en .

*Para más información acerca de los tasks, hay un html de ayuda en la carpeta install del workspace: install/IzPack/doc/izpack/html/index.html*

Lo más normal será llevarse todo el directorio de nuestra extensión, y además, según qué extensiones, se llevarán otros ficheros (ver ejemplos en el propio *install.xml*).

Ahora tendremos que modificar el **buildExt.xml** para preparar la instalación para **MAC OSX** cuyo proceso es distinto. Básicamente, en el *target* llamado **InstallMac** hay que copiar los ficheros que hay que actualizar en la instalación (*igual que en el* **instal.xml** *pero usando los comando del* **ANT**). En el propio fichero hay comentados varios ejemplos. También existe el fichero **resources/configfile** que nos permite adaptar la configuración de la instalación de Mac (añadir un sufijo al nombre de la aplicación o comprobar el MD5 de andami), para más información sobre este fichero se puede consultar el fichero **install/instalador-gvSIG-mac/HOWTO-UPDATER,EXTS.txt** (**CUIDADO CON LOS EL FORMATO DE LOS RETORNOS DE CARRO**).


Con esto ya tenemos todos los parámetros necesarios para generar los binarios, y simplemente habrá que lanzar el **buildExt.xml**, en cuanto finalice encontraremos los binarios de nuestro plugin en la ruta que indicamos en **OUTPUT_DIR** del fichero build.properties.

Dónde dejar los instalables
----------------------------

Los instalables de las versiones previas de gvSIG se dejan en el FTP del proyecto, *downloads.gvsig.org*.

La primera vez que se crea un instalable para una extensión de gvSIG-desktop o gvSIG-mobile se creará en el FTP dentro de la carpeta de usuario del responsable del proyecto, o de la persona encargada de subir los instaladores, una carpeta con el nombre de la extensión, y dentro de esta otra que deberá tener como nombre el número de build de los instalables que se vayan a dejar.

algo como::

  [extname]-[extversion]/[extbn]

Y dentro se dejarán caer los instalables para todas las plataformas
soportadas.

Posteriormente se creará un ticket en gvSIG-Activities indicando la ruta a la carpeta que se acaba de crear asignándolo a *vacevedo*. 

Esta carpeta será **movida** a la zona pública del ftp para mantener los permisos de escritura, indicando en el ticket dónde queda dentro del ftp.

Las siguientes veces que se generen instalables para esa versión de la extensión de gvSIG-desktop o gvSIG-mobile ya no hará falta crear la carpeta en la carpeta personal del responsable del proyecto, podrá hacerlo directamente sobre la parte pública.


Cómo anunciar la generación de los instalables
-----------------------------------------------

El responsable del proyecto creará un ticket en bugtracking_ con las siguientes características:

**Short summary**: Nuevo build projname-projversion. 

**type**: nota.

**Full description**: información de interés para los testers (funcionlidades principales, novedades y cambios con respecto a build anterior), de qué tag del svn sale incluyendo la url pública del SVN o del ViewVC. Tener especial cuidado en que dicha url sea pública y por lo tanto pueda ser accedida sin usuario y contraseña. Esta descripción debe estar tanto en castellano como en inglés. 

**Assign to**: **NO** se asignará a ningún usuario. 

**cc**: se pondrá copia a la lista interna del proyecto: gvsig-announce-builds@lists.gvsig.org

**Subproject**: el que corresponda a la extensión

**Subproject version**: la que corresponda a la extensión

**Subproject build number**: el que corresponda a la extensión

.. note:: Los cambios en la página de descarga de builds en el plone pueden tardar hasta 12 horas en reflejar el nuevo build.

.. _bugtracking: https://gvsig.org/trac/bugtracking/newticket