Adobe Creative Suite Extension Builder allows you to debug your extension while it is running within a Adobe Creative Suite application. You can:
Use Extension Builder to debug the extension while it is running in the host application
Check various logs for warnings and errors
Profile an extension while it is running to find memory leaks or performance bottlenecks
There are two possible workflows for debugging an extension in a Creative Suite host application:
The Debug As option, which assumes that the host application is not running, and allows the IDE to launch it. You can only do this once during an application session.
The Attach As option, which assumes that the host application is already up and running. This allows you to edit and debug the extension repeatedly without restarting the application; however, the option is not available in all Adobe Creative Suite applications.
To debug an Adobe Creative Suite extension with Extension Builder while it is running in the host application:
Make sure the host application is not running. You must allow the IDE to launch the application to ensure that the extension code is available for debugging.
Open your project in Extension Builder.
Set a breakpoint in your ActionScript code.
Right click in the project and choose Debug As.
The IDE offers a debug configuration for each of the host applications that your extension supports. Select the debug configuration to launch the desired application.
Open the panel for the extension that you want to debug, and invoke the code that contains the breakpoint.
Use the Flash Builder debugger to step through the code.
This feature currently supported in Illustrator, InDesign, InCopy, Flash Pro, and Dreamweaver (Windows only).
To attach an Adobe Creative Suite extension to a host application and debug it with Extension Builder:
Make sure the target host application is running.
Open your project in Extension Builder.
Set a breakpoint in the ActionScript code.
Right click in the project and choose Attach As.
Select the application you want to attach; you should see some trace messages.
Switch to the target host application; you should see that the extension is loaded.
Execute the extension. When it reaches the break point, the Flash Builder debugger is triggered.
Use the debugger to step through the code.
After you halt this first debugging session, you can attach again without having to restart the host application.
Launch configurations are the way Extension Builder stores state about your past launches to an application (e.g. what version of the application you last launched to). On the first launch of your project, a launch configuration is automatically created. If you have multiple versions of Creative Suite applications installed on your machine, Extension Builder will prompt you during the first launch to choose a version to launch to:
If you select the "Remember my decision" option, this version will automatically be used on subsequent launches. To change the version you are targeting at a later time, you have to change the launch configuration:
Right click on project and choose Debug As > Debug Configurations...
Select the application for which you'd like to change the launch configuration and expand the tree.
Select the launch configuration associated with your project.
Change version of the application using the combo box.
Select the Apply button.
Make sure you set the historyManagementEnabled flag to false in your extension (in the Application tag in your MXML file).
There is an operating-system flag, PlayerDebugMode, that sets debugging mode for Flash Player. This flag must be set to allow you to run unsigned extensions during development. Extension Builder automatically updates the debug flag for you, but it can fail to do so. If you cannot open your extension, check that the PlayerDebugMode flag is set to 1 in the platform-specific location:
In Windows: The Registry entry HKEY_CURRENT_USER\Software\Adobe\CSXS2Preferences\
In Mac OS: <user>/Library/Preferences/com.adobe.CSXS2Preferences.plist
Photoshop requires a debug file (in addition to PlayerDebugMode) to allow you to run your extension during development. Extension Builder attempts to create this for you as well, but if permissions are restricted for your application folder, you must create the file manually. To do so, create an empty file named debug (with no file extension or contents) in the platform-specific location for each Photoshop version with which you plan to debug extensions:
In Windows: Create the debug file in the same directory as your Photoshop executable. For example: C:/Program Files/Adobe Photoshop CS5/debug
In Mac OS: Create the debug file inside the package contents for Photoshop. For example: /Applications/Adobe Photoshop CS5/Adobe Photoshop CS5/Contents/debug
During a debug session, you can inspect your own code, and also the application scripting objects made available through the Creative Suite ActionScript wrapper libraries (CSAWLib). If your extension uses the CSAWLib API to interact with the host scripting object model, you can see the accessed object properties in your debug perspective.
For example, you can select a com.adobe.illustrator.Document object and inspect its properties, in the same way you inspect the objects that you have defined. Every time you request a property, the tool makes a call to the underlying scripting engine to retrieve its value. The Variables pod here shows the values of some of the properties for the Illustrator document object, such as the default name, "Untitled-1".
Several types of logs are available for help in debugging your Adobe Creative Suite extensions:
You can use the LogBook application to track logging messages sent between the various platform components. To use this application for logging:
Include this code in your application main MXML file so LogBook can listen to and display the logging information traced by your extension:
var loggingTarget:LocalConnectionTarget = new LocalConnectionTarget("_test");
loggingTarget.level = LogEventLevel.ALL;
loggingTarget.includeDate = true;
loggingTarget.includeTime = true;
loggingTarget.includeCategory = true;
loggingTarget.includeLevel = true;
logger = Log.getLogger(this.className);
Go to http://code.google.com/p/cimlogbook/downloads/list and download LogBook-1.3.air
Install the AIR application and start it.
Enter the local connection name, as passed into the constructor of LocalConnectionTarget. In the example, this is '_test'.
Start the host application and open your extension. You should see log messages in LogBook.
To listen for internal messages, set the local connection name in logbook to '_csxs2'
Flash Player runtime embedded in the Creative Suite application has some built-in logging functionality. It is very light-weight and easy to set up, but not as comfortable as LogBook. To use it, you must put trace() calls directly into your scripts, or create a TraceTarget instance. For example:
var traceTarget : TraceTarget = new TraceTarget();
traceTarget.filters = ["*"];
traceTarget.level = LogEventLevel.ALL;
traceTarget.includeDate = true;
traceTarget.includeTime = true;
traceTarget.includeCategory = true;
traceTarget.includeLevel = true;
To generate the flashlog.txt file:
Create a new file mm.cfg in the platform-specific folder:
In Windows XP: C:\Documents and Settings\user\
In Windows Vista and Windows 7: C:\Users\user\
In Mac OS: /Library/Application Support/Macromedia/
Edit the file and add these lines:
The flashlog.txt file is then generated in the platform-specific folder:
In Windows XP: C:\Documents and Settings\user\Application Data\Macromedia\Flash Player\Logs
In Windows Vista and Windows 7: C:\Users\user\AppData\Macromedia\Flash Player\Logs
In Mac OS: /Users/user/Library/Preferences/Macromedia/Flash Player/Logs/
The Adobe Creative Suite extensibility infrastructure creates a log file for each of the applications running extensions. These files provide useful debug information for extension developers. The log files are generated in the platform’s temp folder, and named csxs2.version#-HostID.log; for example, csxs2-ILST.log for an extension running in Illustrator CS5, or csxs2.5-ILST.log for Illustrator CS5.1.
These logs are located at these platform-specific locations:
In Windows XP: C:\Documents and Settings\user\Local Settings\Temp
In Windows Vista: C:\Users\user\Locale\Temp
In Windows 7: C:\Users\user\AppData\Local\Temp
In Mac OS X: /Users/user/Library/Logs/CSXS
If you need more detailed information, you can increase the logging level. The possible log level values are:
"0": Off; no logs are generated
"1": Error; preferred and default level
Update the LogLevel key at these platform-specific locations:
In Windows Registry Editor:
For CS5: HKEY_CURRENT_USER/Software/Adobe/CSXS2Preferences
For CS5.5: HKEY_CURRENT_USER/Software/Adobe/CSXS.2.5
In Mac OS X:
For CS5: /Users/user/Library/Preferences/com.adobe.CSXS2Preferences.plist
For CS5.5: /Users/user/Library/Preferences/com.adobe.CSXS.2.5.plist
You must restart your application for these changes to take effect.
The CS Service Manager keeps log files in the logs folder under the CS5ServiceManager or CS5.5ServiceManager folder, at these platform-specific locations:
In Windows XP: C:\Documents and Settings\user\Application Data\Adobe\
In Windows Vista: C:\Users\user\AppData\Roaming\Adobe\
In Mac OS X: /Users/user/Library/Application Support/Adobe/
Extension Builder enables you to profile an extension while it is running within a Creative Suite application, using Flash Builder’s Profiler tools. You can use the Profiler to find memory leaks or performance bottlenecks in your extension.
The profiling feature is only available to Flash Builder Premium users.
Before profiling an Adobe Creative Suite extension, ensure that the host CS application’s Welcome Screen is disabled. To do this, launch the application; if the Welcome Screen appears, check the "Don't show this again" checkbox.
If the Welcome Screen is not disabled, the Profiler cannot connect to the host application.
Close the host CS application if it is running.
In Extension Builder, right click the extension project and select Profile As, then select an application.
Extension Builder launches the selected application. If your extension targets multiple versions of the selected application and you have more than one version installed, you are prompted to select the version to launch:
In the host application, open your extension from the Windows > Extensions menu.
In Extension Builder, a Connection Established dialog opens. Click Resume to begin profiling.
In some CS applications, the Connection Established dialog opens before you start your extension; the Profiler connects as soon as the host application has launched. In this case, click Resume to start the Profiler, then open your extension.
Use the Flash Builder Profiler tools as documented here: http://help.adobe.com/en_US/flashbuilder/using/WS6f97d7caa66ef6eb1e63e3d11b6c4d0d21-7e46.html
To access the Profiler preferences:
In Windows, choose Window > Preferences > CS Extension Builder > Profiling
In Mac OS, choose Eclipse/Flash Builder > Preferences > CS Extension Builder > Profiling
CS extensions are loaded as sub-applications of a single Flex application called StageManager. This means that the data collected by the Profiler includes data on StageManager and all running CS extensions. In order to make your extension’s profiling data easier to find, make sure no other extensions are running while you are profiling yours.
You can also filter objects in the StageManager namespace (com.adobe.csxs.*) from the profiler perspective. Filtering is controlled by a Profiler preference; Extension Builder automatically creates a filter for these objects by default.
You can set a preference to configure the connection timeout, a millisecond value. This controls how long the profiler waits for an extension to be launched. If no extension is launched within the specified number of milliseconds, the profiling session is cancelled, and the Extension Builder displays an "Unable to Connect" error message.