=============================
Python/Java Wrapper Generator
=============================

:author: Dave Kuhlman
:address: dkuhlman@rexx.com
    http://www.rexx.com/~dkuhlman

:revision: 1.0a
:date: June 24, 2004

:copyright: Copyright (c) 2004 Dave Kuhlman. This documentation is
    covered by The MIT License:
    http://www.opensource.org/licenses/mit-license.

:abstract: This document describes generate_wrappers.py: a python
    script that generates files for Python wrappers for Java a
    class.  This facility uses and requires gcj, libgcj, and CNI.

.. sectnum::    :depth: 4

.. contents::   :depth: 4


Introducing generate_wrappers.py
================================

``generate_wrappers.py`` generates support files that enable
Python to use the classes and methods in a Java source code file.

This facility requires and uses ``gcj``, "The GNU Compiler for the
Java Programming Language".  It can be used only on platforms that
support ``gcj``, ``gcjh``, and ``libgcj``.

The basic strategy is the following:

1. Use ``gcjh`` to generate a header file for your Java class.

2. Write adapter classes, methods, and functions that use the CNI
   (the Compiled Native Interface) API to talk to your Java class.

3. Use SWIG to create Python wrappers for your adapter classes,
   methods, and functions.

4. Compile the resulting source code to produce Python extension
   (a shared library) that you can be import from Python.

``generate_wrappers.py`` helps you by generating some of the files
you need and by generating a ``Makefile`` that generates others.
*But*, you will need to write the C/C++ adapter classes, methods,
and functions by hand yourself.  And, this will require that you
know enough CNI to do so.

Requirements and Limitations
============================

The development strategy supported by ``generate_wrappers.py``
only works on the platforms supported by ``gcj`` and ``libgcj``.
See the following for a list of supported platforms:
http://gcc.gnu.org/java/status.html.

In order to do development with ``generate_wrappers.py``, you must
have the following installed:

- ``gcj`` -- gcj is the GNU Compiler for the Javatm Programming
  Language. Available at: http://gcc.gnu.org/java/index.html.

- ``libgcj`` -- libgcj is the runtime that goes along with the gcj
  front end to GCC.  See: http://gcc.gnu.org/java/libgcj2.html.

- ``SWIG`` -- SWIG is an interface compiler that connects programs
  written in C and C++ with scripting languages such as Perl,
  Python, Ruby, and Tcl.  See: http://www.swig.org.

Limitation -- I'm not too sure about this, but I believe that this
solution limits you to the sub-set of the JDK class libraries that
are supported by ``gcj`` and ``libgcj``.  For more on this, see:
http://gcc.gnu.org/java/faq.html#2_1.


Where to Get ``generate_wrappers.py``
=====================================

You can find ``generate_wrappers.py`` here:
http://www.rexx.com/~dkuhlman/generate_wrappers-1.0a.tar.gz.


Examples
========

There is a simple example of the use of ``generate_wrappers.py``
in the distribution under the ``Examples`` directory.  See the
``README`` file included with the example.


How to Use ``generate_wrappers.py``
===================================

Step 1
------

Run ``generate_wrappers.py`` from the command line.  Give it the
base name of your Java class file.  For example, if your Java
class is in a file named "myclass.java", then you might run the
following::

    $ python generate_wrappers.py myclass

Here is the usage information for ``generate_wrappers.py``::

    /w1/Java/Wrapper_generator [34] ./generate_wrappers.py --help
    usage:
        python generate_wrappers.py [options] <base_file_name>
    example:
        python generate_wrappers.py my_java_class_file

    options:
      -h, --help         show this help message and exit
      -v, --verbose      produce verbose output
      -f, --force        force overwrite of files.  Do not ask.
      -p, --python-impl  generate empty implementation files


p, python-impl
    Generate mostly empty files for the adapter code.  You will
    add code to these files that are wrappers or adapter classes,
    methods, and functions.  The functions and methods in these
    files will be called by Python (through code generated by
    SWIG) and will in turn call the Java code (through CNI).
    Since you will add your own code to these files, I've required
    that you use an explicit switch to generate them, hopefully
    making it less likely that you will over-write your code.


Step 2
------

Add (and later modify as necessary) your adapter code.  When you
run ``generate_wrappers.py``, it prints out a message telling you
where (in which files) to add your adapter code.


Step 3
------

Run make to generate and compile additional code.


Step 4
------

Run Python to test your code.


Step 5
------

Repeat steps 2 through 4 as necessary.


See Also
========

`Python`_: The Python home page.

.. _`Python`: http://www.python.org

`gcj`_: The GNU Compiler for the Javatm Programming Language

.. _`gcj`: http://gcc.gnu.org/java/index.html

`libgcj`_: The libgcj home page

.. _`libgcj`: http://gcc.gnu.org/java/libgcj2.html

`Java Technology`_: The Sun Java support site

.. _`Java Technology`: http://java.sun.com/

`SWIG`_: More information about SWIG, the software wrapper
interface generator.

.. _`SWIG`: http://www.swig.org