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 7 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).

2.2.2 The Hard Way (1) [#]

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

Prerequisites:

• A conforming Java 2 environment,
  • version 1.4.2 or above for GATE 3.1
  • version 5.0 for GATE 4.0 beta 1 or later.
  • version 6.0 for GATE 6.1 or later.
  • version 7.0 for GATE 8.0 or later.

  available free from Oracle or from your UNIX supplier. (We test on various Sun JDKs on Solaris, Linux and Windows XP.)

• Binaries from the GATE distribution you downloaded: gate.jar (which can be found in the directory called bin). You will also need the lib directory, containing various libraries that GATE depends on.
• a suitable Apache ANT installation (version 1.8.1 or newer). You will need to add an environment variable named ANT_HOME pointing to your ANT installation, and add ANT_HOME/bin to your PATH.
• An open mind and a sense of humour.

Using the binary distribution:

• Unpack the distribution, creating a directory containing jar files and scripts.
• To run GATE Developer:
  • on Windows, start a Command Prompt window, change to the directory where you unpacked the GATE distribution and run ‘bin\gate.bat’;
  • on Windows using the GUI, double-click the ‘gate.exe’ file;
  • on UNIX/Linux or Mac open a terminal window and run ‘bin/gate.sh’.
• To embed GATE as a library (GATE Embedded), put gate.jar and all the libraries in the lib directory in your CLASSPATH.

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.site.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 http://svn.code.sf.net/p/gate/code/gate/trunk gate

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

You can browse the complete Subversion repository online at
https://sourceforge.net/p/gate/code/HEAD/tree/.

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:

-h

show usage information

-ld

create or use the files .gate.session and .gate.xml in the current directory as the session and configuration files. If option -dc DIR occurs before this option, the file .gate.session is created from DIR/default.session if it does not already exist and the file .gate.xml is created from DIR/default.xml if it does not already exist.

-ln NAME

create or use NAME.session and NAME.xml in the current directory as the session and configuration files. If option -dc DIR occurs before this option, the file NAME.session is created from DIR/default.session if it does not already exist and the file DIR.xml is created from DIR/default.xml if it does not already exist.

-ll

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).

-rh LOCATION

set the resources home directory to the LOCATION provided. If a resources home location is provided, the URLs in a saved application are saved relative to this location instead of relative to the application state file (see section 3.9.3). This is equivalent to setting the property gate.user.resourceshome to this location.

-d URL

loads the CREOLE plugin at the given URL during the start-up process.

-i FILE

uses the specified file as the site configuration.

-dc DIR

copy default.xml and/or default.session from the directory DIR when creating a new config or session file. This option works only together with either the -ln, -ll or -tmp option and must occur before -ln, -ll or -tmp. An existing config or session file is used, but if it does not exist, the file from the given directory is copied to create the file instead of using an empty/default file.

-tmp

creates temporary configuration and session files in the current directory, optionally copying default.xml and default.session from the directory specified with a -dc DIR option that occurs before it. After GATE exits, those session and config files are removed.

all other parameters

are passed on to the java command. This can be used to e.g. set properties using the java option -D. For example to set the maximum amount of heap memory to be used when running GATE to 6000M, you can add -Xmx6000m as a parameter. In order to change the default encoding used by GATE to UTF-8 add -Dfile.encoding=utf-8 as a parameter. To specify a log4j configuration file add something like
-Dlog4j.configuration=file:///home/myuser/log4jconfig.properties.

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:

gate.home

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.

gate.plugins.home

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.

gate.site.config

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!

gate.user.config

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.

gate.user.session

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.

gate.user.filechooser.defaultdir

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.

load.plugin.path

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.

gate.builtin.creole.dir

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

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.properties¹:

run.gate.user.config=${user.home}/alternative-gate.xml

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

run.java.io.tmpdir=d:/bigtmp

When running GATE Developer from the command line via ant or via the gate.sh script you can set properties using -D. Note that the “run” prefix is required when using ant:

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

but not when using gate.sh:

./bin/gate.sh -Dgate.user.config=/my/path/to/user/config.file

The GATE Developer launcher also supports the system property gate.class.path to specify additional classpath entries that should be added to the classloader that is used to load GATE classes. This is expected to be in the normal “classpath” format, i.e. a list of directory or JAR file paths separated by semicolons on Windows and colons on other platforms. The standard Java 6 shorthand of /path/to/directory/*² to include all .jar files from a given directory is also supported. As an alternative to this system property, the environment variable GATE_CLASSPATH can be used, but the environment variable is only read if the system property is not set.

./bin/gate.sh -Dgate.class.path=/shared/lib/myclasses.jar

2.4 Changing GATE’s launch configuration [#]

With effect from build 4723 (13 November 2013), all the JVM and GATE launch options can be set in the gate.l4j.ini file on all platforms, as well as by using options to the gate.sh command.

The gate.l4j.ini file supplied by default with GATE simply sets two standard JVM memory options:

-Xmx specifies the maximum heap size in megabytes (m) or gigabytes (g), and -Xms specifies the initial size. Other parameters of interest are -XX:MaxPermSize=128m for the "permanent generation", which you may wish to specify if you are getting OutOfMemoryErrors that say "PermGen space".

Note that the format consists of one option per line. All the properties listed in Section 2.3 can be configured here by prefixing them with -D, e.g., -Dgate.user.config=path/to/other-gate.xml.

Proxy configuration (see Section 23.17.2) can now be set in this file by adding these lines and editing them as needed for your configuration.

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

• whether to save settings on exit;
• whether to save session on exit;
• what fonts GATE Developer should use;
• plugins to load at start;
• colours of the annotations;
• locations of files for the file chooser;
• and a lot of other GUI related options;

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

• the site-wide level, which by default is located the gate.xml file in top level directory of the GATE installation (i.e. the GATE home. This location can be overridden by the Java system property gate.site.config;
• the user level, which lives in the user’s HOME directory on UNIX or their profile directory on Windows (note that parts of this file are overwritten when saving user settings). The default location for this file can be overridden by the Java system property gate.user.config.

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.6 Building GATE [#]

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

Prerequisites:

• A conforming Java environment as above.
• A copy of the GATE sources and the build scripts – either the SRC distribution package from the nightly snapshots or a copy of the code obtained through Subversion (see Section 2.2.3).
• A working installation of Apache ANT version 1.8.1 or newer. You will need to add an environment variable named ANT_HOME pointing to your ANT installation, and add ANT_HOME/bin to your PATH. It is advisable that you also set your JAVA_HOME environment variable to point to the top-level directory of your Java installation.
• An appreciation of natural beauty.

To build gate, cd to gate and:

1. Type:
   ant
2. [optional] To test the system:
   ant test
   
3. [optional] To make the Javadoc documentation:
   ant doc
   
4. You can also run GATE Developer using Ant, by typing:
   ant run
5. To see a full list of options type: 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 Eclipse (the required .project file and other metadata are included with the sources), 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.6.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:

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 or downloaded using the GATE Developer plugin manager as appropriate.

Nightly snapshot builds of gate-core are available from our own Maven repository at http://repo.gate.ac.uk/content/groups/public.

2.7 Uninstalling GATE [#]

If you have used the installer, run:

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.8 Troubleshooting [#]

See the FAQ on the GATE Wiki for frequent questions about running and using GATE.