GATE.ac.uk - releases/gate-9.0.1/tao/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 8 or later, including Linux, Mac OS X and Windows platforms. We don’t run tests on other platforms, but have had reports of successful installs elsewhere.

We recommend using OpenJDK 1.8 (or higher). This is widely available from GNU/Linux package repositories. The AdoptOpenJDK website provides packages for various operating systems, and is particularly suitable for Windows users. Mac users should install the JDK (not just the JRE).

Note that wherever possible you should install the 64 bit version of Java as 32 bit versions can have issues with the amount of memory available for GATE to use.

2.2.1 The Easy Way [#]

The easy way to install is to use the installer (created using the excellent IzPack). Download the installer (.exe for Windows, .jar for other platforms) 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 and unpack the ZIP distribution, creating a directory containing jar ﬁles and scripts.
To run GATE Developer:
- on Windows, use the the ‘gate.exe’ ﬁle;
- on UNIX/Linux use ‘bin/gate.sh’.
- on Mac use ‘GATE.app’ – if running from a terminal you can keep GATE in the foreground using GATE.app/Contents/MacOS/GATE or bin/gate.sh
To embed GATE as a library (GATE Embedded), put the JAR ﬁles in the lib folder onto your application’s classpath. Alternatively you can use a dependency manager to download GATE and its dependencies from the Central Repository by declaring a dependency on the appropriate version of group ID uk.ac.gate and artifact ID gate-core (see section 2.6.1).

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

The GATE code is maintained in a set of repositories on GitHub. The main repository for GATE Developer and Embedded is gate-core, and each plugin has its own repository (typically with a name beginning gateplugin-).

All the modules (gate-core and the plugins) are built using Apache Maven version 3.5.2 or later. Clone the appropriate repository, checkout the relevant branch (“master” is the latest snapshot version), and build the code using mvn install

See section 2.6 for more details.

2.2.4 Running GATE Developer on Unix/Linux [#]

The script gate.sh in the directory bin of your installation (or distro/bin if you are building from source) 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 ﬁles ~/.gate.xml and ~/.gate.session to store session and conﬁguration data. Alternately you can run gate.sh with the following parameters:

-h: show usage information
-ld: create or use the ﬁles .gate.session and .gate.xml in the current directory as the session and conﬁguration ﬁles. If option -dc DIR occurs before this option, the ﬁle .gate.session is created from DIR/default.session if it does not already exist and the ﬁle .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 conﬁguration ﬁles. If option -dc DIR occurs before this option, the ﬁle NAME.session is created from DIR/default.session if it does not already exist and the ﬁle DIR.xml is created from DIR/default.xml if it does not already exist.
-ll FILE: use the ﬁle speciﬁed to conﬁgure the logback logger of Gate Developer. Note that if this is not an absolute path and the name is identical to logback.xml then the default ﬁle on the classpath, ${GATE_HOME}/bin/logback.xml is is still used.
-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 ﬁle (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 speciﬁed ﬁle as the site conﬁguration.
-dc DIR: copy default.xml and/or default.session from the directory DIR when creating a new conﬁg or session ﬁle. This option works only together with either the -ln, -ll or -tmp option and must occur before -ln, -ll or -tmp. An existing conﬁg or session ﬁle is used, but if it does not exist, the ﬁle from the given directory is copied to create the ﬁle instead of using an empty/default ﬁle.
-tmp: creates temporary conﬁguration and session ﬁles in the current directory, optionally copying default.xml and default.session from the directory speciﬁed with a -dc DIR option that occurs before it. After GATE exits, those session and conﬁg ﬁles 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 conﬁguration ﬁle add something like
-Dlog4j.configuration=file:///home/myuser/log4jconfig.properties.

Running GATE Developer with either the -ld or the -ln option from diﬀerent directories is useful to keep several projects separate and can be used to run multiple instances of GATE Developer (or even diﬀerent versions of GATE Developer) in succession or even simultanously without the conﬁguration ﬁles 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 ﬁnd its conﬁguration ﬁles.

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

gate.site.conﬁg: points to the location of the conﬁguration ﬁle containing the site-wide options. If not set no site conﬁg will be used.
gate.user.conﬁg: points to the ﬁle containing the user’s options. If not speciﬁed, or if the speciﬁed ﬁle 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 ﬁle containing the user’s saved session. If not speciﬁed, 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 ﬁle if it exists, and when exiting GATE Developer the session is saved to this ﬁle (unless the user has disabled ‘save session on exit’ in the conﬁguration dialog). The session is not used when using GATE Embedded.
gate.user.ﬁlechooser.defaultdir: sets the default directory to be shown in the ﬁle chooser of GATE Developer to the speciﬁed directory instead of the user’s operating-system speciﬁc default directory.
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 ﬁle that deﬁnes 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 setUserConfigFile(), etc. before calling Gate.init(). Note that from version 8.5 onwards, the user conﬁg ﬁle is ignored by default unless you also call runInSandbox(false) before init. See the Javadoc documentation for details.

To set these properties when running GATE developer see the next section.

2.4 Changing GATE’s launch conﬁguration [#]

JVM options for GATE Developer are supplied in the gate.l4j.ini ﬁle on all platforms. The gate.l4j.ini ﬁle supplied by default with GATE simply sets two standard JVM memory options:

-Xmx1G
-Xms200m

-Xmx speciﬁes the maximum heap size in megabytes (m) or gigabytes (g), and -Xms speciﬁes the initial size.

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

Proxy conﬁguration can be set in this ﬁle – by default GATE uses the system-wide proxy settings (-Djava.net.useSystemProxies=true) but a speciﬁc proxy can be conﬁgured by deleting that line and replacing it with settings such as:

-Dhttp.proxyHost=proxy.example.com
-Dhttp.proxyPort=8080
-Dhttp.nonProxyHosts=*.example.com

Consult the Oracle Java Networking and Proxies documentation¹ for further details of proxy conﬁguration in Java, and see section 2.3.

For GATE Embedded, note that Java does not automatically use the system proxy settings by default, you must set java.net.useSystemProxies=true explicitly to enable this.

2.5 Conﬁguring GATE [#]

When GATE Developer is started, or when Gate.init() is called from GATE Embedded (if you have disabled the default “sandbox” mode), GATE loads various sorts of conﬁguration data stored as XML in a ﬁle generally called something like gate.xml or .gate.xml in your home directory. 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 ﬁles for the ﬁle chooser;
and a lot of other GUI related options;

Conﬁguration data can be set from the GATE Developer GUI via the ‘Options’ menu then ‘Conﬁguration’². 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. These options are all stored in the user’s .gate.xml ﬁle.

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 clone of the relevant Git repository or repositories (see Section 2.2.3).
A working installation of Apache Maven version 3.5.2 or newer. 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-core, cd to where you cloned gate-core and:

Type:
mvn install
[optional] To make the Javadoc documentation:
mvn site

In order to be able to run the GATE Developer you just built, you will also need to cd into the distro folder and run mvn compile in there, in order to create the classpath ﬁle that the GATE Developer launcher uses to ﬁnd the JARs.

To build plugins cd into the plugin you just cloned and run mvn install. This will build the plugin and place it in your local Maven cache, from where GATE Developer will be able to resolve it at runtime.

Note if you are building a version of a plugin that depends on a SNAPSHOT version of gate-core then you will need to add some conﬁguration to your Maven settings.xml ﬁle, as described in the gate-core README ﬁle.

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:

You do not need to do anything to allow GATE to access its plugins, it will fetch them at runtime from the internet when they are loaded.

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:

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 ﬁles GATE creates in your home directory (.gate.xml and .gate.session).