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.

__ http://maven.apache.org

__ http://maven.apache.org/run-maven/index.html


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

__ ../../gvsig-compilation/jni-compilation

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

.. include-document:: supported-platforms
   :rest:

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

    

    

        
            
                gvsig-repository
                [USUARIO]
                [CLAVE]
                666
                777
            
        
    

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

__ http://maven.apache.org/guides/mini/guide-encryption.html

To summarize, the steps are:

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

    mvn --encrypt-master-password 

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

    
      [CLAVE MAESTRA ENCRIPTADA]
    

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

    
      {jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}
    

#. Encrypt the password to access the OSOR server::

    mvn --encrypt-password 

   Which will return something like::

    {COQLCE6DU6GtcS5P=}

#. Substitute the open password with the encrypted password in the [USER HOME]/.m2/settings.xml file::

    
      gvsig-repository
      [USUARIO]
      [CLAVE ENCRIPTADA]
    

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

    
      gvsig-repository
      USER
      {COQLCE6DU6GtcS5P=}