Introduction
Automated building of actionscript (flash and flex) applications is becoming more and more important as the Flash Platform starts to mature. It is crucial to have automated builds in order to maintain proper continuous integration and testing practices. If you do not know what continuous integration is then please read the following if you get a chance http://en.wikipedia.org/wiki/Continuous_integration.
Two very popular automated build tools for use with Actionscript are Ant and Maven. Ant is very well supported and preferred by Adobe. However since I have started consultancy work in financial institutions and working on more ‘enterprise’ level Flex applications I have discovered that the build tool of choice is Maven. This is because it can easily (well relatively anyway) integrate Actionscript builds with Java builds and it is extremely good at managing dependencies between projects.
Maven was developed for simplifying the building of large Java projects, but via plugins it can be extended to build other languages. Currently the accepted way of building Actionscript applications using maven is to use the Flexmojos plugin from Sonatype: http://flexmojos.sonatype.org/
Credit where Credit is Due
At the time of writing Flexmojos is heading towards a version 4 release. A massive amount of unpaid work has gone into the project and it has been driven tirelessly by one man, Marvin Froeder. I would like to offer him my support as well as my thanks for making such an indispensable tool.
A Problem
There is a very teasing page on the Sonatype website with a title somewhat like the one of this article https://docs.sonatype.org/display/FLEXMOJOS/Installing+Flex+SDK+into+maven+repository It shows a maven command line that will apparently install an SDK to your local maven repository. You describe what to install by using an XML file called the ‘descriptor’, and they even show an example of what that file structure should be. All well and good, but unfortunately underneath the XML example there is a warning
The descriptors used by Flexmojos to publish Flex SDK aren't public available and won't be provided. The goal is to really make this process hard. If possible impossible to reproduce. People tend to abuse on this, leading to ghost bugs and all kind of inconsistencies. This is a very sensitive process, so be aware that even Flex SDK published on Flexmojos repository can be broken.
This means that, for reasons I do not want to go into here, Sonatype do not want you to install your own SDK into your own maven repository. The only SDK’s that are meant to be used are those installed by Sonatype into the main Sonatype repository.
This is currently causing issues for teams who wish to use SDK’s that have not (or will not) be uploaded to the main Sonatype repository. For example, what do the Away3D team do if they want to use a Molehill enabled version of the SDK? What does a major financial institution do if they have to fix a critical bug in the SDK and need to use that monkey patched version? The answer is that they don’t use maven.
I think that this is wrong and bad for the uptake of maven as a build tool for actionscript applications. Therefore I have now spent some time undertanding how to use the tools suggested on that page along with the ‘descriptors’ file and hence to install my own SDK’s.
In this article I will show you how to use openly available and simple tools to install and/or deploy any Flex SDK you want to any repository that you have permission to do so. By doing so you must be aware that neither Sonatype nor Marvin will offer support for an SDK installed in this manner. However I am willing to offer some support to people and talk about any problems that they encounter. I wish to increase the communities knowledge of how to do these things.
One more word of warning before I continue – I have been banned from the Flexmojos google group for talking about these things, and so if you do wish to try it out, I would recommend that you do not post about it there. I have set up a list to discuss this independantly, and you can find it here http://groups.google.com/group/flex-sdk-maven-install.
The Install Command
A flex SDK is installed to a local maven repository directly from the zip file that you download from Adobe. Which parts of the SDK and their dependencies that get installed are controlled by two xml files called descriptors – one for the framework and one for the compiler. The actual install is performed by calling a maven goal as follows
mvn
org.sonatype.plugins:bundle-publisher-maven-plugin:1.1:install-bundle
-Dbundle={bundle zip file}
-Ddescriptor={bundle descriptor file}
It uses a maven plugin called the bundle-publisher-maven-plugin whose source code can be found here. In the original sonatype page the version was specified as 1.0, but this does not currently work and 1.1 has to be used instead – see the config files section coming up.
The Descriptor File Strucuture
The descriptors describe how the SDK should be installed into a repository. Each one is essentially a list of dependancies and POM’s that the publisher plugin reads. It then extracts the relevant files from the bundle and packages them in a way that can be used by Flexmojos.
Because the descriptor file is XML there is no fixed order to the elements inside it. However each descriptor should have certain sections in it in order to work correctly.
Each descriptor will now be described in more detail.
The Framework Descriptor
The framework descriptor file has several sections.
The Header
This is where some common information is defined
<?xml version="1.0" encoding="UTF-8"?> <mapping> <version>1.0</version> <organization> <name>Adobe Inc.</name> <url>http://www.adobe.com</url> <license/> </organization> <defaults> <groupId>com.adobe.flex.framework</groupId> <version>4.5.0.19786</version> </defaults> <artifacts>
The mapping, version and organisation nodes probably don’t need to be changed (although it would be good to know what the version meant). The important nodes are the default ‘groupId’ and ‘version’ nodes which will form the groupId and version coordinates of the maven install (see here for more information on coordinates). Each artifact installed by the publisher will have this groupId and version unless it is overridden in the actual artifact description, and therefore a lot of repetition is removed.
The header ends with the start of the artifacts node.
The Artifacts
This is where all the actual artifact to be installed are defined. Each artifact is wrapped in an artifact node and then their contants are described.
There are essentially two kinds of artifact in here, POM’s that describe dependencies and the dependencies themselves. The two POM’s defined in the framework descriptor are -
The Common Framework POM
Here is a snippet of the 4.5.0.19786 common framework POM definition in the 4.5.0.19786 descriptor file (it is missing many dependencies).
<artifact> <artifactId>common-framework</artifactId> <type>pom</type> <dependencies> <dependency> <artifactId>core</artifactId> <type>swc</type> </dependency> <dependency> <artifactId>text-layout</artifactId> <type>swc</type> </dependency> <dependency> <artifactId>text-layout</artifactId> <type>rb.swc</type> </dependency> </dependencies> </artifact>
This POM defines all the dependencies for the SDK. Actually to be more accurate the above POM template defines that a POM artifact must be installed with matching structure and dependencies – it is not the actual POM itself. For each dependency listed in this POM there will be a matching artifact that needs to be installed and this artifact will also be listed in the descriptor file.
There are two types of swc artifact – a normal swc and an rb.swc. This is the way in which flex mojos deals with locales. In the above example the advancegrids swc also has a locale swc, but the authoringsupport swc does not.
The Flex Framework POM
This artifact describes a POM that links the flash player dependencies to the common framework dependencies above
<artifact> <artifactId>flex-framework</artifactId> <type>pom</type> <dependencies> <dependency> <artifactId>common-framework</artifactId> <type>pom</type> </dependency> <dependency> <artifactId>playerglobal</artifactId> <type>swc</type> <classifier>10.2</classifier> </dependency> <dependency> <artifactId>playerglobal</artifactId> <type>rb.swc</type> </dependency> </dependencies> </artifact>
Other playerglobal artifacts are added separately but I this makes the one mentioned here the default.
The Player Global Artifacts
Flash players that you want to install are defined here. Normally there is only one flash player per SDK but occasionally you might want to define a couple, for example early 4.5 SDK’s could have 10.1 and 10.2 players in them.
A player global install consists of 3 artifacts, and looks like this
<artifact> <artifactId>playerglobal</artifactId> <type>swc</type> <location>frameworks/libs/player/10.2/playerglobal.swc</location> <classifier>10.2</classifier> </artifact> <artifact> <artifactId>playerglobal</artifactId> <type>rb.swc</type> <classifier>en_US</classifier> <location>frameworks/locale/en_US/playerglobal_rb.swc</location> </artifact> <artifact> <artifactId>playerglobal</artifactId> <type>rb.swc</type> <classifier></classifier> <location>empty.swc</location> </artifact>
The first two artifacts are pretty self explanatory – the player and its en_US resource bundle (you could add others), but what is the third one? What is empty.swc? It is here that we first encounter the empty swc.
The curious incident of the empty.swc
If you look in a maven repository installation of a Sonatype Flex SDK, you will notice that for every swc file that needs a localised resource bundle there is a 22 byte file of type rb.swc.
Here is my mac’s directory list for the textlayout framework from the Sonatype 4.1.0.16076 Flex SDK install.
You can see the 22 byte file just sitting there. It seems that Flexmojos will not work without this file, even though it never gets explicitly mentioned as a dependancy.
Luckily it turns out that this file is just an empty zip file, and it is also the exact same empty zip file for every swc that needs a locale resource bundle. Therefore it is very easy to add an empty.swc to the SDK bundle and then refer to it in the descriptors file every time it is needed, and that is exactly what you see here.
UPDATE: 21/03/2011 – The empty classifier node is necessary to prevent another pom being deployed which would overwrite the one for the main artifact.
Dependencies
Each dependency listed in the POM artifact descriptions must also be in the descriptor file. These are simply added as artifacts that are installed when the publisher does its stuff. Here is the description for the core swc from the 4.5 SDK
<artifact> <artifactId>core</artifactId> <type>swc</type> <location>frameworks/libs/core.swc</location> </artifact>
Dependencies with Locales
Each dependency that requires locale resource bundles consists of at least 3 artifacts – the swc itself, at least one resource bundle and the ubiquitous empty.swc described above. Here is the text layout swc definition.
<artifact> <artifactId>textLayout</artifactId> <type>swc</type> <location>frameworks/libs/textLayout.swc</location> </artifact> <artifact> <artifactId>textLayout</artifactId> <type>rb.swc</type> <classifier>en_US</classifier> <location>frameworks/locale/en_US/textLayout_rb.swc</location> </artifact> <artifact> <artifactId>textLayout</artifactId> <type>rb.swc</type> <classifier></classifier> <location>empty.swc</location> </artifact>
The Configuration Files
Th final piece of the puzzle are the configuration files, themes and fonts required by an SDK install. This requires using nodes in the descriptor that are not listed on the Sonatype page. I found these by analysing the code for the publisher plugin. The required files are gathered together into a single zip file artifact. This zipping up does not work with 1.0 of the publisher plugin which is why version 1.1 at least must be used in the command to perform the install.
<artifact> <artifactId>framework</artifactId> <classifier>configs</classifier> <type>zip</type> <location>frameworks</location> <includes> <include>air-config.xml</include> <include>build.xml</include> <include>flash-unicode-table.xml</include> <include>flex-config.xml</include> <include>localFonts.ser</include> <include>macFonts.ser</include> <include>metadata.xml</include> <include>mx-manifest.xml</include> <include>mxml-2009-manifest.xml</include> <include>mxml-manifest.xml</include> <include>spark-manifest.xml</include> <include>winFonts.ser</include> <include>themes/</include> </includes> </artifact>
The Compiler Decriptor
The compiler descriptor is much simpler and contains a POM artifact and then the dependency artifacts for that POM.
The structure of this file and its content are exactly the same as for the framework descriptor.
The Full Install Process
Once you have made your descriptor files the process becomes this -
- Download the Flex SDK of you choice: For example flex_sdk_4.5.0.19786.zip
- Inject empty.swc into the zip file. In unix/linux/osx you type
zip flex_sdk_4.5.0.19786.zip empty.swc
- Install the framework
mvn org.sonatype.plugins:bundle-publisher-maven-plugin:1.1:install-bundle -Dbundle=flex_sdk_4.5.0.19786.zip -Ddescriptor=flex4.5.0.19786.framework.descriptors.xml mvn org.sonatype.plugins:bundle-publisher-maven-plugin:1.1:install-bundle -Dbundle=flex_sdk_4.5.0.19786.zip -Ddescriptor=flex4.5.0.19786.compiler.descriptors.xml
Source Code And Examples
A lot of source code, examples and tests can be found in a github repository dedicated to this informtaion – https://github.com/piercer/flex_sdk_maven_install.
In there you will find complete descriptors for installing the 4.5.0.19786 Flex SDK, and a script for doing so.
I am sorry that there are no windows scripts. I do not have a windows machine. If anybody would like to contribute some I would be most grateful.
Conclusion
I worked most of this out for myself, and so it might be wrong. Personally I have however had some good successes and am trying to improve the process.
If you want to install/deploy your own SDK’s then please join the google group to discuss things, especially if you have any issues.
Thanks
Conrad Winchester
