NAME

Java::Build::JVM - starts one JVM for compiling

SYNOPSIS

    use Java::Build::JVM;

    my $compiler = Java::Build::JVM->getCompiler();
    $compiler->destination("some/path");

    $compiler->classpath("some/pathto/jar.jar:some/other/path/javas");
    $compiler->append_to_classpath("something/to/add/to/previous/path");

    $compiler->compile([ qw(list.java of.java programs.java) ]);

DESCRIPTION

This class starts a single JVM which it then helps you contact for compiling tasks. This is the most important feature of the popular Ant build tool. Using this class, you can effectively replace Ant, and its notoriously unmaintainable build.xml files, with Perl scripts. Most Ant tasks are already built in to Perl with far more flexibility than Ant provides.

To obtain a compiler, use this module, then call getCompiler. It has that name to prevent conflicts with the Java new keyword.

Once you have a compiler, you may change the destination of subsequent compiles from the location of the source files to a directory of your choice using the destination method. You can create or append to a classpath with the classpath or append_to_classpath methods. Note that your CLASSPATH environment variable still works in its usual way.

Finally, once you have the destination and classpath set, you can compile a list of files by passing them to the compile method. Note that they need to be in an array reference (if you don't know what that means, put the list in square brackets).

Note that you must have tools.jar in your CLASSPATH when you run your script. Without that, JVM.pm will not be able use Inline::Java. The classpath you use inside the script may be the same or different than your environment variable, depending on how you use the classpath and append_to_classpath methods.

Since Sun has, in its finite wisdom, chosen to deprecate the compiling methods that javac uses, there will be one warning for each time you call compile. It will say something like this:

    Note: sun.tools.javac.Main has been deprecated.
    1 warning

This warning is not a problem in Java 1.4.

METHODS

getCompiler

This serves as the constructor for this class. It might be called new, but that is a reserved word in Java which Inline::Java translates into a method name. To avoid confusion, I changed the name. This also leaves open the possibility of turning this into a generic compiler factory which could give you a javac, jikes, or other compiler at your option. For now, only javac is supported.

There are no arguments to this method (except the class name, but Perl does that for you).

The object you receive provides indirect access to javac. Only one JVM is ever started.

classpath

This is a dual use accessor. It always returns the classpath, but if called with an argument, it changes the classpath first. The argument can be anything, including "". This allows you to remove the classpath's value and its effect.

See also append_to_classpath below.

append_to_classpath

Pass a single jar or directory or a colon separated list of jars and/or directories. These will be appended to the end of the classpath. The full classpath is returned.

destination

This is a dual use accessor. It always returns the destination, but if called with an argument, it changes the destination first. The destination (if defined) is used during compile as if you invoked javac at the command line as:

    javac -d destination ...

sourcepath

Dual use accessor for -sourcepath command line option to compiler.

debug

Dual accessor for things which go after -g:. If you never call this, -g is left out. If you do call it, you must supply a valid value. No checking is done here.

compile

This is the operative method. Give it a list of source files to compile (probably with path names attached). It will ask the single JVM to compile the files. The compiler uses the same classes as javac. Any classpath or destination are passed to it.

Path names need to be either absolute, or relative the directory from which the script launched. I have found no way to change the directory used by the JVM housing the compiler after it starts.

Returns true if the compile worked wihtout errors and dies setting the $@ to the javac error message otherwise.

REQUIRES

Inline::Java

BUGS

The JVM will not be moved. Once it starts, I cannot get it to change directories. This affects what source files you can give it. In general, full paths work, but you must supply a proper classpath. You can also supply paths which are relative to the directory from which the script started. In that case, a classpath is probably required. If you know how to fix this, please let me know.

Sun has deprecated this approach to compiling, so you will see deprecation warnings. Since this approach is the one used in Ant, Sun can't very well turn it off, so the warning is that much more annoying. See the DESCRIPTION section for the text of the warning on Red Hat Linux 8.0 with SDK 1.4.1_02.

cpanm Java::Build

perl -MCPAN -e shell
install Java::Build