Introducing Your New YUIDoc Theme

I like YUIDoc. I don’t like its default theme. Since I couldn’t find any other themes on them internets, I wrote my own, named “Dana”.

Since I normally use YUIDoc to document either pure Javascript or jQuery code¹, I didn’t keep any of the old YUI code; I’ve ditched pretty much everything and started from scratch. And this is what I’ve come up with:

As you can see in the screenshot, as an example I’ve generated the well-known YUI API docs. So here’s the original YUI documentation in its original look — and here is the very same documentation sporting the new Dana theme.

I hope you find the latter more pleasing just as I do. :) Click around a bit; check some of the class documentations for a more in-depth comparison; play with the filters; feel the luxurious yet cheap plastic underneath.

This is a work in progress. It’s reasonably stable and working for me so far. YMMV. If you encounter errors, please create a ticket.

You’ll find “Dana” on GitHub. If you’re so inclined, you can dowload the latest stable release as zip/tgz file, too.

Dual-license, MIT & GNU GPL v2. Tested in Safari 5 (OSX), FF3.6 (OSX), IE8 (WinXP).

Assorted MacRuby Snippets #2

This post references MacRuby 0.5, used with Xcode 3.2 on Snopard (10.6.2); the general technique will likely work on other OS/Xcode version, tho. Just saying.

Apps with more than just one framework

The standard MR app template massages $LOAD_PATH a bit in order to have apps which embed the MR framework use said embedded framework in Release builds. The piece of code in question looks like this:

if Dir.exist?(NSBundle.mainBundle.privateFrameworksPath)
  $:.map! { |x| x.sub(/^\/Library\/Frameworks/, NSBundle.mainBundle.privateFrameworksPath) }
  $:.unshift(NSBundle.mainBundle.resourcePath.fileSystemRepresentation)
end

Which is quite alright if all you embed is the MacRuby framework and are building a release. But as soon as you add another one (Sparkle, for example), the test will always be true, whether you’re debugging without embedding MR or not, and your console will show Ruby load errors. The fix is easy, but it took me a few minutes to find the issue, so here we go.

if Dir.exist?( File.expand_path("MacRuby.framework", NSBundle.mainBundle.privateFrameworksPath) )
  $:.map! { |x| x.sub(/^\/Library\/Frameworks/, NSBundle.mainBundle.privateFrameworksPath) }
  $:.unshift(NSBundle.mainBundle.resourcePath.fileSystemRepresentation)
end

Just a heads-up: the rb_main.rb template in the current MR nightlies doesn’t contain the code above anymore — it appears the “magic” was moved into macruby_deploy (changeset), so it’s likely my fix will be unnecessary in MR 0.6.

Accessing the Keychain with MacRuby

This post references MacRuby 0.5, used with Xcode 3.2 on Snopard (10.6.2); the general technique will likely work on other OS/Xcode version, tho. Just saying.

At some point in my project I needed to access OSX’ Keychain to store sensitive userdata. Unfortunately, due to the lack of void pointers in MacRuby 0.5 (see Trac ticket), I couldn’t use standard methods like SecKeychainAddGenericPassword. The guys on the mailing list told me to use a wrapper instead. Doing some reading and poking around the interwebs I finally figured it out, and since it’s a neat trick I thought I’d scribble it down, so maybe it will safe someone in a position like me a bit of time. ;)

I’ve decided to go with ExtendMac’s EMKeychain class because it’s simple, clean, free and has a liberal license (MIT license, if I’m not mistaken).

Disclaimer: I’m not a Obj-C person, and what you’re about to read is what works for me. I’ve tinkered until everything was moving in the right direction. There might be better ways (I’m pretty sure there are), and if what I’ve done here is bollocks, I’d be delighted if you would share your knowledge with me. :) Also, I’d enjoy a comment with your thoughts about this here article. Any opinion will do. Just curious is all.

Step 1: Build the wrapper, EMKeychain.dylib

First, we’ll have to make EMKeychain into a dynamic library. Download it from the site, unzip it, and fire up Xcode. There, start a new project of the type “Cocoa Library”.

When asked for the name, call it “EMKeychain”. It kind of makes sense. This is what you’ll end up with:

In the screenshot you’ll notice a file called EMKeychain_Prefix.pch. That’s a so-called “precompiled header”; Xcode creates it automatically for you on project creation.

Next, add the files EMKeychain.m and EMKeychain.h to your project by dragging them from the download folder to the “Classes” folder.

Since the EMKeychain documentation said the class needs to be linked against Carbon and Security frameworks, do that by right-clicking on the “Linked Frameworks” folder in the tree and selecting Add Existing Frameworks…:

Following the related MacRuby tutorial’s advice, add a constructor to the end of EMKeychain.m:

void Init_EMKeychain(void) { }

Next, adjust the build settings — switch the base SDK to 10.5…

… and enable GC.

Build a release, and you’ll have your wrapper.

Step 2: Using it

Now for the fun part.

1. Add the just built EMKeychain.dylib to your MacRuby project. (Don’t forget to copy the file over.)
2. Add EMKeychain.dylib to Targets ➔ [project name] ➔ Copy Bundle Resources.

And that’s it. If all went well, you should now be able to use EMKeychain’s EMGenericKeychainItem.

Step 3: Mopping up

It’s very likely that when running your release build it’ll crash and burn and complain about a missing /usr/lib/EMKeychain.dylib. In this case, you’ll have to adjust the built executable accordingly using install_name_tool.

You can do that by adding a new Run Script build phase to the target, which should contain this code.

install_name_tool -change /usr/lib/EMKeychain.dylib \
  "@executable_path/../Resources/EMKeychain.dylib" \
  "$TARGET_BUILD_DIR/$PROJECT_NAME.app/Contents/MacOS/$PROJECT_NAME"

It’s possible that on the next build the executable will mope about a missing /usr/local/lib/EMKeychain.dylib now. Duplicate the snippet and adjust the second one accordingly.

Step 4: Get yourself a beer

Because if all went according to plan, you’re done. :)

Xcode & MacRuby: Embed, Compile, Fix

This post references MacRuby 0.5b2, used with Xcode 3.2 on Snopard (10.6.2).

At some point you’ll probably want to create a release build for your app. You’d like to compile it and embed the MacRuby framework so the app is self-contained. Cool beans.

Unfortunately, it’s not as easy as it seems. Yes, the MacRuby Xcode template contains both an “Embed” and a “Compile” target, and they seem to work fine. ;) The problem I ran into, though, was that whenever you would require anything from the Ruby standard library (say, yaml or stringio), the app would forget about the embedded version of MR and look for /Library/Frameworks/MacRuby.framework/….

I didn’t notice this at first since this folder exists on my dev machine (big surprise), but when I tested it on a clean machine (i.e. one where MacRuby isn’t installed), nothing would happen. Well, nothing except some lines in the system.log, that is:

Being a newb to the ancient arts of compiling shit self-written software I was scratching my head rather furiously. It took me several hours of digging around the Googles and macruby-devel to learn about install_name_tool, and how it’s used to adjust the path of a shared library inside a file.

And that’s what I did, then. I’ve created a new build target, “Embed and Compile”, which has two sub-targets:

1. the reference to the default app build phase (which means “MyNewApp” is a direct dependency of the “Embed and Compile” target)
2. a “Run Script” build phase named “Embed, Compile, Fix”

The script runs macruby_deploy and afterwards tells install_name_tool to do its dirty, dirty work. I found it’s not enough to have it adjust the executable only; for me it was necessary to fix all the *.rbo files as well.

So, that’s it. The above works for me, it might work for you as well. If you have comments, suggestions or recommendations, please sound off below. I’m still learning all of this, and any input is appreciated. :)

Oh, and in case I sound ungrateful or anything: I am not. MacRuby 0.5b2 is exactly what is says it is: the second beta of a software’s pre-1.0 version. It’s already pretty damn impressive but not really done yet. I had a hunch what I was getting into, so it’s cool. ;)

Assorted MacRuby Snippets

Some things I’ve learned or discovered during the last few days. Nothing special, but taking notes is usually a good idea, so there.

Get values fromInfo.plist

For example, app name and version:

info = NSBundle.mainBundle.infoDictionary
info.objectForKey("CFBundleName")
info.objectForKey("CFBundleVersion")

Open an URL in the default browser:

url = NSURL.URLWithString("http://municode.de/")
NSWorkspace.sharedWorkspace.openURL(url)

Run an AppleScript

Sometimes you want to execute a short AppleScript snippet to save yourself some time by using the higher-level functionality AS offers instead of writing a huge block of MacRuby. (For example, to eject a FS volume.) Here’s how you do it (the AS is deliberately simple):

script = "display dialog (\"omg\")"
pnt = Pointer.new_with_type("@")
as = NSAppleScript.alloc.initWithSource(script)
as.executeAndReturnError(pnt)

More info at developer.apple.com.

Delete nodes/tags from an XML document

Let’s say you have a variable doc which represents a NSXMLDocument, and you want to remove all em and cite tags:

error = Pointer.new_with_type("@")
selectors = [ "//em", "//cite" ].join("|")
doc.nodesForXPath( selectors, error: error ).each do |n|
  n.detach
end

More notes might follow at a later date. :)

MacRuby compilation step fixes

Just a note, mostly to myself: The default XCode MacRuby rb_main.rb template will contain these lines:

Dir.entries(dir_path).each do |path|
  if path != File.basename(__FILE__) && path.match(/\.rb$/)
    require(path)
  end
end

Works fine for uncompiled files, but when you want to compile your app, there’ll be no *.rb files — just *.rbo files. So rb_main.rb needs to be adjusted.

Dir.entries(dir_path).each do |path|
  if path != File.basename(__FILE__) && path.match(/\.rbo?$/)
    require(path)
  end
end

I just spent 15 minutes wondering about these Unknown class 'Controller', using 'NSObject' instead. Encountered in Interface Builder file at path … in my system log, and I tend to forget this kind of detail so I wanted to jot it down as a reminder to future Carlo.

So, listen up, future Carlo. This is important.

Dev Env acting up when trying to do bulk operations

(What a title…) I was pulling my hair out over the last two days when I was implementing bulk operations in a project of mine.

In this case, the list of operations to do in bulk is compiled in the browser, and then the single requests are sent one by one to the server as single AJAX requests. (Think “mark this as read” functionality.)

My problem was that the first and second call in the bulk list usually went through well, but the rest of the calls just ran against a wall since all of a sudden Rails had problems finding the either logged in user or was missing certain methods and/or attributes. Highly annoying as well as completely erratic, as I was sure my code was okay in the first place.

When trying the same operations on a one-by-one basis, all was good. No issues whatsoever.

So while trying to figure out what the fuck was going on, I’ve played around with different ways to get the current user, checking for the availability of its methods and so on, all to no avail.

At one point I’ve disabled the protect_from_forgery call, and one or two different errors started to appear:

A copy of ApplicationController has been removed from the module tree but is still active

That was new. So I’ve started digging around for an answer, and found it in an old Ruby Forum thread.

Turns out that Rails’ development mode was the culprit, as the app’s code is reloaded on every request; so when a lot of concurrent calls are made, the code might reload slower than the calls are coming in and hijinks ensues.

The overly simple solution to this problem? In /config/environments/development.rb, I just set config.cache_classes to true, meaning the code isn’t reloaded all the time — and as it turns out, my code runs just fine after all! Happy happy joy joy.

The downside is that I’ll have to restart my dev server every time I make a code change, but in this particular case, that’s not a big deal.

The big blog move of 2009

Just a heads-up: I’ve moved my blog today — in two ways. First, I’ve ditched my self-hosted Wordpress setup in favor of Tumblr. Because I ♥ Tumblr.¹ Second, it’s now sitting on blog.zottmann.org instead of carlo.zottmann.org. Old article URLs 301-redirect to their new locations, so all should be well.

Also, I’ve cleaned up the blog history; about 2/3 of the old posts are gone. Most of them either simply lost their context, contained nothing but (now) broken links or are not worth keeping online. Doing my part to keep the intertrons lean!

The move was made possible by Wordpress’ export-to-XML feature, the Tumblr API and a few lines on Ruby code. (The latter is a big hack job, but it works for me. You’ve been warned.)

And to top it of, I’ve picked a new Tumblr theme named “PostCreate” and hacked it to my liking.

I’m pleased so far. :)

Excellent Localmemcache

Yesterday’s Munich on Rails meetup was the usual mix of interesting talks and geeky, delightful conversations. When I say “usual”, I of course mean it’s been the kind of evening I by now kind of expect. ;) Many thanks to Roland for organizing and the Experteers guys for the venue and the food. Nom!

Anyways: interesting talks.

Marco Otte-Witte presented his Excellent gem (gotta love the name) for static code analysis. It’s mostly aimed towards checking Rails code for smell, although —and he made that clear— it’s not targetted at people who strive for the blissful state of “zero warnings”. It’s more relaxed in that way; merely showing you unusual (or stupid or silly) parts of your code, such as missing validations in your models or having instance variables in your partials and the likes. Sadly, at the moment it’s not dealing with HAML templates yet, just ERB. (He’s looking for volunteers, by the way.;)) Here are the slides:

I can actually see myself using it.

And then Sven C. Koehler presented his somewhat irritatingly named¹ yet spiffy Localmemcache. It’s a local, shared-memory-based, persistent key/value store, which looks pretty fascinating. I was a wee bit confused by it until it finally clicked — you wouldn’t be able to tell from its name, but it’s not related to memcached. Aha! It’s a C library with Ruby bindings which offers a more or less simple storage system (values are of the type String, but of course that would include Marshal‘ed data) and apparently blazingly fast — his benchmarks showed that Localmemcache is almost as fast as accessing native Ruby hashes. Its not for everyone —for example, as I understand, it requires a 64-bit Unix system— but it looks like a pretty interesting alternative to memcached for single-machine setups like, say, your single production machine or your local dev box. This should ease the issue of sharing data between different Ruby processes, for example. I’m definitely going to check that out.

Oh, and Peter Schrammel presented a concept for a truly private asset server. As I’m not entirely sure whether this is really public information yet, I’ll keep my yapper shut here. :)

Afterwards we all headed to the Park Café for conversations and drinks. All in all a very nice evening, even though I was still a bit groggy from the day before — the München Twittwoch. (Which reminds me, I should probably whip up a quick post about that as well. Eh.)

Again: my thanks go to the MoR organizers and all the people who showed up, I had a good time. :)

Update: Artikel von Marco zu Excellent auf RailsMagazin.de

God Gotchas

This is a reblog of a post from my new Ruby-themed tumblelog. I know it’s kind of cheap to repost your own stuff, but who cares.

I’ve spent a couple of hours today pulling my hair out while trying to get one of my background job scripts to work with god, the “easy to configure, easy to extend monitoring framework written in Ruby”.

Well, it took a while to make it work, tho. Yes, god is cool and simple and gets the job done. But there are some things that cost me hours and which I found out only by reading the source code.

So, I just want to quickly jot down some gotchas before I forget them again, running the risk of falling into the same traps again in the future.

1. My script used the constant LOG to keep my Logger instance. Logging worked fine when I ran the script by itself, yet when god took over, it didn’t anymore. Actually, the script died rather quickly. As there was no logging at all going on, and all STDOUT output was suppressed, I came rather close to losing it. Turns out god itself is declaring a LOG constant of its own, which was done before my script had the chance, so when it attempted to initialize it, it would actually try to re-declare an existing constant, and we all know how well that works. ;)

2. Once that was done, my script was logging just fine, but it didn’t produce any output whatsoever. Raah! Teeth were gnashed… there was definitely teeth gnashing going on. Even telling “my” Logger (the one inside my script) to write to a file didn’t produce anything. That was a fun hour, really. The reason for this behaviour: god is closing all open file descriptors when it sets up monitoring a script. Which included my script. Awesome! On the upside, it meant I could get rid of the part of my code dealing with different logger behaviours. Meaning less LOC! It doesn’t get any more agile than that, folks.

3. In case you actually want to capture anything your original script is sending to STDOUT, there’s the not-really-documented God::Watch#log. Set it inside your God.watch block to specify a log file. (See example below.)

4. If you need to set ENV variables, God::Watch#env is your friend. Accepts a hash with arbitrary key/value pairs. For example, I declare a few God.watch blocks, one for each value of an array (think “worker 1 to 5”), and I use God::Watch#env to pass the current value to the worker script. Works well.

5. When you do a sudo god stop <watch>, make sure to give it a few moments before running sudo god start <watch> again, or you might end up with orphaned unmonitored scripts running rampant in the background.

6. Running sudo god log without any further arguments will tell you that “You must specify a Task or Group name”. That’s actually a lie, as it only accepts task names. (A group is a number of related tasks. A task is a single monitoring watch.)

So, yeah.

Don’t get me wrong, please: It might not look like it, but once I had figured it all out, I’ve decided I actually like god. I like the feature set, it’s really easy to set up, and it works. I’m happy it exists.