decatur/j2js-compiler

#j2js-compiler

A Java Bytecode to JavaScript Cross-Compiler.

##Installation

1. You need to install this and the following projects

• https://github.com/decatur/j2js-compiler
• https://github.com/decatur/j2js-jre
• https://github.com/decatur/j2js-agent

1. Build all projects. An Eclipse project description is included.

2. Optionally install https://github.com/decatur/j2js-demos

##Building your project

It is highly recommended that you compile your project (i.e. generate class files) against j2js-jre, and not rt.jar. This way you avoid link errors (missing classes or methods) at the cross-compile stage. See the warning at the bottom of the document.

##Usage

java -cp <RUNTIME_CLASSPATH> com.j2js.J2JSCompiler <basedir> <CROSS_COMPILE_CLASSPATH> <entryPointClassName> <targetLocation>

###<RUNTIME_CLASSPATH>

This is the standard Java classpath. The cross-compiler needs the project j2js-compiler, bcel and commons-io on its classpath.

###<basedir>

All non-absolute paths are relative to the basedir.

###<entryPointClassName>

The name of the class to cross-compile. This class must have a method public void main(java.lang.String[]).

The compiler cross-compiles the main method and all other methods which are called from the main method.

###<CROSS_COMPILE_CLASSPATH>

This classpath must contain all classes whose methods are referenced by the main method. In normal operation, this classpath consists of

• the j2js-jre classes directory or jar
• the j2js-agent classes directory or jar
• the classes directory of your personal project

###<targetLocation> All cross-compiled code is stored in the target location. It is one or more JavaScript file starting at 0.js. Only this initial file must be included in your web page with <script src='targetLocation/0.js'/>.

###Example

Suppose the directory layout is

|- j2js-compiler
|- j2js-jre
|- j2js-agent
|- my-project
     |- target
         |- assemblies
             |- 0.js
             |- 1.js
             |- 2.js ...

and you want to cross-compile class org.mydomain.my-project.MyClass. Then

java -cp ../j2js-compiler/libs/commons-io-1.4.jar;^
../j2js-compiler/libs/bcel-5.1.jar;^
../j2js-compiler/target/classes ^
com.j2js.J2JSCompiler . ^
target/classes;../j2js-jre/target/classes;../j2js-agent/target/classes ^
org.mydomain.my-project.MyClass target/assemblies

will create the assemblies.

##Warning The project j2js-jre contains a hand-crafted version of the Java Runtime Environment. Do not put Java/jreX/lib/rt.jar into the <CROSS_COMPILE_CLASSPATH>.

##Limitations The cross-compiler is able to translate any legal Java Bytecode. However, naturally, the compiler cannot support the Java Native Interface (JNI).

##Cross Compiling Scala The current Scala version uses JRE classes such as ClassLoader or SecurityContext even in base Scala classes. These JRE classes do not make sense in a web agent context and are therefore not implemented in j2js-jre.

A workaround would be to hand-craft a subset of Scala classes, avoiding dependencies to JRE classes such as ClassLoader. But this is a lot of work.

So, sadly, we cannot support Scala under this circumstance.