Documentation

Building & Launching AniPlay

This page briefly describes the process of building and Launching AniPlay, the client side viewer of the AniMix project.

Requirements

First of all, check that the you have met the requirements.

When installing the Jave Media Framework and Batik, note the installation locations, you'll need these later.

AniPlay also makes use of the Java look and feel Graphics Repository. Although these graphics are not essential to the operation of AniPlay, they add a consistant look and feel to its interface. Download the repository file, jlfgr-1_0.zip, into a known locations and unzip it. Note the location, as above we will need it shortly. You can either keep this in a separate local directory or place it someplace common where you, or others users can reuse it.

Tools

AniPlay makes use of the Apache Ant build tool, AniPlay requires version 1.6 or greater.

Get the Source

AniPlay is still under development, therefore the best place to get the source is directly from CVS. The following commands can be used to obtain a copy of the latest sources directly from CVS.

# cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/animix login
# cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/animix co -P animix/aniplay

When promted for a password, simply hit return. This will retieve the current CVS snapshot from the Sourceforge CVS server and place it into the newly create directories animix/aniplay.

You can periodically update your local copy of the CVS tree using;

# cvs update

Full instructions for 'checking out' a copy from anonymous CVS are availble on the sourceforge project page.

Building AniPlay

AniPlay can be built in one of three ways, each described below. Each method requires the file, build.xml, to be processed by Apache Ant. Using a terminal, change to the animix/aniplay directory.

A full list of build targets availble within build.xml can be obtained with the following command.

# ant -p

This tells us all of the things we can do with this build file.

Updating Build.xml classpath

Before we compile AniPlay, we need to modify the build file, build.xml, to tell Ant where our dependancies are located.

Using a text editor, open build.xml and replace the contents of the Global Properties 'lib.jmf_home' and 'lib.batik_home' with the respective locations you installed to at the beginning of this guide. For example, if you installed the Java Media Framework into a directory called 'jmf' so that 'bin', 'doc' and 'lib' are directly below 'jmf', you would set the 'lib.jmf_home' property to '/path/to/jmf'.

The Java look and feel graphics respotory is handled slightly differently. Unzipping the downloaded repostory file produces a Java Archive file (a jar). The 'lib.jlfgr' property should be set to point directly to this jar file, not the directory containing it.

Building AniPlay Method 1, 'compile'

This is the simplest method to build and launch AniPlay.

The default target within the build file, build.xml, is 'compile'. We can build AniPlay by simply invoking Ant and it will execute the default target for us.

# ant

Congratulations, you've just built AniPlay. Assuming there were no build errors (if there are, get in touch) , you can now launch the application.

Lauching AniPlay

The build file also contains a target to launch AniPlay. To launch AniPlay we simply invoke Ant specifying this target.

# ant play

Using the build file in this way hides some of the details required in launch AniPlay. This is convenient if you are developing, or are simply just taking a look at AniPlay.

Building AniPlay Method 2, 'bin-cp'

The second method of building and launching AniPlay creates a single executable jar file, making it easy to launch without the aid of the build file.

It should be noted that this method hard codes the classpath data contained within the build file into the executable jar file. While this is convenient for the local machine, it is not recommended if you intend to move the resulting binary from one machine to another (unless the locations of the library dependancies are identical).

The 'bin-cp' target can be used to build the executable jar file by issuing the following command;

# ant bin-cp

A single executable jar file will be created and placed into a newly created 'dist' directory. You can move this file to a convenient location on the local machine, if required.

Lauching AniPlay

The classpath data required to launch AniPlay is already encoded within the executable jar file. You can now launch the AniPlay application passing the '-jar' option to Java. If you are running on the Windows operating system, you can also just double clicking on the jar file.

# java -jar AniPlay-0.0.1.jar

Building AniPlay Method 3, 'bin'

The third method of building and launching AniPlay provides the greatest flexibiliy of the three, although requires a little more work setting an appropriate classpath.

We will use the 'bin' target within to build file to compile and generate a single jar file. This method, however, does not encode the classpath data as part of the jar file. This alloww the resulting jar file to be moved between systems. This comes at the added expense of configuring the classpath on the target system.

Compile the AniPlay application using the 'bin' target.

# ant bin

A single jar file will be created and placed into the 'dist' directory. You can now move this file to a convenient location on the local or any other machine.

Lauching AniPlay

In order to launch the AniPlay jar file resulting from this third method, we need to setup our classpath to include not only the AniPlay jar, but also each of the library dependancies. That is to say, we need to add each of the following to the classpath.

We also need to specify the fully qualified name of the AniPlay application as the main entry point of the application, uk.ac.gla.cmt.animatics.apps.aniplay.AniPlay.

We can now start AniPlay using the -classpath option to the 'java' command. (We could also have choosen to use the CLASSPATH environment variable to specify the classpath instead)

# java -classpath /path/to/AniPlay-0.0.1.jar:/path/to/jmf.jar: /path/to/batik.jar:/path/to/jlfgr-1_0.jar uk.ac.gla.cmt.animatics.apps.aniplay.AniPlay

Note that the classpath path separator (the ':' character) differs between *nix and Windows operating systems.

Further information on setting the classpath can be found at http://java.sun.com/j2se/1.5.0/docs/tooldocs/#general

It may be possible to include an installer, or wrapper script at a later date to ease these steps.

Next

Congratulations! You should now be able to build and launch AniPlay.