rialvalue.com » debug

HowTo create your developer ToolBox with Mixins

Xavi Beumala — Fri, 21 May 2010 11:25:33 +0000

In this post I’ll explain how you can develop a flex library that automatically initializes itself avoiding developers the hassle of remembering how, when and where the libraries need to be initialized and hooked into the application. This can be particularly helpful for debugging libraries like fxSpy, DeMonsterDebugger, KaptInspect, mrdoob, etc. and extremely useful to create your own Flex toolbox that simply plugs-in and can go with you on all your developments.

First, create a class in your library project with whatever name you pick, in my case I’ll call it LibraryInitializer.as, make sure you mark this class to be included on the final swc or even better use the new FB4 option “Include all classes from all sources”. Second and key point, add a public static method named init that receives a parameter and mark the class as a Mixin:

[Mixin]
public class LibraryInitializer
{
public static function init(systemManager:ISystemManager):void
{
}
}

The [Mixin] metadata tag is extensively used in the Flex automation API and it basically gives you a very interesting hook. The static init method of any class marked as a [Mixin] will be invoked at a very early point during the application initialization phase by the SystemManager class or FlexModuleFactory. The Mixins are executed before the preInitialize event is triggered on the main Application. The parameter that the init method receives is a reference to the related SystemManager so you can mark the parameter as an ISystemManager, InteractiveObject or whatever better fits your needs. You can read about another interesting use of the [Mixin] on the Global Exception Handler post .

By adding a Mixin class in a library and linking the library to an Application what you effectively get is a hook where the library can initialize itself and release the developer from manually initializing it.

Let’s see some real world examples.

Libraries like fxSpy, deMonsterDebugger, KaptInspect or mrdoob are extremely easy to use but on each project you end up doing some repetitive steps or adding conditionally compiled code to your Main application class.

I’ll focus on a sample with fxSpy where you can launch it from a contextual option when you right click on the application and see mrdoob memory monitor. The only step required to integrate this will is adding the following compiler option:

-include-libraries=libs/myToolbox.swc

And this is the library initializer, which basically adds a ContextMenuItem to the contextMenu of the systemManager. Note that we have to wait for the APPLICATION_COMPLETE event, otherwise the Flex SDK will override our contextMenu (it happens on the pre-initialize phase).

package
{
import com.flexspy.FlexSpy;

import flash.display.InteractiveObject;
import flash.events.ContextMenuEvent;
import flash.events.Event;
import flash.ui.ContextMenu;
import flash.ui.ContextMenuItem;

import flashx.textLayout.elements.GlobalSettings;

import mx.core.FlexGlobals;
import mx.events.FlexEvent;
import mx.managers.ISystemManager;

import spark.core.SpriteVisualElement;

[Mixin]
public class MyToolBoxInitializer
{
private static var initializer:MyToolBoxInitializer;

public static function init(systemManager:ISystemManager):void
{
systemManager.addEventListener(FlexEvent.APPLICATION_COMPLETE, applicationCompleteHandler);
}

private static function applicationCompleteHandler(event:Event):void
{
var systemManager:InteractiveObject = event.target as InteractiveObject;
systemManager.removeEventListener(FlexEvent.APPLICATION_COMPLETE, applicationCompleteHandler);

initializer = new MyToolBoxInitializer(systemManager);
}

public function MyToolBoxInitializer(target:InteractiveObject)
{
createContextMenu(target);
createMonitor();
}

private function createContextMenu(target:InteractiveObject):void
{
var contextMenu:ContextMenu = target.contextMenu;
contextMenu.customItems = [ createContextMenuItem() ];
}

private function createMonitor():void
{
var sve:SpriteVisualElement = new SpriteVisualElement();
sve.addChild(new Stats());
FlexGlobals.topLevelApplication.addElement(sve);
}

private function createContextMenuItem():ContextMenuItem
{
var contextItem:ContextMenuItem = new ContextMenuItem("Flex Spy");
contextItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, handleContextMenuItemSelect);

return contextItem;
}

private function handleContextMenuItemSelect(event:Event):void
{
FlexSpy.show();
}
}
}

In the Initializer you could also intialize the fps and memory monitor provided by mrdoob by simply adding a new instance to the DisplayList.

These are the benefits I see on this approach:

You won’t have to reapeat yourself in different projects initializing the same libraries always in the same way.
Your main file won’t be cluttered with infrastructure and glue code to configure your libraries.
You won’t need to use conditional compilation for this initializations. You can enable or disable all at once by removing the compiler option. Going an step further you could have diferent compiler profiles / environments on your ant tasks or maven builds or even use the -load-config compiler option to externalize your configurations to an xml file.

You can downdload a zip with 2 sample projects, one for the library and the other for the application using it.

Shortly I’ll blog about some of the things I have in my toolbox that could be helpful for you too.

Debugging production ready AIR applications

Xavi Beumala — Sun, 16 Aug 2009 02:19:49 +0000

One of the biggest problems around testing installed AIR applications is that testers can’t see when a runtime exception is triggered. Lots of times the symptom of a problem will be something completely different to the real cause and developers will have to spend much more time trying to figure out what was the root cause of the problem. Even though you have a good logging policy if there’s an uncaught exception there’s not too much you can do.

Here are some techniques I’ve came across to make testing less painful for everybody.

The debug flag way

One thing I’ve been thinking for a while is that there are not two different versions of the AIR runtime; one with debugging enabled and the other without it (the way Flash Player has). This means that there might be a way to enable and disable debugging in the same runtime. This would allow, at least in some controlled environments, to see Runtime Exceptions and make everybody’s life easier. At least until we have global error handling implemented directly on AIR or Flash Player. Yes, I agree, It’s unbelievable that on its 10th version we still are not able to capture global exceptions: FP-444 and FP-1499

Using Procmon I realized that when an AIR application is launched it tries to read a file in {INSTALLATION_FOLDER}/META-INF/AIR/debug. See the screenshot. What surprised me was the result “NAME NOT FOUND”. Basically the file didn’t exist in the app I was playing with. After some more trial / error, yes, you’re right, this is the flag that switches on and off debugging capabilities.

If an AIR application is launched and an empty file with name debug is found in {INSTALLATION_FOLDER}/META-INF/AIR/debug then, any runtime exception will be displayed in a system modal window! In OS the path for this file will be {APPLICATION_FOLDER}.app/Contents/Resources/META-INF/AIR/debug

So if testers (or users during the earlier versions of your app) are using your application, make sure they create the debug file and attach any stack trace they see to their bug reports.

The adl way

This is not as easy as the previous solution but it gives the testers more options.

Once installed, an AIR application, is not more than the swf file produced from FB, its application descriptor and a native launcher. Given that we have access to the main application swf file and its corresponding descriptor we can use ADL to launch the installed application instead of the native launcher.

Here’s how:

1. Installed the SDK you want to use from http://opensource.adobe.com/wiki/display/flexsdk/Downloads
2. Uncompress the zip in the location you prefer. I’ll refer to this folder as {FLEX_HOME}

In Windows
3. Right click on “My Computer” > Properties
4. Go to “Advanced” tab
5. Click in the option “Environment Variables”
6. In the “System variables” find the “Path” definition and add this to it (double clicking on it): “;{FLEX_HOME}/bin”
7. Make sure your replace {FLEX_HOME} with the path to the folder where you’ve uncompressed the SDK

In OS X
3. Open a terminal
4. Execute this command: open ~/.bash_profile
5. Add the following line to the opened file:
PATH=${PATH}:{FLEX_HOME}/bin
6. Make sure your replace {FLEX_HOME} with the path to the folder where you’ve uncompressed the SDK

In Linux
3. Open a terminal
4. Edit your profile file ~/.profile
5. Add the line: export PATH=$PATH:$FLEX_HOME

Then to launch the application you will have to:

In Windows
1. Open a command line window. Start > “Run …” > cmd
2. Navigate to the folder where the application is installed: cd “Program Files”/MyApp
3. Execute this command: adl META-INF/AIR/application.xml .
4. Don’t forget the dot at the end of the command

In OS X and Linux
1. Open a terminal
2. Navigate to the folder where the application is installed: cd /soft/testAirApp.app/Contents/Resources where testAirApp is the name of your application
3. Execute the following command: adl META-INF/AIR/application.xml .
4. Don’t forget the dot at the end of the command

If during the execution process there’s an exception, ADL will show it.