\chapter{Wrapping Objective-C Libraries}

In this chapter we are going to learn how to use JIGS to expose an
existing Objective-C library to Java.  Technically, we call this
procedure {\sl wrapping} the library.

\subsection{Historical Notes}
Building java wrappers for an objective-C library in JIGS used to be
strongly coupled with building the library itself.  Starting with JIGS
1.4.0, the wrapping mechanism has been redesigned to be totally
independent from the original library: building the objective-C
library and building the java wrappers for it are now totally
independent processes.  You can now build the objective-C library,
install it, and only later on create java wrappers for the library.
You can also easily wrap objective-c libraries which you got in binary
form (as soon as you have the header files from them).

You can still build wrappers in the old way by including
\begin{verbatim}
old-java-wrapper.make
\end{verbatim}
rather than \texttt{java-wrapper.make}.  But please - whenever
possible - use the new - much better - way, and please update any old
wrapper to the new design.  In this manual, we only document the new
design.  The old backward compatibility code will be dropped at some
point in the future.

\section{Compiling ready-to-use wrappers}

We start by reviewing the simplest case: you have a library installed
on your system, and you download the wrappers for that library.  The
wrappers actually consist of a \texttt{GNUmakefile}, a \texttt{.jigs}
file, and possibly a few other support files.  These files contain all
the instructions JIGS needs to wrap your library.  You can try the
discussion out by using any example in the
\texttt{Tools/WrapCreator/Examples/} directory (which are slightly
more complicated, as the library and the wrapper for the library are
kept and compiled in the same directory at the same time).

\subsection{Creating and compiling the wrappers}

When you type \texttt{make}, JIGS will automatically create a
directory called
\begin{verbatim}
JavaWrapper
\end{verbatim}
(or \texttt{JavaWrapper\_debug} if you are compiling with debug
enabled), and generate inside this directory source code for the
wrappers.  It will then enter into this directory, and compile the
wrapper source code (which has just been generated).  If you want more
details about the wrapping process (which classes and which methods
are being wrapped), you can use
\begin{verbatim}
make verbose=yes
\end{verbatim}

To access your library from Java you need to have compiled and
installed both the original library and the wrappers.

Typing \texttt{make install} will install the wrappers, so you should
be ready to use them from Java.

\subsection{Structure of the wrappers}\label{wrapper-structure}

It's not strictly necessary for you to know the structure of the
wrappers to create or use them, so you may safely skip this section.

In the following discussion, we consider wrappers for an imaginary
library called \texttt{libexample.so}.

The wrappers for the library are composed of two parts: a set of Java
classes, and a native Objective-C library, called
\texttt{libexample.A.so} in the example.  This is called after the 
original library (\texttt{libexample.so}) with a \texttt{.A} appended
to the name.

If you go into the \texttt{JavaWrapper} directory, you can inspect
these parts yourself.  There are two main subdirectories in the
\texttt{JavaWrapper} directory, the \texttt{Java} and the
\texttt{Objc} subdirectories.

\subsubsection{The Java subdirectory}

The \texttt{Java} subdirectory contains the Java classes.  All methods
which are not explicitly marked as \texttt{public} in these classes
are to be considered internal to the JIGS engine and you should not
access them directly (you probably will not be allowed to anyway).

All these classes contain a static initializer of the following form:
\begin{verbatim}
 static
  {
    JIGS.loadLibrary ("example.A");
  }
\end{verbatim}
This will load the native library \texttt{libexample.A.so} as soon as
the first Java class is accessed (\texttt{libexample.A.so} will
implicitly load \texttt{libexample.so}).

Then, most methods are \texttt{native}, as in the following example: 
\begin{verbatim}
 /**
   * Wraps the Objective-C method
   * <B>start</B>
   */
  public native void start ();
\end{verbatim}

The implementation of the Java methods marked as \texttt{native} will
be found by the JVM inside the native library \texttt{libexample.A.so}
(see next section).

As it is shown in the example, each class and public method has a tiny
minimal javadoc description.  When the java classes are compiled,
quick reference documentation for the classes will be generated from
these comments by using javadoc, and put into the subdirectory
\texttt{Reference}.  This documentation is minimal, and basically
consists in the list of all Java wrapper classes and methods which
were compiled, and for each one, a comment explaining which
Objective-C class or method it wraps.  While minimal, this
documentation can be quite useful for someone already knowing the
Objective-C API (or having the Objective-C documentation to refer to)
and wanting to use the library from Java.

\subsubsection{The Objc subdirectory}

The \texttt{Objc} subdirectory contains the Objective-C library 
\texttt{libexample.A.so}, which provides to Java the implementation 
of all the \texttt{native} methods in the Java classes.  The
implementation of these methods will call the corresponding methods in
the (pure Objective-C) \texttt{libexample.so} library, by using the
JIGS core engine to catch exceptions, convert arguments and return
types, etc.

\section{The GNUmakefile for java wrappers}
We are now going to learn how to write the \texttt{GNUmakefile} and
the other support files to have JIGS wrap an Objective-C library.  We
begin with the \texttt{GNUmakefile}.  Here is a simple example:

\begin{verbatim}
include $(GNUSTEP_MAKEFILES)/common.make

JAVA_WRAPPER_NAME = Name

include $(GNUSTEP_MAKEFILES)/java-wrapper.make
\end{verbatim}

You need to create a new directory, and put this \texttt{GNUmakefile}
into it.  The \texttt{JAVA\_WRAPPER\_NAME} must be the same as the name
of the library you want to wrap, after removing the \texttt{lib} in
front of the library name.  In the example, we are wrapping a library
called \texttt{libName}.

To correctly generate the java wrappers, you will actually need to
instruct JIGS about what classes and methods you want exposed, and
how.  This will be discussed in detail in the following sections.

As a last comment, you may want to stop JIGS from automatically trying
to compile the java wrapper after creating them, and from installing
it automatically after installing your library.  I don't see why this
could be useful except if you are debugging JIGS itself, anyway if you
ever need this, just add
\begin{verbatim}
BUILD_JAVA_WRAPPER_AUTOMATICALLY=no
\end{verbatim}
to your library's GNUmakefile.  Then - JIGS will still create the java
wrapper source, but will not automatically compile it.  When you want
to compile it, you have to \texttt{cd} into the java wrapper
directory, and type \texttt{make} there.  Similarly, to install the
java wrappers \texttt{cd} into the java wrapper directory, and type
\texttt{make install} (you probably need to be root) - JIGS will not
install them automatically when you install the library.

\section{Specifying the main library header}

\section{Library header name}
JIGS automatically parses your library headers to determine the exact
method declarations of the methods you want to expose.

You need to specify a single header file for your library which
includes all the header files for your library.  JIGS tries to
determine it in the following way: it takes the
\texttt{JAVA\_WRAPPER\_NAME}, and adds \texttt{.h} to it.

For example, if the GNUmakefile for your java wrapper is the following:
\begin{verbatim}
include $(GNUSTEP_MAKEFILES)/common.make

JAVA_WRAPPER_NAME = Game

include $(GNUSTEP_MAKEFILES)/java-wrapper.make
\end{verbatim}
Then your library name is \texttt{libGame}.  The header file JIGS will
try to parse by default is \texttt{Game.h}.  This header file should
include all the header files which might be need to compile code
against your library.

Often, you want to set explicitly the header file name.  You can do
that simply by setting the 
\begin{verbatim}
XXX_HEADER_FILES
\end{verbatim}
variable (where \texttt{XXX} is to be replaced with your
\texttt{JAVA\_WRAPPER\_NAME}).  For example, when wrapping the
gnustep-base library, we have in the \texttt{GNUmakefile}
\begin{verbatim}
include $(GNUSTEP_MAKEFILES)/common.make

JAVA_WRAPPER_NAME = gnustep-base
gnustep-base_HEADER_FILES = Foundation/Foundation.h

include $(GNUSTEP_MAKEFILES)/java-wrapper.make
\end{verbatim}
Please note that it should be a single header; you can't use multiple
headers, despite the variable is called \texttt{HEADER\_FILES}.  The
header file name should be in the full form you use for including it
into C source code, such as in \texttt{Foundation/Foundation.h}.  It
must be in this form because it {\bf will} end up in an Objective-C
source file.

\section{Library header location}
When JIGS has determined the name of the header file to parse, it will
need to find it.  Usually, JIGS will look into the current directory,
and then in the standard GNUstep header directories, that is, it will
look (in the order) into:
\begin{verbatim}
./
$(GNUSTEP_USER_ROOT)/Headers/
$(GNUSTEP_LOCAL_ROOT)/Headers/
$(GNUSTEP_NETWORK_ROOT)/Headers/
$(GNUSTEP_SYSTEM_ROOT)/Headers/
\end{verbatim}
For example, if you are using
\begin{verbatim}
include $(GNUSTEP_MAKEFILES)/common.make

JAVA_WRAPPER_NAME = Game
Game_HEADER_FILES = Game/Game.h

include $(GNUSTEP_MAKEFILES)/java-wrapper.make
\end{verbatim}
then JIGS will look for the following files, in the order:
\begin{verbatim}
./Game/Game.h
$(GNUSTEP_USER_ROOT)/Headers/Game/Game.h
$(GNUSTEP_LOCAL_ROOT)/Headers/Game/Game.h
$(GNUSTEP_NETWORK_ROOT)/Headers/Game/Game.h
$(GNUSTEP_SYSTEM_ROOT)/Headers/Game/Game.h
\end{verbatim}
and pick up the first it finds.

In some cases, that is not enough - for example, you might not yet
have installed your library.  In this case, you need to help JIGS by
telling it where it might find your header, by setting the
\texttt{XXX\_HEADER\_FILES\_DIR} variable (again, replace \texttt{XXX}
with your java wrapper name).  It might be a relative path (relative
to the current directory), such as in
\begin{verbatim}
Game_HEADER_FILES_DIR = ../GameLibrary/
\end{verbatim}
or an absolute one, as in 
\begin{verbatim}
Game_HEADER_FILES_DIR = /opt/games/Source/GameLibrary/
\end{verbatim}

\subsection{Special header flags}
If you need any other special flags for reading the header, use the 
\texttt{XXX\_ADDITIONAL\_CPP\_FLAGS} variable, as in
\begin{verbatim}
Game_ADDITIONAL_CPP_FLAGS = -I/opt/games/Source/Support/Headers
\end{verbatim}
Basically, you should specify all flags which you would normally use
to build a library or a bundle or an executable linked against the
library you want to wrap.

\section{The wrapper directory}
JIGS generates full code for the java wrappers into a specific
directory, which we call the wrapper directory.  By default, this
directory is called \texttt{JavaWrapper} (or
\texttt{JavaWrapper\_debug} if you are compiling with debugging
enabled), but you can change the name of the directory by simply
setting the \texttt{WRAPPER\_DIR\_NAME} variable in your
\texttt{GNUmakefile}.  This is not very common.

To determine if the wrappers are to be rebuilt or not, JIGS keeps a
stamp file in the wrapper directory.

Everything which is inside the wrapper directory is automatically
generated -- this means that
\begin{enumerate}
\item you can always remove the wrapper directory without loosing anything, 
since you can always regenerate the wrappers;
\item you should not edit or modify directly the contents of the wrapper 
directory, because when the wrappers are recreated, the content of the 
directory is destroyed.
\end{enumerate}

\section{The .jigs File}

\subsection{Determining which .jigs file to read}
After running the preprocessor on the header file, JIGS will read a
configuration file to know which wrappers to generate, and how.  By
default, the file is called \texttt{\$(JAVA\_WRAPPER\_NAME).jigs}.  In
the case described before, this file would be called
\texttt{Game.jigs}.  You can override this choice by setting the
\texttt{JIGS\_FILE} variable in your \texttt{GNUmakefile}, but you
shouldn't usually need to.

\subsection{Overview of the .jigs file}
The \texttt{.jigs} file is the main file from which you can control
the way the wrapping is done.  In this file, you need to list all the
classes of your library which you want to expose, and for each class,
which methods.  The \texttt{.jigs} file is in a format called 
\emph{property list} -- please refer to the GNUstep Base Library tutorials 
and documentation if you need more help on property lists.  The
\texttt{.jigs} file is a big dictionary.  Each entry in the dictionary 
is to be thought of as of a different section; the key to the section
is the section name, the value is an array or a dictionary containing
the information referring to that section.  For example, we have the
\texttt{classes} section (containing an array of classes to be wrapped), the
\texttt{types} section (containing a dictionary of mapping of custom C 
types to already known C types), the \texttt{method name mapping}
section (containing a dictionary of mappings from objective-C method
names to Java method names, to be used for the whole library).  Here
is an example:
\begin{verbatim}
{
  classes = (
    {
      "java name" = "gnu.gnustep.GreatGameLibrary.GGLSprite";
      "objective-c name" = GGLSprite;
      "instance methods" = (speed, "setSpeed:");
      initializers = (init);
     }
   );
  
  "method name mapping" = {
    speed = getSpeed;
  };
}
\end{verbatim}

In this example, we only have the \texttt{classes} and \texttt{method
name mapping} sections.  We now examine in detail each section of the
\texttt{.jigs} file.

\subsection{The Classes section}
Probably the most important section in the file is the
\texttt{classes} section, where you list all the classes you want to
be wrapped, and how.  This section is an array, each entry in the
array being a different class to be wrapped.  Here is an example 
of this section:
\begin{verbatim}
classes = (
  {
    "java name" = "gnu.gnustep.GreatGameLibrary.GGLScore";
    "objective-c name" = "GGLScore";

    "initializers" = ("init"); 
    "instance methods" = ("setPoints:", "points");
    "class methods" = ("bestScore", "bestTenScores");
  },

  {
    "java name" = "gnu.gnustep.GreatGameLibrary.GGLPlayer";
    "objective-c name" = "GGLPlayer";

    "class methods" = ("computerPlayer");
    "instance methods" = ("name", "score", "addPoints:");
    "initializers" = ("init", "initWithName:");                 
  }
);
\end{verbatim}
In this example, we want to generate wrappers for two classes:
\texttt{GGLScore} and \texttt{GGLPlayer}.  Information about each 
class is represented by a dictionary.  Any entry in this dictionary
(except the `\texttt{java name}' entry) can be omitted, in which case
a default value will be used.  We briefly now review the use of each
entry.

\subsubsection{java name}
This is a string -- the name that is to be used in Java for the class
you want to wrap.  This is the only compulsory entry for each class.
You need to specify the full Java name of the class, such as
\begin{verbatim}
"java name" = "gnu.gnustep.base.NSArray";
\end{verbatim}
You can decide to use a different name in Java than the name the class
has in Objective-C.  It's generally better to avoid this, but it
should work fine if you ever need to do it.  

\subsubsection{objective-c name}
This is a string -- the Objective-C name of the class you want to
wrap, such as 
\begin{verbatim}
"objective-c name" = "NSArray";
\end{verbatim}
If this entry is not present, it is guessed by taking the last part of
\texttt{java name}.  For example, if \texttt{java name} is 
\texttt{gnu.gnustep.base.NSArray}, then JIGS will use \texttt{NSArray} 
as Objective-C name if you don't specify an Objective-C name.

\subsubsection{initializers}
This is an array -- the list of \texttt{init} methods you want to
wrap, such as
\begin{verbatim}
"initializers" = ("init", "initWithName:", "initWithArray:", "initWithName:array:");
\end{verbatim}
Each method in the \texttt{initializers} list will be exposed as a
constructor.  The Objective-C name of each initializer is discarded 
in Java, so you must make sure that these methods have all different 
signatures.

\subsubsection{class methods}
This is an array -- the list of class methods you want to wrap, such as 
\begin{verbatim}
"class methods" = (
  "contentRectForFrameRect:styleMask:", 
  "frameRectForContentRect:styleMask:", 
  "minFrameWidthWithTitle:styleMask:",
  "removeFrameUsingName:");
\end{verbatim}
Each of these methods is exposed as a static method in Java.  Unless
you use a method mapping (explained below), the Java name of each of
these methods will be obtained by removing from the Objective-C name
everything which comes after the first `\texttt{:}'.  For example, the
methods in the example would be wrapped as:
\begin{verbatim}
public static native NSRect contentRectForFrameRect (NSRect arg0, long arg1);
public static native NSRect frameRectForContentRect (NSRect arg0, long arg1);
public static native NSRect minFrameWidthWithTitle (String arg0, long arg1);
public static native void removeFrameUsingName (String arg0);
\end{verbatim}

Please make sure you do not include any methods of the \texttt{new}
family in the \texttt{class methods} list.  \texttt{new} methods can not
be wrapped because they allocate and return non-autoreleased objects
-- it should not be a problem anyway, because if you need that
constructor in Java, you can get it by simply wrapping the
corresponding \texttt{init} method.

\subsubsection{instance methods}
This is an array -- the list of instance methods you want to wrap,
such as 
\begin{verbatim}
"instance methods" = (
  "arguments",
  "environment",
  "hostName",
  "processName",
  "globallyUniqueString",
  "setProcessName:");
\end{verbatim}
Each of these methods is exposed as an instance method in Java.  The
Java names for these methods are obtained in the same way as for class
methods.

Make sure you do not include any method of the \texttt{copy} and 
\texttt{mutableCopy} family in this list.  Methods of these families 
can not be wrapped like the other ones because they return
newly-created non-autoreleased objects.  It is possible that in the
future JIGS could provide a way to expose these methods; at present,
you can not expose them -- except the ones exposed by \texttt{NSObject}: 
\texttt{NSObject} exposes \texttt{copy} (as \texttt{clone}) and 
\texttt{mutableCopy} (as \texttt{mutableClone}) to Java, so if your 
Objective-C class implements \texttt{copy} and \texttt{mutableCopy},
they will automatically be made available to Java by the
\texttt{NSObject} wrapper without any need to do anything.

\subsubsection{method declarations}
This is an array -- a list of explicit method declarations which you
can use to override the declarations found by the wrapper tool in the
header file if you think the wrapper tool did not use the correct
declaration -- this usually happens only if in your library the same
method is declared in different classes or protocols with different
arguments or return types (this case is infrequent, but it happens
sometime) -- in this case the wrapper tool is likely not to pick up
the correct declaration, because it is designed for the standard case,
when the same signature is used across all classes.  By adding the
correct declaration for your class in the \texttt{method declaration}
section, you can make sure that the declaration you want is used.  For
example, in the gui library the following explicit declaration is used
when wrapping
\texttt{NSBox}:
\begin{verbatim}
"method declarations" = (
   "- (void) setContentView: (NSView*)aView");
\end{verbatim}
This is because \texttt{NSScrollView} uses a conflicting declaration
for this method, taking a \texttt{NSClipView *} argument.

Please note that, while in Objective-C these problems are harmless,
and usually the worst it can happen is that the compiler warns you at
compile time, after you expose your methods to Java these problems
become first-rate problems, because in Java casts are dramatic and
your program can crash if a method expecting a \texttt{NSClipView}
argument receives a generic \texttt{NSView} instead.

\subsubsection{hardcoded constants}
This is an array -- a list of declaration of constants which will be
added as static constants to the Java class, as in the following
example:
\begin{verbatim}
"hardcoded constants" = ("int NotFound = 0x7fffffff");
\end{verbatim}
This \texttt{hardcoded constants} section will generate the following
code in the Java class:
\begin{verbatim}
public static int NotFound = 0x7fffffff;
\end{verbatim}
This example is taken from the wrapping instructions for
\texttt{NSArray}; it allows the Java programmer to access this
constant simply as \texttt{NSArray.NotFound}.  The value of this
constant is of course the value of the C constant \texttt{NSNotFound}
which is returned by many GNUstep Base Library methods when something
is not found.

If your Objective-C library defines some constants, and some methods
which you expose to Java return or accept these constants, you may
want to make these constants available to Java as well by using the
\texttt{hardcoded constants} section.  Enumerations are exposed using 
the \texttt{enumerations} section, as explained in the next
paragraphs.

\subsubsection{enumerations}

Starting from JIGS 1.5.0, enumeration types are automatically
recognized in the header file, and treated by the wrapper tool exactly
as if they were simple \texttt{int}s.  Usually, that is not enough --
you want also to have the enumeration constants available from Java as
static integer constants of some class.  You can use the
\texttt{hardcoded constants} section to manually add them to the
class; this is quite clumsy, because you have to enter all the
enumeration constants manually in the jigs file, and if you change the
enumeration values in the Objective-C code, you have to manually
update the jigs file.

Recent versions of JIGS (1.5.0 and newer) offer a new better option,
in the form of the \texttt{enumerations} section.  For example, the
following line inside a class section
\begin{verbatim}
enumerations = (NSComparisonResult);
\end{verbatim}
will cause the following code to be automatically added to the
generated Java class code:
\begin{verbatim} 
public static int NSOrderedDescending = 1;
public static int NSOrderedSame = 0;
public static int NSOrderedAscending = -1;
\end{verbatim}

Please notice that the wrapper tool has parsed your Objective-C header
file, and extracted the constant values from there automatically!
This means that you don't have to enter the constants in the first
place, and if you ever change the enumeration, the Java wrappers will
be immediately and automatically updated as soon as you recreate them.

\subsubsection{file to include in java code}
This is a string -- a filename (relative to the current directory).
When WrapCreator generates the Java class, it will read the contents
of this file, and add them -- without any change -- inside the Java
class.

For example, to insert a Java method of your own into the generated 
Java wrapper class, you could use the following entry:
\begin{verbatim}
"file to include in java code" = "MyClass.java.add";
\end{verbatim}
Then, you need to put the Java code you want to add into the file
\texttt{MyClass.java.add}.  Here is a trivial example:
\begin{verbatim}
  /**
    * Returns the sum of the arguments.
    */
  public int test (int a, int b)
  {
    return a + b;
  }
\end{verbatim}
This code would be inserted {\em inside} the Java class implementation 
when the Java wrapper is created.

\subsubsection{file to include in preamble java code}
This is a string -- a filename (relative to the current directory).
The only difference with \texttt{file to include in java code}
(described above) is that in this case the code is included {\em
before} the Java class, between the \texttt{import} statements and the
class implementation, rather than {\em inside} the class
implementation.

\subsubsection{file to include in objective-c code}
This is a string -- a filename (relative to the current directory).
When WrapCreator generates the Objective-C code, it will read the
contents of this file, and add them -- without any change -- at the
end of the Objective-C file for that class.  In this way, you can add
arbitrary functions and C or Objective-C code to the wrapper library.

The combination of this feature with the one to include arbitrary java
code into the wrapper allows you to add hand-made wrapped methods to
the java wrapper.  This is a very advanced feature and is not
documented here.

\subsection{Method Name Mapping}
This section is a dictionary -- mapping Objective-C method names 
to Java method names, as in the following example:
\begin{verbatim}
"method name mapping" = {
  "null" = "nullValue";
  "addTimer:forMode:" = "addTimerForMode";
};
\end{verbatim}
Try to avoid method mappings, because they are confusing!  But
sometimes you can't do without, as in the case of \texttt{null} which
can't be exposed with this name to Java because \texttt{null} is a
reserved keyword in Java.  In this case, you use the method mapping.
Please note that JIGS needs to keep a global table of method name
mappings while running in order to map selectors between Java and
Objective-C; for this reason, you need to use the same mappings in all
the classes.

\subsection{Prerequisite Libraries}
Sometimes, the wrappers for your library need the wrappers of some
other GNUstep Objective-C library to work correctly.  For example, you
can't use the wrappers for the GNUstep Gui Library without the
wrappers for the GNUstep Base Library.  If this is the case for your
library, you need to add a \texttt{prerequisite libraries} section,
containing a list of GNUstep libraries whose wrappers you want to be
loaded at run-time when the wrappers for your library are initialized.
For example, in \texttt{gnustep-gui.jigs} there is
\begin{verbatim}
"prerequisite libraries" = ("gnustep-base");
\end{verbatim}
You will probably usually need at least this line.  Please note that
the library is specified using the simplest possible name; JIGS at
run-time will add the correct prefixes (\texttt{lib}) and suffixes
(things like \texttt{\_d} for debug version -- if needed -- and
\texttt{.A} for the wrappers) to load in the library.

\subsection{Types}
The wrapper tool can parse and manage a certain set of C types.  For
example, upon finding \texttt{BOOL} in the Objective-C headers, the
wrapper tool knows how to manage it.

In the \texttt{types} section you can specify a list of C types
specific to your library, and for each of them, a corresponding
(known) C type.  The wrapper tool will know it has to convert to/from
Java the first C type in the same way as it does with the second.  For
example, in the \texttt{gnustep-base.jigs} file, there is the
following line:
\begin{verbatim}
types = { NSTimeInterval = double; };
\end{verbatim}
This simply tells to the wrapper tool that whenever it finds an argument 
of type \texttt{NSTimeInterval} in an Objective-C method declaration, it 
has to treat it in the same way as if it were a \texttt{double}.

Starting from JIGS 1.5.0, the wrapper tool recognizes enumerations
when it parses your header file, and it automatically treats them as
new types corresponding to \texttt{int}.  This means that you don't
need to do anything special to have JIGS wrap methods taking or
returning enumerations -- enumerations should be recognized
automatically, and treated automatically as \texttt{int}s.

\section{Useful Make Options when Creating Wrappers}

At this point, typing \texttt{make} should be enough to generate
wrappers for your library.  

\subsection{Silencing the Wrapper Generator}

By default, wrapper generation is quite verbose -- it tells you
exactly what it is doing -- for example, it lists all the classes and
methods which are being wrapped.  If you find this annoying, you can
turn it off by compiling with the \texttt{verbose=no} option, as in:
\begin{verbatim}
make verbose=no
\end{verbatim}

\subsection{Enabling Debugging}

If you are compiling your library with debugging enabled  -- ie, typing
\begin{verbatim}
make debug=yes
\end{verbatim}
the wrapper library will also be generated with debugging enabled.
This means that the GNUmakefiles for the wrapping library will
always automatically use \texttt{debug=yes} when the wrapping library
is compiled.  The wrapping code itself will be generated in the
\texttt{JavaWrapper\_debug} directory rather than in the \texttt{JavaWrapper}, 
to allow you to keep the two versions.

\subsection{Debugging or Non-Debugging}

When Objective-C GNUstep libraries are loaded from Java using JIGS,
all the libraries must be of the same type -- or debugging libraries
or non-debugging libraries.  

In general, the simplest way you can manage this issue is by
consistently using only libraries of one of the two kind on your
system; ie, compile everything (from the GNUstep Base Library up) with
`\texttt{make}', or compile everything with `\texttt{make debug=yes}'.

If you don't, then you need to read carefully the following part.

\subsubsection{The Fine Prints About Debugging}

JIGS will decide whether to use debugging or non-debugging libraries
at run-time, when it is first initialized from Java.  Debugging
libraries are easy to tell because the name ends with \texttt{\_d}.
For example, the core JIGS library is
\texttt{libgnustep-java}; if you compile it without debugging, it will 
be in the file 
\begin{verbatim}
libgnustep-java.so
\end{verbatim}
but if you compile it with debugging, it will be in the file 
\begin{verbatim}
libgnustep-java_d.so
\end{verbatim}
Because the name is different, you can have both versions on your
system.  JIGS will choose to load debugging or non-debugging libraries
in the following way:
\begin{enumerate}
\item If you have only one version of JIGS installed (ie, only the debugging 
or the non-debugging, but not both), there is no choice -- JIGS will
load libraries of the same kind as itself.  This means if you have a
debugging version of JIGS installed, you will need to have a version
of all libraries you need with debugging enabled.  If you only have a
non-debugging version of JIGS installed, you will need to have a
version of all libraries you need without debugging.
\item If you have both version of JIGS (the debugging and the non-debugging), 
JIGS will decide at run-time which version of itself to use (and
consequently, which version of all other libraries to use).  By
default, it will load the non-debugging version.  This is the default
because the idea is that using a debugger to debug libraries when
accessed from Java in this way is so difficult that most people will
not want to do it (I actually don't know how to do it myself).  But
you can override the default by setting the \texttt{JIGS\_DEBUG}
environment variable.  Setting it to \texttt{YES} or \texttt{yes} will
give priority to the debugging libraries.
\end{enumerate}
Once JIGS has chosen an option, it will follow it consistently.  For
example, if it decided to load debugging libraries, it will ignore all
non-debugging libraries.

\subsection{Turning off the Generation of Quick Reference Doc}

To stop JIGS from automatically generating minimal javadoc comments
and the quick reference documentation from them, it's enough to
compile using \texttt{javadoc=no}, as in:
\begin{verbatim}
make javadoc=no
\end{verbatim}

\section{Including Special Code in the Wrapper GNUmakefiles}\label{special-code-in-GNUmakefiles}

This section describes a feature which is usually not needed, so you
may skip it at a first reading.  As a prerequisite, you probably need
to have read the section \ref{wrapper-structure} to make any use of
this section.

It is possible that you may need/want to insert special code in the
GNUmakefile.preamble and GNUmakefile.postamble for the wrappers.  For
example, some special flags required to compile an Objective-C library
(the Objective-C wrapper library for your library) against your
Objective-C library.

JIGS itself by default does not generate GNUmakefile.preamble and
GNUmakefile.postamble at all; but it will look in the library
directory for the files 
\begin{verbatim}
GNUmakefile.wrapper.objc.preamble
GNUmakefile.wrapper.objc.postamble
GNUmakefile.wrapper.java.preamble
GNUmakefile.wrapper.java.postamble
\end{verbatim}
and, if any of them is present, copy them into the \texttt{JavaWrapper} 
directory, in the following way:
\begin{verbatim}
GNUmakefile.wrapper.objc.preamble --> JavaWrapper/Objc/GNUmakefile.preamble
GNUmakefile.wrapper.objc.postamble --> JavaWrapper/Objc/GNUmakefile.postamble
GNUmakefile.wrapper.java.preamble --> JavaWrapper/Java/GNUmakefile.preamble
GNUmakefile.wrapper.java.postamble --> JavaWrapper/Java/GNUmakefile.postamble
\end{verbatim}

In this way, by adding one of these files to your library's directory,
you can have it copied into the generated wrappers in the appropriate
place.

\subsection{Finding the library}
A typical usage of this is to wrap libraries which have not yet been
installed.  Normally, you create java wrappers for libraries which you
have already installed.  Sometimes though, you need to create java
wrappers for a library before it is installed.  In this case, you
might need to help the compiler to find your actual library when it
links the java wrappers.

You would do so by creating a file called
\begin{verbatim}
GNUmakefile.wrapper.objc.postamble
\end{verbatim}
and adding to this file something like the following line
\begin{verbatim}
ADDITIONAL_LIB_DIRS = -L/opt/nicola/MyLibrary/
\end{verbatim}
%$ [fool emacs' stupid TeX mode]
Please note that you will need to install your library anyway before
you can use the java wrappers, because the library must be found at
run-time as well!

A classical case in which you need this trick is if you are building
the java wrappers with the library itself (that is, if you have a
\texttt{GNUmakefile} which includes both \texttt{library.make} and
\texttt{java-wrapper.make} and which you use to compile both.  In that
case, you need to add
\begin{verbatim}
ADDITIONAL_LIB_DIRS = -L../../$(GNUSTEP_OBJ_DIR)
\end{verbatim}
%$ [fool emacs]
to your \texttt{GNUmakefile.wrapper.objc.preamble} to make sure that,
when the java wrappers are built, the compiler will find the original
library (and you also need to make sure that \texttt{library.make} is
included before \texttt{java-wrapper.make} so that the library is
compiled before the wrappers.

\section{Controlling the Quick Reference Documentation}

This section documents special options which control the quick
reference documentation which JIGS automatically generates with the
wrappers.  You may safely skip this section at a first reading.  You
need to read the section \ref{special-code-in-GNUmakefiles} before
reading this one.

\subsection{Generating Documentation for Packages}
By default, JIGS will treat the Java classes as separate classes, and
document them accordingly.  If you are rather creating a complete
package you may want javadoc documentation for the package.  This is
not very different, it just additionally includes a useful index with 
the list of all the classes in the package.

To get this behaviour, you need to write a 
\begin{verbatim}
GNUmakefile.wrapper.java.preamble
\end{verbatim}
and set \texttt{Reference\_JAVADOC\_FILES} in it.  For example, when 
wrapping the GNUstep Base Library we do:
\begin{verbatim}
Reference_JAVADOC_FILES = gnu.gnustep.base
\end{verbatim}

\subsection{Installation Directory}
By default, JIGS will install the quick reference documentation into 
\begin{verbatim}
$(GNUSTEP_INSTALLATION_DIR)/Developer/libMyLibrary/Java/Reference/
\end{verbatim}%$
where of course \texttt{libMyLibrary} is replaced with your library name.
If you want to change it, you need to write a 
\begin{verbatim}
GNUmakefile.wrapper.java.preamble
\end{verbatim}
and set \texttt{Reference\_DOC\_INSTALL\_DIR} in it.  For example, 
when compiling the GNUstep Base Library wrappers we use
\begin{verbatim}
Reference_DOC_INSTALL_DIR = Developer/Base/Java/
\end{verbatim}
which installs the documentation into
\begin{verbatim}
$(GNUSTEP_INSTALLATION_DIR)/Developer/Base/Java/Reference/
\end{verbatim}%$

\section{Generating RPMs for the wrapper library}

Historically, generating RPMs for the wrappers was a complicated
process, because generation of java wrappers was strongly coupled to
building the library.  Now it's no longer so, and the two processes
are now totally independent, which means that you can build RPMs for
java wrappers normally as for any other gnustep package -- in the
simple, standard way -- just add \texttt{PACKAGE\_NAME} and
\texttt{VERSION} to your \texttt{GNUmakefile}, and provide
corresponding \texttt{.spec.in} and \texttt{.debug.spec.in} files.

