.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH JYTHONC 1 "July 7, 2001"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
jythonc \- compile Python source to real Java classes
.SH SYNOPSIS
.B jythonc
[ \fB\-p, \-\-package\fP \fIpackage\fP ]
[ \fB\-j, \-\-jar\fP \fIjarfile\fP ]
[ \fB\-d, \-\-deep\fP ]
[ \fB\-c, \-\-core\fP ]
[ \fB\-a, \-\-all\fP ]
[ \fB\-b, \-\-bean\fP \fIjarfile\fP ]
[ \fB\-A, \-\-addpackages\fP \fIpkgs\fP ]
[ \fB\-w, \-\-workdir\fP \fIdirectory\fP ]
[ \fB\-s, \-\-skip\fP \fImodules\fP ]
[ \fB\-C, \-\-compiler\fP \fIpath\fP ]
[ \fB\-J, \-\-compileropts\fP \fIoptions\fP ]
[ \fB\-f, \-\-falsenames\fP \fInames\fP ]
\fImodule\fP ...
.PP
.B jythonc \-\-help
.SH DESCRIPTION
\fBJythonC\fP is a utility that compiles Python source code to real
Java classes, and is used for building applets, servlets, beans and so
on, as well as allowing for Python classes to be subclassed in Java.
.PP
JythonC generates actual Java source code, and then invokes a
Java compiler over this source code to create the .class files.  Thus you
will need access to a Java compiler.  The jythonc script will attempt to
guess the specifics of the installed compiler; see
.BR jython.conf (5)
for details on specifying these yourself.
.PP
In order to create a real Java class, the Python module must contain a
Python class with the same name as the module, and that Python class must
subclass exactly one Java class or interface.  The real Java class created
will be a subclass of whatever Java class is subclassed.
.PP
.SS Compiling Python Methods
Normally, compiled Python methods are not directly callable from Java.
There is simply not sufficient information in a Python method definition
to create a useable Java method.  There are however two ways a Python
method can be made into real Java method.  Both ways require that the Python
class have a Java class or a Java interface as its base class.
.PP
.TP
.I Overriding / Implementing a Java method:
By overriding a Java method, the overridden method's signature is used
for the real Java class.  That includes return type, privacy modifier,
arguments, argument types and throws clauses.
.TP
.I Adding a Java method signature to a Python method docstring:
Using a special convention in the method docstring allows for the creation
of a corresponding Java method.  The signature must be written on one line
and must start with the text \fI@sig\fP.  All class names (except those in
\fIjava.lang\fP) must be specified as fully qualified class names.  An
example is:
.PP
.RS
.RS
def setExpression(self, e):
.RS
"@sig public void setExpression(java.lang.String e)"
.RE
.RE
.RE
.SH OPTIONS
A summary of options is included below.
.TP
\fB\-p, \-\-package\fP \fIpackage\fP
Put all compiled code into the given Java package.
.TP
\fB\-j, \-\-jar\fP \fIjarfile\fP
Specifies a jar archive to create and put the results of the compilation into.
Implies \-\-deep.
.TP
\fB\-d, \-\-deep\fP
Compile all Python dependencies of the module.  This is useful for creating
applets.
.TP
\fB\-c, \-\-core\fP
Include the core Jython libraries (about 130K).  Needed for applets since
some browsers don't yet support multiple archives.  Implies \-\-deep.
.TP
\fB\-a, \-\-all\fP
Include all of the Jython libraries (core, compiler and parser).  Implies
\-\-deep.
.TP
\fB\-b, \-\-bean\fP \fIjarfile\fP
Compile into the given jar archive, including the correct manifest for
the Java bean.
.TP
\fB\-A, \-\-addpackages\fP \fIpkgs\fP
Include Java dependencies from the given list of packages.  Default is
\fIorg.python.modules\fP and \fIorg.apache.oro.text.regex\fP.
.TP
\fB\-w, \-\-workdir\fP \fIdirectory\fP
Specifies the working directory into which the generated code will be
placed.  Default is \fI./jpywork\fP.
.TP
\fB\-s, \-\-skip\fP \fImodules\fP
Don't include any of the given modules in compilation.  This should be a
comma-separated list of modules.
.TP
\fB\-C, \-\-compiler\fP \fIpath\fP
Use the specified Java compiler to turn generated Java sources into class
files.  If this is set to \fINONE\fP then compilation ends with the
generation of the Java source file(s).  See
.BR jython.conf (5)
for alternate ways of specifying the Java compiler.
.TP
\fB\-J, \-\-compileropts\fP \fIoptions\fP
Options to pass directly to the Java compiler.  See
.BR jython.conf (5)
for alternate ways of specifying Java compiler options.
.TP
\fB\-f, \-\-falsenames\fP \fInames\fP
A comma-separated list of names that are always false.  Can be used to
short-circuit \fIif\fP clauses.
.TP
\fImodule\fP ...
A list of Python modules to compile.  These can be either .py files or
module names on the python path (see
.BR jython.conf (5)
for further details on property \fIpython.path\fP).
.TP
.B \-\-help
Print a usage message and exit.
.SH ENVIRONMENT VARIABLES
.TP
JAVA (default: /usr/bin/java)
The Java interpreter to use when running Jython and JythonC.
.TP
JAVA_OPTIONS (default: empty)
Options to pass to the Java interpreter when running Jython and JythonC.
.TP
JAVAC (default: /usr/bin/javac)
The Java compiler to use when running JythonC.
.SH EXAMPLES
To create the file \fIappletdemo.jar\fP containing all of the applet
demos in the current directory as well as the core Jython libraries:
.PP
.RS
\fIexample$\fP jythonc \-\-core \-\-deep \-\-jar appletdemo.jar *.py
.RE
.PP
\fBNote:\fP One special thing to consider when building applets is that the
Java VM version used when compiling the sources must usually be the same
as the VM version used by the browser.  If a newer JVM is used when
compiling the applets, the compiled code may have references to classes
that do not exist in older JVMs.
.PP
To generate a skeleton class to allow a Python class to be used as
a \fIjava.awt.Component\fP in a Java gui program:
.PP
.RS
\fIexample$\fP jythonc Graph.py
.RE
.PP
To generate a Jython-based bean:
.PP
.RS
\fIexample$\fP jythonc \-\-deep \-\-bean f2c.jar conversion.FahrenheitToCelsius
.RE
.PP
.SH SEE ALSO
.BR jython (1),
.BR jython.conf (5).
.PP
If the Debian package \fIjython-doc\fP is installed,
full documentation from the Jython authors will be available in
\fI/usr/share/doc/jython-doc/html/\fP.
.SH AUTHOR
This manual page was prepared by Ben Burton <bab@debian.org> for the Debian
GNU/Linux system (but may be used by others).  It is based upon the
official Jython documentation.