Generating a Windows installer for your AIR captive runtime application

With Adobe Flash Builder 4.6 and Flex 4.6, you now have the ability to bundle your AIR application with a captive runtime. In the past you could only deliver your applications as single AIR, EXE, or DMG files, all three of which relied on the AIR runtime to work.

In this tutorial, you'll learn how to take advantage of the new captive runtime feature and enhance it with a minimal and customized installation package for Windows Installer.

Note: This article only applies to Windows desktop applications. It does not apply to applications for Mac OS or mobile devices.

The captive runtime bundle produced by Flash Builder is a directory containing AIR runtime files and your applications (this is true for desktop apps; mobile apps are bundled differently). Here are the major benefits of this export mode:

• Your application is runtime independent, so it can be installed without having to install the AIR runtime beforehand. This also means that the end-user will not be alerted in the case of AIR runtime updates.
• Your application is easily portable (for example, when stored on a CD, a USB thumb drive, and so on)
• Your application can be considered an all-in-one solution.

1. Of course this mode also has drawbacks:

• Your applications will not benefit from bug fixes or improvements in the AIR runtime.
• Your application will not be as easy for you to distribute and for end users to install because there are multiple generated files stores in a directory.

2. This tutorial is focused on the second drawback–specifically, on creating an installation package for Windows Installer to simplify the set up of an AIR application with captive runtime. To follow along you'll need Flash Builder 4.6 and WixEdit, as well as an AIR project ready to bundle.

Exporting your AIR application with captive runtime is simple:

1. Once you have your AIR project ready for export, click the Export Release Build button in Flash Builder (or choose Project > Export Release Build).
2. Type a directory name in as the Base Filename. This is where your exported files will be stored.
3. In the Export Release Build dialog box, select Signed Application With Captive Runtime (see Figure 1).
4. Click Next

You should be familiar with the remaining steps in the export process, so proceed as usual. Once the export is complete, the main difference with captive runtime is that you haven't created just one file, but rather a directory with files and subdirectories (see Figure 2).

If you double-click the newly generated EXE file, you'll notice that your application runs without having to be installed. Using it this way is perfect for some cases, but for other situations you may have a need to provide an installation process for your application. You can do that in a few minutes, through the MSI file format.

To create an MSI file you'll be using the WiX utility, but to make things easier you'll do it through WixEdit. You'll also be typing a few lines of XML.

WiX is short for Windows Installer XML. It is a toolset that uses an XML syntax to describe an installer's structure. Creating XML file and using the WiX command line tools is not always straightforward. To avoid this potentially heavy process you can download and install WixEdit, free software that provides a graphical user interface designed to ease the creation of WiX XML files and the invocation of WiX command line tools.

After you have downloaded, installed, and launched WixEdit, you'll see its startup screen (see Figure 3).

Creating a new WixEdit project

Start by creating a new file.

1. Choose File > New.

2. When the wizard opens (see Figure 4), click Next.

On the next screen, the wizard displays a tree control that you can use to specify where to deploy your AIR application files created by Flash Builder. Here, PFiles corresponds to the Windows Program Files directory; this is where you might want your application to be installed.

3. Right-click PFiles and select Import Folder.
4. Browse to the directory that Flash Builder created and select it (see Figure 6).
5. Click OK.

You'll then see the selected directory and all its files under PFiles (see Figure 7).

Note: If you don't want to install directly in Program Files, you can create a directory tree. To do so, right-click Files and select New Folder. You can do this as many times as you want.

6. Click Next.

The Select Features To Add screen (see Figure 8) lets you choose your installer features, here are the ones that I think are most useful:

• Add Userinterface will allow users to see your setup process, this is pretty much mandatory.
• Desktop Application Shortcut will create a shortcut to the application on the user's desktop.
• Startmenu Application Shortcut will do the same, but in your user's Windows Start menu.
• Startmenu Uninstall Shortcut will, similarly, add an uninstall shortcut on the Start menu.

7. Click Next twice to choose your user interface type (see Figure 9).

8. Select the Minimal interface, which is quite simple but typically enough for an AIR application.
9. Click Next twice.

The Create Desktop Application Shortcut screen enables you to select the file to which the desktop shortcut will link (see Figure 10).

10. Select the EXE file in the drop down list and type a label for the file that will be displayed in the shortcut.
11. Click Next twice.

On the following screen (see Figure 11) you select the file to which the Start menu shortcut will link.

12. As before, select the EXE file and type a label for the shortcut. You can also set the name of the directory that will hold the shortcut.
13. Click Next twice.

14. On the following screen type the name and description for the uninstall shortcut that will appear in your user's Start menu (see Figure 12).
15. Click Next twice.

• Next you will be prompted to customize some of your application's properties (see Figure 13):
• Id: This GUID is generated automatically; leave it as is.
• The language code: 1033 for English, 1036 for French. For more language codes, see http://wix.tramontana.co.hu/tutorial/user-interface/do-you-speak-english.
• The manufacturer's (or publisher's) name: This should be you or your company.
• The product name.
• The identifier used for a potential update: This is also generated automatically; you can leave it as is.
• The application's version.

16. Edit the properties as needed and click Done.
17. Choose File > Save to save your project (see Figure 14).

Fixing WixEdit file paths

A bug in WixEdit (or feature?) prevents it from storing your files' actual paths, you'll have to fix that manually.

1. Choose Tools > Launch External Editor.

A WXS file will then open in Notepad (you can change this file association in WixEdit's settings).

2. Replace Source=" with Source="C:\ in the file.
3. Save your changes and return to WixEdit.

Of course if your files are not on your C drive, replace C with the letter of the drive they are on.

Setting your installer language

If you'd like your installer's dialog boxes to be in a language other than English you will have to change your project's compilation settings. To do so, follow these steps:

1. Choose Build > Build Settings.
2. Make sure Use Custom Commandline For Light.exe is selected.
3. For French, type -cultures:fr-fr before –out (see Figure 15).
4. Click OK.

For information on using other language, see http://wix.tramontana.co.hu/tutorial/user-interface/do-you-speak-english.

Removing or editing optional comments

WixEdit automatically adds optional meta-data (Comments and Description) under Product > Package (see Figure 16). You can simply delete them (by right-clicking and selecting Delete) or edit them.

Customizing the appearance

There are several ways of customizing the appearance of your installation package.

By default WixEdit shows a generic English license, and you may decide to show yours instead by declaring a variable in the WXS file's XML structure. To do so, open the file by choosing Tools > Launch External Editor and add this line after <UIRef Id="WixUI_Minimal" /> :

Make sure to target an RTF file.

You can also customize the appearance using images. These images have to be BMP files and they have specific dimensions. The first one shows up in the first and last steps of your installer (see Figure 17).

To insert such an image, add this line after the license line:

This image has to be 493 × 312 pixels. It will be used as your installer's window background. Refer to the sample files for this article for an Adobe Illustrator template file to help you create your image.

The second image is used to customized your installer's top banner (see Figure 18).

You can add this image by inserting this line after the first image line:

This image has to be 493 × 58 pixels. The sample files for this article also contain an Illustrator template file to help you create it.

Automatically launching your application after installing it

If you want your application to automatically launch after the installation process you have to find its executable key inside the WXS file (look for desktopShortcut). When you have it, add these lines after the image lines:

Building your MSI file

To create your MSI file, complete these steps:

1. Complete your WXS edits, save your file, and return to WixEdit.
2. Choose Build > Build MSI Setup Package and wait a few seconds.
3. Make sure everything is OK by checking the Results Panel. You can safely ignore the potential "advertised shortcuts" warnings.

If it all went well you should see "Finished in x seconds" in the results and find some new files in the directory where you stored your WXS.

4. To test your MSI file, choose Build > Install MSI Package.

That's it!

To uninstall your application from WixEdit, choose Build > Uninstall MSI Setup Package.

Your MSI file is in your WXS directory with an MSI extension. You can now easily share it and distribute your AIR application with captive runtime.

Now that you've seen how easy it is to create a customized installer for your AIR application, you may want to read more about WiX and add new features to your installation package.