WOCompatibility project
Copyright 2008 David F. Elliott <dfe@tgwbd.org>

This Xcode project builds some libraries that make EOModeler and WebObjects Builder from the
Xcode 2.5 release run on Leopard.


--- Prerequisites ---

Download Libstreams from Apple:
http://www.opensource.apple.com/darwinsource/tarballs/apsl/Libstreams-25.tar.gz

Extract the tarball in the project root which will create a Libstreams-25 directory.


--- The libraries ---

libWOCompatibilityStreams:
This is just Libstreams from Apple.  It used to be part of libSystem until Leopard.  A lot of
Apple code like cctools still used it last I checked but apparently this is no longer the case
for the Leopard tools so Apple removed it.  It's very odd to be removing exported functions from a
library that claims to be ABI compatible but that's what Apple did.  To be sure you were never
officially allowed to use these functions since the Libstreams headers weren't installed.

This is mostly needed by WODevKit.framework


libWOCompatibilityObjc:
This is three categories which provide some outdated methods that various bits of the WO tools
need to function properly.  There's not much to it really.


libSystemWOCompatibility:
The original intent was for this to be an umbrella library for libSystem and
libWOCompatibilityStreams only.  WODevKit would then have its reference to libSystem modified
using install_name_tool and would thus be able to use all of the real libSystem functions
and all of the Libstreams functions without having to insert a library and force a flat
namespace.

Well, that does work well except I also needed the Objective-C categories so I figured I'd
fold that in as well and use it not only for WODevKit but also for EOModeler and WebObjects
Builder.  Doing it this way the applications are able to start with these libraries
without needing any DYLD_* environment variables at all.


--- The scripts ---

There are three scripts that need to be run in order as root (e.g. via sudo) to build a
WebObjectsLegacyDevelopment.pkg suitable for installation on Leopard.

woroot-create.sh:
Mount the Xcode 2.5 DMG and run this script with sudo to create a /tmp/WebObjectsLegacyDevelopment.dst
containing all of the WO goodness you need without any of the stuff present in Xcode 3.0's
version of WebObjectsDevelopment.pkg.

woroot-fixup.sh:
Make sure you've built the WOCompatibility.xcodeproj before running this script.  Again, simply
run with sudo and it will install the various dylibs as well as fixup the install names of certain
binaries.  It also changes the WOJavaPBXHelper.pbplugin's Info.plist to indicate GC compatibility.
This works because WOJavaPBXHelper.pbplugin was compiled with GC support.

woroot-package.sh
This one is simple.  You may or may not need sudo (actually you probably don't).  This creates a
regular old .pkg bundle you can then open to install the WO tools into the normal places.


--- Additional notes ---

You must use this with Xcode 3.0 on Leopard.  You must have Xcode 3.0 installed in the usual
/Developer folder.  None of the other installed library names are changed and therefore all of
the EO/WO frameworks link against the Xcode 3 private frameworks (e.g. the DevTools* series of
frameworks in /Developer/Library/PrivateFrameworks).

Note that although those frameworks seem to be ABI compatible (e.g. these old tools will happily
link with the Xcode 3 frameworks at runtime) the 2.5 vs. 3.0 frameworks only seem to talk to
their respective Xcode application.  Therefore you cannot expect WebObjects Builder's variable
browser to work if your project is open in Xcode 2.5.

This isn't really a problem though as I have only found one bug with WebObjects Builder talking
to Xcode 3.   And of course Xcode 3 is newer, so why not use it?

If you are really interested in making the tools work with Xcode 2.5 you can use install_name_tool
to change all references to frameworks in "/Developer" to "/Xcode2.5" (or wherever you installed
Xcode 2.5).  You have to do this for every application and every framework in this package.


--- Bugs ---

We all know that EOModeler and WebObjects builder have their fair share of bugs.  Sorry, I
haven't fixed any of these but frankly I figure you're already used to them by now.  There is
one additional bug though and it's a little odd.  Once you open a web component (.wo bundle)
related to an Xcode project you must leave at least one web component related to any Xcode
project open at all times in WebObjects Builder.

If you close the last Xcode-related component then try to open one again, Xcode will pop up
an error dialog and WO Builder will hang.  To avoid this, either leave one component
open or if you accidently close the last one, simply quit WebObjects Builder before opening
another component.  For instance, you may create yourself a default WebObjects Application
project, open it in Xcode, open its Main.wo from Xcode and minimize it.  Then just remember
to never close it.

All I can figure is that Xcode sees the last component close and thus figures the external tool
no longer needs the project.  WebObjects builder seems to have a different idea and reuses its
existing project connection.  Xcode gets the message and doesn't know what to do with it since
it has already forgotten about the connection.  WO Builder hangs because Xcode fails to respond.

If this is really the case, then theoretically it might be fixable by pruning connections on the
WO Builder side.  I haven't done any real research on this yet but that's probably where I'd
start if I planned on fixing this bug.

--- Other notes ---
The Apple-provided Xcode 3 WebObjectsDevelopment package doesn't put its templates in the right
location for new versions of Xcode (both 2.5 and 3.0 actually).  To remedy this situation run
the following commands:

mkdir -p ~/Library/Application Support/Developer/Shared/Xcode/File Templates
mkdir -p ~/Library/Application Support/Developer/Shared/Xcode/Project Templates
ln -s "/Library/Application Support/Apple/Developer Tools/File Templates/WebObjects" ~/"Library/Application Support/Developer/Shared/Xcode/File Templates/WebObjects"
ln -s "/Library/Application Support/Apple/Developer Tools/WebObjects Support" ~/"Library/Application Support/Developer/Shared/Xcode/Project Templates/WebObjects"

Note that the File Templates should then basically work as before but the Project Templates work
differently.  What is supposed to happen is that WOAssistant.pbplugin enhances the Xcode New
Project dialog to include a WebObjects choice that it manages.  It then uses the files in
the WebObjects Support folder as a base and adds in a few things based on your choices in its
assistants (a.k.a. wizards).

What instead happens here is that you tell Xcode directly about the projects and it will create
them for you by basically just copying the files to a new directory and fixing up some names.
It works well enough.  To get a D2W app just copy the appropriate PageWrapper.wo and MenuHeader.wo
(e.g. BAS, NEU, WOL) to your project and write your Main.wo to bring up D2W as you see fit.
If you're using D2W, you presumably already know how to do this or you can just grab the files from
another one of your projects which is what I tended to do most of the time anyway.

