Note that this document is still under development and may change frequently!
This getting started guide will show you how to distribute your Jython scripts in a snap. By taking the power of Jython, you can of course integrate your Jython code with your Java code and even third-party Java libraries, Jump is smart enough to know how to pack all of them into a single, independent .jar file, a simpler JAR library, a native Mac OS X app bundle, a native Windows .exe executable file, or a WAR file for Python WSGI applications. Supporting native Linux executables is the next. By using Jump, you can distribute your Jython applications in a really easy step. Make things easier both for the developers and normal end users. Let's get it started.
1. Installing Jump
Before you can take advantage of Jump, you'll need to get it installed.
1.1 Install JDK
The Java Development Kit (JDK) is required to compile Java source code, execute Java applications, and do many other things related to Java. I use version 1.6 to develop and test Jump on Mac OS X 10.6. It should also work on Windows and Linux as well. You can download and find more information at http://java.sun.com/.
1.2 Install Jython
You probably already have Jython installed on your computer if you are looking at this page. If not, don't worry. Installing Jython is easy, you can get the latest Jython at http://www.jython.org/, once you have it, you can follow this installation guide to get Jython installed.
1.3 Install Apache Ant
Apache Ant is a popular build tool for Java programmers. Like Jython, you probably already have it if you are a Java programmer. If you don't have it yet, you can get the latest version at http://ant.apache.org/. If you are not sure whether you have it or not, simply type "ant" in command line to check.
1.4 Install Jump
You have two choices to install Jump, the easier way is just to execute easy_install jump in your command line if you have setuptools installed. Remember to use the easy_install binary under Jython's bin directory. On the other hand, if you have no idea about what Setuptools is, you can just download the Jump's source code at http://pypi.python.org/pypi/jump/ and install it by executing jython setup.py install. After you installed Jump, type jump in your command line, and you should see the Jump's help message if successful.
2. Jump Basics
2.1 The simplest "Hello World" example
As usual, you need to create a directory for your project. All the code for you specific project should be put in this directory. In Unix-like environments, you can do this by
mkdir helloworld
Then change into the created directory
cd helloworld
Now you can start writing your HelloWorld? script with your favorite editor, I simply created a file called helloworld.py and its content looks like this:
def main(): print "Hello World!"
Note that you must specify a main entry point to Jump so the final distribution knows where to start executing your program. Therefore, I use a function named main as our main entry point, and our final distribution will start from here. Now we can make our first distribution file by executing
jump jar -m helloworld:main
The -m helloword:main indicates that our main entry point is the main callable in the helloworld module. After Jump finished its work, you should see a new dist directory created in your project's directory, and the final distribution will be there. Now we can execute our first HelloWorld? program by running
java -jar dist/helloworld.jar
And you should see a Hello World! printed on your screen. It works!
2.2 Using Config file
It's pretty annoying to specify the same command options again and over again, so Jump allows you to keep your settings in a config file. To use it, simply create a file named jump.cfg in your project's directory, then you can set the options in the form of key-value pairs under the options section. For example, we can use the following setting to do the same thing last example does.
[options] main-entry-point = helloworld:main
Once you have the config file, you can make a JAR distribution by just running
jump jar
The keys supported in config file can be found in Jump's help message, to see the help message, simply type jump -h or jump in your command line. At the time of this writing (Jump v0.9.7.3), the help message looks like this:
Usage: jump command [options] arg1 arg2 ...
Jump is a build tool for distributing Jython applications.
You can find more about Jump at http://gitorious.org/jump.
Commands:
exe: make Windows native executables
app: make Mac Application Bundles
jarlib: make JAR library files
ant: create build.xml file for ant
jar: make standalone JAR files
war: make a War file for Python WSGI applications
Options:
--version show program's version number and exit
-h, --help show this help message and exit
-v, --verbose run in verbose mode
-n DIST_NAME, --dist-name=DIST_NAME
name of the distribution file
-p INCLUDE_PACKAGES, --include-packages=INCLUDE_PACKAGES
include full Python packages
--ignore-packages=IGNORE_PACKAGES
ignore Python packages
-d DIST_DIR, --dist-dir=DIST_DIR
directory to put the distribution
-m MAIN_ENTRY_POINT, --main-entry-point=MAIN_ENTRY_POINT
main entry point, either Java or Python
--java-only Ignore all Jython code and JAR files
--jump-jython-factory
Use Jump's Jython factory.
exe:
--exe-gui use GUI instead of console mode
--exe-icon=EXE_ICON
application icon in ICO format
--exe-onefile generate only one exe file
app:
--app-vm-arguments=APP_VM_ARGUMENTS
extra command-line arguments for the Java application
--app-development-region=APP_DEVELOPMENT_REGION
the development region of the bundle
--app-icon=APP_ICON
file reference to a Mac OS X icon file
--app-info-string=APP_INFO_STRING
a string for display in the Finder's Get Info panel
--app-jvm-version=APP_JVM_VERSION
the version of the JVM required to run the application
--app-short-name=APP_SHORT_NAME
the string used in the application menu
--app-signature=APP_SIGNATURE
the four-letter code identifying the bundle
--app-vm-options=APP_VM_OPTIONS
command line options to pass the JVM at startup
war:
--war-wsgi-handler=WAR_WSGI_HANDLER
callable wsgi handler
--war-log-level=WAR_LOG_LEVEL
the level of diagnostic output should be logged
--war-cache-callables
whether or not it should cache any callables it
creates
--war-google-app-engine=WAR_GOOGLE_APP_ENGINE
should set in the form of `ID:VERSION`
--war-no-multithread
whether to run in multithread mode
As you can see, there are a bunch of options available there. What these options do are explained in the help message. You can also find more information about Jump's commands at JumpCommands. The point is, all option names listed here could be used in the config file! Note that you can also use hash symbol (#) to comment out a line just like what you do in Python.
2.3 Including resource files
You can include particular resource files in the final distribution. To do this, you need to add a new manifest section in the jump.cfg file. Then you can specify the files or directories you want to include like this:
[manifest] # Include all *.txt files in the project's root directory. include = *.txt # Include the entire `resc` directory. include = resc/** # Exclude all *.py files in the `resc` directory. exclude = resc/*.py
3. Integrating Jython with Java
By taking the power of Jython, you can of course integrate your Jython code with your Java code and third-party Java libraries, you can even start your final distribution from the Java code.
3.1 Starting your distribution from Java code
You can start your distribution from Java code by simply setting the main-entry-point parameter to something like com.jump.doc.Main where the specified class contains a main method. Jump knows that com.jump.doc.Main is a Java main entry point because it doesn't contain a colon (:).
3.2 Using third-party JAR libraries
If you need to use some third-party JAR libraries, you can put them in the PROJECT_DIRECTORY/lib directory. That's all. Once you run the jump command to make a distribution, all JAR files included in this directory will be packaged into the final distribution. Note that you don't have to copy the "jython.jar" file to this directory manually because Jump will find the one you installed on your computer automatically, as well as Jython's standard library. You don't have to install a standalone version.
3.3 Creating pure Java application
Though Jump is primarily designed for Jython. However, you can still use Jump to distribute pure Java applications by simply specifying a java-only option. Once Jump received a java-only request, it won't take care of any Jython code, and won't include Jython-related JAR files in the final distribution.
4. Use Ant directly
Since Jump v0.9.7, you can use jump to generate a build.xml file for ant by jump ant command. Then, you can distribute your applications directly using the ant command.
$ jump ant # Generates `build.xml` in project's root $ ant jar # Same as `jump jar` $ ant jarlib # Same as `jump jarlib` $ ant app # Same as `jump app` $ ant exe # Same as `jump exe` $ ant oneexe # Same as `jump exe --onefile` $ ant war # Same as `jump war`
Note that once you have the build.xml file, any further changes should be made directly in the build.xml file. The jump.cfg file is only effective when you are using jump command. Of course you can use jump ant again to generate a new build.xml file reflecting to the changed jump.cfg file. But you'll lose all the changes of the original build.xml file.
Before you use ant with the generated build.xml file, make sure you have set the JYTHON_HOME environment variable which is a path of where Jython installed. In unix-like system, you'll need do something like this:
export JYTHON_HOME=PATH_TO_JYTHON_DIRECTORY
5. Jump's Jython factory
Since Jump v0.9.7, Jump includes a simple Jython factory that helps you use Jython within Java smoothly. Jump uses PySystemState() to implement this function instead of PythonInterpreter(), so it may require less resources.
5.1 Call Jython function in Java
Say we want to call a Jython function from Java. Take this simple example:
# helloworld.py def say(message): print message
/* Main.java */ import com.ollix.jump.JythonFactory; public class HelloWorld { public static void main(String[] args) { JythonFactory factory = new JythonFactory("helloworld:say"); factory.call("Hello World!"); } }
$ jump jar --jump-jython-factory -m Main # Creates One-JAR distribution $ java -jar dist/helloworld.jar Hello World!
Note that you must supply the jump-jython-factory option if you want to use Jump's Jython factory in your applications, so Jump knows it should package the required jump-jython-factory.jar file in your distribution.
5.2 Using Java interface with your Jython class
/* Main.java */ package hello; import com.ollix.jump.JythonFactory; import hello.HelloWorldType; public class Main { public static void main(String[] args) { JythonFactory factory = new JythonFactory( HelloWorldType.class, "helloworld:HelloWorld"); /* Initialize instance */ HelloWorldType helloWorld = (HelloWorldType) factory.init("Hi"); System.out.println(helloWorld.getMsg()); helloWorld.setMsg("Hello World!"); System.out.println(helloWorld.getMsg()); } }
/* HelloWorldType.java */ package hello; public interface HelloWorldType { public void setMsg(String message); public String getMsg(); }
# helloworld.py from hello import HelloWorldType class HelloWorld(HelloWorldType): def __init__(self, message=None): self.message = message def setMsg(self, message): self.message = message def getMsg(self): return self.message
$ jump jar --jump-jython-factory -m hello.Main $ java -jar dist/helloworld.jar Hi Hello World!
6. Known issues
If you found some other issues not listed in this section. Please report it to the Jump's mailing list.
* import - You can't import Java classes directly in Jython code if you are distributing a JAR executable. For example, if you have a Java class at com.jump.SomeClass, you cannot import it as from com.jump import SomeClass in Jython, use from com import jump and jump.SomeClass instead. This rule is only applied when you are distributing JAR executable files due to the limit of One-JAR.
However, if you do want to include Java class directly in Jython when you're distributing one Jar file. There's a workaround, for our example, you'll need to put sys.packageManager.makeJavaPackage("com.jump", "SomeClass", None) before you import the Java class from com.jump import SomeClass. So, the code would look like this:
import sys sys.packageManager.makeJavaPackage("com.jump", "SomeClass", None) from com.jump import SomeClass
* pylibtracer - Only import statements at the top level of Jython modules are concerned. One of the powerful feature Jump has is that it can find all modules required in your Jython application automatically. But if there are import statements not at the top level of files, for example, within a function or condition statements, the modules imported there won't be found by Jump. If you use some third-party packages like Django that don't follow this rule, or contains some other static resources. You can always import the entire package explicitly by specifying the include-packages option.
