Log in Help
Homereleasesgate-6.0-build3764-ALLdoctao 〉 splitch2.html

Chapter 2
Installing and Running GATE [#]

2.1 Downloading GATE [#]

To download GATE point your web browser at http://gate.ac.uk/download/.

2.2 Installing and Running GATE [#]

GATE will run anywhere that supports Java 5 or later, including Solaris, Linux, Mac OS X and Windows platforms. We don’t run tests on other platforms, but have had reports of successful installs elsewhere.

2.2.1 The Easy Way [#]

The easy way to install is to use one of the platform-specific installers (created using the excellent IzPack). Download a ‘platform-specific installer’ and follow the instructions it gives you. Once the installation is complete, you can start GATE Developer using gate.exe (Windows) or GATE.app (Mac) in the top-level installation directory, on Linux and other platforms use gate.sh in the bin directory (see section 2.2.4).

Note for Mac users: on 64-bit-capable systems, GATE.app will run as a 64-bit application. It will use the first listed 64-bit JVM in your Java Preferences, even if your highest priority JVM is a 32-bit one. Thus if you want to run using Java 5 rather than 6 you must ensure that “J2SE 5.0 64-bit” is listed ahead of “Java SE 6 64-bit”.

2.2.2 The Hard Way (1) [#]

Download the Java-only release package or the binary build snapshot, and follow the instructions below.


Using the binary distribution:

The Ant scripts that start GATE Developer (ant.bat or ant) require you to set the JAVA_HOME environment variable to point to the top level directory of your JAVA installation. The value of GATE_CONFIG is passed to the system by the scripts using either a -i command-line option, or the Java property gate.config.

2.2.3 The Hard Way (2): Subversion [#]

The GATE code is maintained in a Subversion repository. You can use a Subversion client to check out the source code – the most up-to-date version of GATE is the trunk:
svn checkout https://gate.svn.sourceforge.net/svnroot/gate/gate/trunk gate

Once you have checked out the code you can build GATE using Ant (see Section 2.5)

You can browse the complete Subversion repository online at http://gate.svn.sourceforge.net/.

2.2.4 Running GATE Developer on Unix/Linux [#]

The script gate.sh in the directory bin of your installation can be used to start GATE Developer. You can run this script by entering its full path in a terminal or by adding the bin directory to your binary path. In addition you can also add a symbolic link to this script in any directory that already is in your binary path.

If gate.sh is invoked without parameters, GATE Developer will use the files ~/.gate.xml and ~/.gate.session to store session and configuration data. Alternately you can run gate.sh with the following parameters:

show usage information
create or use the files .gate.session and .gate.xml in the current directory as the session and configuration files.
-ln name
create or use name.session and name.xml in the current directory as the session and configuration files.
if the current directory contains a file named log4j.properties then use it instead of the default (GATE_HOME/bin/log4j.properties) to configure logging. Alternately, you can specify any log4j configuration file by setting the log4j.configuration property explicitly (see below).
all other parameters
are passed on to the ant command. This can be used to e.g. set properties using the ant option -D. For example to set the maximum amount of heap memory to be used when running GATE to 6000M, you can add -Druntime.max.memory=6000m as a parameter. The name of any property that should get passed on to GATE should be prepended with ’run.’. In order to change the default encoding used by GATE to UTF-8 add -Drun.file.encoding=utf-8 as a parameter. To specify a log4j configuration file add something like

Running GATE Developer with either the -ld or the -ln option from different directories is useful to keep several projects separate and can be used to run multiple instances of GATE Developer (or even different versions of GATE Developer) in succession or even simultanously without the configuration files getting mixed up between them.

2.3 Using System Properties with GATE [#]

During initialisation, GATE reads several Java system properties in order to decide where to find its configuration files.

Here is a list of the properties used, their default values and their meanings:

sets the location of the GATE install directory. This should point to the top level directory of your GATE installation. This is the only property that is required. If this is not set, the system will display an error message and them it will attempt to guess the correct value.
points to the location of the directory containing installed plugins (a.k.a. CREOLE directories). If this is not set then the default value of {gate.home}/plugins is used.
points to the location of the configuration file containing the site-wide options. If not set this will default to {gate.home}/gate.xml. The site configuration file must exist!
points to the file containing the user’s options. If not specified, or if the specified file does not exist at startup time, the default value of gate.xml (.gate.xml on Unix platforms) in the user’s home directory is used.
points to the file containing the user’s saved session. If not specified, the default value of gate.session (.gate.session on Unix) in the user’s home directory is used. When starting up GATE Developer, the session is reloaded from this file if it exists, and when exiting GATE Developer the session is saved to this file (unless the user has disabled ‘save session on exit’ in the configuration dialog). The session is not used when using GATE Embedded.
sets the default directory to be shown in the file chooser of GATE Developer to the specified directory instead of the user’s operating-system specific default directory.
is a path-like structure, i.e. a list of URLs separated by ‘;’. All directories listed here will be loaded as CREOLE plugins during initialisation. This has similar functionality with the the -d command line option.
is a URL pointing to the location of GATE’s built-in CREOLE directory. This is the location of the creole.xml file that defines the fundamental GATE resource types, such as documents, document format handlers, controllers and the basic visual resources that make up GATE. The default points to a location inside gate.jar and should not generally need to be overridden.

When using GATE Embedded, you can set the values for these properties before you call Gate.init(). Alternatively, you can set the values programmatically using the static methods setGateHome(), setPluginsHome(), setSiteConfigFile(), etc. before calling Gate.init(). See the Javadoc documentation for details. If you want to set these values from the command line you can use the following syntax for setting gate.home for example:

java -Dgate.home=/my/new/gate/home/directory -cp... gate.Main

To set these values when running GATE Developer from the command line via ant, of via the gate.sh script, use the following syntax, prepending ‘run.’ to the property name, for example to set gate.user.config:

./bin/ant run -Drun.gate.user.config=/my/path/to/user/config.file
./bin/gate.sh -Drun.gate.user.config=/my/path/to/user/config.file

Note that gate.home and some other properties are automatically set by build.xml and cannot be overwritten on the command line when using either ant run or gate.sh.

When running GATE Developer, you can set the properties by creating a file build.properties in the top level GATE directory. In this file, any system properties which are prefixed with ‘run.’ will be passed to GATE. For example, to set an alternative user config file, put the following line in build.properties1:


This facility is not limited to the GATE-specific properties listed above, for example the following line changes the default temporary directory for GATE (note the use of forward slashes, even on Windows platforms):


2.4 Configuring GATE [#]

When GATE Developer is started, or when Gate.init() is called from GATE Embedded, GATE loads various sorts of configuration data stored as XML in files generally called something like gate.xml or .gate.xml. This data holds information such as:

This type of data is stored at two levels (in order from general to specific):

Where configuration data appears on several different levels, the more specific ones overwrite the more general. This means that you can set defaults for all GATE users on your system, for example, and allow individual users to override those defaults without interfering with others.

Configuration data can be set from the GATE Developer GUI via the ‘Options’ menu then ‘Configuration’. The user can change the appearance of the GUI in the ‘Appearance’ tab, which includes the options of font and the ‘look and feel’. The ‘Advanced’ tab enables the user to include annotation features when saving the document and preserving its format, to save the selected Options automatically on exit, and to save the session automatically on exit. The ‘Input Methods’ submenu from the ‘Options’ menu enables the user to change the default language for input. These options are all stored in the user’s .gate.xml file.

When using GATE Embedded, you can also set the site config location using Gate.setSiteConfigFile(File) prior to calling Gate.init().

2.5 Building GATE [#]

Note that you don’t need to build GATE unless you’re doing development on the system itself.


GATE now includes a copy of the ANT build tool which can be accessed through the scripts included in the bin directory (use ant.bat for Windows 98 or ME, ant.cmd for Windows NT, 2000 or XP, and ant.sh for Unix platforms).

To build gate, cd to gate and:

  1. Type:
  2. [optional] To test the system:
    bin/ant test
  3. [optional] To make the Javadoc documentation:
    bin/ant doc
  4. You can also run GATE Developer using Ant, by typing:
    bin/ant run
  5. To see a full list of options type: bin/ant help

(The details of the build process are all specified by the build.xml file in the gate directory.)

You can also use a development environment like Borland JBuilder (click on the gate.jpx file), but note that it’s still advisable to use ant to generate documentation, the jar file and so on. Also note that the run configurations have the location of a gate.xml site configuration file hard-coded into them, so you may need to change these for your site.

2.5.1 Using GATE with Maven/Ivy [#]

This section is based on contributions by Marin Nozhchev (Ontotext) and Benson Margulies (Basis Technology Corp).

Stable releases of GATE (since 5.2.1) are available in the standard central Maven repository, with group ID “uk.ac.gate” and artifact ID “gate-core”. To use GATE in a Maven-based project you can simply add a dependency:


Similarly, with a project that uses Ivy for dependency management:

<dependency org="uk.ac.gate" name="gate-core" rev="6.0"/>

The “gate-core” dependency brings in just gate.jar and its minimal dependencies, sufficient to initialize GATE, load and save documents and corpora as XML, etc. The POM lists many other dependencies which are marked as optional, so you can pick and choose which parts of GATE you wish to depend on. In addition you will require the matching versions of any GATE plugins you wish to use in your application – these are not managed by Maven or Ivy, but can be obtained from the standard GATE release download.

2.6 Uninstalling GATE [#]

If you have used the installer, run:

java -jar uninstaller.jar

or just delete the whole of the installation directory (the one containing bin, lib, Uninstaller, etc.). The installer doesn’t install anything outside this directory, but for completeness you might also want to delete the settings files GATE creates in your home directory (.gate.xml and .gate.session).

2.7 Troubleshooting [#]

2.7.1 I don’t see the Java console messages under Windows [#]

Note that the gate.bat script uses javaw.exe to run GATE which means that you will see no console for the java process. If you have problems starting GATE and you would like to be able to see the console to check for messages then you should edit the gate.bat script and replace javaw.exe with java.exe in the definition of the JAVA environment variable.

2.7.2 When I execute GATE, nothing happens [#]

You might get some clues if you start GATE from the command line, using:

bin/ant -Druntime.spawn=false run

which will allow you to see all error messages GATE generates.

2.7.3 On Ubuntu, GATE is very slow or doesn’t start [#]

GATE and many other Java applications are known not to work with GCJ, the open-source Java SDK or others non SUN Java SDK.

Make sure you have the official version of Java installed. Provided by Sun, the package is named ‘sun-java6-jdk’ in Synaptic. GATE also works with Java version 5 so ‘sun-java5-jdk’.

To install it, run in a terminal:

sudo apt-get install sun-java6-jdk

Make sure that your default Java version is the one from SUN. You can do this by running:

sudo update-java-alternatives -l

This will list the installed Java VMs. You should see ‘java-6-sun’ as one of the options.

Then you should run :

sudo update-java-alternatives -s java-6-sun

to set the ‘java-6-sun’ as your default.

Finally, try GATE again.

2.7.4 How to use GATE on a 64 bit system? [#]

32-bit vs. 64-bit is a matter of the JVM rather than the build of GATE -

For example, on Mac OS X, either use Applications/Utilities/Java Preferences and put one of the 64-bit options at the top of the list, or run GATE from the terminal using Java 1.6.0 (which is 64-bit only on Mac OS):

export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home  
bin/ant run

2.7.5 I got the error: Could not reserve enough space for object heap [#]

GATE doesn’t use the JAVA_OPTS variable. The default memory allocations are defined in the gate/build.xml file but you can override them by creating a file called build.properties in the same directory containing


If you start GATE by running bin/ant run you can also overwrite these properties by using the ant command line option -D, e.g.:

./bin/ant run -Druntime.start.memory=256m -Druntime.max.memory=1048m

On Linux, when using the bin/gate.sh command or a link to it to start GATE (see 2.2.4), you can add these parameters to the command line arguments using the -D option, e.g.:

gate.sh -Druntime.start.memory=256m -Druntime.max.memory=1048m

If you don’t use ant to start GATE but your own application directly with the ‘java’ executable then you must use something like:

java -Xmx512m -classpath <your classpath here> <yourClassName>

2.7.6 From Eclipse, I got the error: java.lang.OutOfMemoryError: Java heap space [#]

Configuring xms and xmx parameters in eclipse.ini file just adds memory to your Eclipse process. If you start a Java application from within Eclipse, that will run in a different process.

To give more memory to your application, as opposed to just to Eclipse, you need to add those values in the ‘VM Arguments’ section of the run application dialog: lower pane, in the second tab of ‘Run Configurations’ dialog.

2.7.7 On MacOS, I got the error: java.lang.OutOfMemoryError: Java heap space [#]

You can try to set the environment variable ANT_OPTS to allow for more memory as follows:

export ANT_OPTS=-Xmx1024m

Another cause can be when compiling with Java 6 on Mac. It builds OK using Java 5 with

export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Home

and once built it runs fine with Java 6. Adding


or similar to the <javac> in build.xml might fix it but if you’re making changes that are to be committed to subversion you really ought to be building with Java 5 anyway :-)

2.7.8 I got the error: log4j:WARN No appenders could be found for logger... [#]

This may occur if you start GATE Developer or an application using GATE Embedded in a way so that the directory ’GATE_HOME/bin’ is not in the Java classpath and you did not specify a valid URL for the system property log4j.configuration either. The log4j logging component uses either the file whose URL is specified with the property log4j.configuration or a file named log4j.properties from the classpath for configuration. A quick fix for this problem is usually to copy the file ’GATE_HOME/bin/log4j.properties’ file to a directory which is part of the classpath of your project.

2.7.9 Text is incorrectly refreshed after scrolling and become unreadable [#]

Change the look and feel used in GATE with menu ‘Options’ then ‘Configuration’. Restart GATE and try again. We use mainly ‘Metal’ and ‘Nimbus’ without problem.

Change the video driver you use.

Update Java.

2.7.10 An error occurred when running the TreeTagger plugin [#]

The TreeTagger plugin isn’t supported anymore. However, the TaggerFramework plugin provides support for TreeTagger. Try using that plugin instead. See section 17.3.

2.7.11 I got the error: HighlightData cannot be cast to ...HighlightInfo [#]

That’s a recurring problem when editing a document with annotation highlights showing and it usually involves inserting/deleting some text close or belonging to an annotation in the first place.

The current solutions are to hide the annotation highlights before to edit the text or use document read-only mode so you can only edit annotations or hide then show again the document after the error.

1In this specific case, the alternative config file must already exist when GATE starts up, so you should copy your standard gate.xml file to the new location.