Rebuilding the MacBinary Toolkit 2 for Java

Last revised: 17Feb2003 GLG

Table of Contents

• General Notes
• Recompiling the Mac OS Implementations
• Packaging for Redistribution
• Rebuilding the Demo Apps

General Notes

The platform-neutral Java source needs no special handling. You can recompile it on any platform compliant with JDK 1.1 or later. The only platform-specific source is in the specific implementations.

The implementation of:
    glguerin.io.imp.gen.GenericForker
need to be compiled against the included MRJToolkitStubs.jar file. This imp also needs to be distributed with MRJToolkitStubs.jar, either bound into the same JAR as the implementation, or otherwise available in the class-path. The implementations of PlainForker and JavaOnlyForker in the same package are completely platform-neutral.

The Mac OS implementations in the package tree:
    glguerin.imp.mac.*
need additional special handling outlined below. Since these implementations are Mac-specific, and won't ever be loaded on non-Mac platforms, you don't have to bundle additional classes with them. Either the classes they reference will be present in MRJ on Mac OS, or the implementations will never be loaded, so it doesn't matter what other classes they reference.

Recompiling the Mac OS Implementations

The Mac OS implementations must be compiled against classes that are only available under Mac OS. Most of these classes are distributed as part of the normal MRJ installer, or are present in a default install of Mac OS X. A small number of classes that are not provided with every MRJ have been included with the MacBinary Toolkit distribution.

You should normally only compile against classes from MRJ 2.2 or higher. Older versions of MRJ may or may not work -- I have only tested compiling against MRJ 2.2.

Each Mac OS implementation is compiled against one or more ZIP or JAR files. Special considerations are outlined for each implementation.

• glguerin.io.imp.mac.jd1.* -- the JDirect-1 implementations
  These implementations are for older MRJ versions that don't have JDirect-2. You can safely compile the implementation against MRJ 2.2, even though MRJ 2.2 has JDirect-2. You should disable deprecation warnings before compiling, since all of JDirect-1 is deprecated in MRJ 2.2. Though compiled against MRJ 2.2, the jd1 implementation will run on MRJ versions as far back as MRJ 2.0. This was the last MRJ that ran on 68040 machines, so the jd1 implementation is primarily for them.
    Compile against:
      MRJClasses.zip from a normal MRJ 2.2.* install.

• glguerin.io.imp.mac.jd2.* -- the JDirect-2 implementations
  These implementations are for any Java-capable version of classical Mac OS running on a PowerPC CPU. All such machines should be running MRJ 2.2.5 or higher, since that version of MRJ works over a large range of Mac OS versions (I've tried it on Mac OS 7.6.1 through 9.0). Though Apple does not officially support MRJ 2.2.5 as far back as Mac OS 7.6.1, MRJ does work that far back, at least in my experience. The big hassle is that you have to drag-install MRJ, since the installer in Apple's MRJ distribution refuses to install on a Mac OS that old.
    Compile against:
      MRJClasses.zip from a normal MRJ 2.2.* install.

• glguerin.io.imp.mac.ten.* -- the JDirect-based Mac OS X implementations
  These implementations are for Mac OS X, 10.0 or higher. They use JDirect-3 and Carbon. The source can be compiled on platforms other than Mac OS X, although the classes only run on Mac OS X. If the source is compiled on Mac OS X, it may not work when run on a JDK 1.1 JVM. That's because you will have compiled against the newer JDK 1.3 versions of the Java classes, and older JVMs don't have all the features of newer ones.

  To compile on classical Mac OS or Mac OS X, for JDK 1.1:
    Compile against:
      MRJClasses.zip from a normal MRJ 2.2.* install.
      MBXCarbonCore.jar included with the MacBinary Toolkit.
  The classes in MBXCarbonCore.jar are the minimal set of Mac OS X classes needed to compile the implementation on platforms other than Mac OS X itself.

  To compile on Mac OS X for JDK 1.3 or higher:
    Compile against:
      ui.jar found in the normal Mac OS X install at:
        /System/Library/Frameworks/JavaVM.framework/Classes/ui.jar
  This JAR contains the Java classes unique to Mac OS X. Despite its name, it contains far more than just user-interface classes.

• glguerin.io.imp.mac.macosx.* -- the JNI-based Mac OS X implementations
  These implementations are for Mac OS X, 10.1 or higher. They use JNI and Carbon. Only the CarbonMacOSXForker imp requires a Carbon event-loop. The native code works in Cocoa-Java apps, or in plain Java apps. Just don't call the code that needs a Carbon event-loop under Cocoa (the TinWatcher class).

  The source consists of Java and C source-files. The Java and C source can be revised and compiled separately, as long as the native-methodAPIs remain the same. That is, you can change the Java code and recompile the classes, without changing the already-compiled JNI-library, as long as you don't change any of the native method APIs in the Java source.

  The Java source can be compiled on any platform, even JDK 1.1. The C source should be compiled on Mac OS X 10.1 or higher, or on a cross-compiling environment targeting Mac OS X 10.1 or higher. The C code uses the Mac OS FSRef-based API, also Alias Manager, and Icon Services. It is not portable to other OSes.

  To recompile the Java on any platform, just compile it normally. If you changed any native method API, you'll need to regenerate the JNI-header files and edit the C source accordingly.

  To recompile the C, compile the one C source file "MacOSXForkerIO.c". It #includes the JNI-headers it needs, and the system-framework headers. Other than "MacOSXForkerIO.c", all the other supplied C files are machine-generated JNI-headers.

  If you use an IDE such as ProjectBuilder or CodeWarrior, you may want to set up these two imps under a separate target or even a separate project. All the other imps use the 'native' keyword in a JDirect context, so they have no corresponding C source, nor JNI-headers, nor any JNI component. These two imps use the 'native' keyword in a JNI context, which means there is a corresponding C-library source, generation of JNI-headers, and other things that JDirect obviates.

Packaging for Redistribution

The GenericForker implementation is compiled against MRJToolkitStubs.jar. You must also include this ZIP in your executable redistribution, or the generic imps will fail with a "Class not found" error. The easiest thing to do is simply merge MRJToolkitStubs.jar into your redistribution's JAR file. Another option is to include it as an additional component of the classpath, though this is needlessly complex from a user's perspective.

DO NOT redistribute the MBXCarbonCore.jar classes with any executable-only redistribution. They are only intended for recompiling the Mac OS X imp, and will only make your executable redistribution pointlessly larger than it needs to be.

The MacOSXForker and CarbonMacOSXForker imps have a separate JNI-library file that contains the native code. This library-file should be placed in Contents/Resources/Java within an app-bundle, or in the same place the JAR is placed in a Java extensions location. Basically, wherever you put the JAR, put the JNI-library there, too.

Rebuilding the Demo Apps

The classical Mac OS apps were created using JBindery from the MRJ SDK. The creator-IDs are 'MBcx' for Converter, 'MBsx' for Spy. (I have not officially registered these creator ID's with Apple yet.) Be sure to include the relevant resource-file from the "Resources for droplets" folder when you rebuild the apps.

You can also rebuild the classical Mac OS apps using MRJAppBuilder from the MRJ SDK. I have included the configuration properties files to do this in the "Resources for droplets" folder. These properties files are configured to build a merged application. That means you must add an appropriate JAR-file to MRJAppBuilder's "Files to merge" list, along with the appropriate "Resources-XXX.rsrc" file.

I chose to distribute the classical Mac OS apps as JBindery-built apps, rather than as apps built by MRJAppBuilder. This is mainly because JBindery-built apps will work on older versions of MRJ, as far back as MRJ 2.0. Apps built by MRJAppBuilder, on the other hand, will only work under MRJ 2.2 or higher. This would prevent the apps from working on older platforms, such as 68040 machines under MRJ 2.0, and I didn't want to do that.

The Mac OS X apps were originally created using MRJAppBuilder on Mac OS X, a tool that's included with the Mac OS X Developer Tools. Thereafter, I edited the configuration files using the Mac OS X tools "Property List Editor" for the Info.plist, and "TextEdit" for the MRJApp.properties file. "Property List Editor" is in Apple's Developer Tools install. Double-clicking Info.plist launches the right program, but you have to drag-n-drop MRJApp.properties onto TextEdit. If you understand XML, you can edit Info.plist with TextEdit, or with your XML editor of choice. To gain access to the files bundled into the app itself, contextual-click on the application and choose the "Show Package Contents" contextual-menu item to see the internal anatomy of the app-bundle.

To Greg's Home Page
To Greg's Software Page