Dreaming up a Flex JavaScript SDK

We finally made it through the long list of language features and those odd three features (Weak References, Proxy, and Dictionary) that are langage and runtime features at the same time. We are now with both feet in runtime feature land! A few days ago I thought that perhaps the best way to introduce cross-compiling ActionScript runtime features to JavaScript is probably by describing a fictional Flex JavaScript SDK.


Science Fiction?

This may sound a little bit like science fiction to you, but what if you launched Flash Builder, hit File/New/Flex Project and checked “Use a specific SDK” under Flex SDK Version. From the pop-up menu you would then select “Flex x.x for JavaScript” (x.x being the version number) and that would be everything needed to get you started on writing your first JavaScript application in ActionScript. Or even better: You open an old Flex Project, navigate to File/Properties/Flex Compiler/Flex SDK Version, change the SDK to “Flex x.x for JavaScript” and recompile your project to an HTML app.

That’s how easy creating HTML apps in Flash Builder should be in my opinion. Everything should be transparent, even Flash Builder’s source-level debugging of ActionScript running as JavaScript in the browser should just work. JavaScript and HTML would just be features delivered through a specialized Flex SDK.


Flex SDK’s Blue Print

Let’s have a look at the current structure of Flex SDKs. Flex SDKs are usually located in the Flash Builder’s …/sdks/x.x.x version folders. For example you would find Flex SDK 4.6 in …/sdks/4.6.0. To me it would make sense to do the same with our Flex JavaScript SDK and use a folder like …/sdks/4.6.0-js .

Every Flex SDK has pretty much the same structure:

  • ant – support for ant (flex tasks).
  • asdoc – support for generating documentation from ActionScript source files.
  • bin – platform dependent launcher
  • frameworks – runtime libraries and skins
  • lib – Java JAR files used by the launchers in bin and by the Flash Builder IDE.
  • runtimes – native AIR framework for OSX.
  • samples
  • templates

Our Flex JavaScript SDK would probably use the same structure where it made sense. Only a few files and folders under lib and frameworks would need to be replaced.


What’s in the lib folder?

As mentioned earlier SDK’s lib folder contains Java JAR  files that are used by the platform dependent launch utilities in the bin folder and by the Flash Builder IDE. There are three JARs that I would like to focus on for now:

  • asc.jar – ActionScript compiler
  • mxmlc.jar – MXML and ActionScript compiler for creating applications (SWFs).
  • compc.jar – MXML and ActionScript compiler for creating libraries (SWCs).

Those are the main three JARs we would need to replace with our cross-compiler versions:

  • asc.jar (a.k.a. jsc.jar) – ActionScript to JavaScript cross-compiler.
  • mxmlc.jar (a.k.a. mxmljsc.jar) – MXML and ActionScript to JavaScript cross-compiler for creating HTML applications (JS).
  • compc.jar (a.k.a. compjsc.jar) – MXML and ActionScript to JavaScript cross-compiler for creating libraries (SWCs).

Those three JARs form FalconJS. Our Flex JavaScript SDK should probably use the original names asc.jar, mxmlc.jar, and compc.jar. Instead of lib/optimizer.jar FalconJS currently uses Google’s Closure compiler, which is copied into the SDK to …/lib/google/closure-compiler/closure.jar.


What’s under frameworks?

There is a lot of stuff under Flex SDK’s frameworks folder. In order to keep things simple I will only look at two sub-folders, which I think are the most important ones.

  • frameworks/javascript currently only contains one folder called “fabridge”, which contains glue code for DOM/SWF interactions.
  • frameworks/libs is the folder where you can find almost all of the SDK’s SWCs.

The frameworks/javascript folder seems like a good place to put JavaScript libraries like jQuery and Google Closure Library. The fabridge folder does not make any sense in the browser and should be removed.

In the “regular” Flex SDK  you’ll find within the frameworks/libs folder a SWC called player/x.x/playerglobal.swc, which contains the implementation of ActionScript core classes (Object, Array etc) as well as the complete Flash Runtime API (flash.display.* etc).

For our Flex JavaScript SDK I recommend splitting up what traditionally goes into playerglobal.swc into two pieces: browserglobal.swc (for the ActionScript core classes) and flash.swc (for the Flash Runtime API). Those two SWCs form FlashRT (or a.k.a “runtime-js” in earlier versions). The following list probably describes the bare minimum set of files you need in order to cross-compile ActionScript that uses the Flash Runtime API to JavaScript:

  • frameworks/javascript/jquery-1.5.1.js
  • frameworks/javascript/goog/base.js
  • frameworks/javascript/…
  • frameworks/libs/browser/browserglobal.swc
  • frameworks/libs/browser/browserglobal.abc
  • frameworks/libs/flash.swc
The Flex specific SWCs (Peter Flynn’s FlexJS) are:
  • frameworks/libs/framework.swc
  • frameworks/libs/mobilecomponents.swc
  • frameworks/libs/mobiletheme.swc
  • frameworks/libs/mx.swc
  • frameworks/libs/spark.swc
  • frameworks/libs/sparkskin.swc
Please note that those SWCs are very special SWCs created by FalconJS’s compc.jar. You can use them in “regular” Flash Builder projects and even compile SWCs and SWFs. But the resulting SWCs and SWFs created by “regular” Flex SDKs will never run in the Flash Player. Only the FalconJS versions of asc.jar, mxmlc.jar, and compc.jar are able to extract JavaScript from those SWCs listed above and create JavaScript applications.
In the following posts I will explain FlashRT and its two main components browserglobal.swc and flash.swc