Repository navigation
Expand file tree
/
Copy pathgettingstarted.tex
More file actions
397 lines (334 loc) · 18.2 KB
/
Copy pathgettingstarted.tex
File metadata and controls
397 lines (334 loc) · 18.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapt[chap:gettingstarted]{Installing and Running GATE}
\markboth{Installing and Running GATE}{Installing and Running GATE}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\sect[sec:gettingstarted:download]{Downloading GATE}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
To download GATE point your web browser at
\htlinkplain{http://gate.ac.uk/download/}.
%You should next read the section \ref{sec:howto:install} to install and run
%GATE Developer.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\sect[sec:gettingstarted:install]{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
\htlink{https://adoptopenjdk.net/}{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.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsect[sec:gettingstarted:easy]{The Easy Way}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The easy way to install is to use the installer
(created using the excellent \htlink{http://izpack.org/}{IzPack}).
\htlink{http://gate.ac.uk/download/}{Download the installer} (\verb!.exe! for
Windows, \verb!.jar! for other platforms) and follow the instructions it gives
you. Once the installation is complete, you can start GATE Developer using
\verb|gate.exe| (Windows) or \verb|GATE.app| (Mac) in the top-level
installation directory, on Linux and other platforms use \verb|gate.sh|
in the \texttt{bin} directory (see section~\ref{sec:gettingstarted:runonlinux}).
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsect[sec:gettingstarted:hard]{The Hard Way (1)}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{itemize}
\item
Download and unpack the ZIP distribution, creating a directory containing jar
files and scripts.
\item To run GATE Developer:
\begin{itemize}
\item on Windows, use the the `\verb!gate.exe!' file;
\item on UNIX/Linux use `\verb!bin/gate.sh!'.
\item on Mac use `\verb!GATE.app!' -- if running from a terminal you can keep
GATE in the foreground using \verb!GATE.app/Contents/MacOS/GATE! or
\verb!bin/gate.sh!
\end{itemize}
\item
To embed GATE as a library (GATE Embedded), put the JAR files in the
{\tt 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
\verb!uk.ac.gate! and artifact ID \verb!gate-core! (see
section~\ref{sec:gettingstarted:maven}).
\end{itemize}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsect[sec:gettingstarted:git]{The Hard Way (2): Git}\label{sec:gettingstarted:svn}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The GATE code is maintained in a set of repositories on
\htlink{https://github.com/GateNLP}{GitHub}.
The main repository for GATE Developer and Embedded is \verb!gate-core!, and
each plugin has its own repository (typically with a name beginning
\verb!gateplugin-!).
All the modules (\verb!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 \verb!mvn install!
See section~\ref{sec:gettingstarted:build} for more details.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsect[sec:gettingstarted:runonlinux]{Running GATE Developer on Unix/Linux}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
The script \verb|gate.sh| in the directory \verb|bin| of your installation
(or \verb!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 \verb|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 \verb|gate.sh| is invoked without parameters, GATE Developer will use the
files \verb|~/.gate.xml| and \verb|~/.gate.session| to store session and
configuration data. Alternately you can run \verb|gate.sh| with the
following parameters:
\begin{description}
\item[-h] show usage information
\item[-ld] create or use the files \texttt{.gate.session} and
\texttt{.gate.xml} in the current directory as the session and
configuration files. If option \texttt{-dc }\emph{DIR} occurs before this option,
the file \texttt{.gate.session} is created from \emph{DIR}\texttt{/default.session}
if it does not already exist and the file \texttt{.gate.xml} is created
from \emph{DIR}\texttt{/default.xml} if it does not already exist.
\item[-ln \emph{NAME}] create or use \emph{NAME}\texttt{.session} and
\emph{NAME}\texttt{.xml} in the current directory as the session and
configuration files. If option \texttt{-dc DIR} occurs before this option,
the file \emph{NAME}\texttt{.session} is created from \emph{DIR}\texttt{/default.session}
if it does not already exist and the file \emph{DIR}\texttt{.xml} is created
from \emph{DIR}\texttt{/default.xml} if it does not already exist.
\item[-ll \emph{FILE}] use the file specified to configure the logback logger of Gate Developer.
Note that if this is not an absolute path and the name is identical to \texttt{logback.xml}
then the default file on the classpath, \verb|${GATE_HOME}/bin/logback.xml| is is still used.
\item[-rh \emph{LOCATION}] set the resources home directory to the \emph{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~\ref{sec:developer:savestate}).
This is equivalent to setting the property \texttt{gate.user.resourceshome} to
this location.
\item[-d \emph{URL}] loads the CREOLE plugin at the given URL during the
start-up process.
\item[-i \emph{FILE}] uses the specified file as the site configuration.
\item[-dc \emph{DIR}] copy \texttt{default.xml} and/or \texttt{default.session}
from the directory \emph{DIR} when creating a new config or session file. This option works
only together with either the \texttt{-ln}, \texttt{-ll} or \texttt{-tmp} option
and must occur before \texttt{-ln}, \texttt{-ll} or \texttt{-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.
\item[-tmp] creates temporary configuration and session files in the current
directory, optionally copying \texttt{default.xml} and \texttt{default.session}
from the directory specified with a \texttt{-dc DIR} option that occurs
before it. After GATE exits, those session and config files are removed.
\item[\emph{all other parameters}] are passed on to the \texttt{java} command.
This can be used to e.g. set properties using the \texttt{java} option
\texttt{-D}. For example to set the maximum amount of heap memory to be
used when running GATE to 6000M, you can add
\texttt{-Xmx6000m} as a parameter.
In order to change the default encoding used by GATE to \texttt{UTF-8} add
\texttt{-Dfile.encoding=utf-8} as a parameter. To specify
a log4j configuration file add something like \\
\texttt{-Dlog4j.configuration=file:///home/myuser/log4jconfig.properties}.
\end{description}
Running GATE Developer with either the \texttt{-ld} or the \texttt{-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.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\sect[sec:gettingstarted:sysprop]{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:
\begin{description}
\item[gate.site.config] points to the location of the configuration file
containing the site-wide options. If not set no site config will be used.
\item[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.
\item[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.
\item[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.
\item[gate.builtin.creole.dir] is a URL pointing to the location of GATE's
built-in CREOLE directory. This is the location of the {\tt
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 {\tt gate.jar} and should not generally need to be
overridden.
\end{description}
When using GATE Embedded, you can set the values for these properties before
you call {\tt Gate.init()}. Alternatively, you can set the values
programmatically using the static methods {\tt setUserConfigFile()},
etc. before calling
{\tt Gate.init()}. Note that from version 8.5 onwards, the user config file is
ignored by default unless you also call {\tt runInSandbox(false)} before init.
See the Javadoc documentation for details.
To set these properties when running GATE developer see the next section.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\sect[sec:gettingstarted:launchconfig]{Changing GATE's launch configuration}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
JVM options for GATE Developer are supplied in the \texttt{gate.l4j.ini} file
on all platforms. The \texttt{gate.l4j.ini} file supplied by default with GATE
simply sets two standard JVM memory options:
%
\begin{verbatim}
-Xmx1G
-Xms200m
\end{verbatim}
%
\texttt{-Xmx} specifies the maximum heap size in megabytes (\texttt{m}) or
gigabytes (\texttt{g}), and -Xms specifies the initial size.
Note that the format consists of one option per line. All the properties listed
in Section~\ref{sec:gettingstarted:sysprop} can be configured here by prefixing
them with \texttt{-D}, e.g., \texttt{-Dgate.user.config=path/to/other-gate.xml}.
Proxy configuration can be set in this file -- by default GATE uses the
system-wide proxy settings (\verb!-Djava.net.useSystemProxies=true!) but a
specific proxy can be configured by deleting that line and replacing it with
settings such as:
%
\begin{verbatim}
-Dhttp.proxyHost=proxy.example.com
-Dhttp.proxyPort=8080
-Dhttp.nonProxyHosts=*.example.com
\end{verbatim}
Consult the Oracle \emph{Java Networking and Proxies} documentation\footnote{see
\url{https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html}}
for further details of proxy configuration in Java, and see
section~\ref{sec:gettingstarted:sysprop}.
For GATE Embedded, note that Java \emph{does not} automatically use the system
proxy settings by default, you must set \verb!java.net.useSystemProxies=true!
explicitly to enable this.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\sect[sec:gettingstarted:gateconfig]{Configuring GATE}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
When GATE Developer is started, or when {\tt Gate.init()} is called from GATE
Embedded (if you have disabled the default ``sandbox'' mode), GATE loads
various sorts of configuration data stored as XML in a file
generally called something like {\tt gate.xml} or {\tt .gate.xml} in your home
directory. This data holds information such as:
\begin{itemize}
\item whether to save settings on exit;
\item whether to save session on exit;
\item what fonts GATE Developer should use;
\item plugins to load at start;
\item colours of the annotations;
\item locations of files for the file chooser;
\item and a lot of other GUI related options;
%\item where the local Oracle database lives.
\end{itemize}
Configuration data can be set from the GATE Developer GUI via the
`Options' menu then `Configuration'\footnote{On Mac OS X, us the standard
`Preferences' option in the application menu, the same as for native Mac
applications.}. 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 file.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\sect[sec:gettingstarted:build]{Building GATE}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\mbox{ }
Note that you don't need to build GATE unless you're doing development
on the system itself.
{\bf Prerequisites:}
\begin{itemize}
\item
A conforming Java environment as above.
\item
A clone of the relevant Git repository or repositories (see Section~\ref{sec:gettingstarted:git}).
\item
A working installation of \htlink{http://maven.apache.org/}{Apache Maven} version
3.5.2 or newer. It is advisable that you also set your \verb!JAVA_HOME!
environment variable to point to the top-level directory of your Java
installation.
\item
An appreciation of natural beauty.
\end{itemize}
{\bf To build gate-core}, cd to where you cloned {\tt gate-core} and:
\begin{enumerate}
\item
Type: {\tt \newline
mvn install
}
\item
$[$optional$]$ To make the Javadoc documentation:
{\tt \newline
mvn site
}
\end{enumerate}
In order to be able to \emph{run} the GATE Developer you just built, you will
also need to cd into the \verb!distro! folder and run \verb!mvn compile! in
there, in order to create the classpath file that the GATE Developer launcher
uses to find the JARs.
{\bf To build plugins} cd into the plugin you just cloned and run
\verb!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.
{\bf Note} if you are building a version of a plugin that depends on a SNAPSHOT
version of \verb!gate-core! then you will need to add some configuration to
your Maven \verb!settings.xml! file, as described in the \verb!gate-core!
README file.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsect[sec:gettingstarted:maven]{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:
\begin{small}
\begin{verbatim}
<dependency>
<groupId>uk.ac.gate</groupId>
<artifactId>gate-core</artifactId>
<version>8.5</version>
</dependency>
\end{verbatim}
\end{small}
Similarly, with a project that uses Ivy for dependency management:
\begin{small}
\begin{verbatim}
<dependency org="uk.ac.gate" name="gate-core" rev="8.5"/>
\end{verbatim}
\end{small}
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 \verb|http://repo.gate.ac.uk/content/groups/public|.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\sect[sec:gettingstarted:uninstalling]{Uninstalling GATE}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
If you have used the installer, run:
\begin{small}
\begin{verbatim}
java -jar uninstaller.jar
\end{verbatim}
\end{small}
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).
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\sect[sec:gettingstarted:troubleshooting]{Troubleshooting}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
See the \htlink{http://gate.ac.uk/wiki/gate-user-faq.html}{FAQ on the GATE
Wiki} for frequent questions about running and using GATE.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%