Building the Java Embedding Plugin

  1. Building the Java Embedding Plugin
  2. Building the MRJ Plugin JEP
  3. Tools for Deciphering Undocumented APIs and Classes
  4. Return to Java Embedding Plugin Readme

I) Building the Java Embedding Plugin

The source distribution of the Java Embedding Plugin is a "project" that was created using XCode 2.5 on OS X 10.4.11 (Tiger). XCode version 2.5 or greater is required to build it. Choose "Build" from the "Build" menu. The binary (JavaEmbeddingPlugin.bundle) will be in the build/Release subdirectory, and will be a universal binary (supporting both ppc and i386 Macs).

II) Building the MRJ Plugin JEP

Doing this is rather a pain, because you first have to build Mozilla itself from source. The MRJ Plugin JEP derives from source for the MRJ Plugin Carbon included with Mozilla 1.6's source tarball. But pretty much any recent version of Firefox, Seamonkey or Camino will do. Source tarballs for released Firefox versions are available at ftp://ftp.mozilla.org/pub/mozilla.org/firefox/releases/, in the source subdirectory for the specific release whose source you want. Good build instructions (including for Mac OS X) are available at http://developer.mozilla.org/en/docs/Build_Documentation.

Note that your .mozconfig file needs to make the Objdir the top level directory -- otherwise you'll get lots of warnings about missing files. This isn't what Mozilla.org's build instructions recommend, so you probably won't be able to use a build you've already made.

mk_add_options MOZ_OBJDIR=@TOPSRCDIR@

Note also that you won't be able to use recent "trunk" (aka mozilla-central) builds: The MRJ Plugin Carbon has been removed from these builds, along with APIs that it needs to run.

The MRJ Plugin Carbon exists in the plugin/oji/MRJCarbon subdirectory. It doesn't get built when you build Mozilla. To build it with my additions and corrections, you need XCode 2.5 or greater.

  1. Untar the MRJ Plugin JEP source tarball in the appropriate directory, so that the original files get overwritten.

    My source distribution also includes a patch file, but that's just for reference.

  2. Find the MRJPlugin.xcodeproj project in the plugin/oji/MRJCarbon/plugin directory and double-click on it. Don't open the old MRJPlugin.pbproj project -- doing so may overwrite the new MRJPlugin.xcodeproj project.
  3. Choose "Build" from the "Build" menu.

    The binary (MRJPlugin.plugin) will be in the plugin/oji/MRJCarbon/plugin/build/Release directory, and will be a universal binary (supporting both ppc and i386 Macs).

III) Tools for Deciphering Undocumented APIs

  1. Class-dump

    2. This program is a prerequisite for doing any serious Cocoa programming. Use it to "dump" the equivalent of a header file for any Cocoa binary. For the purposes of the Java Embedding Plugin, the most interesting binaries are the AppKit framework (/System/Library/Frameworks/AppKit.framework/AppKit) and AWT's Java native library (/System/Library/Frameworks/JavaVM.framework/Libraries/libawt.jnilib). You might also want to take a look at the WebKit framework (/System/Library/Frameworks/WebKit.framework/WebKit). Apple releases source for most (though not all) of the WebKit at http://webkit.org/.

    Class-dump is available at http://www.codethecode.com/projects/class-dump/.

  2. nm -pm (or nm -pam)

    3. I'm not sure whether nm (which is a mnemonic for "name") is included with a standard OS X installation, or whether you need to install one of the Developer Toolkits. It displays the symbols in an executable or library. The two nm parameters that I find most useful are -p (which causes the symbols to be displayed in the order in which they occur in the binary) and -m (which makes nm use a more verbose display for Cocoa symbols, like that used by class-dump). (Symbols that appear together in the binary are often used together in the code. The -p parameter preserves this information.)

  3. JReversePro

    4. This program claims to be able to "decompile" Java classes to a human-readable form of bytecode or "disassemble" them to Java source code. (Odd terminology -- the reverse of what you would expect.) I've only ever been able to get it to "decompile" to bytecode -- but that's still extremely useful.

    One serious limitation is that JReversePro (which hasn't been updated for a while) can't read .class files created by J2SE 5.0/1.5's javac compiler. But JAD (see next item) can usually do a pretty good job of this ... though it's also quite old, and can't ready any Java-1.5-specific (or even Java-1.4-specific) structures.

    JReversePro is a Sourceforge project, available at http://jrevpro.sourceforge.net/.

  4. JAD (aka JAva Decompiler)

    5. This program can either disassemble Java classes to human-readable bytecode or decompile them to Java source code.

    Inevitably, its decompilation to source code isn't always totally correct. And (because it's quite old) it doesn't understand Java-1.5-specific (or even Java-1.4-specific) structures in .class files. (As far as I know I've never encountered any such structures, so this seems not to be a serious problem.)

    But unlike JReversePro it doesn't refuse to work on .class files created by an unsupported versions of javac. And it's much easier to use JAD to disassemble/decompile many .class files at once.

    http://en.wikipedia.org/wiki/JAD_(JAva_Decompiler)
    http://www.varaneckas.com/jad

    JAD's last home page of record is http://www.kpdus.com/jad.html -- which is no longer accessible. Fortunately Tomas Varaneckas has created a mirror from which many of the downloads are still available (http://www.varaneckas.com/jad).

  5. Understanding Java Byte Code

    6. The locus classicus for deciphering Java bytecode is chapter 6 of Sun's Java Virtual Machine Specification. I've also found the "Java Virtual Machine Online Instruction Reference" very useful. If you don't find it at this URL, do a Google search on its title.

  6. Sun's Java "Community Source"

    7. Sun makes available the full source code for its JVM. The license used to be very restrictive -- practically speaking it prevented you from making any changes or (presumably) from using any of it in your code. Sun is now in the process of adopting the GPL. But whatever the license terms, this source code is extremely useful as a reference for Sun's undocumented classes. Apple's JVM isn't identical to Sun's (which is why you also need to see Apple's Java bytecode). But it's often very close.

    http://java.sun.com/j2se/jrl_download.html
    http://download.java.net/jdk6/source/
    http://download.java.net/openjdk/jdk7/

IV) Return to Java Embedding Plugin Readme