Simon Gregory

A code validator was for a long time one of the tools missing from the ActionScript developers toolbox. Last year that changed and we can now benefit by keeping a robotic eye on our projects. One that helps improve style and consistency, and avoid complexity. Something even more important in team or distributed code environments. Hooking validation up to a continuous integration server is even better as the audit triggers automatically, problems get reported and graphed, and builds can be failed when maximum limits are breached – a clear signal that it’s time to review and refactor.

Joa Ebert was first to the market with AS3V and I quickly wired it up to run with TextMate. AS3V is 90% to 95% there, but still needs a couple of features. My guess is that Joa is now focusing on other things.

Since then Adobe have open sourced FlexPMD. After a couple of false starts I was able run the RC4 build against the codebase I was working with at the time. Even though we’d been through and fixed most of the 3,000 odd issues reported by AS3V, FlexPMD kicked out over 5,000 ‘violations’. The code had been worked on by around 20 developers over a 3 year period so it’s likely to be an extreme case, but still my advice is to use it from the start of a project.

For TextMate users the FlexPMD.tmbundle should help make the process easier. Installation and usage details are covered in the README. They boil down to using ⇧⌃v then selecting ‘Project’, ‘Document’ or ‘Show Report’.

Finally its worth saying that being pragmatic is a sensible option when working with validation tools. They aren’t a substitute for a good programmer. So blindly accepting the default ruleset and fixing everything won’t necessarily be productive. You can and should consider modifying the rules to get what suits you and your team, and there’s always going to be exceptions to the rule. Which is what //NO PMD is for.

Being a Ruby lover I’ve always intended on using Sprouts for project management. But when I was last looking for a solution you couldn’t easily specify which revision of a Flex SDK a project should be built with. This was something we needed to do. Access to the continuos integration box was limited which also caused problems, so we went with ant. I’ve been rolling out the same ant scripts and associated libraries into projects ever since. Code should be DRY, so why not your projects?

Minimalism in action

Maven has always been on the radar, but Flexmojos has made it all the more attractive to flash developers so there’s been more and more chatter about it recently. At work it’s been talked about for while, and after a sales pitch from Mischa, I’ve finally started to put it into action. So far it’s really cool, simple, clean, and consistent. The projects I’ve converted just end up with test and src directories. A lot of junk is gone, reduced to a few lines in a pom.xml file. They’re smaller and easier to understand. Just the kind of minimalism I like.

Getting an overview

Starting by understanding how Maven works is a sensible idea, for this try Maven:The Complete Reference. Then, for flex related tasks the Flexmojos site is a good source of information. Keeping an eye on the Flexmojos mailing list also helps.

Installing maven 2 + 3

Maven comes preinstalled on OS X so type mvn --version into the Terminal and you’re likely to see this:

Apache Maven 2.2.1 (r801777; 2009-08-06 20:16:01+0100)
Java version: 1.6.0_20
Java home: /System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home
Default locale: en_GB, platform encoding: MacRoman
OS name: "mac os x" version: "10.6.4" arch: "x86_64" Family: "mac" 

This means you’re good to go with all versions of Flexmojos prior to 4.x but you’ll need to install Maven 3 if you need to use any of the features in 4, as I’m after AIR compilation, and ASDOC builds against Flex SDK 4 I needed to install the Maven 3 beta.

To start with download it, then unzip to /usr/local/apache-maven/apache-maven-3.0-beta-1. You’ll then need to edit your ~/.profile to include the following:

export M2_HOME=/usr/local/apache-maven/apache-maven-3.0-beta-1
M2="$M2_HOME/bin"
PATH="$M2:$PATH"
MAVEN_OPTS=-Xmx1024m

The last line isn’t necessary, but I added it to give Maven a little more memory to work with. The install notes also say you need to set JAVA_HOME. I didn’t find it necessary, but if you want to then finding out where JAVA_HOME is on a mac means running /usr/libexec/java_home (should be the same as what Maven’s just told you above) and adding the results to your ~/.profile. For me this was:

export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home

Running tests also meant doing a little bit of work. If they don’t work for you then you may need to tell Flexmojos where to find your install of the standalone flash player. So going back to your ~/.profile you will need add the following:

PATH="$PATH:/Applications/Flash Player Debugger.app/Contents/MacOS/"

Then your pom file needs the following added to the flexmojos-maven-plugin configuration node.

<flashPlayerCommand>Flash Player Debugger</flashPlayerCommand>

There’s a full example of this here

Concluding with poms

Once installed maven is designed to automatically fetch all the resources it needs. This is done via configuring your pom files to reference the right artifacts so that maven can retrieve them. Where a dependency can’t be found online you have the opportunity to install it locally. So far I’ve used the documentation and found example files and have been reasonably productive. This example pom tests, compiles, validates and generates asdocs for a swc library I’m experimenting with. I’m looking to expand this to include swf + air compilation, and test coverage reports.

As Flexmojos 4.x is still under active development it can be tricky to get something to work as expected, you do need a little patience. But that is to be expected with alpha software. Version 3 doesn’t offer the full feature set I’d like so at the moment maven doesn’t feel like the complete solution. But as the source is now on github so maybe I can find some time to help out. Overall I’m totally sold on the concept and am looking forward to 4.x moving into stability.

When I upgraded to Snow Leopard a few months ago I found out quite quickly that locate didn’t work on the command line. Why locate is missing I don’t know, maybe find was supposed to replace it. But find doesn’t look deep enough into the system files to be useful for me. I finally got round to looking into the problem.

Using locate file.txt get’s us this:

WARNING: The locate database (/var/db/locate.database) does not exist.
To create the database, run the following command:

  sudo launchctl load -w /System/Library/LaunchDaemons/com.apple.locate.plist

Please be aware that the database can take some time to generate; once
the database has been created, this message will no longer appear.

Ok. So it’s easy enough to run:

sudo launchctl load -w /System/Library/LaunchDaemons/com.apple.locate.plist

But that didn’t do anything for me. Locate still threw the same error and top didn’t reveal any processes that appeared to be working overtime to build the database(*see below). Trying the launchctl load command again says it’s already loaded, and using start com.apple.locate via a launchctl daemon gets a start error:No such process message. So I opened /System/Library/LaunchDaemons/com.apple.locate.plist which revealed the task that actually does the work is locate.updatedb, so I tried:

sudo /usr/libexec/locate.updatedb

Which successfully built the database and locate now works. The one question remaining is wether the database will be updated automatically every Saturday at 3am as the plist file suggests. Maybe not, if the <key>Disabled</key><true/> in the plist is to be believed – so I’ve blindly switched it to false and am hoping for the best.

* I ran through this process again on a second machine, and it appears that I jumped the gun on this as I just left the machine be for half an hour and came back to it and the database worked.

Initially I set out with the aim to switch from Subversion to Git before there was an official plan from the TextMate crew. This has now changed, and all bundles that show Github activity are being removed from the TextMate svn repository. Which means that the official bundles I mirrored now have a duplicate Github mirror, and one that is more central for TextMate users and should be the root of all development. The Apache bundle was easy to sort, as there were no forks I could simply delete my copy. The Ant bundle wasn’t so straightforward.

Theoretically there’s no reason why two mirrored repositories couldn’t be used as each can be added as a remote. But because of their independent initialisation against the svn repo their histories aren’t identical this doesn’t work correctly in practice. Even though the file contents are identical at each commit git still recognises separate commits because git-svn appends unique metadata. So you end up with a lot of messy duplication in the history tree.

The fastest solution is to rebase one mirror into the other. Public rebasing isn’t the done thing as it’s bad practice to be changing the repository history when others could be working against it. However in this case we are looking to retire one history completely. I think, given that there’s only a little work in the forks, and the file content is the same it is the right solution.

So here are the steps I took to merge my mirror into the official one

• Forked and cloned the official bundle on github
• cd‘d to the root of the clone
• Added new remote using git remote add old-origin git@github.com:simongregory/ant-tmbundle.git
• Fetch the remote data git fetch old-origin
• Created old-master branch from the old-origin/master with git br old-master old-origin/master
• Checked out old-master git co old-master
• Rebased old-master onto master using git rebase master
• Switched back to master git co master
• Merged master with old-master git merge old-master
• Deleted the old-master branch git br -D old-master
• Created new sg branch git co -b sg
• Cherry picked the one commit I needed git cherry-pick 91f598
• Pushed the branch git push origin sg
• Removed the old-origin remote using git remote rm old-origin

Then to linked to the official TextMate remote using

• git remote add tm git@github.com:textmate/ant.tmbundle.git
• Fetched the remote data git fetch tm
• Checked master out git co master
• Synced master branches by pushing git push tm (only possible if you have write access)

One extra thing to note is the change from the old naming convention using a hyphen to a period.

There’s likely to be a better way of achieving this, but this is what worked for me. It won’t work if you have any private branches as you wouldn’t be able to pull them across. In this case I’d look at inverting the process and adding the new fork as a remote to the existing repository and merging from there.

Git is one of the tools I’ve been meaning to try for a while now. It’s a version control systems that offers a distributed model, is fast, light and perfect for branching and merging.

I was pretty confident I’d be up and running quickly with git as I’m used to subversion. But given the past few days experience I wouldn’t say it’s been easy. It may have been, but I decided my way in would be to mirror both the Flex and ActionScript 3 TextMate Bundles over on github – which meant using git svn. In principle it looked straightforward, but after a few clumsy maneuvers I was quickly disorientated (mainly because git svn dcommit happens to rebase on the quiet). I don’t think I’m out of the woods yet but am really beginning to see what all the noise over git is about. It’s well worth the initial steep learning curve.

What I’m hoping to see are forks of the bundles, new features, feedback, and maybe one or two bug fixes ;) There are some branches to try as well. One or two build solutions have been cooked up but not quite finished. Alongside a basic attempt to integrate fdb, but it still needs a UI bolting on the front to offer true integration.

Oh, and for those of you who’ve been waiting for the auto-completion alpha then that’s in the main bundle now. Take a look at the ‘Auto Complete’ command – I’ll post a little more about it soon.

The ActionScript 3 bundles had the ability to auto import a class for a long time, but the functionality has been limited to the area of the document between the package and class declarations. There have been some interesting solutions to improve this workflow, but ultimately it needed a more elegant solution.

If you grab the most recent version of the bundle you’ll now find that ⇧⌘I can be invoked from a wider scope and will present you with a list of possible classes to import based on the current word. Select one and an import statement for the class will be generated and injected into the document (or a tooltip saying the class is already imported).

I ought to stress that the importing is improved, but needs more work. The command is scoped to work within a public class, so any private classes hiding beneath your package block won’t benefit. You’re also likely, if you’re tidy, to want to organise the imports statements later on. But what is great about this is it let’s you skip a repetitive task and focus on higher level logic.

Here’s a little teaser showing autocompletion for ActionScript 3 in action using TextMate.

It’s work in progress and I’m planning on releasing it for testing once Dialog 2 moves out of review. I also need to add the functionality to search multiple ancestors in interfaces to resolve the type of an item.

I’ve quickly put together a bundle for working with JSFL, or the Flash JavaScript API. If you’re not familiar with JSFL it is used to automate and extend the Flash IDE. The bundles language grammar relies on the JavaScript bundle being installed (which is one of TextMates default bundles) as it extends it and adds all of the JSFL objects, methods and properties. You also get:

Run (⌘R)

Runs the current document in Flash.

Documentation (⌃H)

Searches the documentation and presents a list of matches. As I only have access to machines with Flash CS3 installed I don’t know the alternative paths to the documentation previous (and later) versions of Flash use so please drop me a line and I’ll include them.

Auto Complete Method / Property (⌥⎋)

Provides a pop-up list of the available method and property completions based on the current word.

I’d recommend checking out the bundle from here for the most up to date version, otherwise you can download it as a zip here.

JSFL Bundle

The Apache bundle, which I originally contributed in the early days of TextMate, was due an upgrade. So I’ve made a few improvements…

Start, Stop, Restart and Graceful commands (⌘R)

These commands, which all target apachectl, are now bound to ⌘R under the source.apache-config scope which makes it more convenient to directly control httpd from TextMate.

As apachectl requires sudo privileges I used applescript for authentication. For reasons only known to Apple the password request dialog would launch but not get focus – leaving you to reach for the mouse to target the input field. Moving away from the keyboard is slow so this was something that really annoyed me. I’ve now switched to using the excellent tm_dialog system which makes things much smoother.

It is also possible to store your admin password in your Keychain, this is done by selecting the “Add to Keychain” toggle in the password request dialog box. I’m more than happy with the security implications of this as I’m fairly good at keeping my machines locked. If you do choose to do this then the command line security app will have access to the keychain item and is the only way someone could gain access.

Documentation (⌃H)

This now searches a documentation index file for the current word/selection then redirects or presents a list of matches as appropriate. If you appear to have the documentation installed locally then the script favours it over the apache website.

Open Include (⇧⌘D)

The language definition has been improved to add a scope for Includes. Using the key combination apple-shift-D on this scope opens the file referenced by the inlcude, or directory if it is wild carded.

Open Config… (⇧⌘C)

Previously there were various commands to open the apache.conf files these have now been consolidated into one command which searches the apache install directory, either /etc/apache2 or /private/etc/httpd depending on your version of OS X and the /users, /extra and /other subdirectories. All the conf files found are presented in pop-up from which one can be choosen to open.

Bundle Configuration

It is now possible to override the default bundle behaviour by setting the following environmental variables. TMAPACHEDIRECTORY, TMAPACHEACCESSLOG, TMAPACHEERRORLOG and TMAPACHEMANUAL_URI all allow the custom targeting of files and directories. See the bundle help for a detailed explanation.

I’m often opening the bundles I develop – and nosing through the others – as projects, and doing so via the Finder or the File > Open menu is long winded. To speed up the process here’s a small command which searches the default bundle locations and presents all the bundles in a dialog. Pick the one you’re interested in and TextMate opens it as a project. That’s if it’s enabled, when it’s not the default behavior is to enable it, second time round it will open as a project.

Download