Using the AIR Debug Launcher (ADL)



Use the AIR Debug Launcher (ADL) to run both SWF-based and HTML-based applications during development. Using ADL, you can run an application without first packaging and installing it. By default, ADL uses a runtime included with the SDK, which means you do not have to install the runtime separately to use ADL.

ADL prints trace statements and run-time errors to the standard output, but does not support breakpoints or other debugging features. If you're developing a SWF-based application, use the Flash Debugger for complex debugging issues. You can connect to the Flash Debugger by starting the debugger program before running your application with ADL.

Launching an application with ADL

Use the following syntax: 

adl [-runtime runtime-directory] [-pubid publisher-id] [-nodebug] application.xml [root-directory] [-- arguments]

-runtime runtime-directory Specifies the directory containing the runtime to use. If not specified, the runtime directory in the same SDK as the ADL program is used. If you move ADL out of its SDK folder, then you must specify the runtime directory. On Windows and Linux, specify the directory containing the Adobe AIR directory. On Mac OS X, specify the directory containing Adobe AIR.framework.

-pubid publisher-id Assigns the specified value as the publisher ID of the AIR application for this run. Specifying a temporary publisher ID allows you to test features of an AIR application, such as communicating over a local connection, that use the publisher ID to help uniquely identify an application. As of AIR 1.5.3, you can also specify the publisher ID in the application descriptor file (and should not use this parameter).

Note: As of AIR 1.5.3, a Publisher ID is no longer automatically computed and assigned to an AIR application. You can specify a publisher ID when creating an update to an existing AIR application, but new applications do not need and should not specify a publisher ID.

-nodebug Turns off debugging support. If used, the application process cannot connect to the Flash debugger and dialogs for unhandled exceptions are suppressed. (However, trace statements still print to the console window.) Turning off debugging allows your application to run a little faster and also emulates the execution mode of an installed application more closely.

application.xml The application descriptor file. See Setting AIR application properties.

root-directory Specifies the root directory of the application to run. If not specified, the directory containing the application descriptor file is used.

-- arguments Any character strings appearing after "--" are passed to the application as command line arguments.

Note: When you launch an AIR application that is already running, a new instance of that application is not started. Instead, an invoke event is dispatched to the running instance.

Printing trace statements

To print trace statements to the console used to run ADL, add trace statements to your code with the air.trace() function:

trace("debug message"); 
air.trace("debug message");

In JavaScript, you can use the alert() and confirm() functions to display debugging messages from your application. In addition, the line numbers for syntax errors as well as any uncaught JavaScript exceptions are printed to the console.

ADL Examples

Run an application in the current directory: 

adl myApp-app.xml

Run an application in a subdirectory of the current directory: 

adl source/myApp-app.xml release

Run an application and pass in two command line arguments, "tick" and "tock": 

adl myApp-app.xml -- tick tock

Run an application using a specific runtime: 

adl -runtime /AIRSDK/runtime myApp-app.xml

Run an application without debugging support: 

adl myApp-app.xml -nodebug

Connecting to the Flash Debugger (FDB)

To debug an HTML-based AIR application with the Flash Debugger, start an FDB session and then launch the application using ADL.

  1. Start FDB. The FDB program can be found in the bin directory of the Flex SDK.

    The console displays the FDB prompt: <fdb>

    The Flex SDK is available from http://opensource.adobe.com.

  2. Execute the run command: <fdb>run [Enter]

  3. In a different command or shell console, start a debug version of your application: 

    adl myApp.xml

  4. Using the FDB commands, set breakpoints as desired.

  5. Type: continue [Enter]

If an AIR application is SWF-based, the debugger only controls the execution of ActionScript code. If the AIR application is HTML-based, then the debugger only controls the execution of JavaScript code.

To run ADL without connecting to the debugger, include the -nodebug option:

adl myApp.xml -nodebug

For basic information on FDB commands, execute the help command: 

<fdb>help [Enter]

For details on the FDB commands, see Using the command-line debugger commands in the Flex documentation.

ADL exit and error codes

The following table describes the exit codes printed by ADL:

Exit code

Description

0

Successful launch. ADL exits after the AIR application exits.

1

Successful invocation of an already running AIR application. ADL exits immediately.

2

Usage error. The arguments supplied to ADL are incorrect.

3

The runtime cannot be found.

4

The runtime cannot be started. Often, this occurs because the version or patch level specified in the application does not match the version or patch level of the runtime.

5

An error of unknown cause occurred.

6

The application descriptor file cannot be found.

7

The contents of the application descriptor are not valid. This error usually indicates that the XML is not well formed.

8

The main application content file (specified in the <content> element of the application descriptor file) cannot be found.

9

The main application content file is not a valid SWF or HTML file.