A few weeks ago, I wrote a post detailing how to use Merapi in a Production Environment. That tutorial was primarily written to address managing Java and AIR on a Windows Platform including creating an installer that installs both the Adobe AIR Runtime, the Java-side of an application, and the AIR-side of an application. However, I realized that I was neglecting those OS X enthusiasts out there, so this article is for you guys! However, I would still recommend reading Merapi in a Production Environment first for an in-depth overview of integrating Java and AIR through Merapi as this post is only for creating a Mac bundled installer.

The first thing I noticed while trying to make a Mac installer with the bundled Adobe AIR Runtime is that there is relatively little out there that addresses this issue. While there are some resources provided by Adobe after applying for a distribution license, there were still some questions that I had to answer on my own. What will follow is a step-by-step approach that I took to create a Mac installer.

1. Create a Java Installer

The Java installer will serve as the core of our installer. It is responsible for copying class files and jars into the Applications directory and it is also responsible for executing the Adobe AIR Runtime installer which will install both the AIR Runtime on the user’s computer (if they don’t have it already), and installing the AIR-side of the application. Much of this portion I discovered through this post and I won’t go into as much detail as Dem Pilafian covers that material very well.

The tool that I used to initially create a bundled Java app is called “Jar Bundler”. It is located in Developer/Applications/Utilities and is part of XCode. This tool allows you to specify your Main Class, any additional Classes or Jars that are part of the library, an icon, and some configuration options. When you click on the “Create Application” button, you will see that a MyJavaApp.app bundle is created. If you right-click the app bundle and select “Show Contents”, you will see what Jar Bundler created for you. In the Contents folder you will see a PList file (XML-based file which contains the properties for the application), a folder called MacOS which contains the executable, and another folder called Resouces which contains your icon and a subfolder called Java with all the Class and Jar files contained in your Java Application.

At this point you may also have realized what a pain the Jar Bundler is! If you haven’t yet, you will realize it the ump-teenth time you need to create another version of the installer. It doesn’t save an XML configuration file like Launch4j does on the PC, nor does it remember where your previous files selections were so you have to navigate through your Java application looking for class and jar files every single time. Plus, Jar Bundler does not support every application configuration option for your application.  That means you have to go into the PList file and do it manually every time.

To solve this problem, I wrote a script which automatically builds the jar files I need and copies them into MyJavaApp.app/Contents/Resources/Java automatically. It also overwrites the PList file that is generated by Jar Bundler to give me more configuration options. Basically, the only thing that remains from Jar Bundler is the executable.

2. Include the AIR Application inside the bundle

After you get the Java bundle set up, it is time to include the AIR portion of the application. Inside of MyJavaApp.app/Contents/Resources, create a directory called AIR. This directory will contain the Adobe AIR Runtime and MyAirApp.air. During the install process we will run the AIR Runtime and pass it a reference to MyAirApp.air to be installed with the runtime.

3. Create an Install Package

With the application bundle in place, we now need to generate an installer. This can be done by using PackageMaker (Developer/Applications/Utilities) or a third party app called Iceberg. I prefer Iceberg due to its intuitive user interface and step-by-step process, however the choice is up to you although I will use Iceberg throughout this tutorial.

Mac install packages are very handy and much easier to create than Windows EXE executables in my opinion. However there are a few things to keep in mind. If you have any custom welcome text, license information, or README this can be displayed in the installer as well. Iceberg allows you to specify text files for each of these three functions in the Documents section. Also, there are Perl or Bash scripts that can be executed during different stages of the install process. You can find these in the Scripts section of Iceberg in their order of execution.

  • preinstall:  This script is run before files are installed.
  • preinstall:  This script is run after the preinstall script, but before files are installed.  This script is only run if the application has not been installed previously on the target machine.
  • preupgrade:  This script is run after the preinstall script, but before files are installed.  This script is only run if the application has already been installed on the target machine.
  • postinstall:  This script is run after files have been installed and before the postflight script.  This script is only run if the application has no been installed previously on the target machine.
  • postupgrade:  This script is run after files have been installed and before the postflight script.  This script is only run if the application has already been installed on the target machine.
  • postflight:  This script is run after files have been installed.

Also, keep in mind that each script must return zero.  If it doesn’t, the installer will determine that they have failed.  For my application, I created a preflight script that checked to see if there were any previous versions of the app and then I removed them.  I also created a postflight script that installed the .air application inside of the already created MyApp.air inside of the Applications directory.  The script contained a couple of lines that looked something like this:

?View Code BASH
1
2
3

cd /Applications/myApp.app/Contents/Resources/AIR
 
Adobe_AIR_Installer.app/Contents/MacOS/Adobe\ AIR\ Installer -silent -location /Applications/myApp.app/Contents/Resources/AIR MyAirApp.air
Note that the Adobe_AIR_Installer.app is the AIR Runtime Installer and myApp.app is the application bundle that contains the Java application made by the Jar Bundler with the AIR files inside of an AIR directory.  The second line basically makes a call to the “Adobe AIR Installer” executable and tells it to run silently.  It also specifies where the AIR application will be installed (The AIR directory), and the path to MyAirApp.air.

Now that I have explained some of the components of a Package, let’s open up Iceberg and get started.  First, create a new project and go through each of the steps customizing the installer to fit your specifications.  Add any custom text files or scripts and then define where your app will be installed.  I put MyApp.app under the Applications directory.  When you are finished configuring the package, go to the Build menu and select Build and Run.  This will allow you to test your package and scripts to see how well they work.  Also, make sure to save your project when you are finished.  This will keep your configuration settings as a .packproj file that you can use to make future builds.