Next: 3.2 Accessing the GNUstep Up: 3. Programming GNUstep in Previous: 3. Programming GNUstep in

Subsections

- 3.1.1 Compiling a Single Class
- 3.1.2 Compiling Classes Belonging to a Package
- 3.1.3 Installing Java classes where you like
- 3.1.4 Creating Java Tools
- 3.1.5 Documenting Classes Using Javadoc

# 3.1 Compiling Java Code Using GNUstep Make

## 3.1.1 Compiling a Single Class

Even without JIGS, the GNUstep make package has builtin support for compilation of generic java projects.

As an example, consider the following java class:

    import java.lang.*;

    class Pisa
    {
      public static void printQuote ()
        throws Throwable
      {
        System.out.println ("Ahi Pisa, vituperio de le genti");
      }
    }

This class just prints out the famous quote by Dante about the Italian city of Pisa; it makes only use of the standard java classes, so there is no need to have JIGS to compile or run it.

Compiling this class can be quite easily done directly, but we want to start learning how to use the GNUstep make package facilities for java, so we write the following `GNUmakefile`:

    include $(GNUSTEP_MAKEFILES)/common.make

    JAVA_PACKAGE_NAME = test
    test_JAVA_FILES = Pisa.java

    include $(GNUSTEP_MAKEFILES)/java.make

The makefile is straightforward: the `JAVA_PACKAGE_NAME` is just a name identifying the package (any name would do); `JAVA_FILES` is a list of java files to be compiled.

You should now try to compile this java program by typing `make`. This - quite simply - compiles the java class. What is more interesting is what happens when you type `make install`: in this case, the java class is installed into `$GNUSTEP_LOCAL_ROOT/Libraries/Java/`, which in my case means that the compiled class is installed into

    /usr/GNUstep/Local/Libraries/Java/Pisa.class

Since the GNUstep initialization script - usually

    /usr/GNUstep/System/Makefiles/GNUstep.sh

- adds `/usr/GNUstep/Local/Libraries/Java` to the `CLASSPATH`, after you have installed `Pisa.class`, you can just access `java Pisa` from any Java program automatically.

This can be unfortunate, because if you install many different classes, you end up with all the classes being installed in the same big flat messy directory. The java approach to this is to use packages, an approach which is fully and simply supported by the GNUstep make package.

## 3.1.2 Compiling Classes Belonging to a Package

To organize our java classes better, we decide to create a new package, called `misc.quotes`, and to make our class part of it. To do this, we rewrite our program as follows

    package misc.quotes;

    import java.lang.*;

    class Pisa
    {
      public static void printQuote ()
        throws Throwable
      {
        System.out.println ("Ahi Pisa, vituperio de le genti");
      }
    }

and we save it into the file

    misc/quotes/Pisa.java

This directory is relative to the position of the GNUmakefile, which is where we will run the compiler. We then rewrite our GNUmakefile to be as follows:

    include $(GNUSTEP_MAKEFILES)/common.make

    JAVA_PACKAGE_NAME = test
    test_JAVA_FILES = misc/quotes/Pisa.java

    include $(GNUSTEP_MAKEFILES)/java.make

Typing `make` will compile the `misc.quotes.Pisa` class as usual.

To include the class in other classes, we need now to always specify the full package name, as in

    import misc.quotes.Pisa;

The GNUstep Make Package knows nothing about java packages; but, when installing java class files, it preserves the relative path of the classes, so that running `make install` will install `Pisa.class` into

    $GNUSTEP_LOCAL_ROOT/Libraries/Java/misc/quotes/

In my case, this means that it is installed into:

    /usr/GNUstep/Local/Libraries/Java/misc/quotes/Pisa.class

Since the GNUstep make package does not really know about java packages, it is perfectly correct to compile and install classes belonging to different java packages with the same `GNUmakefile`, as in the following example:

    include $(GNUSTEP_MAKEFILES)/common.make

    JAVA_PACKAGE_NAME = fun
    fun_JAVA_FILES = \
      misc/quotes/Pisa.java       \
      misc/quotes/Farinata.java   \
      misc/quotes/Ulisse.java     \
      misc/jokes/Sailor.java      \
      misc/jokes/Worker.java

    include $(GNUSTEP_MAKEFILES)/java.make

This will correctly compile and install the classes belonging to the two different packages `misc.quotes` and `misc.jokes`; please don't be confused by the `JAVA_PACKAGE_NAME` variable, which bears no relation with java packages, and it is just a temporary name used internally by the make package.

## 3.1.3 Installing Java classes where you like

Compiled Java classes are automatically installed into

    $GNUSTEP_LOCAL_ROOT/Libraries/Java/

and this makes sure that they are always in the classpath. This is what you normally want.

But sometimes you might need to modify this behaviour. For example, if you are writing Java servlets, you might want to install them in a special, different place. To do this, you may set the `JAVA_INSTALLATION_DIR` variable in your makefile:

    include $(GNUSTEP_MAKEFILES)/common.make

    JAVA_PACKAGE_NAME = servlet
    servlet_JAVA_FILES = MyServlet.java

    JAVA_INSTALLATION_DIR = /usr/local/servlets

    include $(GNUSTEP_MAKEFILES)/java.make

This GNUmakefile will compile your servlet, and install it into `/usr/local/servlets`.

## 3.1.4 Creating Java Tools

In GNUstep, a tool is a program which is run directly from the command line. The GNUstep make package (versions newer than 1.0.0) supports natively Java tools.

As an example, we now show how to turn our Pisa class into a Java tool. We modify the code to be:

    import java.lang.*;

    class Pisa
    {
      public static void main (String[] args)
        throws Throwable
      {
        System.out.println ("Ahi Pisa, vituperio de le genti");
      }
    }

and we replace the `GNUmakefile` with the following one:

    include $(GNUSTEP_MAKEFILES)/common.make

    JAVA_TOOL_NAME = Pisa
    Pisa_JAVA_FILES = Pisa.java
    Pisa_PRINCIPAL_CLASS = Pisa

    include $(GNUSTEP_MAKEFILES)/java-tool.make

There are some differences with the `GNUmakefile` we use before. We include `java-tool.make` rather than `java.make` because we want to create a Java tool rather than a generic Java class. `JAVA_TOOL_NAME` is the name of the tool - this is quite important now, because it is the name we will use to invoke the tool from the command line: when you install the tool, GNUstep make will generate and install a shell script in `$GNUSTEP_LOCAL_ROOT/Tools` with that name (`Pisa` in this case), which runs your java program (setting up the class path and the library path if needed). So, once you have installed the Java tool, just typing `Pisa` at the shell prompt will run your it. `JAVA_FILES` are, as usual, the Java source files for the tool. `PRINCIPAL_CLASS` is the class which implements the `main` method - the GNUstep make package needs this information, so that it can prepare the shell script to run this class.

## 3.1.5 Documenting Classes Using Javadoc

The GNUstep make package has also some support for generating documentation using `javadoc`; if you want to use this facility, please read on. Otherwise, you may safely skip this section.

Here is an example of the usual `GNUmakefile` with added documentation using javadoc:

    include $(GNUSTEP_MAKEFILES)/common.make

    JAVA_PACKAGE_NAME = fun
    fun_JAVA_FILES = \
      misc/quotes/Pisa.java       \
      misc/quotes/Farinata.java   \
      misc/quotes/Ulisse.java     \
      misc/jokes/Sailor.java      \
      misc/jokes/Worker.java

    DOCUMENT_NAME = Reference
    Reference_JAVADOC_FILES = misc.quotes misc.jokes
    Reference_DOC_INSTALL_DIR = Developer/Fun/

    include $(GNUSTEP_MAKEFILES)/java.make
    include $(GNUSTEP_MAKEFILES)/documentation.make

As you see, you need to choose a document name, list the packages you want to document, choose the installation directory, and include `documentation.make`. We now review each option in more detail.

`DOCUMENT_NAME` is a name describing the documentation to be generated. It has some importance, because the documentation is generated inside a directory called `$(DOCUMENT_NAME)`. In this case, when I run `make`, make creates a directory called `Reference`, and runs `javadoc` telling him to put the documentation into this directory (this is accomplished by using the `-d` option to `javadoc`).

`JAVADOC_FILES` contains a list of packages to be documented. It might also contain standalone java files - which need to be specified with full pathnames then, as in

    Reference_JAVADOC_FILES = /home/nicola/java/test/test.java

You can mix package names and java file names - and use an arbitrary number of them.

`DOC_INSTALL_DIR` specifies where the generated documentation is going to be installed when you run `make install`. In the example, it will end up being installed in

    $(GNUSTEP_LOCAL_ROOT)/Documentation/Developer/Fun/Reference/

which on my system means

    /usr/GNUstep/Local/Documentation/Developer/Fun/Reference/

Additional options you may want to use are:

1. Setting `ADDITIONAL_JAVADOCFLAGS` before including `documentation.make` allows you to pass custom flags to javadoc - a standard example is:

       ADDITIONAL_JAVADOCFLAGS += -public

2. By default, the make package will tell javadoc to look for source files in the current directory; if some of them are elsewhere, you can specify additional paths to look for the source files by setting a `JAVADOC_SOURCEPATH`:

       Reference_JAVADOC_SOURCEPATH=/home/nicola/Java/Nico:/home/nicola/Java/Nicola

   Before running javadoc, the make package will always add `./` in front of the sourcepath - for example, in this case it would use

       -sourcepath ./:/home/nicola/Java/Nico:/home/nicola/Java/Nicola

   when invoking javadoc. Please refer to the javadoc documentation if you want to learn more about the sourcepath.

Next: 3.2 Accessing the GNUstep Up: 3. Programming GNUstep in Previous: 3. Programming GNUstep in