Safe from the Losing Fight

I’ve already posted the press release for Hearts Attack, but I thought I’d share a little about how Hearts Attack came about.

Way back in 2008 the original iPhone SDK came out, and I, like a lot of people, was excited about developing apps for the iPhone. My company is primarily a software development services company so I was mainly interested in learning the SDK so we could pick up iPhone contracts in addition to Mac ones. It also happens to be the case that my favorite card game is hearts, so I decided a good way to learn the iPhone SDK was to write my own hearts game.

After a couple of weeks I had the basic functionality implemented, and noticed I was playing it a lot. I realized then that I could probably make this into a product. Furthermore, releasing an iPhone app through the App Store seemed like a good way for us as a company to begin making the transition from a services based company to a product based one.

If I was going to release Hearts Attack as a published app, I knew the UI and presentation had to be greatly improved. I went through a lot of mockups for the main playing view, including one where everyone’s cards — all 52 of them — were always visible somewhere on the table (a truly horrible idea). Unfortunately I don’t seem to have most of the mockups around anymore, but I found a couple which you can see below. (See the product page for the end result.)

The biggest challenge I had was fitting everything on the screen and it still being legible and usable. By trial and error I figured out how small I could make the cards and still make them tappable, as well as their optimal position to make them accessible with one hand.

I began thinking about what would make Hearts Attack unique or different from its competitors. Back then there were literally just two iPhone hearts games in the App Store, and I felt pretty confident that what I had was already better than them, but I wanted to be sure. I decided on: oddball talking computer opponents, a tutorial that gave not only card suggestions but the rationale behind the choice (a pet peeve of mine), and multiple undo support for mis-taps and tactical errors.

The last step was to get professionals to do the sound and graphics. I ended up hiring a sound designer, a graphics designer, and a character illustrator. The sound design went smoothly, but getting the graphics done was a lot more involved than I anticipated, which is another story for another day. Jordan of OneToad Design created the app icon, playing backgrounds, and the special card backgrounds for the queen of spades and jack of diamonds. Lara Kehler did the character illustrations, which turned out great.

Unfortunately, Hearts Attack went on hiatus in early 2009. I was working full time on an iPhone contract, and simply didn’t have a lot of time to put into Hearts. Secondly, I had lost all desire in finishing it. It was becoming increasingly apparent that iPhone users didn’t want to pay more than $0.99 for anything, despite all the whining I did about it. I convinced myself it wasn’t worth releasing Hearts because it would never make back the money it cost us to make. Hearts stayed dormant for an entire year.

A couple of months ago, I decided to pick Hearts Attack back up again. I had the time and, as someone pointed out to me, it would never make money if I didn’t release it. I was tempted to update the app to the latest SDK (I started Hearts back before you could even use nibs on the iPhone) and add some features. I decided against this, because I really just wanted to ship it. I did have to update it to the 2.2.1 SDK because the current Xcode tools no longer ship with the 2.0 SDK.

Instead I focused on fixing the bugs and adding polish. Fortunately for me my wife happens to be a professional software tester with iPhone experience, so I got lots of good bugs to fix. I also prepared a press release, created a website, and otherwise got ready for the release. After I felt the app was stable enough, I submitted it to Apple on Friday. It was approved on Monday.

At this point, I’m still not convinced I’ll ever make back the money we spent on sound and graphic designers. A hearts card game simply is never going to be a big seller, and price point isn’t high enough to make up for that. Right now, I’m tending to think pessimistically about sales, but I’m going to do what I can to drum up sales and see how things go.

It’s a “wait and see” situation as to if we develop any more iPhone applications to sell ourselves. Of course, regardless of how well Hearts Attack does, we’d be happy to develop your iPhone app for you.

Lately it seems there’s been a lot of talk about distributed version control systems — especially git and Mercurial — and how they’re the bee’s knees or possibly even the cat’s pajamas.

But at the risk of having my programmer’s license revoked, I have to confess I don’t really care about version control systems. I mean, I think it’s important to use version control, but I don’t get all excited about the latest ideas in version control technology or the newest VCS on the block. It’s just a tool. It keeps versions of all my code, and allows me to revert to previous versions, see when and how things changed, and collaborate with other programmers working in the same codebase. Beyond that I don’t much care.

The tools don’t make the programmer.

What’s new with DVCS is the proponents seem to think they need to evangelize their system. Unfortunately they rather suck at it, and their arguments usually leave me feeling that I don’t want to use software used by such jerks, on account that it might make me into a jerk. Or at least a bigger one.

However, I do think that a DVCS can be a really useful tool so I’ve come up with some suggestions for those wanting to effectively evangelize their favorite version control system, or at least annoy me less when they talk.

1. Don’t be condescending or insulting

   I think it’s part of human nature — or at least programmer nature — to assume you’re the smartest guy in the room, and think that anyone who disagrees with you is a real buffon. Programmers seem to take great pleasure in showing that the other person is an idiot, or didn’t know something they did, or is at least not as clever as they are. A lot of arguments for git or Mercurial seem to revolve around explaining how git or Mercurial are so clearly superior that only morons would use something else.

   While this works great for rallying the troops, it’s counterproductive when trying to win someone over to your side.

   Think of it this way: suppose someone comes to your door to tell you about their religion. During the discussion they are self righteous and condescending; they don’t listen to your arguments, but are only interested in proving that they’re right. Are you likely to be swayed to believe in their religion? If you’re like the other hairless bipedal mammals inhabiting this planet you won’t be, even if they had some valid points.

   As soon as you become insulting or condescending, your arguments will be rejected out of hand. I know this will upset some programmers because they believe if you show your argument is superior, everyone will accept it. But that’s not the way people work.

2. Try to be helpful

   The best way to introduce someone to your DVCS is by trying to help them. Not in the “I have all the answers” way, but in the “I’ve dealt with that before, and here’s what I did” kind of way. People will run into the kinds of problems that DVCS are good at solving. When they do, you can helpfully suggest a solution.

   However, some care should be taken so the suggestion doesn’t come off the wrong way.

   Wrong	Right
   Dude, why are you using subversion?	I’ve run into that problem before. I solved it by using feature X of git/hg in this way.
   Dude, just use git/hg.	You smell nice.

   Be aware that people may not know where their pain points are. I’ve seen customers jump through some excruciating hoops to get a piece of software to do something when there was an easier way. People get used to pain and begin to assume it’s normal. If you notice something like that, even if they’re not complaining about it, you can politely suggest a better way.

   Instead of a list of features that a DVCS provides or abstract arguments as to why they should be using it, people respond better to concrete examples of how a piece of software can make their lives better. People are also more responsive when they know you’re on their side, trying to help them, even if they don’t — or currently can’t — take your suggestion. Keep in mind switching VCS in the middle of product cycle is likely something most people can’t do.

   The right attitude is that of trying to help a friend, not conquer an enemy.

3. Be willing to answer questions, even dumb ones

   Distributed version control works differently from centralized version control, and it does require a different way of thinking. I know I was confused by it when I first started looking into it. A lot of tutorials jump into the mechanics of how to perform certain tasks, but rarely talk about the philosophy of the system or why things are the way they are. If you want to successfully persuade people that your DVCS is the best then you need to be willing to do a lot of patient education.

   I say “patient” because after using centralized version control they might have difficulty switching over to a new mental model. Or they might have heard a lot of FUD about your DVCS that you need to put to rest. It’s important to do this patiently, respectfully, and not insultingly because they’ve picked up misinformation or don’t immediately “get it” like you do. Otherwise they might ignore your DVCS so they don’t have to deal with people who look down on them because they don’t “get it.”

4. Make it trivial to install and use

   This seems like a no brainer, but it is an important part of any software. If it’s hard to try out and use your DVCS, it simply won’t get used. I think that for the most part both git and Mercurial succeed in this respect. My only complaint is neither has a good Mac GUI client. Contrast that with Subversion which has both Versions and Cornerstone on the Mac. You shouldn’t underestimate the draw of an easy to use, beautiful GUI.

I think Joel Spolsky has given the best example of how to properly promote and evangelize a DVCS. He wrote a blog post — Distributed Version Control is here to stay, baby — about how he came to learn and use DVCS. It’s well written, and instead of condescending, he’s actually humble and admits he was wrong about DVCS to begin with. Joel also created a site called HgInit that does an amazing job of explaining the philosophy behind Mercurial and gives a solid introduction to right way to use it. It’s actually the site that convinced me to start using Mercurial for real.

The talk I’m working on for NSConference 2010 involves a decent amount of OpenCL kernel code. Originally, I thought I would develop the kernel code the same way I develop Core Image kernel code: build the kernel in Quartz Composer and then copy paste the code into Xcode when I got it working.

Unfortunately, I’ve not had much luck with Quartz Composer in way of meaningful compiler errors. Sometimes it returns good errors, sometimes inscrutable ones.

Composer: Wait, wait, I remember this… it’s COBOL, right?

However, I’ve found debugging OpenCL kernels to be much easier thanks to the invention of a function I like to call “printf.” If you run your kernel on the CPU, then you can print out values just like in C. With debugging solved, I just needed to figure out how to find compiler errors without having to run my code.

Unlike Core Image, OpenCL actually requires you to compile your kernel code explicitly before using it. The API’s required to do this will return nice compiler error messages and everything. The obvious thing to do would be wrap up these API’s in a command line tool and invoke the tool from Xcode, which is what I did.

The Code

You can download the Xcode project for clc, the OpenCL Compiler here. It requires Mac OS X 10.6 Snow Leopard and the associated Xcode tools. To install, just build the project and copy the resulting binary into your path somewhere. I used ~/bin.

Most of the code is self explanatory, with the possible exception of the output. Unlike most compilers, clc doesn’t output object code because the host and runtime CPU/GPU’s could easily be different. It could simply copy the source code as is for the output, but that was a little too obvious for my tastes. Instead clc compresses the source code and stuffs it into a binary plist. It has the slight benefit of potentially being smaller on disk, and making your source code negligibly less accessible to prying eyes, if you’re into that sort of thing.

There are definite possibilities for improvement. For example, there could be an option to encrypt the source code to be more “secure.” Or it could store the binary code generated by the host machine in the output on the chance that the host and runtime machines have the same hardware.

Setting up Xcode

To use clc, you’ll need to set up a build rule in your app’s target settings to run all OpenCL source files through it. Selecting the menu item Project > Edit Active Target, and then selecting the Rules tab, should land you here:

Add another rule, set it to process OpenCL source files using a Custom script. For the custom script enter:

~/bin/clc ${INPUT_FILE_PATH} -o ${TARGET_BUILD_DIR}/${PRODUCT_NAME}.app/Contents/Resources/${INPUT_FILE_BASE}.clar

Finally, you’ll need to tell Xcode where you’re putting the output file, which is:

${TARGET_BUILD_DIR}/${PRODUCT_NAME}.app/Contents/Resources/${INPUT_FILE_BASE}.clar

By default, Xcode won’t put OpenCL source files (.cl) into the target, meaning they won’t get compiled. For each of your OpenCL source files
you’ll need to explicitly add them to your target. There are several ways to do this, but the easiest is probably selecting all of them, and doing a Get Info (File > Get Info). Switch to the Targets tab and check the target they should be compiled into.

Runtime Code

At runtime, it’s pretty easy to retrieve the original OpenCL source code using the + (NSString *) openCLSourceWithData:(NSData *)data error:(NSError **)error; method on ONOpenCLArchive. However, there are a couple of convenience methods on NSBundle that makes retrieving the kernel easier. For example:

#import "ONOpenCLArchive.h"

NSString *kernelSource = [[NSBundle mainBundle] openCLResource:@"MyKernel"];

That’s pretty much all there is to it.

Conclusion

Although not ground breaking, this little tool has certainly been helpful to me by finding compiler errors at compile time instead of runtime. Hopefully it will be useful to other people as well.

For the uninformed, NSConference is a Mac developer’s conference put on by Scotty “The Scottster” Scott and his faithful sidekick, Tim “The Faithful Sidekick” Isted. They’re kind of the Batman and Robin of the Mac programming conference world, but have a slightly lower probability of bat-gassing you than the real dynamic duo.

This year they aren’t content with bringing conference justice to only the UK, so they’re branching out to the good ‘ole U.S. of A. by way of Atlanta, GA. To help you decide which conference you should attend, US or Europe, I’ve prepared the following quiz:

1. What is your opinion of Seattle?

   1. It’s nice, but isn’t nearly rainy or dreary enough.
   2. I like their coffee.
   3. The residents have too many teeth.

2. Describe your driving habits

   1. I like to drive on the left side of the road.
   2. I like to drive on both sides of the road.
   3. I like to merge right six lanes without signaling while going 147 mph on the off ramp and giving the finger with both hands in my black Camaro.

3. The pinnacle of human achievement is…

   1. Afternoon tea
   2. Sliced bread
   3. Hee Haw

Scoring: Give yourself -1 points for any 1 answer, 0 points for any 2 answer, and 1 point for any 3 answer.

If you scored is less than zero, you should attend NSConference Europe; if greater than zero, NSConference USA. If you scored exactly zero, you are truly a cultured individual and should attend both.

Personally, I’ll be attending both, and not just because of peer pressure and insightful quizzes. I’ll be presenting a talk on how to implement a watercolor brush using Core Image and OpenCL and maybe some duct tape. If you enjoy the graphics articles that I post here, you’ll probably enjoy my presentation. If not, I hear Steve “I’m Batman” Scott does a mean Adam West impression.

For one of my side projects that I’m currently working on, I decided to implement an AppleScript interface. Designing and implementing one wasn’t that bad, although Apple’s AppleScript documentation was sometimes confusing. Fortunately, CocoaDev has a good overview on how to implement AppleScript support.

However, one of my frustrations with working with other app’s AppleScript interfaces was trying to figure out how the interface was intended to be used. Sure, the AppleScript Editor would show me all the actions and classes, but it isn’t always obvious how things are supposed to fit together. Something that would help in these cases is AppleScript recording. I could record the app performing the actions I cared about, then examine how the app itself used the actions and classes. Unfortunately, it seems like only the Finder and BBEdit ever got around to implementing AppleScript recording.

In the hopes of increasing the number of apps with AppleScript recordability, I’m going to document my approach to implementing it. For brevity, I’ll assume you’ve already an AppleScript interface implemented for your Cocoa app.

Thinking Big Design Thoughts

If you have an AppleScript interface for your application, you may think of your app architecture as something like this:

Here your AppleScript interface and graphical interface are independent peers, and both modify your model classes directly to accomplish your application’s tasks. Each interface is separate and largely ignorant of the other.

However, when implementing AppleScript recordability it is helpful to think about your app’s architecture in a different way:

In this case the GUI is dependent on, and implemented in terms of, the AppleScript interface. The general guideline is that anything the GUI does that mutates or alters the model goes through the AppleScript interface. However, if the GUI simply needs to access or get information from the model, it would go directly to the model, not through the AppleScript interface. Accessing the model can happen at seemingly random times to the user, and spamming the AppleScript Editor with these accesses when recording only confuses the user.

Suppose an application has table view and a button that deletes the currently selected item in that table view. The table view data source would be implemented the standard way, simply going directly to the model, bypassing the AppleScript layer. However, the delete button, since it alters the model, would be implemented by invoking the AppleScript delete command on the object represented by the current table row.

This design has some other benefits besides recordability. Notably it helps test your AppleScript interface design and implementation. If you find that implementing a GUI feature in terms of your AppleScript interface is impossible or difficult, congratulations, you found a bug! Also, merely testing your GUI also exercises your AppleScript interface. It is not a replacement for testing your AppleScript interface explicitly, but it certainly helps.

Implementation Hardships

Everything I’ve talked about so far hasn’t been all that novel, and probably has been met with large bucket fulls of “well, duh”s by anyone who’s ever looked into implementing AppleScript recording. The problem isn’t thinking about how to design in recordability, but actually implementing recordability.

As things stand now, doing something as simple as “invoking the AppleScript delete command on the object represented by the current table row” is incredibly involved and painful. You have to manually build up the AppleEvent that represents the delete command and the target model object using functions like AEBuildAppleEvent or classes like NSAppleEventDescriptor. Then you have to remember to target your app by specifying the kCurrentProcess process serial number (specifying kCurrentProcess as the ProcessSerialNumber is currently the only way to enable recording. Bundle identifiers, urls, and pid_t’s do not work.), and parse the AppleEvent you get back into something useful. You’d have to do this for every property or method on your model object you want exposed for recordability.

Dreaming of Ponies

The thing is, the Cocoa runtime has a lot of the AppleScript information from your SDEF file at its disposal and could theoretically generate these interfaces for you. In the ideal hypothetical situation, invoking the delete action via AppleScript inside your app could be as simple as:

// Suppose ONEmployee is our model object, with the appropriate AppleScript interface implemented
ONEmployee *employee = [_employees objectAtIndex:0];
ONEmployeeASProxy *proxy = employee.appleScriptInterface;
[proxy delete];

Here, any object that implemented the objectSpecifier method for AppleScript support would automatically get an appleScriptInterface property. The object returned by appleScriptInterface would be a proxy object implementing the same methods and properties as the original object. The proxy object would implement these methods by building up the appropriate AppleEvents, sending them, and parsing the resulting event back into a usable object.

Apple actually gets tantalizingly close to this with the Scripting Bridge. Outside users of your app can run your SDEF file through the sdp command line tool and get a nice Objective-C interface of proxy objects that build, send, and parse AppleEvents to and from your app. However, there is not currently a way tell these proxy objects to target kCurrentProcess, or to initialize one of the proxy objects by passing in a model object that implements objectSpecifier. (I’ve written this up as rdar://problem/7359646.)

Harsh Reality

Since I didn’t want to wait on Apple to extend the Scripting Bridge to make my life easier, I decided to write a couple of classes to help out. You can download the code here. The code is under the MIT license.

The classes work similar to the SBObject and SBElementArray classes in the Scripting Bridge framework. Using these classes, you can invoke the delete AppleScript method like so:

// Suppose ONEmployee is our model object, with the appropriate AppleScript interface implemented
ONEmployee *employee = [_employees objectAtIndex:0];
[ASObj(employee) invokeCommand:@"delete"];

The ASObj function creates an ASObject proxy object for any NSObject that implements objectSpecifier. invokeCommand takes care of marshalling the parameters into an AppleEvent, sending it, and unmarshalling the return value into an NSObject. The name of the command is the name of the name used in AppleScript, not the Cocoa implementation.

invokeCommand can take parameters, although it gets more tricky:

ONEmployee *employee = [_employees objectAtIndex:0];
[ASObj(employee) invokeCommand:@"giveRaise" with:[NSNumber numberWithInt:10], @"Percent", nil];

First, the parameters must be named (it’s not done by parameter order), and those names must match the Cocoa Key in the SDEF, not the user visible parameter name. Second, the marshalling code (from random NSObjects to AppleEvents) is a bit sparse. I’ve only added code for the types I needed for my project. If you use it, you may need to add support for other types. The same goes for return values; I only added support for the types that I use.

ASObject also has support for properties. For example this marks an employee as exempt:

ONEmployee *employee = [_employees objectAtIndex:0];
[ASObj(employee) setObject:[NSNumber numberWithBool:YES] forProperty:@"isExempt"];

The same type restrictions for parameters apply to properties as well. The Cocoa Key for the property must be used here, the same as parameters.

Elements also have basic support, which is where the ASElementArray comes in. Right now the only interesting thing to do with an element array is retrieve a reference to a specific element:

ONEmployee *employee = [_employees objectAtIndex:0];
ASObject *dependent = [[ASObj(employee) elementForKey:@"dependents"] objectAtIndex:0];
[dependent setObject:[NSNumber numberWithBool:YES] forProperty:@"insured"];

Unlike other methods, ASElementArray’s objectAtIndex does not execute an AppleEvents or otherwise take any actions. Instead it constructs an object specifier (i.e. an ASObject) for the given element.

The code is still somewhat rough and incomplete, but should help with anyone wanting to implement AppleScript recording. If nothing else, it should serve as a starting point or sample code for anyone rolling their own solution.