Personal tools
You are here: Home gvSIG Projects gvSIG Desktop Documentation Developers documentation gvSIG devel guide gvSIG 2.0. Developers guide Trabajar con el núcleo de gvSIG
gvSIG Desktop
gvSIG Desktop

Cached time 11/21/13 16:49:07 Clear cache and reload

 


Introducción

En este apartado se definen los pasos necesarios para poder preparar un espacio de trabajo con el núcleo de gvSIG 2.0, así como compilarlo y generar instalables del mismo.

Note

si vamos a desarrollar un nuevo plugin o librería para gvSIG, es preferible trabajar con un build o instalable, y recurrir a esta opción sólo si no disponemos de binarios o tenemos que hacer alguna modificación sobre los proyectos del propio core.


Compilar gvSIG


Initial configuration

Prerequisites

Before starting the installation process and configuration of all the elements needed to operate gvSIG, it is recommended to review the basic starting points that are needed to make the process of running the application a successful experience.

  • First, this guide is based on the use of the open source multiplatform integrated development environment Eclipse, on which all the necessary processes for the preparation and support of gvSIG will run. The version that was used in the preparation of this tutorial is 3.2, so it is advisable to use the same version or higher.

  • It is also necessary to install any of the existing Eclipse plugins for working with Subversion, because there is no default support for developing such functionality. You may use the version of Subclipse or Subversive that is best suited to the version of Eclipse that you installed.

  • On the other hand, and to ensure the proper functioning of all the components that are used by gvSIG, you will need to have installed version 1.5 or higher of Java Virtual Machine (JVM) from Sun Microsystems. It is important to check that this is a version of SUN, as gvSIG will not function properly on virtual machines from other entities, like the one that comes with the Debian GNU systems. For everything to run well the following must be considered:

    • In the Java preferences of Eclipse, indicate the JVM to be used to run projects.
    • Verify that Eclipse has the correct JVM set in the initial configuration, as starting Eclipse with the wrong JVM version can cause problems when running gvSIG.
  • Finally, in addition to the Java virtual machine, gvSIG depends on a set of native libraries, among which are GDAL and PROJ. In case of Ubuntu, the libraries to be used are included in the distribution, and those can be installed through the corresponding package manager. The packages to be installed for the proper functioning of gvSIG are:

    • GDAL: libgdal1-1.4.0, libgdal1-1.5.0 or libgdal1-1.6.0 package, depending on which is available in your distribution.
    • GRASS (through GDAL): libgdal1-1.4.0-grass, libgdal1-1.5.0-grass or libgdal1-1.6.0-grass, depending on the GDAL version that you installed. When you install this package, it will also install GRASS.
    • PROJ: proj package

    For Windows or Mac, these libraries will be obtained through Maven when compiling and generating a build of gvSIG.

Once your computer meets these requirements, you can proceed with the installation of Maven and the creation of a workspace for gvSIG, since the other needed elements will be obtained by the built project of the application.

Initial configuration of Maven
Configuration of Maven

Apart from having a JDK installed, there is no need for any special configuration to begin working with Maven on gvSIG, because the gvSIG build project will install everything that is needed, including Maven.

However, if you want to install Maven yourself, you can download it from the project website and install it following the installation instructions. Keep in mind that Maven version 2.2.1 or higher is required for gvSIG.

You may also need to configure Maven to access the Internet through an HTTP proxy; the configuration is shown on the Maven installation page.

If you use the Maven installation included in the build project, you can find this in the Maven subfolder.

Note

Maven tests in gvSIG are done with the version included in the build project; with another Maven version the build of the project may not function properly.

Whether you install it yourself, or use the version provided by the build project, the subdirectory bin will contain the mvn script, that you can use when you are using Linux, Mac or any other Unix version, and the mvn.bat file for if you are using Windows. The most convenient way (to be able to run it from the console) is by adding the script to the run path (usually by adding the directory build/maven/bin to the PATH variable) so that you can run it from anywhere.

Later on we will describe some common tasks that can be used, either from a console or through the launchers from the External Tools menu in Eclipse.

Platform Configuration

gvSIG employs several native libraries, which are needed both for compilation and when running the application. Since they are native, you must use those that correspond to the platform on which you are compiling gvSIG.

A small configuration is needed to indicate the platform details to Maven, so that it can load the corresponding native libraries when compiling gvSIG. To do this, create a file .gvsig.platform.properties in your user's home directory with the following contents:

native_platform=linux
native_distribution=all
native_compiler=gcc4
native_arch=i386
native_libraryType=dynamic
export native_classifier=${native_platform}-${native_distribution}-${native_compiler}-${native_arch}-${native_libraryType}

The first 5 values are the important ones; their meaning is explained in the section on compiling native libraries.

The currently supported values, i.e. for which the native libraries are already compiled and available, are:

platform distribution compiler arch libraryType Comentarios
linux all gcc4 i386 dynamic Versión de 32 bits (equivalente en general a una Ubuntu-10.04)
win nt vs8 i386 dynamic Versión de 32 bits, compatible con windows XP, Vista y 7.
mac 10.5 gcc4 universal dynamic Plataforma todavía no disponible. Está en proceso de preparación y pueden variar alguno de los parámetros de la plataforma.

This configuration allows us to work directly with the configuration of the project that has been prepared to integrate Maven with Eclipse for gvSIG. If we invoke Maven from the command line, we will need to introduce these parameters to Maven in a different way. There are two options:

  • Include the native-classifier and the native-platform variables values each time you invoke Maven. Example:

    mvn -Dnative-classifier=linux-all-gcc4-i386-dynamic -Dnative-platform=linux install
    
  • Define an environment variable MAVEN_OPTS that includes the native_classifier variable. In Linux, for example, it would be enough to include the following in the .bash_rc file:

    if [ -f "${HOME}/.gvsig.platform.properties" ]
        then
            . ${HOME}/.gvsig.platform.properties
            export MAVEN_OPTS="-Xmx256M -XX:MaxPermSize=64m -Dnative-classifier=${native_classifier} -Dnative-platform=${native_platform}"
        else
            export MAVEN_OPTS="-Xmx256M -XX:MaxPermSize=64m"
        fi
    

    With this we can directly pass the platform values to Maven from Eclipse and to Maven from the console. For other operating systems you can pass the value directly to the native_classifier in the definition of the environment variable, but if you change the platform value, you must remember to change it for both cases (from Eclipse and from the console).

In addition to the platforms for which compiled native libraries are available, you can compile them by following the steps indicated in the document compilation of native libraries, and configure the parameters of the .gvsig.platform.properties file or the corresponding environment variable.

Write access to the Maven repository of gvSIG

Those who are responsible for publishing binaries, source code or gvSIG project documentation will need to configure Maven to have write access to the server which hosts the gvSIG Maven repository through SCP (SSH).

To do this you must configure the Maven settings.xml file with the necessary information to access the Maven repository of gvSIG. This file is located in the USER_HOME/.m2 /, where USER_HOME is the user's home directory, which depends on the operating system that you are using.

If this is the first time you use Maven 2, you will need to create this folder as well as the settings.xml file manually.

The file needs an entry to configure the access to the gvSIG server, which is indicated with its ID gvsig-repository. Since the access is through SSH, we need to include the username and password:

<?xml version="1.0" encoding="UTF-8"?>

<settings xmlns="http://maven.apache.org/POM/4.0.0" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                        http://maven.apache.org/xsd/settings-1.0.0.xsd">

    <servers>
        <server>
            <id>gvsig-repository</id>
            <username>[USUARIO]</username>
            <password>[CLAVE]</password>
            <filePermissions>666</filePermissions>
            <directoryPermissions>777</directoryPermissions>
        </server>
    </servers>
</settings>

Note

It is important to include the permission settings as indicated in the example above, because with every file that is uploaded, the user and group that uploaded it is specified to prevent other users from uploading modifications to the same file. In any case, a script on the OSOR server will update the file permissions on a daily basis.

If you do not want to show the password in the previous file, Maven can encrypt passwords from the latest versions onwards. To do this, follow the steps described in the Maven documentation on Password Encryption

To summarize, the steps are:

  1. Create a master password to encrypt the server passwords with this command:

    mvn --encrypt-master-password <clave-maestra>
    

    This will return the encrypted password, something like:

    {jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}
    
  2. Keep the master password in the file [USER HOME]/.m2/settings-security.xml (create the file if it doesn’t exist yet) with the following content:

    <settingsSecurity>
      <master>[CLAVE MAESTRA ENCRIPTADA]</master>
    </settingsSecurity>
    

    Using the example from the previous step, it would be something like this:

    <settingsSecurity>
      <master>{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}</master>
    </settingsSecurity>
    
  3. Encrypt the password to access the OSOR server:

    mvn --encrypt-password <clave>
    

    Which will return something like:

    {COQLCE6DU6GtcS5P=}
    
  4. Substitute the open password with the encrypted password in the [USER HOME]/.m2/settings.xml file:

    <server>
      <id>gvsig-repository</id>
      <username>[USUARIO]</username>
      <password>[CLAVE ENCRIPTADA]</password>
    </server>
    

    Following the previous example, it would result in something like this:

    <server>
      <id>gvsig-repository</id>
      <username>USER</username>
      <password>{COQLCE6DU6GtcS5P=}</password>
    </server>
    
How to create an Eclipse workspace for gvSIG

The steps for creating an Eclipse workspace for working with gvSIG are as follows:

  1. Start Eclipse and create a new workspace for gvSIG 2.0.

  2. Set the encoding used in gvSIG (ISO-8859-1):

    Window > Preferences: General > Workspace > Text file encoding = ISO-8859-1
    
  3. Set compatibility with Java 1.5 / 5.0 for all the projects (those which are compatible with Java ME CDC also have compatibility with Java 1.4):

    Window > Preferences > Java > Compiler > Compiler Compliance Level = 1.5 (or 5.0). 
    
  4. In Eclipse, register the subversion repository in which we will be working.

    It is possible to access to the subversion repository in two different ways:

    • Anonymous access with read only permission.
    • Access with read and write permission. For this you need a user in the infrastructure of gvSIG.

    The access URL is: https://devel.gvsig.org/svn/gvsig-desktop.

    Because a default installation of Eclipse does not provide support for subversion, it is necessary to install plugins for doing so:

    Note

    It is important to take note of the subversion plugin's version or configuration, and to ensure that is the same version as the subversion client in all cases: command line, Eclipse, etc. This is because with each new version of subversion the local format of the information changes, and backward compatibility is not maintained.

    In other words, if a subversion 1.6 client is used for doing a checkout or an update, an older version (1.5. 1.4, etc.) will not work correctly if it is used subsequently.

    If internet access is through a proxy, this must first be configured in Eclipse. To do this select the option:

    Window > Preferences > General > Network Connection 
    

    Proxy access to the network can be configured in the preferences window. It is possible to choose either System proxy configuration or to specify a Manual proxy configuration and then manually set the connection values.

    To register the choosen subversion repository, open exploring perspective of the subversion repository. If it is not available, it can be accessed from:

    Window > Open Perspective > Other : SVN Respository Exploring
    

    Once the perspective has been opened, it is possible to add the gvSIG repository from the SVN repositories view.

    From this point onwards project locations within the gvSIG subversion repository will be referred to. The repository has the usual subversion structure:

    • trunk: latest development version.
    • tags: closed versions and builds, for which a tag is generated.
    • branches: development branches.

    From here on, the subversion paths will show [Repository]/[VERSION] rather than indicating the repository, and if trunk, tags/v2_0_0_Build_2007, etc. Keep in mind that at the time of writing, version 2.0 is being developed in branches/v2_0_0_prep branch, which is where projects can currently be downloaded, even though they will in future be moved to the trunk.

  5. Download the build project.

    To do this, one must apply a checkout from the source repository. From the SVN Repository view, navigate to:

    [VERSION] (ej: branches/v2_0_0_prep)
    

    Select the build folder and apply a checkout by clicking on the left button on the folder and selecting the appropriate option. In the checkout dialog, accept the default options and click Finish.

    Once finished, the project will be available in the Java or Resource perspective.

    Alternatively, the following command can be executed from the console:

    svn co https://devel.gvsig.org/svn/gvsig-desktop/branches/v2_0_0_prep/build
    

    As with Eclipse, if internet access is through a proxy, the subversion client must be configured to connect to the server through the proxy. The configuration instructions are available in the FAQ of the official subversion web, or in the section on configuration of servers in the subversion book.

    Once the build project has been downloaded from the console, it can be imported into Eclipse.

  6. Open the Ant view by selecting the following menu option:

    Window > Show view > ant
    
  7. Install the basic configuration of Maven for gvSIG.

    The build project contains the basic Maven configuration for all the gvSIG projects in a general pom.xml, as well as specific configurations for each project type:

    • library: build/libraries-pom/pom.xml
    • native library: build/libraries-jni-pom/pom.xml
    • extension: build/extension-pom/pom.xml

    Initially, and each time that any of these files are changed, these files must be installed in the local repository of Maven. There are two ways of doing this:

    • Eclipse: Add the build.xml file in the build project to the open Ant view. A number of Ant objectives will appear, amongst which is mvn-install. This is launched by double clicking or by selecting the required objective and clicking the icon.

    • Console: from the build folder, launch:

      mvn install
      
  8. Configure Eclipse to correctly load the projects generated from Maven.

    To do this, from the Ant view invoke the objective: mvn-configure-eclipse-workspace. This will automatically create an environment variable in Eclipse, which is used to refer to the jars of the dependences managed through Maven. It will ask for the location of the workspace, which usually will be the default.

    Alternately, from the console it is possible to use Maven as follows:

    mvn -Declipse.workspace=<path-to-eclipse-workspace> eclipse:add-maven-repo
    

    Then close Eclipse and open it again.

  9. Check that the M2_REPO variable is correctly defined in Eclipse. From the menu select:

    Window > Preferences : Java > Build Path > Classpath Variables 
    

    The variable value must be something like (replace [USER_HOME] for the user's folder, according to the Operating System):

    M2_REPO = [USER_HOME]/.m2/repository
    
  10. To the Ant view add the build.xml file from the group of projects that you are going to work on. Groups of Projects will be explained in detail at a later stage but for now think of them as lists of projects (libraries and extensions) which are in the build/projects folder.

    If the intention is to download the projects of a complete gvSIG, add the following file to the Ant view:

    build/projects/gvsig-standard/build.xml
    
  11. Start downloading the projects.

    To do this, from the Ant view invoke the objective: svn.checkout.all. A form opens where it is possible to select:

    • The URL of the subversion server, which depends on whether public access with read only rights, or access with read and write rights (which requires a user name and password) is preferred.
    • The SVNKit version to use. It is necessary to check that this is the same as that of the subversion support plugin installed in Eclipse. As in the previous cases, accessing the Internet through a proxy requires the access for the SVNKIT library to be configured. In fact, this library reads the same configuration as the native client of subversion, whose configuration is described in Download the build project. More information is available in the users guide of SVNKIT
    • User name and password to access subversion, if applicable.
    • Whether to automatically create the Eclipse project configuration once the download is complete. If this option is deactivated, the Eclipse projects have to be generated either from the mvn eclipse option on the External tools menu or from the console with the instruction: mvn -P eclipse-project.

    Alternatively, it is possible to invoke this Ant objective from the console, or to do a checkout of each project, from Eclipse or from the console. In the latter case, it will be also be necessary to generate the Eclipse project configuration.

  12. Import the projects into Eclipse. Once the previous step is complete the projects can be imported into Eclipse by choosing the following menu option:

    File > Import > General > Existing projects into workspace
    

    Click on Select root directory and select the workspace directory. The list showing the projects to import will appear and, after accepting them, Eclipse will proceed to compile the imported projects.

    Note

    when importing the projects, check that the option Copy projects into workspace is deactivated, because the intention is to use the same projects which have been downloaded directly.

  13. The eclipse plugin for maven does not link eclipse projects between them until they are already imported into the eclipse workspace, so we must regenerate the projects eclipse configuration.

    From the Ant view, select the mvn-eclipse-eclipse goal. Once the process has finished, select all projects and refresh them (F5 o press the right button and select the Refresh option).

  14. Finally, the eclipse plugin for maven generates the eclipse plugin configuration only for the java projects, that is, the projects which have java code. As there are some multimodule projects, only the eclipse project configuration of the submodule final children will be generated. As an example, the org.gvsig.annotation project has the following structure:

    org.gvsig.annotation
    ├── org.gvsig.annotation.lib
    │   ├── org.gvsig.annotation.lib.api
    │   └── org.gvsig.annotation.lib.impl
    ├── org.gvsig.annotation.main
    └─── org.gvsig.annotation.swing
        ├── org.gvsig.annotation.swing.api
        └── org.gvsig.annotation.swing.impl
    

    If we look at the current imported projects, we will find only the following ones:

    • org.gvsig.annotation.lib.api
    • org.gvsig.annotation.lib.impl
    • org.gvsig.annotation.main
    • org.gvsig.annotation.swing.api
    • org.gvsig.annotation.swing.impl

    We need to have, at least, each root parent project to be able to update everything when synchronizing from subversion, as well as allowing us to perform actions to all the submodules of the same project.

    There is only one way that we are aware of to be able to import those root parent projects:

    • Select the eclipse menu: File > New > Project....

    • In the dialog, select the option: General > Project and click Next

    • In the following dialog, fill in the following form fields:

      • Project name: The name of the parent root project to import. Ex: org.gvsig.annotation.
      • Use default location: Select this option.

      Finally click Finish and the project will be available in eclipse. Its not a java project, so we must not edit java files from it, but through the subprojects. Those root projects will be used only to perform maven actions to all the submodules or to synchronize from subversion.

    Those are the projects to import that way:

    • org.gvsig.annotation
    • org.gvsig.annotation.app
    • org.gvsig.app.document.layout.app
    • org.gvsig.app.document.table.app
    • org.gvsig.exportto
    • org.gvsig.exportto.app
    • org.gvsig.geometrymeasurement.app
    • org.gvsig.hyperlink.app
    • org.gvsig.installer
    • org.gvsig.installer.app
    • org.gvsig.newlayer
    • org.gvsig.newlayer.app
    • org.gvsig.personaldb
    • org.gvsig.selectiontools.app
    • org.gvsig.symbology
    • org.gvsig.symbology.app

Note

This final step is certainly cumbersome, but we haven't found a more authomatic way to perform it. We had already tried to commit to subversion the .project files of those root projects but then, in the initial eclipse import of all the gvSIG projects, only the root projects are included. You had to import then each child submodule one by one, which is still worse. The maven plugin for eclipse could be used to solve that problem, but is has other problems still to be solved.

Integración con eclipse

En el momento de preparar esta guía, Eclipse no lleva soporte de forma oficial para maven. Existen algunos plugins disponibles que permiten integrar maven en eclipse, aunque parece que todavía no son completamente funcionales. Uno de ellos (Q4E), de hecho, está en proceso de ser incorporado a eclipse de forma oficial, bajo el nombre Eclipse IAM, pero todavía no ha sido liberado.

Por no ligarnos a un plugin no oficial de eclipse, por ahora se va a emplear una integración básica de eclipse con maven, que permita en cierta forma compartir la configuración de proyecto de maven con eclipse, así como invocar a maven desde el propio eclipse.

Preparar el workspace para trabajar con maven

Note

si nos hemos descargado el workspace siguiendo las instrucciones del documento Cómo montar un workspace con Eclipse (ver documentos relacionados), ya tendremos el workspace preparado.

Para que el eclipse sea capaz de encontrar el repositorio de maven es necesario configurar la variable en el workspace. Esto lo podemos hacer de forma sencilla empleando el plugin eclipse de maven, con el objetivo:

mvn configure eclipse workspace

Al hacerlo desde eclipse, ya tomará por defecto el valor del path del workspace sobre el que estamos trabajando.

Si queremos lanzarlo desde consola, la instrucción es:

mvn eclipse:add-maven-repo -Declipse.workspace=WORKSPACE_PATH

En 'WORKSPACE_PATH' especificaremos la ruta absoluta al workspace.

Generación de proyectos de eclipse desde maven

Note

los proyectos generados desde eclipse con los objetivos create library y create extension ya generan también automáticamente el proyecto de eclipse.

Si tenemos un proyecto configurado con maven, no es necesario crear manualmente el proyecto de eclipse, ya que maven puede generarlo por nosotros. Para ello bastará con usar el siguiente objetivo:

mvn eclipse

Desde consola, la instrucción equivalente es:

mvn -P eclipse-project

Note

La forma habitual de generar un proyecto de eclipse desde maven es emplear la instrucción mvn eclipse:eclipse. Sin embargo, para algunos proyectos, como los que generan varios jars en los que se incluyen clases de tipo Library, el plugin de maven que genera los proyectos de eclipse no es capaz de generar toda la configuración necesaria, por lo que se ha creado un perfil desde el que se invoca al plugin de eclipse y, además, añade el resto de configuración necesaria. Si en algún caso se creara el proyecto de eclipse sin usar el perfil eclipse-project, el único problema es que los tests unitarios que empleen el mecanismo de inicialización automática de librerías no funcionaran si los lanzamos desde eclipse.

Esto generará los archivos de eclipse necesarios, que nos permitirán importar el proyecto desde eclipse, con todas las dependencias, directorios de fuentes, etc. ya definidos.

Si ya existe el proyecto de eclipse, el objetivo anterior no lo sobreescribe, para ello tenemos que emplear antes el objetivo:

mvn eclipse clean

O desde consola:

mvn eclipse:clean

En los proyectos de gvSIG, está configurado de forma que, además de descargar y enlazar las dependencias binarias (jars con clases) en el proyecto de eclipse, maven intentará descargar también los jars con los fuentes y los javadocs correspondientes, enlazándolos a cada jar de binarios. Esto nos permitirá ver fácilmente la documentación y el código fuente de las dependencias de nuestros proyectos.

Por otro lado, si generamos los proyectos de eclipse para un grupo de proyectos, maven nos enlazará las dependencias entre los proyectos del grupo a nivel de proyecto, en vez de a nivel de archivo jar.

Esto permite que los proyectos de eclipse no se suban al repositorio de fuentes de gvSIG, ya que se pueden generar fácilmente para un proyecto o conjunto de proyectos.

Cómo invocar maven desde eclipse

Para facilitar el uso de maven desde eclipse, se han preparado una serie de lanzadores con los objetivos más usados en los proyectos con maven.

Dichos lanzadores están definidos dentro del proyecto build, por lo que una vez incluido este proyecto en nuestro workspace de eclipse, los tendremos disponibles automáticamente.

Para lanzar cualquiera de ellos deberemos tener abierto el proyecto sobre el que queremos trabajar, y seleccionar el lanzador correspondiente desde la opción de Herramientas externas (External Tools).

Errores habituales
  • Eclipse no detecta una dependencia en el repositorio de maven, aunque el jar correspondiente sí que existe en disco

    Por alguna razón, parece que Eclipse no se da cuenta de cambios en librerías de dependencias que están puestas a través de una variable de entorno. Incluso refrescando y recompilando el proyecto a veces no detecta el jar correspondiente.

    Una forma que suele funcionar consiste en:

    1. Cerrar el proyecto.
    2. Abrir el proyecto.
    3. Recompilar el proyecto.
Plataformas soportadas
platform distribution compiler arch libraryType Comentarios
linux all gcc4 i386 dynamic Versión de 32 bits (equivalente en general a una Ubuntu-10.04)
win nt vs8 i386 dynamic Versión de 32 bits, compatible con windows XP, Vista y 7.
mac 10.5 gcc4 universal dynamic Plataforma todavía no disponible. Está en proceso de preparación y pueden variar alguno de los parámetros de la plataforma.

Compilar un grupo de proyectos

Maven permite trabajar con lo que llama multimódulos o una estructura multiproyecto. Esto nos permite lanzar una orden de maven sobre un grupo o jerarquía de proyectos, desde una única llamada a éste. Para ello tenemos un pom.xml que hace referencia a un conjunto de proyectos de maven.

La estructura habitual consiste en tener una organización en árbol de proyectos, pero también podemos tener una estructura plana, en el que el proyecto que contiene el pom.xml en el que se hace referencia al resto de proyectos se encuentra a la misma altura que estos.

En gvSIG la estructura de proyectos que hay en el repositorio de fuentes no está pensada para ser descargada tal cuál, sino que se debe descargar proyecto a proyecto, con lo que tenemos una lista de proyectos todos dentro del mismo directorio.

Aunque en un futuro se podría migrar a una estructura multimódulo de proyectos, por ahora la vamos a simular mediante grupos de proyectos dentro del directorio build de gvSIG. Dentro de este, en el subdirectorio projects se han creado una serie de directorios, cada uno de los cuáles hace referencia a un grupo de proyectos:

build
`-projects
  |-gvsig-base
  |-gvsig-cdc-compat
  |-gvsig-coverage
  |-gvsig-coverage-base
  ...

Si accedemos a uno de estos directorios, vemos que contienen un archivo pom.xml, el cuál hace referencia a un conjunto concreto de proyectos. Así, si desde aquí usamos maven, la orden se lanzará automáticamente para cada uno de los proyectos referenciados.

Este mecanismo nos permite, de forma cómoda, realizar operaciones de compilación e instalación sobre un conjunto de proyectos, o incluso generar un build de gvSIG completo.

El criterio para definir los grupos ha sido el de unir proyectos sobre una misma funcionalidad o cuyo desarrollo se realice de forma conjunta. Además, aprovechando que un pom.xml puede hacer referencia, tanto a proyectos sueltos, como a otros conjuntos de proyectos, se ha definido un grupo para la generación de un build completo con la unión de otros grupos.

Por ejemplo, si estamos desarrollando sobre GPE, actualmente está dividido en los siguientes proyectos:

  • libGPE
  • libGPE-XML
  • libGPE-GML
  • libGPE-KML
  • extGPE-gvSIG

Si queremos compilarlos todos a la vez, bastará con ir al directorio gvsig-gpe y realizar la orden:

mvn compile

Esto realizará la compilación de los distintos proyectos de GPE, uno tras otro. Si, en alguno de ellos, se produce un error de compilación, el proceso se detendrá y no seguirá en los siguientes.

Dentro de cada uno de estos directorios de grupos de proyectos, tenemos también un script de utilidad que nos permite hacer un checkout de forma rápida de los proyectos del grupo. Por ejemplo, si queremos desarrollar sobre GPE, bastará con hacer un checkout inicial del directorio build y, a continuación, desde el subdirectorio projects/gvsig-gpe llamar al script svnco.sh, que se encargará de hacer un checkout de los proyectos de GPE.

Compilar un gvSIG completo

Aprovechando el mecanismo anterior de los grupos de proyectos, se han definido dos grupos que permiten trabajar con todos los proyectos de un build de gvSIG:

  • gvsig-base: conjunto de proyectos básicos para tener un build de gvSIG mínimo con soporte vectorial sobre algunos formatos de archivo básicos. Se puede emplear durante el desarrollo de nuevas extensiones que no dependan de otros proyectos, sin cargar otras extensiones.
  • gvsig-standard: conjunto de proyectos de un build estándar de gvSIG. Incluirá habitualmente el conjunto de proyectos que conformarán un build oficial de gvSIG.

A partir de ahora consideraremos que vamos a trabajar con la versión del build estándar.

Para compilar todo gvSIG usaremos maven, bien desde eclipse, bien desde consola. La forma habitual será mediante el objetivo install:

  • Eclipse: si no lo tenemos aún, añadiremos a la vista de Ant el archivo build/projects/gvsig-standard/build.xml y lanzaremos el objetivo mvn-install. De la misma forma, tenemos otros objetivos de uso habitual accesibles con este mecanismo, con su equivalencia en maven, como por ejemplo:

    • mvn-clean
    • mvn-install
    • mvn-install-without-tests: equivalente a mvn -Dmaven.test.skip=true install
    • mvn-reinstall: equivalente a mvn clean install
    • mvn-reinstall-without-tests: equivalente a mvn -Dmaven.test.skip=true clean install

    Al menos la primera vez deberían compilarse y lanzarse los tests unitarios en los proyectos que los tengan activados. El resto de veces, se puede hacer la compilación sin lanzarlos mediante el objetivo mvn-install-without-tests.

  • Consola:

    mvn install
    

Esto compilará todos los proyectos e instalará todas las extensiones y sus archivos en la ubicación correspondiente.

Arrancar gvSIG

Los builds de gvSIG desde maven están configurados para ser generados en el directorio build/product, en vez de dentro del proyecto de _fwAndami como se hacía con ant.

Podemos lanzar gvSIG de dos formas distintas:

  • Eclipse: automáticamente, al haber incluido el proyecto build se nos habrán configurado una serie de configuraciones de arranque de utilidad. Para arrancar gvSIG seleccionaremos:

    Run > Run Configurations > Java Application
    

    De la lista de configuraciones, tendremos al menos las siguientes 3:

    • gvSIG Linux
    • gvSIG Mac
    • gvSIG Windows

    Seleccionaremos la que corresponda a nuestro sistema operativo. Esta configuración la podemos usar, tanto para ejecución normal, como para ejecución de gvSIG en depuración.

    Estos launchers están configurados incluyendo en su classpath la lista the archivos .jar disponibles en la carpeta build/product/lib de forma individual, los cuáles se corresponden con el propio jar the andami más todas sus dependencias. Dado que dichos archivos se generan y copian a través de maven, algunas veces eclipse no se da cuenta de los cambios en dicha carpeta.

    Algo que pasa algunas veces es que eclipse cree que no hay nada en la carpeta build/product/lib, y sin embargo sí que están los archivos. Entonces, al usar uno de los launchers eclipse nos da un error, algo como:

    The archive: /build/product/lib/castor-0.9.5.3.jar which is referenced by the classpath, does not exist 
    

    Para solventarlo bastará con ir a la carpeta build/product/lib con el package explorer, project explorer o navigator de eclipse y refrescarlo. Entonces ya aparecerán los archivos jar necesarios y podremos lanzar el launcher de nuevo.

  • Consola: dentro del directorio build/product tenemos ya un gvSIG.sh, o un gvSIG.bat según corresponda, para arrancar el build de gvSIG que hayamos generado.

Librerías nativas

Introducción

Algunas de las extensiones de gvSIG, necesitan el uso de librerías nativas para su funcionamiento. El problema existente con este tipo de librerías es que es necesario tenerlas compiladas para cada plataforma y sistema donde se quiera hacer uso de gvSIG.

Para facilitar la distribución y construcción de estas librerías se ha integrado con el actual sistema de construcción basado en maven. Para ello se ha añadido funcionalidad a las fases de construcción. Es necesario entender que cuando se trabaja con librerías nativas existen tres partes claramente diferenciadas:

  • Código Java: Código únicamente Java y que puede ser distribuido sin tener que recompilar para cada plataforma, éste código se compila de manera estándar y no necesita ningún tipo de tratamiento especial. Éste código será el encargado, mediante una API concreta y conocida de la máquina virtual, de cargar las librerías nativas.
  • Código JNI: Código generalmente en C/C++ que hace uso de la API JNI(Java Native Interface). Éste codigo ya es dependiente de plataforma y requiere ser compilado para cada plataforma destino donde se quiera utilizar la librería.
  • Dependencias nativas externas: En proyectos tan grandes, es habitual depender de otras librerías. En gvSIG el caso más claro es la librería GDAL. Estas dependencias requieren también estar compiladas para la plataforma destino y además se necesita tener acceso a su SDK, para poder compilar la parte JNI anteriormente mencionada.
Uso de librerias nativas ya compiladas

Un desarrollador java que trabaje sobre una plataforma para la cual existan librerías nativas ya compiladas no tendrá que preocuparse de hacer nada especial para el uso de estas. Estas nativas aparecen como dependencias de otras librerías java y serán descargadas a $HOME/.m2 cuando hagamos un mvn install del proyecto java que las incluya. Posteriormente, cuando se hace un mvn install -Pinstall-extensions de la extensión que hace uso de las librerías java, los binarios nativos de los cuales se dependa serán instalados en el directorio .depman de nuestro “home”.

Actualmente para que se reconozca la plataforma en la que estamos se ha de indicar explícitamente.

El proyecto org.gvsig.maven.base contiene un directorio org.gvsig.maven.base.pom con un fichero pom.xml donde podemos cambiar la plataforma, distribución, compilador y arquitectura sobre la que estamos funcionando en caso de que no nos vaya bien la que viene por defecto. Una vez hecho esto deberemos ir al raiz del proyecto y ejecutar mvn install para instalar los cambios en nuestro repositorio local.

Este proyecto puede descargarse de: https://svn.forge.osor.eu/svn/gvsig-tools

Compilación de las Librerías Nativas

Con esta pequeña introducción a la problemática de las librerías nativas a continuación se explica cómo compilar las librerías que actualmente se encuentras migradas a maven.

Requerimientos

Para cada sistema, ya no sólo es necesario tener instalado el JDK y por supuesto maven (aunque se puede hacer uso del maven que se distribuyen dentro del directorio build). Es necesario descargarse los programas necesarios para compilar en cada sistema.

Para todos los sistemas es necesario descargarse e instalar CMake: http://www.cmake.org.

  • Windows:
    • Visual Studio 2005 (vs8)
    • CMake
  • Linux(Debian o Ubuntu):
    • apt-get install build-essential
    • apt-get install cmake
  • Mac:
    • Developer Tools distribuidas en el propio CD de MacOS X.
    • CMake

Es necesario tener un workspace al menos con los siguientes proyectos:

  • build
  • org.gvsig.maven.base
  • libjni-xxxx (todos los que queramos compilar)
Compilar
  • Compilar Java: Es tan sencillo como lanzar la instrucción del directorio de la librería ( o el target ant asociado ). Automáticamente se descargará la librería JNI de la que depende y las librerías externas de las que depende desde el repositorio de maven:

    Linux: mvn install -Dnative-distribution="all"
    Windows y Mac: mvn install 
    
  • Compilar Java + JNI: Al igual que antes se compilará la parte Java y en este caso se compilará también la parte JNI, las dependencias externas se descargarán desde el repositorio de maven:

    Linux: mvn install -Dnative-distribution="all" -Pjni-devel
    Windows y Mac: mvn install -Pjni-devel
    
Consideraciones a tener en cuenta
  • Las librerías nativas necesitan siempre del parámetro -Dnative-distribution={mi distribución linux}. La razón por la que es necesario es que según que distribución para la que se haya compilado puede que requiera unas dependencias externas u otras, o incluso pueden ocurrir problemas de compatibilidad binaria con las librerías del sistema.

  • Si una distribución linux no está soportada o no se han subido al repositorio de maven las dependencias, entonces fallará la búsqueda de dependencias y dará un error, es por tanto responsabilidad de los mantenedores de las librerías subir esas dependencias para las distribuciones oficiales de gvSIG.

  • En Windows, se considera que el compilador por defecto es el Visual Studio 2005 (vs8), por tanto para poder lanzar la compilación es necesario abrir una Consola de Visual Studio 2005" para que se definan correctamente las variables de entorno del compilador.

  • Aunque el sistema se lanza y se maneja con Maven, internamente hace uso de CMake, una herramienta multiplataforma que permite la compilación y generación de proyectos de compilación.

  • Para poder subir ficheros al repositorio hay que tener configurado el fichero settings.xml de nuestro repositorio local ($HOME/.m2) con los valores correctos para el servidor. Un ejemplo de este fichero podría ser el siguiente:

    <?xml version="1.0" encoding="UTF-8"?> 
     <settings xmlns="http://maven.apache.org/POM/4.0.0" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/POM/4.0.0"
      http://maven.apache.org/xsd/settings-1.0.0.xsd"> 
       <servers>
        <server> 
         <id>gvsig-repository</id> 
         <username>nbrodin</username> 
         <password></password> 
        </server> 
       </servers> 
     </settings>
    
Compilación en linux

Desde una consola del sistema debemos tener definida la variable JAVA_HOME. Para ello escribimos:

export JAVA_HOME=$javasdk

donde $javasdk es nuestra ruta local al JSDK de java. Actualmente la versión utilizada es la 1.6.0

La instrucción de compilación desde dentro del proyecto libjni-xxxx es la siguiente:

mvn install -Dnative-arch=$arch -Dnative-distribution=$distri -Pjni-devel -Dmaven.test.skip

donde $arch puede tomar los valores “X86_64”, “i386”, “universal” y $distri puede ser “nt”, "all", “Ubuntu-9.10”, “10.5”, etc...

El flag -Pjni-devel forzará a compilar el código nativo.

Si el proceso se completa con éxito se generará:

  • Un jar con las clases de java ya compiladas
  • Un jar con los fuentes de java
  • Un jar con los javadocs
  • Un tar.gz con las librerías nativas compiladas

Los jar, tar.gz y fuentes se instalarán en el repositorio local de maven (.m2). Cuando estas dependencias sean necesitadas por una librería o extensión de gvSIG serán copiadas desde ahí.

El nombre del jar tendrá la forma siguiente:

“Estructura de paquete”-”versión”.extensión

Ej: org.gvsig.jgdal-2.0.jar

El nombre de los fuentes será:

“Estructura de paquete”-”versión”-sources.extensión

Ej: org.gvsig.jgdal-2.0-sources.jar

El de los javadoc:

“Estructura de paquete”-”versión”-javadoc.extensión

Ej: org.gvsig.jgdal-2.0-javadoc.jar

Y el de los binarios:

“Estructura de paquete”-”versión”-”operativo”-”distribución”-”compilador”-”plataforma”-dynamic/static.tar.gz

Ej: org.gvsig.jgdal-2.0-linux-all-gcc4-i386-dynamic.tar.gz

Las dependencias en tiempo de compilación con librerías del sistema se resolverán automáticamente si estas están debidamente instaladas. Por ejemplo para linux la compilación de jgdal necesita de la librería gdal instalada y se usará la del repositorio oficial de la distribución que usemos.

Para subir la versión que hemos compilado al repositorio habrá que hacer "deploy" del proyecto usando la siguiente instrucción:

mvn deploy -Dnative-arch=$arch -Dnative-distribution=$distri -Pjni-devel -Dmaven.test.skip

Los parámetros serán los mismos que usamos para hacer "mvn install"

Compilación en windows

Para compilar un proyecto nativo desde una consola en windows deberemos asegurarnos primero de que está definida la ruta al jdk de java en la variable PATH y que la variable JAVA_HOME también está definida.

Al abrir una consola de windows deberemos cargar el entorno de Microsoft Visual Studio. Para eso, habrá que ejecutar desde la consola el fichero llamado vcvars.bat, que está en el directorio bin de VC. La ruta más común para este fichero suele ser:

“C:Archivos de programaMicrosoft Visual Studio 8VCbin”

La compilación se hará con el comando:

mvn install -Pjni-devel -Dmaven.test.skip

Para subir la versión que hemos compilado al repositorio habrá que hacer "deploy" del proyecto usando la siguiente instrucción:

mvn deploy -Pjni-devel -Dmaven.test.skip

Los parámetros serán los mismos que usamos para hacer "mvn install"

Regenerar las dependencias nativas para la ejecución

La dependencias nativas (proyectos libjni-xxxx) son compiladas e instaladas en el repositorio local de maven ($HOME/.m2) usando “mvn install”, pero no son instaladas para ejecución a no ser que lo invoquemos explícitamente. Las dependencias nativas que se usan en la ejecución estarán en el directorio $HOME/.depman. En caso de linux el directorio lib contendrá las librerías y en caso de windows será el directorio bin. Para que esto suceda se ejecutará la instrucción:

mvn install -Pinstall-extension -Dmaven.test.skip

Esta instrucción se ejecutará dentro de la extensión que tenga dependencias con las librerías nativas, aunque sea de forma indirecta. Hay que tener en cuenta que las extensiones tienen un directorio distribution con un fichero distribution.xml con la información para regenerar las dependencias de las distribución en ejecución.

Dependencias externas (SDKs)
Estructura del SDK

Las librerías que no están instaladas en el sistema necesitan ser resueltas para compilar. Para ello es necesario disponer del SDK de estas dependencias. El SDK de una dependencia contiene:

  • Un directorio bin con las librerías dinámicas y ejecutables que tenga
  • Un directorio data con ficheros de datos
  • Un directorio include con las cabeceras para compilar
  • Un directorio lib con librerías para compilación estática

El sdk estará empaquetado un tar.gz y el nombre tendrá la siguiente estructura:

“nombre de librería”-”version”-”operativo”-”distribución”-”compilador”-”plataforma”-dynamic/static.tar.gz

Ej: gdal-1.7.1-win-nt-vs8-i386-dynamic.tar.gz

A la hora de compilar una librería nativa es necesario que las dependencias estén instaladas en el directorio $HOME/.depman. Cuando se hace un maven install cogerá el tar.gz con el SDK del cual se depende y que está en el repositorio local (.m2) y lo descomprimirá en $HOME/.depman. En caso de que no esté instalado en el repositorio local se lo descargará del repositorio remoto. Este proceso se realizará de forma automática.

Subir SDK al repositorio

Cuando creamos un SDK del cual depende una librería nativa tendremos que subirlo al repositorio una vez montada la estructura que hemos definido en el apartado anterior. Para esto tendremos que empaquetar manualmente los ficheros en un tar.gz.

Una vez tenemos el paquete hecho habrá que subirlo al repositorio usando maven. La instrucción que debemos usar es similar a la siguiente:

mvn deploy:deploy-file
 -Dfile=”C:\gdal-1.7\gdal-1.7.1-win-nt-vs8-i386-dynamic.tar.gz”
 -Durl=scp://shell.forge.osor.eu/home/groups/gvsig-desktop/www/downloads/pub/projects/gvSIG-desktop/maven-repository
 -DrepositoryId=gvsig-repository
 -DgroupId=org.gdal
 -Dversion=1.7.1
 -DartifactId=gdal
 -Dpackaging=tar.gz
 -Dclassifier=win-nt-vs8-i386-dynamic

En este caso se muestran valores de ejemplo para subir el SDK de gdal en su versión 1.7.1 en un windows de 32 bits con compilación con Visual Studio 8. Habría que sustituir estos valores por los correctos para nuestro caso.

El parámetro -DrepositoryId contiene una etiqueta que corresponde con el identificador que debe haber dentro del fichero settings.xml de nuestro directorio .m2. De esta forma podrá conectarse al repositorio por scp validando previamente la cuenta.

Dependencia de proyectos con librerías nativas

Es bastante común hacer uso de dependencias dentro de un proyecto tan grande como es gvSIG. Maven nos ayuda en la tarea de definir esas dependencias. En este apartado se explica como hacer que tu proyecto Java tenga como dependencia una librería nativa.

Únicamente es necesario modificar la sección <dependencies> de tu proyecto Java:

<dependency>
  <groupId>org.gvsig</groupId>
  <artifactId>org.gvsig.jgdal</artifactId>
  <version>2.0</version>
</dependency>
<dependency>
  <groupId>org.gvsig</groupId>
  <artifactId>org.gvsig.jgdal</artifactId>
  <version>2.0</version>
  <classifier>${native-classifier}</classifier>
  <type>tar.gz</type>
</dependency>

El ejemplo anterior lo que nos muestra es que se depende de la librería org.gvsig.jgdal, la primera parte se refiere a la parte Java de jgdal (los .jar), y la segunda parte se refiere a la parte nativa, es decir el conjunto de binarios dependientes de plataforma.

${native-classifier}

El elemento <classifier> de un pom, permite añadir un clasificador a cualquier artefacto maven, de manera que nos permite hacer un tratamiento especial. En el caso de las librerías nativas, el clasificador se ha utilizado para añadir la plataforma, arquitectura, distribución, sistema operativo y tipo de dependencia.

La propiedad ${native-clasifier} se genera a partir de otras propiedades, a continuación se muestra para cada sistema operativo soportado el valor que toma:

  • Linux:

    <native-platform>linux</native-platform>
    <native-distribution>all</native-distribution>
    <native-compiler>gcc4</native-compiler>
    <native-arch>i386</native-arch>
    <native-libraryType>dynamic</native-libraryType>
    
  • Windows:

    <native-platform>win</native-platform>
    <native-distribution>nt</native-distribution>
    <native-compiler>vs8</native-compiler>
    <native-arch>i386</native-arch>
    <native-libraryType>dynamic</native-libraryType>
    
  • MacOSX:

    <native-platform>mac</native-platform>
    <native-distribution>10.5</native-distribution>
    <native-compiler>gcc4</native-compiler>
    <native-arch>universal</native-arch>
    <native-libraryType>dynamic</native-libraryType>
    

La propiedad se genera de la siguiente forma:

<native-classifier>
 ${native-platform}-
 ${native-distribution}-
 ${native-compiler}-
 ${native-arch}-
 ${native-libraryType}
</native-classifier>

Por tanto es fácil cambiar cualquier valor desde la línea de comandos haciendo uso de -Dnative-distribution="valor que quiero que tenga".

<type>tar.gz</type>

Otro elemento que no es habitual en las dependencias de tipo jar, es el elemento <type/>. En este caso, se está usando para que la extensión de la dependencia que busque sea de tipo tar.gz, ya que en este caso al no ser un único fichero, si no un conjunto de binarios o incluso de ficheros necesarios para la compilación de librerías nativas, estos se empaquetan y comprimen en un archivo contenedor (tar.gz).

Destino de los binarios nativos

Al igual que maven tiene un repositorio local donde se descargan los jars de los que se depende, se ha creado un repositorio local donde se descomprimen los binarios nativos:

${user.home}/.depman

Donde en cada sistema operativo toma el valor adecuado. Los proyectos al descomprimirse generan una estructura de directorios similar al de un SDK de librerías nativas multiplataforma:

${user.home}/.depman/
                    |-include      
                        -- Cabeceras de archivos para C/C++
                    |-lib          
                        -- Nativos en linux/mac (.so/.dylib) o 
                           librerías de enlace en windows (.lib).
                    |-bin          
                        -- Nativos en Windows (.dll).
                    |-Frameworks   
                        -- Nativos en Mac (.framework)

Maven cuándo se descarga una dependencia nativa de tipo tar.gz, automáticamente la deposita en el repositorio de maven (${user.home}/.m2) sin descomprimir y a continuación la descomprime en el directorio ${user.home}/.depman. Además ese directorio se añade a los PATHS de ejecución de los Tests unitarios de librerías y proyectos Java, para que si requieren de la librería nativa no existan problemas de ejecución.

Creación/Migración de librerías Nativas a Maven

En este apartado se plantean las bases para la creación o migración de nuevas librerías nativas dentro de gvSIG. Primero se explica la estructura que deben seguir los proyectos para su correcta compilación y generación. A continuación cómo integrar el proyecto en CMake y cómo se debe generar el pom.xml para que todo el sistema compile de manera integrada en el sistema de construcción de gvSIG además de resumir el ciclo de vida de una librería nativa dentro del sistema de construcción de maven.

Estructura del proyecto

Para llevar a cabo un proyecto de una librería nativa, se recomienda una estructura de directorios determinada que facilitará la construcción y organización del proyecto:

librería-jni/
             |-src/
                   |-main/
                   |      |-java
                              -- Ficheros .java
                   |      |-native
                              -- Ficheros .cpp y de cabecera de C++
                   |      |-resources
                              -- Ficheros de recursos a incluir en el .jar
                   |-test/
                          |-java
                              -- Tests unitarios

Seguir esta estructura es importante, tanto para proyectos de maven, como para la compilación de la parte nativa, ya que CMake seguirá esta estructura para buscar los archivos fuente y generar los binarios nativos.

Integración con CMake

Aunque maven es capaz de compilar y administrar dependencias de tipo jar, no es así con las librerías nativas. Existe algún plugin que es capaz de ello, pero no al nivel que se requiere en un proyecto tan grande como gvSIG. Por ello se hace uso de CMake, que es un sistema para la construcción de librerías nativas multiplataforma (no únicamente librerías JNI).

CMake se encarga de generar los ficheros de proyecto y de compilación para cada plataforma y en cada sistema operativo, permitiendo manejar de una forma centralizada varios sistemas e incluso compiladores. Por ejemplo para linux generará los ficheros Makefile necesarios y para Windows generará los ficheros NMakefile o las soluciones de Visual Studio que se tenga instalada en el sistema.

Para facilitar la tarea se han incorporado al directorio build una serie de Macros de CMake que simplifican los ficheros de proyecto.

Para integrar una librería JNI con CMake es necesario crear en el directorio raíz un fichero CMakeLists.txt que tendrá la siguiente estructura:

PROJECT(jgdal)

CMAKE_MINIMUM_REQUIRED(VERSION 2.6.0 FATAL_ERROR)

SET(JGDAL_VERSION_MAJOR "2")
SET(JGDAL_VERSION_MINOR "0")
SET(JGDAL_VERSION_PATCH "0")
SET(VERSION "${JGDAL_VERSION_MAJOR}.${JGDAL_VERSION_MINOR}.${JGDAL_VERSION_PATCH}")

SET(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/../build/CMakeModules;${CMAKE_SOURCE_DIR}/CMakeModules;${CMAKE_MODULE_PATH}")

FIND_PACKAGE(DepMan REQUIRED) 
INCLUDE(GeneralMacros) 

CONFIGURE_DEFAULTS()

IF(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  SET(CMAKE_INSTALL_PREFIX
    ${DEPMAN_PATH} CACHE PATH "depman path install prefix" FORCE
  )
ENDIF(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)

FIND_PACKAGE(JNI REQUIRED) 
FIND_PACKAGE(GDAL REQUIRED) 

ADD_SUBDIRECTORY(src/main/native)

CONFIGURE_END()

El ejemplo anterior está basado en el de JGDAL y tiene varias instrucciones a tener en cuenta. La instrucción para la busqueda en el sistema de las librerías JNI necesarias para la compilación nativa es:

FIND_PACKAGE(JNI REQUIRED)

Para la búsqueda de otras dependencias que tu proyecto necesite se deberá hacer de una forma similar, por ejemplo en el caso de GDAL se hace:

FIND_PACKAGE(GDAL REQUIRED)

Aunque CMake incorpora una gran cantidad de scripts para la búsqueda de dependencias, si no tiene una, se pueden crear nuevas, como es el caso de GDAL, que se encuentra dentro del directorio CMakeModules ubicado en el directorio build.

Otra instrucción del script a tener en cuenta es la de:

ADD_SUBDIRECTORY(src/main/native)

Esta instrucción indica que se debe buscar archivos CMakeLists.txt en ese subdirectorio para configurar el resto de la compilación.

Hasta ahora sólo hemos configurado el entorno base de CMake, a continuación se muestra el script que debe ir dentro del directorio donde se encuentran los fuentes (.cpp,.c), para realizar la compilación del binario nativo:

SET(LIB_NAME jgdal)

FILE(GLOB SOURCES "*.c*")

include_directories(
    ${CMAKE_SOURCE_DIR}/include
    ${JAVA_INCLUDE_PATH}
    ${JAVA_INCLUDE_PATH2}
    ${GDAL_INCLUDE_DIR}
)

SET(LIBRARIES_OPTIMIZED 
    ${GDAL_LIBRARY}
)

SET(LIBRARIES_DEBUG
    ${GDAL_LIBRARY}
)

SETUP_JNILIB(${LIB_NAME})

En este ejemplo, se están almacenando todos los ficheros .cpp y .c en la variable SOURCES y posteriormente se está configurando el entorno con los directorios de cabecera necesarios. Las variables JAVA_INCLUDE_PATH, JAVA_INCLUDE_PATH2 y GDAL_INCLUDE_DIR se definen al hacer uso de FIND_PACKAGE en el script principal, por lo que son accesibles para su uso en otros scripts. Luego se configuran las librerías de las que se depende, en este caso GDAL_LIBRARY. Finalmente se configura para que se cree una librería JNI.

Se recomienda que si se desea hacer un uso intensivo y avanzado de CMake se lea la documentación del mismo (http://www.cmake.org).

Integración con Maven

Para entender como se integra la construcción de librerías nativas en Maven es necesario entender como lleva a cabo la construcción maven, para ello primero exponemos lo que se denomina ciclo de vida de maven y a continuación mostraremos la configuración inicial.

Ciclo de vida de proyectos maven

Maven realiza ciertas fases denominadas ciclo de vida o lifecycle para llevar a cabo la compilación de los proyectos. En el caso de las librerías nativas, lo que se ha hecho es insertar ciertas acciones durante la ejecución de algunas de esas fases, aprovechando así el sistema de construcción que provee.

Los ciclos y lo que se realiza en cada uno de ellos se menciona a continuación:

  • generate-sources: genera makefiles y busca dependencias nativas (target/target_cmake)
  • compile: make install (target/target_cmake_product)
  • package: genera tar.gz del producto compilado en target/
  • install: instala el tar.gz en .m2/repository
  • deploy: se instala en el repositorio remoto
Ficheros de Configuración

El fichero de configuración pom.xml es similar a cualquier otro proyecto java, pero en este caso se configuran ciertos parámetros necesarios.

La cabecera se debe configurar de la siguiente manera:

<project xmlns="http://maven.apache.org/POM/4.0.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <groupId>org.gvsig</groupId>
     <artifactId>org.gvsig.jgdal</artifactId>
     <packaging>jar</packaging>
     <version>2.0</version>
     <name>libjni-gdal Library</name>
     <parent>
         <groupId>org.gvsig</groupId>
         <artifactId>gvsig-base-library-jni-pom</artifactId>
         <version>2.0-SNAPSHOT</version>
     </parent>
     <properties>
         <build-dir>${basedir}/../build</build-dir>
     </properties>
     ...

No hay diferencia con otros proyectos, lo único a tener en cuenta es que la definición del elemento padre es: <artifactId>gvsig-base-library-jni-pom</artifactId>

El manejo de dependecias sigue siendo igual que en los proyectos java, aunque en las librerías nativas es habitual encontrarse que se depende de otras librerías nativas, por tanto se han de configurar correctamente, por ejemplo:

<dependencies>
   <dependency>
     <groupId>org.gdal</groupId>
     <artifactId>gdal</artifactId>
     <version>1.6.0</version>
     <classifier>${native-classifier}</classifier>
     <type>tar.gz</type>
   </dependency>
</dependencies>

En algunos casos, nos podemos encontrar que una dependencia se pueda obtener por el sistema de paquetes del sistema (como es el caso de Ubuntu o Debian), por lo que no es necesario añadir la dependencia para ese sistema y sí para el resto, para ello se hace uso de los profiles de maven:

<profiles>
   <profile>
     <id>windows-profile</id>
     <activation>
       <property>
           <name>native-platform</name>
           <value>win</value>
       </property>
     </activation>
     <properties>
       <!-- This hack is necessary to allow correct search in windows -->
       <build-dir>${basedir}\..\build</build-dir>
     </properties>
     <dependencies>
       <dependency>
         <groupId>org.gdal</groupId>
         <artifactId>gdal</artifactId>
         <version>1.6.0</version>
         <classifier>${native-classifier}</classifier>
         <type>tar.gz</type>
       </dependency>
     </dependencies>
   </profile>
   <profile>
     <id>linux-profile</id>
     <activation>
       <property>
           <name>native-platform</name>
           <value>linux</value>
       </property>
     </activation>
   </profile>
   <profile>
     <id>mac-profile</id>
     <activation>
       <property>
           <name>native-platform</name>
           <value>mac</value>
       </property>
     </activation>
     <dependencies>
       <dependency>
         <groupId>org.gdal</groupId>
         <artifactId>gdal</artifactId>
         <version>1.6.0</version>
         <classifier>${native-classifier}</classifier>
         <type>tar.gz</type>
       </dependency>
     </dependencies>
   </profile>
</profiles>

Con esta configuración y al incluir el pom padre específico para librerías jni, se incorporan a las fases del ciclo de vida la generación de los proyectos tipo makefile o NMakefile, la compilación, el empaquetado de los .tar.gz, la instalación en el repositorio de maven y por supuesto la instalación en el repositorio de librerías nativas ${user.home}/.depman y finalmente al hacer un deploy, el despliegue de esa dependencia.

Java ME CDC

  • cdc: compila un proyecto para Java ME CDC. Activa la compatibilidad con Java 1.4 y compila sobre el API de Java ME CDC. En algunos proyectos se emplea también para desactivar la compilación o generación de jars de partes no compatibles con Java ME CDC. Este perfil sólo se usa para el desarrollo en gvSIG Mobile. Ejemplo de uso:

    mvn -P cdc install
    

Existen una serie de proyectos que mantienen compatibilidad, al menos a nivel de API, con Java ME CDC.

Para compilar (o cualquier otra acción) para Java ME CDC hay que activar un perfil de maven preparado para ello: cdc:

mvn -P cdc clean compile 

Si se cambia entre compilación para Java SE y Java ME CDC, es recomendable limpiar la compilación para que no se empleen classes compiladas para el otro perfil, por eso se ha incluido la llamada al clean antes.


Problemas conocidos

No se encuentra la dependencia jre:javaws:jar:any

Se ha detectado que la versión del jdk 1.5 que se instala desde los repositorios en una Ubuntu de 64 bits (paquete sun-java5-bin) no instala el archivo javaws.jar, lo que provoca un error de dependencias al tratar de compilar el proyecto _fwAndami. Para solucionar esto hay que descargarse la versión del jdk 1.5 de 32 bits y copiar manualmente el jar al directorio correspondiente (${java.home}/lib/javaws.jar).

Este error también puede ocurrir si se está utilizando el OpenJDK, ya que parece ser que esta librería no está incluida. De momento gvSIG no soporta el OpenJDK, así que se puede copiar a mano la librería o bien usar el JVN de Sun.


Trabajando con un proyecto gvSIG

Compilar mi proyecto

Para compilar un proyecto desde maven, basta con invocar el objetivo:

mvn compile

Desde eclipse, se ha creado un lanzador en la opción de External Tools que permite compilar desde maven fácilmente, con el nombre: mvn compile.

Antes de usar este lanzador, deberemos seleccionar o estar editando algun archivo del proyecto que vamos a compilar, ya que se emplea la variable project_loc para invocar a maven sobre un proyecto.

Hay que tener en cuenta que el proyecto de eclipse está configurado de forma que las clases compiladas se generan en el mismo directorio que lo hace maven, así que, por lo general, al invocar este objetivo sobre un proyecto que tengamos abierto en eclipse, ya esté todo compilado y no haga nada.

Además de compilar, si queremos lanzar los tests unitarios de nuestro proyecto desde maven, emplearemos el objetivo:

mvn test

Finalmente, si queremos que el código que compilemos en un proyecto, esté disponible para otros proyectos que dependendan del mismo, deberemos generar el o los archivos .jar correspondientes, e instalarlos en el repositorio local de maven. Para ello emplearemos el objetivo:

mvn install

El objetivo install, además de compilar, lanza los tests unitarios del proyecto. Si queremos hacer la instalación sin lanzarlos, podemos usar el objetivo:

mvn install (no tests)

El equivalente desde consola es:

mvn -Dmaven.test.skip=true install

Los proyectos de gvSIG están configurados para generar, además del archivo .jar con las clases compiladas, otro archivo .jar con los fuentes. Esto nos será útil al enlazar las dependencias en maven y su uso desde los proyectos de eclipse.

Por otro lado, si queremos hacer una instalación y compilación desde cero, podemos usar el objetivo:

mvn clean install

Desplegar mi proyecto

Si nuestro proyecto es una extensión de gvSIG, existe una tarea adicional, además de la compilación y generación de archivos .jar: la instalación de la extensión sobre gvSIG.

Para ello se ha creado el siguiente perfil en maven:

install-extension: copia los archivos .jar generados, junto con el resto de recursos de la extensión (configuración, properties con textos multiidioma, imágenes, etc.) a gvSIG.

Dicho perfil está activado por defecto en los proyectos de tipo extensión, cuando invocamos al objetivo:

mvn install

Publicar mi proyecto

Una vez que hayamos terminado un determinado desarrollo en nuestro proyecto, y queramos que esté disponible para otros proyectos, sin que éstos tengan que descargar el código fuente de nuestro proyecto y compilarlo, podemos publicarlo en el repositorio de maven de gvSIG.

Este paso adicional se realiza a través del objetivo:

mvn deploy

Este objetivo realiza un mvn install y, a continuación, sube los artefactos generados, como el archivo .jar con las clases compiladas, al repositorio de maven.

Note

para que el deploy funcione deberemos tener un usuario con permisos en el proyecto gvSIG, y haber realizado correctamente la configuración definida en el documento Configuración inicial de maven (ver contenido relacionado al final del documento).

Los proyectos de gvSIG están configurados de forma que el repositorio al que se suben los artefactos es el de gvSIG.

Como se comenta en el apartado de compilación, en gvSIG se genera, por defecto, tanto el archivo .jar con las clases compiladas como el archivo .jar con el código fuente, que también se subirá al repositorio.

Además, si estamos publicando una versión con cambios significativos, será conveniente publicar también el javadoc en un archivo .jar. Para ello activaremos el perfil release con el siguiente objetivo desde eclipse:

mvn deploy release

Desde consola, el uso de maven directo es el siguiente:

mvn -P release deploy

TODO

Note

estudiar para el futuro el uso del maven release plugin

Generación de documentación e informes

Maven permite la generación de documentación a partir de los fuentes de un proyecto, como por ejemplo el javadoc.

Para ello existen una serie de plugins especiales de maven para la generación de informes.

Por ejemplo, para generar el javadoc usaremos el plugin correspondiente de la siguiente forma:

mvn javadoc:javadoc

Además de la generación de informes individuales, maven permite la generación de lo que llaman el site. Este consiste en un conjunto de páginas de informes de maven enlazadas, con un menú que nos permite navegar por todos los documentos generados.

De hecho, este mini website generado con maven es lo que emplean muchos de los proyectos Java de apache como website del proyecto.

Para los proyectos de gvSIG, se ha preconfigurado una serie de plugins con las opciones adecuadas del proyecto. Además, existen una serie de páginas que muestran información extraída del archivo pom.xml del proyecto, por lo que será importante completar y mantener actualizada dicha información.

En los proyectos que se generen usando los arquetipos de maven, el archivo pom.xml ya lleva los atributos necesarios predefinidos, a falta de rellenar y completar con valores reales.

Para generar el site invocaremos el objetivo:

mvn site

Esto nos generará la documentación dentro de nuestro proyecto, en la carpeta:

target/site

TODO

  • Links javadoc, la variable site-repository y referencias entre proyectos.
  • Publicación del site en el servidor público de gvSIG.

Cómo añadir o actualizar una dependencia

Si vamos a añadir o actualizar una dependencia externa en un pom.xml en un proyecto de gvSIG, tendremos que hacer lo siguiente:

Primero, nos asegurarnos que la dependencia y la versión que nos interesa está ya disponible en algunos de los repositorios oficiales de maven. Para ello tenemos dos opciones:

  • Realizar una búsqueda manual, mediante google o inspección directa de alguno de los repositorios alternativos de maven.

Si hemos encontrado la dependencia deseada, ya podemos modificar el pom.xml, pues ya sabemos que está disponible para todos.

Si no hemos encontrado la dependencia, habría que pedir al proyecto original que suban la dependencia al repositorio oficial de maven, proporcionándoles la información necesaria para ello para que les sea más sencillo:

Así, contribuiremos con la comunidad a facilitar el uso de la librería correspondiente a través de maven. En algún proyecto es posible incluso que nos propongan que nos encarguemos de actualizar nosotros el repositorio de maven con nuevas versiones de una librería.

Si desde el proyecto original no se quiere hacer o se tarda mucho, podemos subirla temporalmente al repositorio maven de gvSIG, quitándola cuando esté disponible en el repositorio oficial.

¿Cómo subir una libraría al repositorio maven de gvSIG?

Lo ideal sería que todas las librerías de las que depende un proyecto de gvSIG tuviesen un repositorio maven para poder descargarlas. Lamentablemente esto siempre no es así y a veces hay que subir una librería al repositorio maven de gvSIG.

En ese caso, para hacer pruebas lo primero que debemos hacer es incluir la dependencia en nuestro repositorio local de maven. Para ello usaremos el siguiente comando:

mvn deploy:deploy-file -Durl=REPO_URL
                   -DrepositoryId=some.id
                   -Dfile=your-artifact-1.0.jar
                   [-DpomFile=your-pom.xml]
                   [-DgroupId=org.some.group]
                   [-DartifactId=your-artifact]
                   [-Dversion=1.0]
                   [-Dpackaging=jar]
                   [-Dclassifier=test]
                   [-DgeneratePom=true]
                   [-DgeneratePom.description="My Project Description"]
                   [-DrepositoryLayout=legacy]
                   [-DuniqueVersion=false]

El comando admite muchas opciones, sobre las cuáles podemos encontrar más documentación en la web del proyecto maven, en el apartado del plugin deploy. Sin embargo, lo más habitual será emplear lo siguiente:

mvn deploy:deploy-file -DgroupId=$LIBRARY_GROUPID
                   -DartifactId=$LIBRARY_ID
                   -Dversion=$LIBRARY_VERSION
                   [-Dclassifier=$LIBRARY_CLASSIFIER]
                   -Dpackaging=jar
                   -Dfile=$LIBRARY_JAR
                   -Durl=$REPOSITORY_URL                  
                   -DrepositoryId=gvsig-repository

Los valores de las variables (empiezan por $) deberemos sustituirlos por:

LIBRARY_GROUPID:
un valor típico suele ser el dominio principal del proyecto. Por ejemplo, para los proyectos gvSIG es org.gvsig, para los proyectos apache org.apache, etc.
LIBRARY_ID:
identificador o nombre de la librería. Suele ser un nombre único o bien un nombre con estilo de paquete java. En gvSIG los proyectos emplean este último formato (ej: org.gvsig.tools.lib).
LIBRARY_VERSION:
versión del jar que vamos a subir.
LIBRARY_CLASSIFIER:
para proyectos que generan varios jars, se emplea este valor para distinguir entre ellos. Un valor típico es tests, para el jar con los tests unitarios del proyecto. Es opcional y no suele ser necesario.
LIBRARY_JAR:
path absoluto al archivo .jar que vamos a subir, o bien relativo desde el directorio donde ejecutamos maven
REPOSITORY_URL:

url del repositorio maven al que vamos a subir. En general usaremos dos opciones:

  • El repositorio local de maven: $USER_HOME/.m2/repository.

    En este caso hay que tener en cuenta que la dependencia sólo estará disponible para nuestro usuario en local. Suele emplearse para pruebas antes de subir la dependencia al repositorio de gvSIG.

  • El repositorio maven de gvSIG: dav:https://devel.gvsig.org/m2repo/j2se

    Una vez subido a este repositorio ya estará disponible para el resto de desarrolladores.

Note

Para que el deploy funcione se ha tenido que configurar previamente el fichero settings.xml tal y como se indica en el documento "Configuración inicial de maven" de la guía del desarrollador, apartado "Acceso de escritura al repositorio maven de gvSIG".

A modo de ejemplo, supongamos que tenemos un jar de la librería JEP en su versión 2.4.0 que queremos incluir como dependencia. La instrucción completa a emplear sería:

mvn deploy:deploy-file -DgroupId=org.nfunk \
               -DartifactId=jep \
               -Dversion=2.4.0 \
               -Dpackaging=jar \
               -Dfile=jep.jar \
               -Durl=dav:https://devel.gvsig.org/m2repo/j2se \
               -DrepositoryId=gvsig-repository

How to create a gvSIG installer with installjammer

A quick howto prepared in the process of creating the gvSIG 2.0 installer using installjammer:

  • Download last final version of installjammer (http://www.installjammer.com/. While creating this document the last final version available was the 1.2.15 one, but it had a bug with link files, so we have used an hourly build of the 1.2 branch.

  • Run installjammer and click on the new installer icon.

  • Go through the wizard options filling the required information. Of special interest for gvSIG:

    • Theme selection: Modern Wizard
    • Platforms: Linux X86, Linux X86 64 and Windows. (tar and zip ones kill installjammer when building)
    • Additional features: all checked but the "Allow users to select custom components in your install", as that will be managed through the gvSIG own installer.
  • Add files to install.

    • Create a file group for the common files non platform dependent, called gvSIG base. Add to it the product directory, checking everything but the platform dependent files and the plugins that won't be installed in the minimal installation.

      Add to it also the $HOME/.depman/data folder to be copied to the root installation folder.

    • Create a file group for each supported platform (linux, windows, etc.). Add to them the product and $HOME/.depman/lib and bin folders and select only the files or folders of each platform

    When you add a folder or file to a group, InstallJammer stores the absolute path. That would make a bit difficult to share the installer configuration. To solve it, Virtual Text variables can be used:

    • Add a %BaseDir% Virtual Text variable pointing to your gvSIG installation. Then, for each product folder added in the file groups, edit the Location property and set it to <%BaseDir%>.
    • Add three more variables to point to the data, lib and bin folders too, called:
      • BaseNativeLibsDir: path to the $HOME/.depman folder.
      • Lini386NativeLibsDir: path to the $HOME/.depman/lib folder.
      • Wini386NativeLibsDir: path to the $HOME/.depman/bin folder.
  • Add license panel:

    1. Open Install Panes and Actions > Standard Install

    2. After the Welcome screen add a License agreement pane.

    3. By default the license must be written in the configuration pane options. To read the license from a file, add a Execute script after the pane, with Execute action = Before pane is displayed and the tcl script:

      set file [::InstallAPI::FindObjects -alias "ProgramLicense"]
      set file [$file srcfile]
      ::InstallAPI::SetVirtualText -virtualtext LicenseText -value [read_file $file]
      
    4. The file with the license contents must be updated with the alias ProgramLicense. Go to Groups and files, look for the license file LICENSE.txt and into the properties update the Alias field.

  • Find java executable while installing:

    1. Create an action group called Find Java Actions, with the same name in its alias property (very important or it won't be shown when called from a pane action).
    2. Add a Locate Java Runtime action to the group and set the Minimum Version property to 1.5.
    3. Add a Message Box action to the group to be shown when the java executable is not found. Set the properties:
      • Icon: error
      • VirtualTextField: JavaNotFound
      • Message: <%JavaNotFound%>
      • Add a condition of type String is Condition with the properties: - Operator: false - String: <%JavaFound%>
    4. Add a Exit action to the group to exit the installer after the previous message box is shown if the java executable is not found. Set properties:
      • Exit code: -1
      • Add a condition of type String is Condition with the properties: - Operator: false - String: <%JavaFound%>
    5. Add a Execute Action to the Welcome Screen pane with the properties:
      • Alias: Find Java
      • Action: Find Java Actions
  • Replace variables in the gvSIG linux launcher (gvSIG.sh):

    1. Add a Replace Text In File action into the Copying files pane, just after the Install Everything one.

    2. Configure the added action with the properties:

      • Files: gvSIG.sh

      • String Map:

        "JAVA_HOME=${JAVA_HOME}" "JAVA_HOME='<%JavaHome%>'"
        "GVSIG_HOME=`pwd`"  "GVSIG_HOME='<%InstallDir%>'"
        
  • Launch the gvSIG add-ons installer before the installation process end:

    1. Add a Custom Text Pane 1. To internationalize the text properties, save the project and look for the stored values in the .mpi file. It will be something like:

      54A9E67A-F932-CDD4-6F9A-8842AAE31ACC,Title
      

      Add the properties to be translated to the msg files located in build/projects/gvsig-standard/gvsig-standard-installer/src/main/installjammer

    2. Add a new Action group called Install addons actions, with the same value for the Alias property.

    3. Add to the group an action to launch the Addons manager in linux (or other non windows OS), using a Execute External Program action with the properties:

      • Alias: Launch addons manager not windows
      • Console title: <%AppName%> add-ons manager
      • Program command line: <%ProgramExecutable%> --install --installURL=http://gvsig-desktop.forge.osor.eu/gvSIG-desktop/dists/<%Version%>/packages.gvspki language=<%Language%>
      • Working Directory: <%InstallDir%>
      • Add a condition of type Platform Condition so it is launched only in non windows OSs, with the properties: - Operator: is not - Platform: Windows
    4. Add to the group an action to launch the Addons manager in windows, using a Execute External Program action with the properties:

      • Alias: Launch addons manager windows
      • Console title: <%AppName%> add-ons manager
      • Program command line: <%InstallDir%>/gvsig-package-installer.exe --install --installURL=http://gvsig-desktop.forge.osor.eu/gvSIG-desktop/dists/<%Version%>/packages.gvspki language=<%Language%>
      • Working Directory: <%InstallDir%>
      • Add a condition of type Platform Condition so it is launched only in windows, with the properties: - Operator: is - Platform: Windows
    5. Add a Execute Action to the Welcome Screen pane with the properties:

      • Alias: Install addons
      • Execute action: before next pane is displayed
      • Action: Install addons actions
  • Add support to show the README contents in Spanish of English. By default installjammer configures the project to show the contents of only one file. To add this support is easy:

    1. Add a README panel with the Spanish contents by creating a copy (Copy and then Paste) of the View Readme Window action into the Finish actions group. Rename it to View Leeme Window and set the properties:
      • Text File: <%InstallDir%>/LEEME.txt
      • Add a condition so it only runs in Spanish, of type String Match Condition with the properties:
        • Match Case: No
        • Operator: matches
        • Pattern: es*
        • String: <%Language%>
      • Change the File Exists Condition property:
        • Filename: <%InstallDir%>/LEEME.txt
    2. Add a condition to the View Readme Window action so it only runs in non Spanish languages, of type String Match Condition with the properties:
      • Match Case: No
      • Operator: does not match
      • Pattern: es*
      • String: <%Language%>

gvSIG install build preparation steps

Prerequisites

You have to install the application used to create gvSIG installers in your computer: InstallJammer.

Go to http://www.installjammer.com and download the last final available version. The last version tested in the project has been the 1.2.15, but it had a bug in the installation of links (needed for native libraries), so the last 1.2 hourly build with that bug solved has been used.

Once installed, get sure the installjammer application (the installjammer executable itself, not a link) is available in your execution PATH.

Install build preparation steps

  1. If necessary, update value of the package.info.state parameter in the paramers section of the pom.xml files of each plugin.

  2. Update your workspace projects and clean, compile and install everything (mvn clean + mvn install). All external projects (org.gvsig.maven.base, org.gvsig.tools, etc.) must have been deployed in their last version previosly.

  3. Launch gvSIG and perform a quick test.

  4. Install the JRE plugin from jre_6_windows_i586 from the addons nanager.

  5. Just in case you have created a previous build and you still have the generated add-on packages, remove everything into your build/product/install folder.

  6. The gvSIG launchers for windows are still not generated automatically, so you should regenerate them with the Launch4J tool. Open the xml files located in build/projects/gvsig-standard/gvsig-standard-installer/src/main/launch4j with the Launch4J utility, update version and build numbers and regenerate the .exe files.

  7. In case there have changes (new files in fwAndami, libCorePlugin or any other change in the online installer content) use the InstallJammer application to check that all the necessary files are included.

  8. Generate the gvSIG installer and all the plugins add-ons: launch the goal mvn-create-installer from the build.xml of the gvsig-standard project available into build/projects/gvsig-standard.

    Once the process is finished, you will have the following artifacts:

    • gvSIG installers in: build/projects/gvsig-standard/gvsig-standard-installer/target/installjammer/output
    • add-on packages in: build/product/install/pool

    If there is an error while the process is generating the installers (at the end of the process), take a look at the InstallJammer configuration maintenance section.

  9. From the command line, define the following environment variables:

    USER=[downloads.gvsig.org user]
    BUILD_NUMBER=2043
    
  10. Upload the installers to downloads.gvsig.org: copy the installers to /srv/download/gvsig-desktop/dists/2.0.0/builds/$BUILD_NUMBER/. Ex:

    ssh $USER@downloads.gvsig.org "cd /srv/download/gvsig-desktop/dists/2.0.0/builds; mkdir $BUILD_NUMBER"
    scp build/projects/gvsig-standard/gvsig-standard-installer/target/installjammer/output/* \
      $USER@downloads.gvsig.org:/srv/download/gvsig-desktop/dists/2.0.0/builds/$BUILD_NUMBER/
    
  11. Generate if needed the add-on packages of plugins not included into the gvsig-standard project group, like:

    • CRS
    • Raster
    • Geoprocessing
    • Thematic Maps
    • Etc...
  12. Upload the add-on packages to /srv/download/gvsig-desktop/pool. Ex:

    tar cvzfC upload.tar.gz build/product/install/ pool
    scp upload.tar.gz $USER@downloads.gvsig.org:/srv/download/gvsig-desktop
    ssh $USER@downloads.gvsig.org "cd /srv/download/gvsig-desktop; tar xvzf upload.tar.gz; rm upload.tar.gz"
    
  13. Create the distribution for the build. Replace STATE and BUILD_NUMBER by the values of the distribution.

    ssh $USER@downloads.gvsig.org "cd /srv/download/gvsig-desktop/dists/2.0.0; ../gvspkg mkdist --state STATE --build BUILD_NUMBER"
    
  14. Install and perform a quick test of the generated installers, downloading all add-ons and checking some basic functionalities (linux, windows, ...).

  15. If everything is OK, commit all changes in the buildNumber.properties files of each project. Else, solve any found problems and return to the first step.

  16. Create a tag of the files included into the install build, with the build number in the tag name. Take into account that some of the project will be located in other svn repositories. You will have to create a tag into each of them, appart from the one in the gvsig-desktop project repository [1].

    To create the tag, if you use the subclipse eclipse plugin, follow those steps (should be very similar if you use subversive instead):

    1. Select in your package explorer, project explorer or navigator, the projects to create the tag with.
    2. Click over them with the right button and select the option Team > Branch/Tag...
    3. In the Copy to URL: field put the URL to the tag to create. Ex: https://devel.gvsig.org/svn/gvsig-desktop/tags/v2_0_0_Build_2043. Check also the Create any intermediary folders that are missing and Preserve folder structure. The last one will put the projects into the tag with the same structure as the main branch (frameworks/_fwandami, libraries/libCompat, etc.).
    4. In the Create copy in the repository from: select the Working copy option. This way the tag will be created from the files you have into your workspace, so the tag won¡t contain any changes commited by other people while you where performing the build process.
    5. In the tag comment, put something about the build being created, like: gvSIG 2.0.0 build 2043.

    Sadly, the subversion server might sometimes cut the connection so the tag process may stop in the middle. In that case, you will have some of the projects already available in the tag.

    As the process follows the order of the projects in your package or project explorer, look in the svn log for the project where the error was produced, deselect the projects (already tagged) in your package/project explorer view listed before that project and start again with the previous steps.

  17. Refresh the plone download page cache:

  18. Create the notice ticket in the gvsig-desktop project tracker.

Note

TODO

  1. Perform a deploy of the projects included into the build, through the mvn-deploy-release (this is the same as the mvn-deploy one, but also generates and uploads the javadocs jar files) command in gvsig-standard.

  2. Only if there are changes in the API or other important changes generate or update the project's maven sites. As the command is still not available in the gvsig-standard ant configuration, you must call it from the command line: mvn site-deploy.

    One way would be to launch the mvn site-deploy goal into the gvsig-standard-project, but the maven site plugin knows about multimodule projects, and it would try to create a main site also for the gvsig-standard-project, which could take forever to finish.

    Another way to do it is to use some script to launch the mvn site-deploy goal for each project. You need to have mvn available into your execution path. As an example, into your workspace folder, launch the following command:

    for i in lib* org* _fwAndami app* ext*; do cd $i; mvn site-deploy; cd ..; done     
    
[1]That last sentence will change when those external projects generate add-on packages by itselfs.

JCRS

The JCRS related projects are not included anymore in the gvsig-standard build process.

As it has few changes and depends on native libraries, the packages for each platform will have to be created when there are changes in the CRS projects.

If you want to compile or create installers of the JCRS plugin, use the gvsig-jcrs group available into build/projects. With that group you will be able to work with all the CRS related projects at once: checking out, compiling, generating package installers, ....

The natives are selected depending on two things:

  • The values configured into the $HOME/.gvsig.platform.properties file. Look for available values in the Maven initial configuration document.
  • Your current platform, which activates a profile on each project with native dependencies selecting the required version of them, as may be different for each platform.

Taking this into account, how can you get all native dependencies for the supported platforms? There are two ways to do it:

  • Manually: change the $HOME/.gvsig.platform.properties once for each platform and compile each project with native dependencies deactivating your platform profile and activating the one desired:

    mvn -P linux-profile,\!windows-profile compile
    

    Take into account that if you launch the previous command in the console, the $HOME/.gvsig.platform.properties file is read on each login shell. Another way to change the platform properties for maven is to set them in the MAVEN_OPTS environment variable:

    export MAVEN_OPTS='-Xmx384M -XX:MaxPermSize=64m -Dnative-classifier=linux-all-gcc4-i386-dynamic'
    
  • Automatically: use the script build/projects/gvsig-jcrs/prepare-all-platforms.sh, which will perform all required steps in the JNI projects.

InstallJammer configuration maintenance

Launch installjammer

Once installed, you can open the InstallJammer GUI by running the installjammer executable. As the gvSIG installer configuration uses variables to point to the local paths, you must run installjammer like this:

installjammer -DBaseDir [PATH_TO_GVSIG] \
              -DBaseNativeLibsDir $HOME/.depman \
              -DLini386NativeLibsDir $HOME/.depman/lib \
              -DWini386NativeLibsDir $HOME/.depman/bin \
              -DInstallVersion 2.0.0.2025 \
              -DVersion 2.0.0 \
              --
Deleted or new files and folders

InstallJammer, by default, includes all the new files available in the folders to include in the installation, but fails if any of the previous available files is not available anymore.

That might be useful most of the times, so if you add a file you don't need to update the installjammer configuration. Also if you forgot to install a file or folder, it fails so you can correct it.

But there are times when you want that explicit change:

  • Delete a file or change it with another one with another name (ex: a new library version). If this is the case you must open the InstallJammer gui and remove the old file in the Groups and Files section.
  • There is a new file or folder you don't want to be included by default. For example, when a new plugin is added, as the gvSIG/extensiones is added to the installation with some plugins to be included, the new one would be included too. You must open the InstallJammer gui and uncheck the new file or folder in the Groups and Files section.
Plugins de gvSIG incluidos en el InstallJammer

En el instalable que se genera con el el InstallJammer se deberan incluir los siguientes plugins de gvSIG:

  • org.gvsig.coreplugin
  • org.gvsig.installer.app.extension

Modificación del lanzador de la aplicación para windows

Puede ser necesario modificar de alguna manera el lanzador de la aplicacion para windows gvsig-desktop.exe para lo cual se deben seguir los siguientes pasos:

  1. Descargar la aplicación launch4j de http://launch4j.sourceforge.net/
  2. Descomprimirlo y ejecutarlo.
  3. Abrir el archivo /build/projects/gvsig-standard/gvsig-standard-installer/src/main/launch4j/gvsig.xml
  4. En la pestaña Basic se deben cambiar las rutas absolutas que figuran en los campos Output file, Jar e Icon por las que correspondan con nuestro workspace. Concretamente:
    • Output file debe apuntar a nuestro_workspace/build/product/gvsig-desktop.exe
    • Jar debe apuntar al jar de andami en nuestro_workspace/build/product/lib/org.gvsig.andami-2.0-SNAPSHOT.jar
    • Icon debe apuntar a nuestro_workspace/build/product/gvSIG.ico
  5. En la pestaña Classpath se debe tener seleccionado el checkbox Custom classpath, en el campo Main class debe figurar org.gvsig.andami.Launcher y en el Classpath únicamente el jar de andami ./lib/org.gvsig.andami-2.0-SNAPSHOT.jar
  6. En la pestaña Header en Header type se debe seleccionar la opción GUI.
  7. En la pestaña Single instance no debemos seleccionar nada para que se puedan tener múltiples instancias de la aplicación ejecutándose al mismo tiempo.
  8. En la pestaña Version Info se pueden cambiar los campos File version, Free form, File description, Product version y, de nuevo, Free form pero esta vez de la sección Additional information, por lo que corresponda a la versión y número de build que vamos a generar.
  9. Hacer el resto de modificaciones que necesitemos.
  10. Salvar la configuración.
  11. Generar el ejecutable pulsando el icono con forma de engranaje Build wrapper.
  12. Si todo ha ido bien, este proceso habrá dejado el archivo gvsig-desktop.exe en la ruta que habíamos seleccionado en Output file.
  13. En algún momento de la instalación de la aplicación, se lanza también el instalador de complementos de gvSIG para lo cual generamos otro ejecutable gvsig-package-installer.exe. Para modificar dicho ejecutable podemos repetir estos mismos pasos teniendo en cuenta que:
    • el archivo de configuración que debemos abrir es /build/projects/gvsig-standard/gvsig-standard-installer/src/main/launch4j/gvsig_package_installer.xml y
    • que el Output file debe ser nuestro_workspace/build/product/gvsig-package-installer.exe

Official version publishing of gvSIG

To publish an official version of gvSIG Desktop in www.gvsig.org, the following steps must be followed:

  1. Rename the binaries with the following nomenclature:
      • gvSIG-[major-number]_[minor-number]_[revision-number]-[Build-Number]-[final_pilot_alpha_RCx_prot]-[operat_syst-3_letters]-[Processor_Type]-[JVM_description]-[JVM].[file_extension].
        For example: gvSIG-1_9-1245-final-lin-i586-withjre-j1_6.bin, gvSIG-1_9-1264-RC2-win-i586-j1_5.bin
  1. Rename source code files (if it's a file) with the following nomenclature:
      • gvSIG-[major-number]_[minor-number]_[revision-number]-[Build-Number]-[final_pilot_alpha_RCx_prot]-[operat_syst]-src.[file_extension].
        For example: gvSIG-1_9-1265-final-lin-src.zip
  1. Upload binaries and source code to OSOR.eu:
      • In the Forge of the project, being logged, go to Files (for example in gvSIG Desktop: http://forge.osor.eu/frs/?group_id=89)
      • In every project, 2 Packages will be created: one for stable versions and another one for unstable ones, for example: gvsig-desktop (final ver.), gvsig-desktop (other ver.), gvsig-network-ext. (final v.), gvsig-mobile (final v.)...
      • In the corresponding Package, the Release must be created. For example:
        For example: gvSIG 1.9 RC2
      • Every file will be uploaded to this release.
  1. Upload the manuals to OSOR.eu:
      • They will be renamed like this: 
        • gvSIG-[major-number]_[minor-number]_[revision-number]-man-[manual_version]-[language_2_letters].[file_extension]
                      For example: gvSIG-1_1-man-v1-en.pdf
      • In the Forge of the project, being logged, go to Files (for example in gvSIG Desktop: http://forge.osor.eu/frs/?group_id=89): 
        • A "Releases" folder must be created (if it doesn't exist)
        • Inside that folder, a new folder called as the name of the version, with 2 figures (eg: 0.3) must be created
        • Inside that folder, a new folder called as the name of the version, with 3 figures (eg: 0.3.0) must be created
        • Manuals in pdf format will be uploaded to this last folder.

 

Official version publishing of gvSIG Mobile

To publish an official version of gvSIG Mobile in www.gvsig.org, the following steps must be followed:

  1. Rename the binaries with the following nomenclature:
      • gvSIG_Mobile-[gvSIG_Mobile_version]-[Status]-[operat_syst]-[Processor_Type]-[JVM_description].[file_extension].
        For example: gvSIG_Mobile-1_0-final-WMX-forPhoneME.cabgvSIG_Mobile-0_3-Pilot-WMX-forPhoneME.cab, gvSIG_Mobile-0_3-RC2-WMX-forPhoneME.cab
  1. Rename source code files (if it's a file) with the following nomenclature:

      • gvSIG_Mobile-[gvSIG_Mobile_version]-[Status]-src.[file_extension].
        For example: gvSIG_Mobile-1_0-final-src.zip,  gvSIG_Mobile-0_3-Pilot-src.zip
  2. Upload binaries and source code to OSOR.eu: 
      • In the Forge of the project, being logged, go to Files (for example in gvSIG Mobile: http://forge.osor.eu/frs/?group_id=214)
      • In every project, 2 Packages will be created: one for final versions and another one for versions on development, for example: gvsig-mobile (final ver.), gvsig-mobile (other ver.).
      • In the corresponding Package, the Release must be created. For example:
        • gvSIG Mobile 0.3 Pilot
      • Every file will be uploaded to this release.
  3. Upload the manuals to OSOR.eu:
      • They will be renamed like this: 
        • gvSIG_Mobile-[gvSIG_Mobile_version]-[Status]-man-[manual_version]-[language_2_letters].[file_extension] 
                      For example: gvSIG_Mobile-0_3-Pilot-man-v1-en.pdf
      • In the Forge of the project, being logged, go to Files (for example in gvSIG Mobile: https://forge.osor.eu/docman/?group_id=214):
        • A "Releases" folder must be created (if it doesn't exist)
        • Inside that folder, a new folder called as the name of the version, with 2 figures (eg: 0.3) must be created
        • Inside that folder, a new folder called as the name of the version, with 3 figures (eg: 0.3.0) must be created
        • Manuals in pdf format will be uploaded to this last folder.

           

 


Powered by Plone CMS, the Open Source Content Management System

This site conforms to the following standards: