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:

  <p><br><br>
  <b> Code name: extname-extversion-#build.number#</b>
  </p>
  

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

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

  <target name="buildNumber">  
    <propertyfile     file="build.number"
        comment="Build Number for ANT. Do not edit!">
      <entry key="build.number" default="0" type="int" operation="+" />
    </propertyfile>
    <property file="build.number" />
  </target>
  

  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):

  <target name="copy-data-files">
              <copy file="config/config.xml" todir="${without_src}"/>
              <copy file="build.number" todir="${without_src}"/>
              <copy file="config/about.htm" todir="${without_src}"/>   <!-- AQUÍ SE HACE LA COPIA DEL about.htm A LA CARPETA TEMPORAL -->
              <loadproperties srcFile="build.number"/>
              <replace casesensitive="true"
              file="${without_src}/about.htm"
              token="#build.number#"
              value="${build.number}"/>                               <!-- AQUÍ SE HACE EL REMPLAZO DE #build.number# --> 
              <copy todir="${without_src}">
                      <fileset dir="config" includes="text*.properties"/>
              </copy>
              <copy todir="${without_src}/images">
                      <fileset dir="images/" includes="*"/>
              </copy>
  </target>
  

• De nuevo en el build.xml de nuestro plugin, hay que crear un target <distribution>, que llama al target <buildNumber> 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:

  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):

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

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_<extcodename>-<extplatform>.<zip|exe|bin>

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_<extcodename>-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 "<appname> </appname>". Luego habrá que situarse en el final del fichero, en la zona <pack>. 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:

• <file>: 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.

• <fileset>: copia un conjunto de fichero o directorios. Tiene los siguientes campos:

  • targetdir: Para especificar el destino, de igual manera que <file>.
  • ** 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 <file>.

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