Building

   I)   Building the Java Embedding Plugin
   II)  Building the MRJ Plugin JEP
   III) Tools for Deciphering Undocumented APIs and Classes

I) Building the Java Embedding Plugin

The source distribution of the Java Embedding Plugin is a "project"
that was created using the version of Apple's Project Builder that
gets installed with its December 2002 Developer Tools.  This is all
you need to build a Mac OS X 10.2.8 compatible version of the Java
Embedding Plugin (on OS X 10.2.8).  On Tiger (Mac OS X 10.4.X) you'll
need to use XCode, since Project Builder doesn't run on Tiger.  (XCode
is available on the Tiger installation DVD, and also as a free
download from Apple.)  On Panther (Mac OS X 10.3.X) you'll need to use
either XCode alone or a combination of Project Builder and XCode.  If
you need to preserve Project Builder compatibility (in order to
preserve compatibility with OS X 10.2.8), you'll need to run XCode
from the command line (i.e. "xcodebuild -buildstyle Development" in
the project directory).  Otherwise XCode will "upgrade" the project
files and make them incompatible with Project Builder.

Building the Java Embedding Plugin is pretty straightforward if you
want to support just one major OS version:  Make sure the appropriate
files are selected or deselected under "Other Sources" and its
subgroups.  Then choose "Build" from the "Build" menu.  The binary
(JavaEmbeddingPlugin.bundle) will be in the "build/" subdirectory (or
in the "build/Development/" subdirectory, if you're using XCode 2.1 or
later).  If you build only on OS X 10.4.9 or 10.5, your
JavaEmbeddingPlugin.bundle will only work with J2SE 5.0 or higher (not
with Java 1.4.2).  If you build on an Intel Mac your
JavaEmbeddingPlugin.bundle will be an Intel-only binary, and if you
build on a PPC Mac it will be a PPC-only binary.

  Mac OS X 10.2.8
    Java 1.4.1 Specific (everything)
    Java 1.4.1/1.4.2 Specific (everything)

  Mac OS X 10.3.9
    Java 1.4.2/1.5.0 Specific (everything at top level)
      Panther Specific (everything)
    Java 1.4.1/1.4.2 Specific (everything)
    Java 1.4.2 Specific (everything)

  Mac OS X 10.4.9 (or 10.5)
    Java 1.4.2/1.5.0 Specific (everything at top level)
      Tiger Specific (everything)
    Java 1.5.0 Specific (everything)

Supporting more than one major OS version in the same binary is
trickier.  (The reasons are that Apple made incompatible changes
between some of their Java versions, and still don't provide support
for cross-platform Java development in even their most recent version
of XCode.)  So is building a universal binary.

My binary distribution of the Java Embedding Plugin supports all
versions of Java available on Mac OS X 10.2.8, 10.3.X, 10.4.X and
10.5, and contains both universal binaries and PPC-only binaries.  To
build it I used three bootable partitions on a PPC Mac -- one running
OS X 10.2.8 and Java 1.4.1, one running OS X 10.3.9 and Java 1.4.2,
and one running OS X 10.4.9 and J2SE 5.0.  The first two partitions
contain a copy of Project Builder from the December 2002 Developer
Tools release.  The Panther partition also contains a copy of XCode
1.5 that I downloaded from Apple.  The Tiger partition contains a copy
of XCode 2.2.1 that I downloaded from Apple.

The following describes how I build the Java Embedding Plugin.  Other
ways may work, but I haven't tested them.

In Project Builder on OS X 10.2.8, choose "Clean All Targets" from the
"Build" menu.  Then make sure that all the files under "Java 1.4.1
Specific" and "Java 1.4.1/1.4.2 Specific" are checked, and that those
under the other "Java N.N.N" groups and subgroups are all unchecked.
Choose "Build" from the "Build" menu.  When the build process is
finished, uncheck all the files under "Java 1.4.1 Specific" and "Java
1.4.1/1.4.2 Specific", and check all those under "Java 1.4.2/1.5.0
Specific : Tiger Specific" and "Java 1.5.0 Specific".  Then quit
Project Builder.

In the project's build/JavaEmbeddingPlugin.build/
JavaEmbeddingPlugin.build/JavaClasses/jep/ directory, move all *.class
files whose names include the string "141" one level up (to the
build/JavaEmbeddingPlugin.build/JavaEmbeddingPlugin.build/JavaClasses/
directory).

In the project's build/JavaEmbeddingPlugin.build/
JavaEmbeddingPlugin.build/JavaClasses/apple/awt/ directory, move all
*.class files whose names include the string "141" two levels up..

In the project's build/JavaEmbeddingPlugin.build/
JavaEmbeddingPlugin/build/JavaClasses/sun/plugin/services/ directory,
move all *.class files whose names include the string "141" three
levels up.

Delete the following two files and one directory from the project's
build/JavaEmbeddingPlugin.build/JavaEmbeddingPlugin.build/ directory:

   JavaEmbeddingPlugin.hmap
   JavaFileList
   JavaClasses/sun

Reboot into OS X 10.4.9.  Open a Terminal session and run the
following command in the project's top directory:

   xcodebuild -configuration Development

Reboot into OS X 10.3.9.  Delete the following three files from the
project's build/JavaEmbeddingPlugin.build/JavaEmbeddingPlugin.build/
Objects-normal/ppc/ directory:

   AppletView.o
   Controller.o
   Handlers.o

Delete all files and subdirectories from the project's build/
JavaEmbeddingPlugin.build/JavaEmbeddingPlugin.build/PrefixHeaders/
directory.

Run Project Builder.  Make sure all the files under "Java 1.4.2/1.5.0
Specific" and its subgroups are checked _except_ those under "Java
1.4.2/1.5.0 Specific : Tiger Specific".  Also check those under "Java
1.4.1/1.4.2 Specific" and "Java 1.4.2 Specific".  Make sure all the
files under the other "Java N.N.N" groups are unchecked.

Quit Project Builder.  Open a Terminal session and run the following
command in the project's top directory.

   xcodebuild -buildstyle Development

Delete the following file from the project's build/
JavaEmbeddingPlugin.build/JavaEmbeddingPlugin.build/ directory.

   JavaEmbeddingPlugin.hmap

Move all those files whose names include "141" from the
build/JavaEmbeddingPlugin.build/JavaEmbeddingPlugin.build/JavaClasses/
directory back to the directories from which you moved them above.

Move (or copy) all files whose names include "142Tiger" or "150" from
directories under the build/JavaEmbeddingPlugin.build/Development/
JavaEmbeddingPlugin.build/JavaClasses/ directory to the appropriate
directories under the build/JavaEmbeddingPlugin.build/
JavaEmbeddingPlugin.build/JavaClasses/ directory.

Move (or copy) the "com" directory from the build/
JavaEmbeddingPlugin.build/Development/JavaEmbeddingPlugin.build/
JavaClasses/ directory to the build/JavaEmbeddingPlugin.build/
JavaEmbeddingPlugin.build/JavaClasses/ directory.

(Optional:  Delete the build/Development/ and build/
JavaEmbeddingPlugin.build/Development/ directories -- those created by
XCode 2.2.1 in Tiger.)

(Optional:  Use a Terminal session to delete all the .DS_Store files
from the project's build/ directory -- otherwise they will be included
in the JavaEmbeddingPlugin.bundle's *.jar files.)

Run Project Builder again.  Make sure all the files under the "Java
N.N.N" groups and subgroups are unchecked.  Quit Project Builder.  Run
the following command (in the Terminal session you opened above) in
the project's top directory.

   xcodebuild -buildstyle Development

The binary (JavaEmbeddingPlugin.bundle) in the project's "build"
directory should be a PPC-only binary that supports all available Java
versions on OS X 10.2.8, OS X 10.3.X and OS X 10.4.X.  Copy this
binary elsewhere (if you wish to preserve it).

Reboot into OS X 10.4.9.  Double-click on
JavaEmbeddingPlugin.xcodeproj in the i386/ directory -- this will
launch XCode.  Choose "Clean All Targets" from the "Build" menu.
After it finishes choose "Build".  When the build is finished the
JavaEmbeddingPlugin.bundle binary in the build/ directory should be a
universal binary.

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.  Before
JEP 0.9.3, that was also the version you needed to build.  Now any
version of Mozilla, Firefox or Camino will do, except for source trees
pulled from the trunk between the dates of 2004-04-02 and 2004-05-13
(the reason for this exclusion is apparent in the comment, in
MRJPlugin.h, above where nsPluginThreadPtr is defined).  Source
tarballs for released Mozilla versions are available at
ftp://ftp.mozilla.org/pub/mozilla.org/mozilla/releases/, in the "src"
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.  If you're
building a recent Mozilla.org browser (one that uses a .mozconfig
file), your .mozconfig file needs to make the "Objdir" the top level
directory -- otherwise you'll get lots of warnings about missing
files.

  mk_add_options MOZ_OBJDIR=@TOPSRCDIR@

The MRJ Plugin Carbon exists in the plugin/oji/MRJCarbon subdirectory.
It doesn't get built when you build Mozilla.  To build with my
additions and corrections, first 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, because it's incomplete -- the tarball
includes two additional "binary" (Unicode-encoded) resource files.)
Then run Terminal, change to the plugin/oji/MRJCarbon/plugin directory
and run "pbxbuild -buildstyle Development" (on OS X 10.2.8) or
"xcodebuild -buildstyle Development" (on OS X 10.3.X or 10.4.X).  Once
the build has finished, the binary (MRJPlugin.plugin) will be in
plugin/oji/MRJCarbon/plugin/build or (if you use XCode 2.2.1)
plugin/oji/MRJCarbon/plugin/build/Development.  This binary will be
PPC-only if you build on a PPC Mac, and Intel-only if you build on an
Intel Mac.

Currently it's only possible to build a universal binary in Mac OS X
10.4.X on a PPC Mac, and then only if you've first built a PPC-only
MRJPlugin.plugin using XCode 1.5 on OS X 10.3.9.  If you wish to
preserve your PPC-only binary, first copy it to another location.
Then double-click on MRJPlugin.xcodeproj in the plugin/oji/MRJCarbon/
plugin/i386 directory (this will launch XCode).  Choose "Clean All
Targets" from the "Build" menu and then choose "Build".  The
MRJPlugin.plugin binary in the plugin/oji/MRJCarbon/plugin/build
directory will now be a universal binary.

III) Tools for Deciphering Undocumented APIs

A) Class-dump

   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 also 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/.

B) nm -pm (or nm -pam)

   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.)

C) JReversePro

   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/.

D) JAD (aka JAva Decompiler)

   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.

   JAD's current home page is:
   http://www.kpdus.com/jad.html

E) Understanding Java Byte Code

   The locus classicus for deciphering Java bytecode is chapter 6 of
   Sun's Java Virtual Machine Specification
   (http://java.sun.com/docs/books/jvms/index.html).  I've also
   found the "Java Virtual Machine Online Instruction Reference" very
   useful (http://mrl.nyu.edu/~meyer/jvmref/ref-Java.html).

F) Sun's Java "Community Source"

   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://www.sun.com/software/communitysource/j2se/java2/index.html

