Getting Started with Adobe AIR

By on January 21, 2009 5:13 pm

As previously announced by Dylan Schiemann, SitePen has released the Dojo Extensions for Adobe AIR (dAIR) project that help make it simple to use Dojo into an AIR application. These extensions also simplify some of the more difficult AIR APIs by wrapping them and adding some syntactic sugar.

Working with Adobe AIR is a real treat for a web developer. You get to work with desktop features such as native drag and drop, system icons, reading and writing files, an encrypted SQLite database, and chrome-less, non-rectangular windows (even with HTML!). You also have access to all of the features of Flash, like audio and video, sound transforms, uploads and downloads, byte arrays, and Pixel Bender. Best of all, you get to have a single target environment, in WebKit — CSS3 selectors and styling, a super-fast JavaScript engine, and no compatibility issues with a certain browser.

Adobe worked hard at making desktop applications easy and accessible for web developers. I’ll explain the steps to get your development environment setup.

The first step is to download and install the Adobe AIR SDK; although actually, there’s no installation needed. You simply unzip the package to a folder on your computer. I recommend a simple file path, close to your hard drive root that’s easy to type on the command-line. On my Mac, I’m using: /Users/mike/Sites/AIR and on my PC: C:\AIR. Linux users can join the party too, as Adobe has just released a version of AIR for them. The steps for Linux are quite similar to those on a Mac with a few exceptions that I’ll point out.

The relevant executables we will use are in the AIR/bin folder: adl and adt. adt is used for compiling your application into an AIR file. adl is used much more frequently for previewing the application during development. As a matter of fact, we can already access adl in the console with an absolute path:

//Mac & Linux


Which shows the output:

application descriptor file not specified
  adl ( -runtime  )? ( -pubid  )? -nodebug?  
  adl -help

This output is a good thing. It means that we have access to the executables. However, using absolute paths can be quite a hindrance to a project, especially during collaboration, so we naturally need to add the AIR/bin to our system path. In Windows, this is relatively straightforward:

  1. Right click on My Computer, and select “Properties”
  2. Click on the Advanced tab and select “Environmental Variables”
  3. In the system variables box below, scroll until you see the Path variable in the left column; select that line and click “Edit”.
  4. Add C:\AIR\bin to the end of the line. You may find it easier to copy this text and paste it into Notepad so you can see it better.

Open cmd.exe (Start -> Run -> type “cmd”), and from a different directory than AIR, try typing “adl”. You should get the same output as above.

For Mac users, adding to the system path is a little trickier or easier depending on your command-line experience. You need to edit your .profile file, which is hidden by default. To show hidden files on a Mac, in the Terminal window type the following two lines:

defaults write AppleShowAllFiles YES
KillAll Finder

You should now see the .profile file in your root User directory. If you don’t see it, you are allowed to create one – but make sure it’s not there before you do or you will overwrite your existing file. I had to create one myself. Linux users follow the same steps, but the file is .bash_profile. Add the path to AIR/bin at the end of the export PATH statement. Mine looks like this (line break is inserted here for readability):

export PATH="/usr/local/bin:/usr/local/sbin:/usr/local/mysql/bin:

Save the file. In Terminal type “source ~/.profile” (or .bash_profile) to register the file with the system. Check the path by typing “adl”. It should be good to go! To restore the system’s hidden file state, use the same two lines as above, but use NO instead of YES.

Now let’s build a test app. For the simplest test case, we need two files: the XML descriptor, and the HTML file which will represent our application. First build an HTML file — anything will do. Give it a title and some text in the body. Then build your XML descriptor file. A very simple one will look like this:


For best results, the XML file should always be at the root of your application directory structure, and the HTML file (and dependent files) at or below the root. Also expect to target the XML from the command line at the root. These rules are not absolute, but it gets complicated otherwise. For now, keep these two files in the same directory. Adobe has more complete details on the descriptor file. At the command line, navigate to the directory where the XML resides and type: “adl test.xml”. You should see a preview of the HTML application in a 300 by 200 pixel window.

Now that we’ve finished coding our awesome desktop app, let’s compile it so the whole world can see it. AIR applications use signed certificates to maintain authenticity and security of releases. We don’t need to acquire a certificate for our purposes; we can use an anonymous certificate. But first that needs to be created. At the prompt, use the following:

adt -certificate -cn SelfSigned 1024-RSA cert.pfx mypass

This creates a self-signed certificate named cert.pfx with the password “mypass”. Now we can finally compile your AIR app:

adt -package -storetype pkcs12 -keystore cert.pfx test.air test.xml test.html

You’ll be prompted for the password, “mypass” and then it should build pretty quickly. After the certificate argument, you have the name of your final build, followed by all the files (or directories) that are to be packaged in the build. You can now double click on your newly created test.air file, and install it. Since it’s unsigned, there will be some warnings about its origin. Click install, and after completion, it will launch your application.

You now have the beginning steps for developing Adobe AIR desktop applications. In a future post, I’ll show you how to setup your directories to use the AIR runtimes, include the Dojo Extensions for Adobe AIR, and make full use of the Dojo Toolkit!