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.

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.

${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.

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.

<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>
     ...

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

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