How-To Build gvSIG Mobile 1.0 Workspace

First of all, to compile gvSIG Mobile 1.0 there are some needed software that have to be installed.

Download Eclipse

http://www.eclipse.org/downloads/

Download Eclipse SDK (so far so good with version 3.4 or greater), the common developers version is not enough, because we'll need to develop Equinox plugin and bundles. (For instance download the Eclipse Modeling Tools)

Install Subclipse

As usual install the Subclipse plugin using the Eclipse market or following the instructions from the url

http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA

Install PDE

Install PDE software o check it is installed correctly. There are two ways to find out if PDE is installed (Eclipse Plug-in development environment).
- From Windows -> Preferences: The new option 'Plug-in Development' is active.

After check it out if it's installed and didn't find it then can be installed using the eclipse market.

Equinox Download

http://archive.eclipse.org/equinox/drops/R-3.5-200906111540/index.php#Equinox

Download the Equinox bundles that we need to run the application from Eclipse:

org.eclipse.equinox.transforms.hook - Transformer Hook Framework Extension

org.eclipse.equinox.wireadmin - Wire Admin Service

org.eclipse.equinox.util - Equinox Util Bundle

org.eclipse.osgi - OSGi System Bundle

org.eclipse.osgi.services - OSGi Release 4.0.1 Services

org.eclipse.osgi.util - OSGi Release 4.0.1 Utility Classes
Once all are downloaded, copy all to the eclipse plugins folder from the file explorer.
Restart Eclipse to update the new loaded plug-ins. Maybe need run eclipse -clean from the console to update the OSGI plugins.

Install Maven

http://maven.apache.org/download.html

Download the latest Maven from your operating system that we need to compile the application from console, follow the installation instructions for your operating system.

Downloading the gvSIG Mobile Projects

Configure gvSIG Mobile SVN

Add the gvSIG Mobile SVN

https://devel.gvsig.org/svn/gvsig-mobile

Can found more information about the project from: https://devel.gvsig.org/redmine/projects/gvsig-mobile

Downloading the workspace from the tag

Simply download all the projects from the tag:

SVN repository: https://devel.gvsig.org/svn/gvsig-mobile
Tag folder: /appGvsigMobile/tags/gvsig_mobile_1_0__22_nov_2012

Downloading the workspace from latest versions

Alternatively, you can download each project from their original URLs to get the latest versions (compilation is not guaranteed in all cases):

Download Core Bundles

Checkout the next projects from the SVN gvSIG Mobile repository:

BUILD PROJECT

https://devel.gvsig.org/svn/gvsig-mobile/build/trunk (Check that is downloaded named as 'build')

GVSIG BASE PROJECTS:

From https://devel.gvsig.org/svn/gvsig-mobile/appGvsigMobile/trunk/ download the projects:
- org.gvsig.mobile.core.GvSigCore
- org.gvsig.mobile.core.libraries
- org.gvsig.mobile.dll
- org.gvsig.mobile.extension.base
- org.gvsig.mobile.logging
- org.gvsig.mobile.logging.configure

SYMBOLS SUPPORT PROJECT:

From https://devel.gvsig.org/svn/gvsig-mobile/FMap/trunk donwload:
- org.gvsig.mobile.symbology

PROJECTION PROJECT:

From https://devel.gvsig.org/svn/gvsig-mobile/projection/trunk download:
- org.gvsig.mobile.libProjection

Download Extra Functionality Bundles

There are others gvSIG Mobile projects that can be downloaded to get all the gvSIG Mobile functionality, if you want all the functionalities then must download also the next projects:

SHAPEFILE FILE FORMAT SUPPORT PROJECT:

From https://devel.gvsig.org/svn/gvsig-mobile/FMap/trunk/FMap_dal download:
- org.gvsig.mobile.dal.dalfile

ECW FILE FORMAT SUPPORT PROJECT:

From https://devel.gvsig.org/svn/gvsig-mobile/appGvsigMobile/trunk/ download the projects:
- org.gvsig.mobile.ecw

WMS PROJECT:

From https://devel.gvsig.org/svn/gvsig-mobile/appGvsigMobile/trunk/ download the projects (Depends on ECW FILE FORMAT):
- org.gvsig.mobile.extension.wms

GML, KML FILE FORMATS PROJECT:

From https://devel.gvsig.org/svn/gvsig-mobile/appGvsigMobile/trunk/ download the projects (Depends on SHAPEFILE FILE FORMAT):
- org.gvsig.mobile.gpe

WFS PROJECTS:

From https://devel.gvsig.org/svn/gvsig-mobile/appGvsigMobile/trunk/ download the projects (Depends on GML FILE FORMAT):
- org.gvsig.mobile.extension.wfs
- org.gvsig.mobile.wfs

EDITING PROJECTS:

From https://devel.gvsig.org/svn/gvsig-mobile/editing/trunk download:
- org.gvsig.mobile.extension.editing
- org.gvsig.mobile.extension.editing.gps

GPS SUPPORT PROJECTS:

From https://devel.gvsig.org/svn/gvsig-mobile/libLocation/trunk/extLocation download:
- org.gvsig.mobile.extension.gps
From https://devel.gvsig.org/svn/gvsig-mobile/libLocation/trunk download :
- org.gvsig.mobile.bundle.libLocation

PROJECTION EXTENSION PROJECT:

From https://devel.gvsig.org/svn/gvsig-mobile/projection/trunk download:
- org.gvsig.mobile.extension.wkprojection

All the bundles above are optional.

Compile bundles using maven

Download gvSIG Mobile dependencies

OSGI don't allow the symbol '-' to number bundles version, like 2.0-SNAPSHOT, Then all the gvSIG Mobile bundles version must be numbered as 1.0.SNAPSHOT.
Is recommended delete all the M2_REPO repository before start the dependencies download or choose another repository name on settings.xml
Maven 2.2.1 or latter version must be installed and the PATH updated to index the absolute path to the directory build/maven/bin.

Editing our settings.xml file

Developers who have commit permission in the gvSIG Mobile repository should write their user/password settings here in case they need to deploy something.

Other developers need to have this settings file too (the user and password will not be used):

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<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>[user]</username>
         <password>[password]</password>
         <filePermissions>666</filePermissions>
         <directoryPermissions>777</directoryPermissions>
     </server>
 </servers>

 <!-- optionally you can change the path to your local            -->
 <!-- maven repository. Remember you have to edit the little file -->
 <!-- build/initial_m2/build.xml to point at the same folder      -->
 <localRepository>[path_to_local_maven_repo]</localRepository>

 <!-- This value is changed during the setup of the workspace -->
 <!-- (see instructions)                                      -->
 <offline>true</offline>
 </settings>

Where:

[user] must be our user account in the gvSIG Mobile project
[password] must be our password in the gvSIG Mobile project
[path_to_local_maven_repo] is (optionally) the path to our local maven repository. The default value is [user_home]/.m2/repository (for example "C:\Users\Peter\.m2\repository" in Windows 7 or "/home/Peter/.m2/repository" in Linux)

Install Dependencies

From Eclipse, right-click on the file build/initial_m2/build.xml and execute it (Run ass/Ant Build). This process will take about 20 seconds and will provide a first version of your local maven repository. Open the file first with the Eclipse text editor to make sure that the target folder is actually your local maven repository.
Open the file [user_home]/.m2/settings.xml and make sure the offline parameter is false.
From the system console, go to the workspace build folder and type:

mvn -P cdc install

Move to the build/projects/gvsig-mobile-init folder and type:

mvn -P cdc clean package eclipse:eclipse -Declipse.pde -Dmaven.test.skip=true install

Now open the file [user_home]/.m2/settings.xml again and make sure the offline parameter is true.

Compile Projects and Build Eclipse Projects

In order to compile gvSIG Mobile Core from the System Console, you need to have the mentioned projects downloaded, and then open a system console, go to the workspace folder build/projects/gvsig-mobile-core and type:

mvn -P cdc clean package eclipse:eclipse -Declipse.pde -Dmaven.test.skip=true install

In order to compile gvSIG Mobile Standard from the System Console, move to the build/projects/gvsig-mobile-standard folder and type:

mvn -P cdc clean package eclipse:eclipse -Declipse.pde -Dmaven.test.skip=true install

Finally, refresh (F5) and clean the projects within Eclipse.

Problems during the building

If the maven build process finish with 'BUILD SUCCESSFULL' but on Eclipse several compilation errors are shown, sometimes is because the MANIFEST.MF are bad built. Then try to:

If red cross appears on MANIFEST.MF, maybe it's enough doing CTRL+SHIFT+F (Format the Manifest) and saving it. Eclipse seems to have a bad refresh system.

To prevent maven memory problems during the compilation:

ERROR: java heap space - java.lang.OutOfMemoryError*

In Windows we have to run from System Console before projects compilation:

set MAVEN_OPTS=-Xmx1024m

Configure and launch gvSIG Mobile from Eclipse

Run Workspace

First of all make a new OSGI application launcher:

Run Configurations -> New OSGI Framework...
Now select all the workspace bundles just clicking on the Workspace check at Bundles Tab. Once all the bundles are selected we have to set the right Start Level to each one:

CORE GVSIG MOBILE START LEVELS:

org.gvsig.mobile.core.GvSigCore -> Start Level 2
org.gvsig.mobile.dll -> Start Level 1
org.gvsig.mobile.extension.base -> Start Level 5
org.gvsig.mobile.libProjection -> Start Level 3
org.gvsig.mobile.core.libraries -> Start Level 1
org.gvsig.mobile.logging -> Start Level 1
org.gvsig.mobile.logging.configure -> Start Level 1
org.gvsig.mobile.symbology -> Start Level 3

Then must select the OSGI dependencies from the Target Platform check, checking next bundles as active and setting the right Start Level if allowed.

OSGI START LEVELS:

javax.servlet - Servlet API Bundle -> Start Level 1
org.eclipse.osgi - OSGi System Bundle -> Start level 2 or Default
org.eclipse.osgi.services - OSGi Release 4.0.1 Services -> Start level 2
org.eclipse.osgi.util - OSGi Release 4.0.1 Utility Classes -> Start level 2
org.eclipse.equinox.util - Equinox Util Bundle -> Start level 2
org.eclipse.equinox.wireadmin - Wire Admin Service -> Start level 2

The other gvSIG Mobile functionalities have to set the right start level to launch the application bundles in a right order. The Start Level for those extra functionalities are:

SHAPEFILE START LEVEL:

org.gvsig.mobile.dal.dalfile -> Start Level 3

ECW START LEVEL:

org.gvsig.mobile.extension.ecw -> Start Level 6

WMS START LEVEL:

org.gvsig.mobile.extension.wms -> Start Level 6

GML, KML FILE START LEVEL:

org.gvsig.mobile.gpe -> Start Level 4

WFS START LEVELS:

org.gvsig.mobile.extension.wfs -> Start Level 6
org.gvsig.mobile.wfs -> Start Level 4

EDITING START LEVELS:

org.gvsig.mobile.extension.editing -> Start Level 6
org.gvsig.mobile.extension.editing.gps -> Start Level 6

GPS START LEVELS:

org.gvsig.mobile.extension.gps -> Start Level 6
org.gvsig.mobile.bundle.libLocation -> Start Level 1

PROJECTION START LEVEL:

org.gvsig.mobile.extension.wkprojection -> Start Level 4

Then click on Validate Bundles button. If there are lost dependencies we can click on Add Required Bundles and validate again, no problems must be detected.
Save configuration and Run...

Once OSGI is launched, we can launch Equinox orders from Eclipse Console. Equinox show the console commands typing the command ?help?.

The most used commands are ss, start y stop:

ss: List the bundles installed on the Equinox framework.

It's possible stop and start bundles with the ?start? and ?stop? commands with the bundle number id. For instance to stop the org.gvsig.mobile.extension.base just type ?stop 13?. Those commands are useful when one bundle don't START (It shows ?ACTIVE? status) correctly then starting them with the ?start? command the console shows all the launched exceptions.

When is activated org.gvsig.mobile.dll it look for the jni libraries in the paths defined at the java.library.path. You can set this library path with -Djava.library.path = your_libraries_path option setted as VM arguments at the Arguments Tab from Run Configurations. If the java.library.path doesn't contain the JNI libraries then UnsatisfiedLinkError is launched at the app start.

Preparing the binaries after compilation

Moving the resulting compiled bundles to the device

Simply follow these steps in order to copy the resulting compiled bundles to the final device (whether it's a PDA, smartphone or PC):

The result of your compilation is inside the build folder:

build/product/gvSIG-Mobile/bundles

That folder contains subfolders with the essential and the optional bundles, depending on how your workspace is configured.

The binaries of the final application (you can get them here for PDA/smartphone -small file- and for Windows/Linux PC) consists of several folders. One of them contains the bundles, so you simply need to replace the existing bundles with the new ones from your build folder. The exact location of the bundles in the final destination is:

/jars/gvSIG-Mobile/bundles

Finally, restart the application in the target device.