.. contents:: Tabla de Contenidos
:depth: 3
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::
gvsig-repository
nbrodin
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 programa\Microsoft Visual Studio 8\VC\bin”
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 ** de tu proyecto
*Java*::
org.gvsig
org.gvsig.jgdal
2.0
org.gvsig
org.gvsig.jgdal
2.0
${native-classifier}
tar.gz
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 **** 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::
linux
all
gcc4
i386
dynamic
- Windows::
win
nt
vs8
i386
dynamic
- MacOSX::
mac
10.5
gcc4
universal
dynamic
La propiedad se genera de la siguiente forma::
${native-platform}-
${native-distribution}-
${native-compiler}-
${native-arch}-
${native-libraryType}
Por tanto es fácil cambiar cualquier valor desde la línea de comandos haciendo
uso de *-Dnative-distribution="valor que quiero que tenga"*.
tar.gz
*******************
Otro elemento que no es habitual en las dependencias de tipo *jar*, es el
elemento **. 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::
4.0.0
org.gvsig
org.gvsig.jgdal
jar
2.0
libjni-gdal Library
org.gvsig
gvsig-base-library-jni-pom
2.0-SNAPSHOT
${basedir}/../build
...
No hay diferencia con otros proyectos, lo **único a tener en cuenta es que la
definición del elemento padre es**:
*gvsig-base-library-jni-pom*
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::
org.gdal
gdal
1.6.0
${native-classifier}
tar.gz
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::
windows-profile
native-platform
win
${basedir}\..\build
org.gdal
gdal
1.6.0
${native-classifier}
tar.gz
linux-profile
native-platform
linux
mac-profile
native-platform
mac
org.gdal
gdal
1.6.0
${native-classifier}
tar.gz
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.
