Running gvSIG CE

From gvSIG CE Wiki

Jump to: navigation, search

Once you have compiled all required JAR files and a set of native binaries for your operating system, you are ready to create a gvSIG CE distribution. In this context, a "distribution" is a set of all files requried to copy gvSIG CE onto a computer and run it. Remember that gvSIG CE is portable software: There is no separate installation step for deploying it on a computer. Users simply run gvSIG CE from the folder that contains the distribution.

This page will show you how to prepare a complete gvSIG CE distribution (including the compiled Java sources, and all C/C++ support libraries), and how to run the software.

32/64 bit note: The JARs produced by the Java compiler contain machine-independent byte code that will run on any CPU type and any operating system for which a JVM is available. The native support binaries, however, are machine-specific. Therefore, in order to get e.g. a working gvSIG CE on 64 bit Linux, you need to combine a 64 bit Linux JVM with 64 bit Linux native binaries.

Windows note: These instructions assume that you have MSYS installed and running as described in Getting started with MSYS. We will not provide instructions for Windows' own "cmd.exe".

Contents

Preparation (file system layout)

A gvSIG CE distribution has a fixed layout of files and folders that differs between operating systems. In the following instructions, we assume that the variable "CE_ROOT" always contains the absolute path up to and including the name of top (=root) folder in which gvSIG CE is stored.

Read on below to find out about the individual layout for each supported operating system.

Linux

On Linux, the folder layout of the distribution looks like this:

 $(CE_ROOT)
   bin
     default
     gvSIG
     lib
     theme
   doc
   jre
     bin
     lib
   lib
   license

These are the roles of some of the folders:

$(CE_ROOT)/bin - The base system, settings files and templates, as well as the startup-script (launcher).

$(CE_ROOT)/doc - Documentation, including user manuals.

$(CE_ROOT)/jre - A complete Java Runtime Environment, optimized for running gvSIG CE.

$(CE_ROOT)/lib - Linux native binaries that mainly add support for the GDAL/OGR geodata drivers.

$(CE_ROOT)/license - Files containing license terms for gvSIG CE and 3rd party components.

The following commands will create the folder structure that needs to be in place for the following instructions to work:

 mkdir "$CE_ROOT"
 mkdir "$CE_ROOT/bin"
 mkdir "$CE_ROOT/bin/default"
 mkdir "$CE_ROOT/bin/gvSIG"
 mkdir "$CE_ROOT/bin/lib"
 mkdir "$CE_ROOT/bin/theme"
 mkdir "$CE_ROOT/doc"
 mkdir "$CE_ROOT/lib"
 mkdir "$CE_ROOT/license"

Note that the "jre" folder and its subfolders do not need to be created at this point.

Mac OS X

Windows

Base system

Linux

The base system files go into "$CE_ROOT/bin" and its subfolders. In the following, whenever a file source is given (such as "_fwAndami"), then this refers to a project folder in your Eclipse workspace where the individual components of gvSIG CE reside. See here for details.

$CE_ROOT/license - Copy the licensing terms for gvSIG CE directly into this folder:

  _fwAndami/
            GPL.V2.txt
            gvSIG.CE.license.txt

$CE_ROOT/bin - This folder contains the start-up script, GUI translation files and some other essential files. Copy the following files into here:

 _fwAndami/
           andami.jar 
           castor.properties
           config/
                  *.properties

$CE_ROOT/bin/defaults - These are default configuration files that gvSIG CE will use if any local user settings folder do not yet exist (see the section on Customizing gvSIG CE for details). Copy the files from "_fwAndami/defaults" into here:

 _fwAndami/
           defaults/
                    andami-config.xml
                    plugins-persistence.xml
                    usr.properties
                    usr.script

$CE_ROOT/bin/gvSIG - This is where all the compiled Java classes (JARs) go that make up gvSIG itself and all of its extensions. Copy the entire "extensiones" directory from

Java Runtime Environment (JRE)

Although it would be possible to use a JRE that already exists on the user's system, we prefer to bundle gvSIG CE with a version that we know will work well with the software and contains everything the user needs.

Working JREs can be extracted from the JDKs available at https://github.com/alexkasko/openjdk-unofficial-builds. They are contained in the "jre" folder. If you have already downloaded an OpenJDK distribution, then check if that folder is already present.

Read on below to find out the details for each supported operating system.

Linux

Extract the "jre" folder from the OpenJDK distribution that you downloaded and place it into "$CE_ROOT",

In addition, we need to put the Java Image I/O extensions int the JRE, as described here.

Also, do not forget to include the files specifying the license conditions in "doc"!

The completed layout should look as follows:

 $CE_ROOT/
          bin/
              [...]
          doc/
              [...]
          license/
                  [...]
                  Sun.Java.Adv.Img.IO/
                                  COPYRIGHT-jai.txt
                                  DISTRIBUTIONREADME-jai.txt
                                  LICENSE-jai.txt
                                  THIRDPARTYLICENSEREADME-jai.txt
                  [...]
          jre/                             
              bin/
                  [...]
              lib/
                  [...]
          lib/
              [...]
              ext/
                  [...]
                  jai_codec.jar
                  jai_core.jar
                  jai_imageio.jar
              [...]

Mac OS X

Windows

Support libraries (native binaries)

For distribution, the native binaries and the Java interface classes in their JAR files need to be copied into the right gvSIG subdirectories.

All platforms

Copy the following files into the folder bin/gvSIG/extensiones/com.iver.cit.gvsig/lib of your gvSIG distribution:

 $WORKSPACE/src/libjni-potrace/jar-dist/*

Copy the following files into the folder bin/gvSIG/extensiones/org.gvsig.crs/data of your gvSIG distribution:

 $WORKSPACE/dist/share/proj/*

Copy the following files into the folder libs/gdal_data for your gvSIG distribution:

 $WORKSPACE/dist/share/gdal/*

Copy all files in $WORKSPACE/dist/share/proj to the gvSIG distribution folder extensiones/org.gvsig.crs/data.

There are some more grid shift data files in .gsb file format that can be downloaded from the PROJ.4 project page. For distribution with gvSIG, they also need to be copied into extensiones/org.gvsig.crs/data.

Copy all license files required by 3rd party libraries (e.g. MrSID, ECW) into ...

Linux

*TODO*: strip binaries; remove unneeded symlinks (cp w/o referencing?)

Copy the following files into the libs folder of your gvSIG distribution. Assuming the variable GVSIG_DIR points to the base directory of your gvSIG distribution, the following lines will copy the files to the right folders; don't forget the -d flag, or you will end up with a lot of duplicates:

 cp -d $WORKSPACE/src/libjni-mrsid/lib/* $GVSIG_DIR/libs
 cp -d $WORKSPACE/src/libjni-mrsid/sdk/lib/*.s* $GVSIG_DIR/libs
 cp -d $WORKSPACE/src/libjni-ecw/lib/* $GVSIG_DIR/libs
 cp -d $WORKSPACE/src/libjni-gdal/lib/* $GVSIG_DIR/libs
 cp -d $WORKSPACE/src/libjni-potrace/lib/* $GVSIG_DIR/libs
 cp -d $WORKSPACE/src/libjni-proj4/lib/* $GVSIG_DIR/libs
 cp -d $WORKSPACE/src/dist/lib/*.s* $GVSIG_DIR/libs
 cp -dR $WORKSPACE/src/dist/lib/postgresql $GVSIG_DIR/libs

Windows

 strip $WORKSPACE/dist/bin/*.dll

Copy "gdalserver"!

Start-up scripts

On each supported operating system, gvSIG CE is started via a start-up script. The most essential job of this script is to set the Classpath for the Java Virtual machine. But it also sets additional environment variables that are important for the proper operation of gvSIG. And finally, it configures the look and feel and optimal performance of the JVM.

Linux

Mac OS X

Windows

Next steps

Read the section on Java VM Tuning to learn how to get the best performance out of your gvSIG CE distribution.

Previous steps

Go back to Compiling SAGA GIS

Go back further to Compiling GRASS GIS

Go back even further to Compiling the C/C++ support libraries.