What is it?

What does it do?

Given a WebObjects Application package (a .woa directory), woaFrameworkMerger.pl copies all of its referenced nonsystem frameworks into the .woa itself, making the .woa stand-alone (no longer dependant on external frameworks).

Technically, it:

• Reads the .woa/Contents/MacOS/MacOSClassPath.txt file to discover all of the .woa's referenced frameworks.
• Creates a new directory, "Frameworks", inside .woa/Contents (if one didn't exist before)
• Copies all referenced nonsystem frameworks (those are frameworks referenced with paths beginning with /, .. or LOCALROOT) into the ..woa/Contents/Frameworks directory if:
  • it didn't already exist -or-
  • the original referenced framework is newer than the local copy
• Rewrites ..woa/Contents/MacOS/MacOSClassPath.txt and its evil twin, .woa/Contents/Unix/UnixClassPath.txt, to point to the freshly copied internal frameworks.

Why would you want to do that?

• I've had too many experiences where a framework mod made my app unable to restart.
• Deployment simplicity (one package to tarball and upload).
• Dependencies. Often I want to rev a framework for one app, but the others don't need a redeploy.
• Locality. Nothing to install system-wide, easy to install, remove and archive an app.
• My script allows relative path referencing of frameworks in projects, something that otherwise fails.

How do I use it?

perl woaFrameworkMerger.pl /path/to/MyApp.woa

(the path can be relative)

Can I integrate it with Project Builder?

Yes -- in fact, I recommend it! Just add a final "Shell Script" Build Phase to your project's top-level target. It should look something like this:

Here, I put a symbolic link in ~/Library to point to where woaFrameworkMerger really lives. But it's cool just to put the script there as well.

This all sounds very Unixy. What about Windows support?

woaFrameworkMerger.pl currently does not support Windows. This is largely because I don't know how .woa/Contents/Windows/CLSSPATH.TXT or .woa/Contents/Windows/SUBPATHS.TXT work, and I lack the time and motivation to spend cycles learning, coding and testing. If you want to add Windows support, please be my guest! Doesn't look too hard...

What's this woaFrameworkAndWSResourceMerger.pl?

It's a descendant of woaFrameworkMerger.pl, written by Giorgio Valoti, that copies over your web server resources as well as your frameworks. To quote Giorgio:

I've made a quick and dirty hack to merge web server resources using your script.

I copy *all* the frameworks' web server resources, so I can set the property WOFrameworksBaseURL to /WebObjects/<APP_NAME>.woa/Contents/Frameworks without subclassing the resource manager. I use the modified version with a different PBX setup. I've created a new legacy target with a simple shell script:

pbxbuild -target ${PRODUCT_NAME} -buildstyle Deployment build
pbxbuild -target ${PRODUCT_NAME} -buildstyle WebServer build
perl ~/Developer/Tools/woaframeworkmerger/current ${DSTROOT}${LOCAL_LIBRARY_DIR}/WebObjects/Applications/${PRODUCT_NAME}.woa

This way, I avoid a potential problem with the script when used as an additional aggregate target build phase, namely the scripts does not find the web server distribution directory.

Use it the same way you use woaFrameworkMerger.pl — woaFrameworkAndWSResourceMerger.pl just does more. It probably makes sense to merge these two scripts eventually, and provide switch-based control over its actions, but we'll have to save that for another day.