MacPorts headaches...

Recently I started doing some of my development work on a little MacBook. Pretty nice as I drop down into terminal, have all the power of *nix (FreeBSD-based in this case), and still have Mac niceties available to me, such as MacVim for editing.

Everything is rocking along just fine: I've got Cucumber and RSpec running and working my way thru "The RSpec Book" (pretty useful so far). However, I needed to install FXruby so that I could do some graphical work and figured this would be no problem. Turned out to be a little tricky and I had to remember an issue I ran into a while back on a Linux system.

First off, this won't work:

     gem install fxruby

It'll install that gem alright, but that's not enough to get things running: you have to get Fox installed as well and that doesn't come along with the gem.

Of course, to do that, you have to install MacPorts which is actually relatively painless (see the MacPorts Guide for how to do this).

Once you've done this, then you can install the complete FXRuby collection of stuff (see the FXRuby Book at PragProg.com)...

     sudo port install rb-fxruby

and it's a very large collection indeed: it took over 1 hour on my machine.

The only hitch I ran into was having too old a version of the Mac XTools package, so that was another 800Megs of download and an install. If you do this make sure you get the right version: XTools 3.1 is for OS X 10.5 and XTools 3.2 is for 10.6. Check this first or you'll spend most of an hour installing fxruby only to have it complain about the wrong XTools version and you'll have to start over.

MacPorts updates your ~/.profile or ~/.bash_profile file (note that the MacPorts install docs only mention ~/.profile and I had to dig a bit to find that they had properly modified my ~/.bash_profile file) so that your system can find the added programs...

But that's not quite everything you have to do and here was the gotcha for me. Even after I went through all this, I kept getting strange messages out of my test runs, things like:

  "unable to load file ubygems"

(the missing 'r' is not a typo: that was the exact error message) when executing the "require 'rubygems'" statement.

I tried adding the command:

      export RUBYOPT=rubygems

to my profile so that I wouldn't have to add a require 'rubygems' statement but that didn't solve the problem.

BTW, when I went to the RubyGems Guide, they said to use the -rubygems option on the ruby command line, but that also generated the same error.

After a little more digging, I found the problem: MacPorts installs everything in /opt/local, which is not where the normal gem command installs things (if you do a simple "gem install ' they wind up in /usr/bin).  Thus, after MacPorts was installed, ruby got a tad confused and couldn't find everything it needed.  Then I remembered what I had run into when I was working on my Linux box: trying to install a LAMP stack: everything got put into /opt/local, but then it was out of the normal stream of things and there were ongoing problems. I finally bit the bullet in that case, removed the LAMP stack, and manually installed everything into their default locations. Life has been pretty good in Linux-land ever since.

The solution? Install rubygems using MacPorts so that my FXRuby could find what it needed. That was a simple:

     sudo port install rb-rubygems

and now my ruby apps would run again, load the gems, and I had a simple FXRuby app running.

Quite frankly, I'm not sure of all the nitty-gritty details of this problem and I'm not even sure that I won't have further problems downstream when I want to use another gem, but I'll face that problem when I come to it. If anyone has a definitive answer as to WHY this happened and a better approach to Mac OS X gem  installation, I'm all ears.

A Users Guide is a great developer tool...

Today I was reminded just how important documentation is, particularly End-User documentation... you know, the instructions for how folks are actually going to use your system.

In my spare time, I've been developing a very small system for a client (unfortunately not in Ruby/Rails, but that's another story). It's designed to replace one labor-intensive portion of their Commission calculation process, which is spreadsheet-intensive. You've seen them before: someone develops a simple spreadsheet to "save time" and eventually, the spreadsheet is a monster and the whole process takes days to complete and is fraught with potential errors. And with the sales reps watching the numbers like a hawk, nothing slips by.

The piece I'm replacing is for maintaining the Work In Process costs and pricing factors for the products developed  in-house. It's a tiny database application which outputs an Excel workbook that is dropped into the monster spreadsheet and thereby replaces a very time-consuming manual update process. In fact, the process has been so challenging in the past that cost updates have been few and far between. The new system will allow them to make pricing changes at will.

Over the past few weeks, time permitting, I've developed small pieces of the system and run it by the client to make sure that my understanding is correct, and they've approved the prototype pieces that I've provided to them. This is actually part of my proposal process: try out important pieces of the system, and then let the client approve the results.

Today, I started writing the contract for the actual development. As part of the scope of work, I provided screen shots and a high-level overview of the procedural steps for using the system. As I worked through the steps in the workflow, I suddently realized that I was omitting one piece! I had prototyped that portion of the system early on and it worked OK, but the table I had created was only a dummy table, hand-crafted for testing, and I had not provided the necessary support for a user to maintain that table!

Fortunately I found this out before completing development and installing it for my client. At this stage in the game, it was pretty easy to add the required functionality and include it in the Users Guide.

You can call it what you want: Requirements or Design or Testing. Developing a Users Guide can help in all areas of your application life cycle methodology. In this case, I  like to think of the Users Guide as being a form of UI Testing: I used it to test my prototype design (screenshots, data entry forms, reports, and output files) against the user interaction that would be required to actually do something productive with the system.

Does this apply to Rails? You bet! Just watch Jospeh Wilk's Cucumber presentation at Scotland on Rails 2009. He suggests that you "...think about the user interface first " and asks "...how is the business user going to achieve value through the interface?" He also stresses figuring out what's really important to you and to your user (see his example of "Popping the Why Stack"). I particularly like his question: "Have we achieved what the user wants yet?" It's all about a single-minded focus on the user of the system and the value that the system is to provide.

Fortunately my Users Guide test failed and I was able to address the issue today, not later down the road when it would be more time-consuming. And I saved a potentially awkward situation with my client.

So... I'm going to be more careful about writing Users Guides and testing the user workflow in the future...

When do you write your Users Guide?