<chapter id="invocation">

<title>Invocation</title>

<indexterm>
<primary>invocation</primary>
<secondary>GoGui</secondary>
</indexterm>

<section>
<title>General</title>
<para>
<application>GoGui</application> can be invoked with the command:
<programlisting>
<userinput>java -jar gogui.jar [options] [file]</userinput></programlisting>
using the file <filename>gogui.jar</filename> in the
<filename>lib</filename> subdirectory.
</para>
<para>
The command line for executing the actual Go program can be given
with the <option>-program</option> option.
Otherwise, GoGui will start with the Go program attached in the previous
session, or without Go program if none was attached.
You can attach and detach a Go program at any time by using the
<guimenuitem>Attach</guimenuitem>, <guimenuitem>New Program</guimenuitem> and
<guimenuitem>Detach</guimenuitem> menu items from the
<guimenu>Program</guimenu> menu.
</para>
<para>
See <xref linkend="reference-gogui"/> for a complete listing of the possible
command line options to <userinput>gogui</userinput>.
</para>
<para><!-- Empty paragraph to enforce space in JEditorPane --></para>
</section>

<section>
<title><application>GoGui</application> on Unix</title>
<para>
<indexterm>
<primary>invocation</primary>
<secondary>Unix</secondary>
</indexterm>
For Unix systems, there are launcher scripts in the
<filename class="directory">bin</filename> directory.
<indexterm>
<primary><envar>GOGUI_JAVA_HOME</envar></primary>
</indexterm>
The launcher scripts respect the environment variable
<envar>GOGUI_JAVA_HOME</envar>, if defined, and look for the jar files
in <filename class="directory">../lib</filename>
relative to the <filename class="directory">bin</filename> directory.
You can add the <filename>bin</filename> directory of GoGui to your
<envar>PATH</envar> environment variable.
<indexterm>
<primary><envar>PATH</envar></primary>
</indexterm>
The invocation is then simply:
<programlisting>
<userinput>gogui [options] [file]</userinput></programlisting>
To register <application>GoGui</application> as a handler
for <ulink url="http://www.red-bean.com/sgf/"><acronym>SGF</acronym></ulink>
files, you can configure a new file association for the type
<userinput>application/x-go-sgf</userinput> and the file name pattern
<userinput>*.sgf</userinput> to execute
<userinput>gogui</userinput>.
<indexterm>
<primary>SGF</primary>
<secondary>register GoGui as a handler</secondary>
</indexterm>
</para>
<para>
For Linux systems, there is a shell script <filename>install.sh</filename> in
the main directory, which will install GoGui on the system, including the
creation of desktop menu entries, entries in the help system, and the
registration as a handler for SGF files. This script needs to be run as root.
</para>
<para><!-- Empty paragraph to enforce space in JEditorPane --></para>
</section>

<section>
<title><application>GoGui</application> on Windows</title>
<para>
<indexterm>
<primary>invocation</primary>
<secondary>Windows</secondary>
</indexterm>
On Windows, the Java installation registers Java as a
handler for jar-files and it is possible to launch GoGui by
double-clicking on <filename>gogui.jar</filename> from a file browser.
You can also drag a link to this file to the desktop.
</para>
<para><!-- Empty paragraph to enforce space in JEditorPane --></para>
</section>

<section>
<title><application>GoGui</application> on Mac OS X</title>
<para>
<indexterm>
<primary>invocation</primary>
<secondary>Mac OS X</secondary>
</indexterm>
On Mac OS X, GoGui can be invoked using the UNIX launcher scripts in
the <filename>bin</filename> directory.
It is also possible to create an application bundle for Mac OS X by typing
<programlisting>
<userinput>ant gogui.app</userinput></programlisting>
in the main directory. The resulting application bundle will be in
<filename>build/GoGui.app</filename>. This requires that the
<ulink url="http://ant.apache.org">Ant</ulink> build system is installed on
the system.
</para>
<para><!-- Empty paragraph to enforce space in JEditorPane --></para>
</section>

</chapter>
