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:
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:
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.
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.
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.
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:
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=}
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>
Encrypt the password to access the OSOR server:
mvn --encrypt-password <clave>
Which will return something like:
{COQLCE6DU6GtcS5P=}
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>
The steps for creating an Eclipse workspace for working with gvSIG are as follows:
Start Eclipse and create a new workspace for gvSIG 2.0.
Set the encoding used in gvSIG (ISO-8859-1):
Window > Preferences: General > Workspace > Text file encoding = ISO-8859-1
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).
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:
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:
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.
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.
Open the Ant view by selecting the following menu option:
Window > Show view > ant
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:
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
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.
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
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
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:
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.
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.
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).
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:
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:
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:
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.
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.
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.
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.
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).
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:
| 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. |