How many times has this happened to you? You've written a little Java utility, or maybe even a more complex application, and you want to create Mac OS X application bundle for easy distribution.
You'd like to be able to do it automatically from your build process, but you're forced to go run the Apple Jar Bundler and tweak all the settings manually every time you build.
Well no more! JarBundler is a feature-rich Ant task which will create a Mac OS X application bundle from a list of Jar files and a main class name. You can add an Icon resource, set various Mac OS X native look-and-feel bells and whistles, and maintain your application bundles as part of your normal build and release cycle. It is free software licensed under the GNU General Public License.
This release is based on the earlier work of Seth Morabito.
Source and binary, all platforms (ZIP): | jarbundler.zip |
Source and binary, all platforms (TAR): | jarbundler.tar.gz |
Move the file jarbundler-2.1.0.jar
into /usr/share/ant/lib or
into your local ANT lib directory. Remove any older versions at this time.
NB: This location used to be /Developer/Java/Ant/lib. You
may have to try both to get things to work.
To use the Jar Bundler Ant Task, create a task definition in your
ANT build.xml file like this: Now, from a target, you can add the "jarbundler" task. The nested jarfileset element specifies a
FileSet.
All
files included in this fileset will be included in the application
bundle and added to the app bundle classpath. Only required if the
jars attribute is not set. The nested jarfilelist element specifies a
FileList. All
files included in this filelist will be included in the application
bundle and added to the app bundle classpath. Only required if the
jars attribute is not set. This ANT DataType element allows developers to specify java properties
for the info.plist. This DataType repalces many jarbundler tag attributes. However, if
a deprecated attribute is used it will take precedent over a javaproperty. This was done
to maintain backward compatibility with earlier versions of jarbundler.
This task takes name/value pairs:
Additional Java Properites can be found in the Apple Developer Connection document:
Apple Java Properties for JDK 1.4+
The nested execfileset element specifies a
FileSet. All
files included in this fileset will be added to the application
bundle's "Contents/MacOS" directory and set executable. Optional. The nested execfilelist element specifies a
FileList. All
files included in this filelist will be added to the application
bundle's "Contents/MacOS" directory and set executable. Optional. The nested resourcefileset element specifies a
FileSet. All
files included in this fileset will be added to the application
bundle's "Contents/Resources" directory. Optional. The nested resourcefilelist element specifies a
FileList. All
files included in this filelist will be added to the application
bundle's "Contents/Resources" directory. Optional. The nested javafileset element specifies a
FileSet. All
files included in this fileset will be added to the application
bundle's "Contents/Resources/Java" directory. Optional. The nested javafilelist element specifies a
FileList. All
files included in this filelist will be added to the application
bundle's "Contents/Resources/Java" directory. Optional. The nested extraclasspathfileset element specifies
a FileSet.
All files included in this fileset will be added to the
application bundle's classpath, but the files will not be
copied into the bundle itself. This allows you to specify external
system classpath dependencies without bundling the resources. Resources
can be files or directories. Optional. The nested extraclasspathfilelist element specifies
a FileList.
All files included in this filelist will be added to the
application bundle's classpath, but the files will not be
copied into the bundle itself. This allows you to specify external
system classpath dependencies without bundling the resources. Resources
can be files or directories. Optional. Note that in fact the files are installed in locations which have the same relation
to either Contents/MacOS or Contents/Resources directories as the
files in the FileSet or FileList have to the 'dir' attribute. Thus in the case:
the *.jnilib files will be installed in Contents/Resources/ppc
A minimal example might look like this This will create a Mac OS X application bundle called "MyApp.app" in
the directory "release" using a JAR file which was created in the "build" directory. You can use FileSets or FileLists for more complex builds. For example: Associating Documents with your Application Fix bug when using localized Help Books, the menu application would appears as (null)
Corrected the encoding for the Info.plist XML file so that the copyright character,
amongst others, are processed correctly. Thanks to Christian Roth for both pointing out
the encoding problem and providing a one line solution!
Added bundle attribute to documenttype task in order to specify
documents which are in reality directory trees, yet treated as a single entity by the Finder.
Thanks to Deerwood McCord Jr. for the implementation.
Added mimetypes attribute to documenttype task in order to specify
Multipurpose Internet Mail Extensions (MIME) types for the document.
Thanks to Deerwood McCord Jr. for the implementation.
No longer required to delete the existing application bundle, i.e. .app directory,
before invoking the jarbundler task. This is now done by the task itself.
The filename of the stubfile attribute will be used as the Java Application Stub filename
within the bundle and for the value of the CFBundleExecutable key in the Info.plist.
This usage provides a way for each Java application to have a uniquely named executable
filename. This is useful when using the UNIX 'top' command to distinguish applications.
Thanks to Deerwood McCord Jr. for the this idea.
Info.plist is built internally as a DOM tree instead of concatenating strings. This
resulting DOM tree is serialized into the file using two space indentation and one tag per line.
Improved readablity of the verbose output. The contents of the Info.plist file
is controlled by the showPlist attribute.
Reorganize JarBundler documentation by splitting out advanced features
Added <documenttype> nested task so that file associations can be set up
for the application. Thanks to Dan Stowell a sample "Info.plist" file containing
document type entries. Added <javafileset> and <javafilelist> nested tasks,
which mirror <resourcefileset> and <resourcefilelist>, in
order to add files to the Contents/Resources/Java directory Added Apple Help Book support by...
Thanks to Will Lowe for an example Help Book project with JNI code.
Split the "Hello, World" example into a complex build which associates
document types and uses a Help Book, and a simple minimal build
Reorganize 'example' source directory to include Objective-C JNI code and use
package structure for "Hello, World" application rather than putting everything
Added <resourcefileset> and <resourcefilelist> nested elements,
which mirror <execfileset> and <execfilelist>, and add files to
the Contents/Resources directory.
Added build attribute to jarbundler task. See also version
and infostring for usage.
Added jar attribute to jarbundler task.
Added shortname attribute to jarbundler task. See also name
for usage.
JarBundler is now a SourceForge project!
Changed task package to net.sourceforge.jarbundler
Changed the package from 'com.loomcom.ant.tasks.jarbundler' to
'com.informagen.ant.tasks.jarbundler' so that version 1.4 can remain installed without
conflict
Added a nested DataType called "javaproperty" so that new properties can be added
by end users and deprecated properties can be removed. Former jarbundler
tag atributes are still available but have been deprecated in favor of their
'javaproperty' equivalents.
Currently, a jarbundler tag attribute overrides a javaproperty tag. This was
done to maintain backward compatibility with version 1.4
Fixed a bug that was causing application arguments not to be set. Added "extraclasspath" attribute, and "extraclasspathfileset" and
"extraclasspathfilelist" nested elements, allowing users to
optionally add external resources to the runtime classpath which will
not be copied into the application bundle at build time. Removed
some Java 1.4 requirements to allow building the sources under Java
1.3. Clarified the documentation. Added Ant property setters for "bundleid" and "developmentregion".
Bundleid has no default, and is optional. Developmentregion defaults
to "English", and is also optional. Fixed documentation on the
website. Fixed several minor bugs, and improved BuildException messages.
Jarfilesets and execfilesets now preserve directory structure
when copying. Thanks to Trevor Harmon for pointing out bugs and
enhancements. "execs" and "jars" can now be set using embedded FileSets or
FileLists. Added a "verbose" flag, which currently sees limited use.
Added "chmod" attribute, which can be used to point to a non-standard
'chmod' command (not normally needed!) Increased error checking.
Hopefully, the code is now robust enough for widespread production
use! Added setter for "execs" attribute. Added setter for "workingdirectory"
attribute. Fixed missing setter for "arguments" attribute. Added
alternate Java runtime parameter names for Mac OS X Java VM version
1.4.1. Included change submitted by Pierre-Luc Paour.
Thanks also to Dante Briones and Graham Perks
for pointing out bugs and enhancements. Added setter to properly support the "vmoptions" parameter.
(Change submitted by Alok Saldanha) Please contact Will Gilbert if you have bugs to report, patches to the code,
ideas for enhancements, or any other suggestions! I can be reached
at gilbert@informagen.com Thanks to Dan Stowell for suggesting the "documenttype" task and supplying
and example Info.plist file.
Thanks to Will Lowe for providing an example project which implemented "Apple
Help Book" support for Java.
The Jar Bundler Ant Task is Copyright © 2002 - 2006, Seth J. Morabito. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
the
GNU General Public License for more details. You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.Using in the Build file
<taskdef name="jarbundler"
classname="net.sourceforge.jarbundler.JarBundler" />
<jarbundler dir="release"
name="MyApp"
mainclass="org.foo.myapp.Main"
jar="myapp.jar" />
Task Attributes, required
Attribute
Description
dir
The directory in which your application bundle will be created.
name
The name of your application bundle (minus the ".app" extension).
mainclass
The name of the main class to run when the application bundle is launched.
jar
A single jar file to be used in your application.
Task Attributes, optional
Attribute
Description
arguments
Extra command-line arguments for the Java application.
build
Application build number. This string is used in the default
"About..." box along with the 'version' number. This default About Box format is "version (build)" i.e.
"4.3.1 (231)". Also see version and infostring attributes.
bundleid
Unique identifier string for the bundle. This string should be in
the form of a java package name, for example com.apple.myapp.
developmentregion
The development region of the bundle.
extraclasspath
A list of files or patternsets (space or comma seperated) to
add to the bundle's classpath. The files referenced by this property will
not be copied into the bundle, so the resulting .app may only work
on systems that have these external resources available.
helpbookfolder
Specify the directory name of the Help Book in the "resources"
directory. When this name must match the directory name when using
the <resourcefileset> task to copy the Help Book HTML files into the bundle.
helpbookname
Specify the name of the Help Book. This is string is also used
as the META tag to designate the initial HTML file to be loaded into the Help Viewer application.
icon
File reference to a Mac OS X icon file. This file is created with
the Mac OS application located at "/Developer/Applications/Utilites/Icon Composer"
infostring
A string for display in the Finder's Get Info panel. Also see version and build attributes.
jvmversion
The version of the JVM required to run the application.
Typically a string in the form "1.3", "1.3+", "1.4", "1.4+", etc.
shortname
The string used in the application menu.
showplist
If true, display the contents of the Info.plist file
signature
The four-letter code identifying the bundle.
splashfile
**Needs link to Apple Technical Document**
stubfile
If set, the location of a Mac OS X Java Application Stub file
to use for this application bundle. See the section "Specifying the Java Launching
Stub File" below.
verbose
If true, output more verbose information to Ant while the task is
running.
version
Version number displayed in Finder, this version number can be though of
as the "Marketing" version without distracting build information. The marketing version
is a string that usually displays the major and minor version of the bundle. This string
is usually of the form n.n.n where n is a number. Also see build and
infostring attributes.
vmoptions
Command line options to pass the JVM at startup.
workingdirectory
The working directory for the Java application.
startOnMainThread
Task Attributes, deprecated
Attribute
Description
aboutmenuname
The string to display in the "About" menu of the
running application. (Deprecated under JVM 1.4.1)
antialiasedgraphics
If set to true, use anti-aliasing when rendering graphics.
antialiasedtext
If set to true, use anti-aliasing when rendering text.
chmod
The full path to the BSD 'chmod' command.
execs
A list of files or patternsets (space or comma seperated) to
place into the "Resources/MacOS" directory and set executable.
growbox
Show the Aqua resize (grow) box.
growboxintrudes
Resizable window's growbox (resize control) intrudes
into AWT content. If turned off, the bottom of the window is
pushed down 15 pixels. (Deprecated under JVM 1.4.1)
jars
A list of jar files or patternsets (space or comma seperated) to be used in your application.
type
The Mac OS type of the bundle.
shortinfostring
Use infostring attribute instead.
smalltabs
If set to true, tab controls in Swing applications more
closely resemble the Metal look and feel. If set to false, the tabs
assume a larger size more similar to the default Aqua controls.
(Deprecated under JVM 1.4.1)
liveresize
If set to true, enable live-resizing of windows.
(Deprecated under JVM 1.4.1)
screenmenu
If set to true, puts Swing menus
in the Mac OS X menu bar if using the Aqua look and feel.
apple.laf.useScreenMenuBar
property instead:
<javaproperty name="apple.laf.useScreenMenuBar" value="true"/>
Nested DataType Task
<jarfileset>
<jarfilelist>
<javaproperty ...>
<javaproperty name="apple.awt.showGrowBox" value="true"/>
<execfileset>
<execfilelist>
<resourcefileset>
<resourcefilelist>
<javafileset>
<javafilelist>
<extraclasspathfileset>
<extraclasspathfilelist>
Note on FileList and FileSet target locations
<resourcefileset dir="builddir/architectures" includes="ppc/*.jnilib"/>
Examples
<jarbundler dir="release"
name="MyApp"
mainclass="org.foo.myapp.Main"
jar="build/myapp.jar" />
<jarbundler dir="release"
name="MyApp 1.0"
mainclass="org.foo.myapp.Main" >
<jarfileset dir="build">
<include name="**/*.jar" />
<exclude name="**/CVS" />
</jarfileset>
<jarfilelist dir="lib" file="GUI.jar, Utils.jar" />
</jarbundler>
Advanced JarBundler Tasks
History
Released: Jan 2007 (version 2.0.0)
Thanks to Angelo van der Sijpt for this addition.
Thanks to Anthony Goubard for this fix.
Thanks to Christian Menz for providing this modification to the source code.
Thanks to Philip Weaver for providing these. See "Creating a Disk Image"
June 19, 2006 (version 1.9)
April 12, 2006 (version 1.8.1)
April 11, 2006 (version 1.8)
March 22, 2006 (version 1.7)
March 2, 2006 (version 1.6)
February 2006 (version 1.5)
13 November 2004 (version 1.4):
23 October 2004 (version 1.3):
26 July 2004 (version 1.2):
26 July 2004 (version 1.1):
25 July 2004 (version 1.0):
28 Dec 2003 (version 0.5):
12 October 2003 (Version 0.2:)
Contact
Acknowledgments
License