You’re looking at a draft of a chapter from a work in progress, tentatively titled Scripting Mac Applications With Ruby: An AppleScript Alternative, by Matt Neuburg.
Covers rb-appscript 0.6.1. Last revised Jun 23, 2012. All content ©2012 by the author, all rights reserved.
Chapter 1: Installation and Usage
This chapter describes how to install rb-appscript. Installing rb-appscript is not difficult; in the best-case scenario, it’s a matter of issuing a single-line command in the Terminal. The best-case scenario, however, depends upon your having installed Xcode (Apple’s Mac OS X developer tools) and upon your version of Ruby being sufficiently recent.
If you haven’t already installed Xcode, Apple’s developer tools, you should start by installing it. The developer tools contain command-line versions of such things as the gcc compiler, which you’ll need in order to compile the C code in rb-appscript.
To obtain the latest version of Xcode, you must register at http://developer.apple.com/products/membership.html; it looks forbiddingly expensive, but actually it’s free: just sign up for an “ADC Online Membership”. You will then be able to log in at http://developer.apple.com/mac/ and locate and download Xcode.
Be sure to get the latest version compatible with your system. (As of this writing, the latest Leopard version of Xcode is 3.1.2; the latest Tiger version is 2.5). This is a big download! You’ll need a reasonably fast Internet connection (faster than dial-up through a modem).
When the download is completed, open the .dmg and run the installer that you’ll find there. On Leopard, be sure to check the “UNIX Development Support” option in the installation options to get the command-line compiler tools.
Mac OS X comes with Ruby installed. You can see that this is the case by testing Ruby’s version at the command line (in the Terminal):
$ ruby --version
On the machine I’m currently using, the reply is:
ruby 1.8.6 (2008-08-11 patchlevel 287) [universal-darwin9.0]
That is a sufficiently recent version of Ruby. If you have already upgraded Ruby to 1.8.7, that’s fine. On the other hand, rb-appscript’s compatibility with the recently released Ruby 1.9.x is uncertain, and I do not recommend that upgrade.
On Tiger (Mac OS X 10.4.x), the default Ruby is 1.8.2. This is not really sufficient, and I recommend that you upgrade it to at least the latest version of 1.8.6 if you have not already done so. (If you’ve already upgraded to Ruby 1.8.7 that’s fine too.) The standard explanation for how to do this is Dan Benjamin’s blog entry at http://hivelogic.com/articles/view/ruby-rails-mongrel-mysql-osx, so you might start by reading it. You can ignore everything having to do with mysql and rails; we’re just going to upgrade Ruby.
As Dan Benjamin’s article rightly says, the first step is to make sure that your PATH environment variable includes /usr/local/bin and /usr/local/sbin. Not only should your PATH include these directories; it should start with these directories. That’s because this is where you’re going to install your Ruby upgrade, and you want the upgrade version to overshadow the default version. Your installation won’t overwrite anything; you’ll still have both Ruby 1.8.2 and Ruby 1.8.6, but when you say ruby at the command line, 1.8.6 will be used. So start by checking your PATH in the Terminal:
$ echo $PATH
/usr/bin:/bin:/usr/sbin:/sbin:/usr/X11/bin
If, as in this example, the PATH doesn’t start with /usr/local/bin:/usr/local/sbin:, we need to change it so that it does. Unlike Dan Benjamin, I like to edit .bash_profile (not .bash_login) to set my PATH. Open or create this invisible file in your home directory using a convenient text editor such as TextMate or TextWrangler (BBEdit), make sure it is set to Unix line endings if you’re creating it, and insert this line at the end:
export PATH="/usr/local/bin:/usr/local/sbin:$PATH"
Save the file and open a new Terminal window (to get a fresh shell) and check your PATH again:
$ echo $PATH
/usr/local/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/X11/bin
Next, we must install the Readline tool. It is currently available at this Web site: http://tiswww.case.edu/php/chet/readline/rltop.html. There’s a link there for downloading the latest version (6.0), so click it and download it. Use the link that speaks of getting the file from the “master GNU ftp site” (ftp://ftp.gnu.org/gnu/readline/readline-6.0.tar.gz as of this writing). Find the downloaded file (readline-6.0.tar.gz) and double-click it to unpack it. In the Terminal, cd into the resulting directory (readline-6.0) and issue these commands (you will have to wait a long time after each command for the output to stop and return you to the shell):
$ ./configure --prefix=/usr/local
$ make
$ sudo make install
At last we are ready to obtain the Ruby source code. To do so, you’ll use ftp. Since I don’t know whether you have a GUI ftp client, I’ll describe how to do this at the command line in Terminal. Start like this:
$ ftp ftp://ftp.ruby-lang.org/pub/ruby/1.8/
Connected to carbon.ruby-lang.org.
220 (vsFTPd 2.0.5)
331 Please specify the password.
230 Login successful.
Remote system type is UNIX.
Using binary mode to transfer files.
200 Switching to Binary mode.
250 Directory successfully changed.
250 Directory successfully changed.
250 Directory successfully changed.
ftp>
We are now in an interactive session with the ftp tool. Our first task is to get a listing of the current directory. I display here only a part of the output:
ftp> dir
229 Entering Extended Passive Mode (|||28589|)
150 Here comes the directory listing.
...
-rw-r--r-- 1 1014 100 3957979 Aug 08 2008 ruby-1.8.6-p286.tar.bz2
-rw-r--r-- 1 1014 100 4590373 Aug 08 2008 ruby-1.8.6-p286.tar.gz
-rw-r--r-- 1 1014 100 5606110 Aug 08 2008 ruby-1.8.6-p286.zip
-rw-r--r-- 1 1014 100 3956902 Aug 11 2008 ruby-1.8.6-p287.tar.bz2
-rw-r--r-- 1 1014 100 4590393 Aug 11 2008 ruby-1.8.6-p287.tar.gz
-rw-r--r-- 1 1014 100 5606238 Aug 11 2008 ruby-1.8.6-p287.zip
-rw-r--r-- 1 1014 100 3905975 Jun 09 2007 ruby-1.8.6-p36.tar.bz2
-rw-r--r-- 1 1014 100 4535005 Jun 09 2007 ruby-1.8.6-p36.tar.gz
-rw-r--r-- 1 1014 100 5544539 Jun 09 2007 ruby-1.8.6-p36.zip
-rw-r--r-- 1 1014 100 3967709 Mar 31 09:22 ruby-1.8.6-p368.tar.bz2
-rw-r--r-- 1 1014 100 4602095 Mar 31 09:22 ruby-1.8.6-p368.tar.gz
-rw-r--r-- 1 1014 100 5619494 Mar 31 09:22 ruby-1.8.6-p368.zip
-rw-r--r-- 1 1021 100 3946186 Mar 12 2007 ruby-1.8.6.tar.bz2
-rw-r--r-- 1 1021 100 4589394 Mar 12 2007 ruby-1.8.6.tar.gz
-rw-r--r-- 1 1021 100 5545642 Mar 12 2007 ruby-1.8.6.zip
-rw-r--r-- 1 1014 100 4137518 Apr 09 04:44 ruby-1.8.7-p160.tar.bz2
-rw-r--r-- 1 1014 100 4818817 Apr 09 04:44 ruby-1.8.7-p160.tar.gz
-rw-r--r-- 1 1014 100 5876269 Apr 09 04:44 ruby-1.8.7-p160.zip
-rw-r--r-- 1 1021 100 23658 Jun 09 2008 ruby-1.8.7-p17.diff.gz
-rw-r--r-- 1 1021 100 4114057 Jun 09 2008 ruby-1.8.7-p17.tar.bz2
-rw-r--r-- 1 1021 100 4803589 Jun 09 2008 ruby-1.8.7-p17.tar.gz
-rw-r--r-- 1 1021 100 5879852 Jun 09 2008 ruby-1.8.7-p17.zip
...
226 Directory send OK.
ftp>
The version numbers and the dates show us that the latest version of Ruby 1.8.6 is p368. (No year is listed, so the year is this year, 2009.) It’s possible that this will have changed when you read this, so focus on whatever version is most recent. We’re going to download the .tar.gz file for that version. So in this case, that is ruby-1.8.6-p368.tar.gz. To download it, say this:
ftp> get ruby-1.8.6-p368.tar.gz
local: ruby-1.8.6-p368.tar.gz remote: ruby-1.8.6-p368.tar.gz
229 Entering Extended Passive Mode (|||55004|)
150 Opening BINARY mode data connection for ruby-1.8.6-p368.tar.gz (4602095 bytes).
226 File send OK.
4602095 bytes received in 00:28 (156.31 KB/s)
We have now downloaded the Ruby source code and we’re done with ftp, so exit nicely:
ftp> exit
221 Goodbye.
Find the downloaded file (ruby-1.8.6-p368.tar.gz) and double-click it to unpack it. In the Terminal, cd into the resulting directory (ruby-1.8.6-p368) and issue these commands (you will have to wait a really long time after each command for the output to stop and return you to the shell):
./configure --prefix=/usr/local --enable-pthread --with-readline-dir=/usr/local --enable-shared
make
sudo make install
sudo make install-doc
Ruby 1.8.6 is now installed and is your default Ruby, which you can confirm by saying ruby --version in a new Terminal window. You should finish by updating your gem tool; to do so, it might be sufficient to follow the instructions below, under “Leopard”. If that doesn’t work, install gem from scratch, as follows. First, download the latest version from http://rubyforge.org/projects/rubygems/. Find the downloaded file and double-click it to unpack. In the Terminal, cd into the resulting directory and then say:
sudo ruby setup.rb
On Leopard (Mac OS X 10.5.x), Ruby comes installed as a package of files in a framework (in /System/Library/Frameworks/Ruby.framework); the default ruby command, in /usr/bin, is a symlink pointing into that framework. A sufficiently recent version of Ruby is already installed. But a sufficiently recent version of the gem command-line tool, by default, is not. If you intend to install rb-appscript as a gem, you should update gem. (Actually, you should probably do this in any case.) To do so, say at the command line:
$ sudo gem update --system
As a matter of general principle (though this is not required) you might then want to update your existing gems. To do so, say:
$ sudo gem update
The Ruby.framework package on Leopard is inviolable, so new and updated gems are installed into /Library/Ruby.
You have presumably installed Xcode and a sufficiently recent version of Ruby, and your gem tool is up to date, so you can now install rb-appscript as a gem by saying:
$ sudo gem install rb-appscript
The gem tool will go out on the Internet, grab the latest release of rb-appscript, configure it, compile it, and install it. That’s it! You have installed rb-appscript and you’re ready to use it.
An alternative is to install rb-appscript as a library. To do so, download the latest release of the rb-appscript package from the rb-appscript page at RubyForge, http://rubyforge.org/projects/rb-appscript/. Double-click the .zip file to unzip it; this gives you the rb-appscript folder. In the Terminal, cd into that folder. For example, you might say something similar to this:
$ cd /Users/yourname/Downloads/rb-appscript-0.5.2
Now issue the three commands described in the README document:
$ ruby extconf.rb
$ make
$ sudo make install
To test that rb-appscript is installed, say this at the command line:
$ ruby -e 'require "rubygems"; require "appscript"; p Appscript'
If that doesn’t cause an “uninitialized constant” error, rb-appscript is present and you’re good to go.
Since rb-appscript is a Ruby library, you can use rb-appscript anywhere you would use Ruby. Here are some examples:
TextMate. TextMate is a powerful and flexible environment for editing and executing Ruby scripts, and is far and away my favorite place for developing and testing with Ruby and rb-appscript. You can learn more about TextMate at its Web site, http://macromates.com/.
Command line. You can call ruby (or better, env ruby) at the command line, handing it the pathname of a Ruby text file. For occasional simple queries and testing you can also use irb, the interactive Ruby interpreter.
The Script menu and FastScripts. If you store a shell script in your Library/Scripts folder, its name will appear in the built-in Mac OS X Script menu, and you can run the script by choosing it from the menu. (A shell script must declare its language through a “shebang” line; for example, the first line of a Ruby script might read #!/usr/bin/env ruby.) The Script menu is also application-sensitive, so you can arrange for certain scripts to appear only if a certain application is frontmost. If you don’t see the Script menu, you can enable it through the AppleScript Utility application. An alternative, with better management features, is FastScripts (http://www.red-sweater.com/fastscripts/); it costs $15, but the downloadable demo is a perfectly adequate version that you can use for free.
GUI Wrappers. There are various ways to wrap your Ruby script in a simple user interface. For example, Platypus (http://www.sveinbjorn.org/platypus) is an elegant free application that embeds your shell script into a small Cocoa application, without your having to learn any Cocoa or Objective-C. This is nice because it’s easy to distribute your script to others who are not savvy about the command line. You can include extra resources in the application’s bundle (for example, you could include rb-appscript itself, so that the end user doesn’t have to install it), and output display is available as text or HTML. Similarly, you might take a look at Pashua (http://www.bluem.net/en/mac/pashua/), which is also free. And let’s not neglect Automator, which is already on your computer; you can wrap a Ruby script into an Automator action and incorporate that action as a workflow (which itself can be saved as a standalone application), and building your own Automator action, with a custom interface, is not all that difficult. Of course, at that point you might even consider just writing a Cocoa application; some day, MacRuby will allow the Cocoa programmer to work entirely in Ruby (and the intention is that rb-appscript should work in this environment), but that’s in the future and beyond the scope of this book.
You’re looking at a draft of a chapter from a work in progress, tentatively titled Scripting Mac Applications With Ruby: An AppleScript Alternative, by Matt Neuburg.
Covers rb-appscript 0.6.1. Last revised Jun 23, 2012. All content ©2012 by the author, all rights reserved.
This book took time and effort to write, and no traditional publisher would accept it. If it has been useful to you, please consider a small donation to my PayPal account (matt at tidbits dot com). Thanks!