Lesson 6
Tools for Rails Developers

comments

In the episodes up until now, we’ve discussed the case for Ruby on Rails, and walked through the major conceptual parts of a Rails application. We are going to switch gears in this episode and focus on the rich ecosystem of tools and technologies that make developing web applications with Ruby on Rails productive and fun.

Continuing with the conceptual approach we’ve been using in this series of LearningRails podcasts, we’ll explain a bit about what each of the tool categories are, what they help you do, and familiarize you with some of the popular choices out there. In many cases, these are the same tools we actually use while working on our own projects. We won’t be going in to “how to use” aspects of most of these tools, leaving that for future podcasts or articles at BuildingWebApps.com. We’ve included some links to additional resources in the show notes at LearningRails.com.

One thing is certain, the Ruby on Rails world is constantly changing and growing, tools frequently get updates, and new products and even categories of tools are introduced often. We’ll try to point out areas of particular activity, and you can visit the rest of this site for more write-ups and links as we are able to review products of interest.

IDEs and Editors

We start off with perhaps the tool you will find yourself in most often while developing Ruby on Rails code: the sturdy text editor. There are two schools of thought in the Rails community, and this is common among programmers in other technologies too. Some like to use a programming editor that is small, fast, and mostly focused on the act of writing code. The truth is, even with so-called simple editors, many have features that allow the editor to integrate with scripts, tools in the operating system, and other conveniences, such that you don’t have to leave the editor environment as much.

Examples of popular full featured editors are TextMate and BBEdit on the Macintosh, SciTE and UltraEdit on Windows, and vim, Emacs, and JEdit on pretty much all operating systems. Is one better than another? That is hard to say, as we find the choice of a text editor becomes one of those fairly personal choices programmers make.

The other school of thought when it comes to working with code is to focus on collections of tools that are all assembled together into a unified interface, and this is where Integrated Development Environments (aka IDEs) come in. Particularly since 2007, there has been significant activity by both open source and commercial groups to provide sophisticated IDEs for Rails.

A typical IDE will combine not only a programmer’s editor, but also simplified navigation of your Ruby on Rails files and project, graphical debugging tools, integrated source code control, nice interfaces for database tools and Ruby on Rails automation scripts, and many other features. At their best, the IDEs present a unified look and feel across tools, so it is easier to use and learn them together.

Sun Microsystem’s open-source, cross-platform NetBeans has crossed over from being mostly a Java related tool to a full fledged Ruby and Rails IDE. Other companies have introduced free and commercial solutions that are also cross platform, such as Aptana’s Aptana Studio, Borland’s CodeGear, and ActiveState’s Komodo.

Do you go with an IDE or a text editor? We suggest you give both a try to find what works best for your development style. If you are a new practitioner, the IDEs give you a bit more help getting a handle on the tools within their single environments, but you will also find a lot of helpful material on the web that explains how to work from the command line as well.

Chris: I’m a command-line guy, and I love the speed of a dedicated programmer’s editor and a nearby terminal window. I spend much of my coding time in TextMate and appreciate its extensible environment for interacting with the operating system and key tools such as source code control. It has just the right level of automation me, and everything can be accessed without going to the mouse. Michael is, however, getting me to spend more time in the various IDEs out there, and I appreciate the progress being made towards an integrated Ruby tool set.

Michael: I’m more comfortable with an IDE. Sometimes its slowness bugs me, but I’m willing to trade that for being able to pick commands from menus instead of having to remember them. I use NetBeans, and I really like the ability to command-click on a method invocation, for example, or a call to a partial template, and be taken automatically to its definition.

For our seminar, we used NetBeans as the teaching environment both because it is a little easier to learn, and because it is cross-platform. For some reason, all the best-liked programmer’s editors outside of IDEs are on one platform or the other.

Gems

When you install your Ruby on Rails development (or production) environment, you typically start out with Ruby itself. The Ruby language has many collections of code that have been contributed to the community by individuals and teams alike. Related code collections are typically assembled together into self-contained packages, called “RubyGems” or “gems” for short. Gems are not in any way specific to Rails; they’re used for all sorts of Ruby programs.

Gems can be downloaded to your system and have code built in to automatically install themselves and any dependencies they require. Typical gems have some level of documentation that also gets installed. The “gem” tool itself is one of the first things you usually install after Ruby. On many installations, it comes prebundled for you.

Many of the tools we’ll discuss in this episode are available and installed via the Rubygems package mechanism. Rubygems was originally the brainchild of Chad Fowler, Jim Weirch, Rich Kilmer, David Black, and Paul Brannan, and came into being during a couple of late night hacking sessions at RubyConf in 2003. The gem package mechanism has matured to encompass the complete set of tools needed to assemble and author, install, update, and remove code distributed via gems. If you were to peek inside of a gem archive that you download, you would find not only the code you want to use, and its associated documentation, but also supplementary files that act as installation scripts, license files, version information, and other data the gem author may wish to include.

Ruby on Rails is distributed as a gem, or more correctly, as a collection of related gems. Other common examples of gems used with Rails applications include Mongrel, an application server; net-ssh, a secure shell communication library; RedCloth, which translates Textile to HTML; tzinfo, which deals with time zone adjustments; and ZenTest, which provides a suite of testing tools. Type gem list at the command line to see what gems are installed on any system. Installation is as easy as typing gem install and the gem name.

One cool aspect about using gems is that the tool can manage the update process for you. When you need to get fixes for some code that is distributed via a gem package, you can issue a simple command to check for and install an update, such as gem update rails.

Gems are, by default, installed in a location near your Ruby interpreter, and like the Ruby interpreter, they’re part of the environment that is available to all applications, including all Rails applications. It can be a source of some grief when you deploy to a new server and need to make sure it has all the right gems, or when you or another developer brings up a new development machine. One solution to this is to “freeze” the gems into your Rails application, keeping a copy of the gem associated with the application. This means that you may end up with multiple copies of a single gem, if you have multiple applications on one system, and it makes updating the gems a little more work, but it ensures the portability of your application. See the show notes for some pointers to articles that explain how to do this.

Automation

We mentioned our old friend the command line when speaking about editors. Many Rails experts like using command line tools to quickly get things done. You will notice over time that you typically use a common set of commands over and over again, usually in sequence, and that it is easy to make mistakes. Echos of the Don’t Repeat Yourself mantra are also applicable when it comes to tools and working through various administrative tasks. Automating your work by writing sequences of commands into scripts is the command line equivalent to being DRY in your code. Ruby and Rails provide a number of helpful ways to get more automated.

One such utility that is an important part of a Ruby and Rails installation is the tool developed by Jim Weirich called Rake. Rake is a tool for running other tools. You can write scripts that act as recipes for getting various tasks done. Rails pre-installs a set of useful rake scripts for you when you create your project. Rake is accessible from the command line and often via a graphical user interface in the various IDEs.

You use rake to run Ruby programs that execute your Rails database migrations, to run tests, to conduct various deployment activities, and many other housekeeping actions. You can devise your own rake recipes to automate common tasks, such as converting artwork files into another file format or importing log information and creating reports, by writing small rake compatible Ruby programs.

Besides rake scripts, Rails also deposits a set of plain Ruby scripts in your project’s script directory. These Ruby programs include the “server” script that you will use to run your application locally, the “console” and “breakpointer” scripts that you may use to conduct debugging sessions, the “generate” script that can be used to build new pieces of code through the use of code generation recipes, and many others. Like rake, these scripts can be run at a command line as well as graphically in most IDEs.

Plugins

Like the general purpose collections of code and tools you can use via Ruby’s gem libraries, Ruby on Rails has a specialized way of distributing add-on code and tools that are specific to extending the Rails framework. These extensions are called “plugins” and they add features to Rails that can make your application development much easier (and faster).

By having this plugin mechanism, the core team developing Rails can focus on the essential features that are at the center of Rails, and leave interesting, but perhaps less frequently used features to other people to develop on their own time frame. In the end, this helps core Rails stay (relatively) slim and focused, yet provides a wealth of additional code that you can pick and choose as you see fit. In the most recent release of Rails, some features that are quite widely used were pushed out into plugins, in part to slim down Rails and in part so it would be easier for those features to evolve independently.

Whereas gems get installed as a system-wide collection of programming modules that you can use across projects, plugins typically are installed on a project by project basis. You don’t have to worry about adding some feature to one project and having it accidentally appearing in another.

The “plugin” Rails script that is installed into the scripts directory of your project provides a tool to get plugins loaded up. You install a plugin by typing “ruby script/plugin install” followed by the url of the target plugin. The plugin script proceeds to download the desired source code and installs it into your project’s vendor/plugins directory. Your application automatically knows about plugins directory, and it will discover all installed plugins within it, adding their lib directories to the application path for you. After installation, a plugin is immediately ready for use.

There are many options for maintaining plugins once they are installed. You can, of course, just add a copy of the code into your own directory and manually update it when needed. Alternatively, you can link any plugin’s directory to its original source via external source code control systems, either directory using such tools as Subversion’s externals or with an intermediary tools, such as Piston.

Source Code Control

Was there a time you needed an important file on your computer and it was that exact moment when the hard-drive decided to die? Have you ever made some changes to a file and a couple of hours later realized you made a mistake, and didn’t have enough levels of undo? Maybe you work with another collaborator and need to make changes to the same file and you need help getting your work merged together.

Source code control systems help with these and other challenges. If you’ve used a change tracking system in a word processing program before, you’ve encountered some of the same concepts that are used in source code control. These systems work by tracking changes between versions of files and directories in an efficient manner, and by associating additional information with those changes, like the author, the date of the change, and perhaps a comment by the author about why a change was made.

Source code control systems are typically set up so a copy of your files is stored on some other computer besides the one you are working on. This can act as a safety net in case something happens to your machine. In some systems, such as the popular Subversion or its still active predecessor CVS, the master copy of your files is stored on a central server. Regardless of how your files are stored, the collection is typically referred to as a source code repository. With other systems, such as the up and coming git and mercurial systems, there isn’t a master copy, but the code is scattered across multiple computers in a distributed way.

All of these systems provide helpful tools to not only save and restore your files and their various versions, but they also provide means for merging your changes in with a different version of the file. This is extremely helpful when more than one person works on a project. Even better, while the tools all work from the command line, most IDEs have built in some support for easy to use GUIs to maintain your files.

In the Rails world, source code control usage is a standard practice and Subversion is by far the most predominant tool in current use. Many other tools work by interacting with the source code control server, particularly those tools that help you deploy your application to your production environments. Additionally, when you go to grab open source code, or contribute some code back to the community, you’ll find that sites like RubyForge and other repositories utilize source code control to access their files.

There are many options for getting started with source code control on your own project. You can choose to run your own source code control server, leverage one of the many ISPs who offer source code control access, or subscribe to one of the various services such as Unfuddle. If you use a distributed system like git, you don’t even need that, just someone to share your code with.

Once you have a source code control system running, there are some common tasks you will do in your day to day development. Let’s consider some common examples from Subversion. When you want to start working on a clean copy of your code, you use “checkout” to download it from the server. After you have made modifications that you want to save, you send them back with a “commit” command. If you are working on your files and want to grab changes made by others, you can use the “update” command. Updating not only pulls the latest version of files, but also starts a cycle of merging changes together. It automatically handles non-conflicting changes, and guides you to where conflicts exist so you can “resolve” them manually. There are many other commands to interact with the source code control system, and it is worth the time to familiarize yourself with them.

Deployment

As Michael mentioned previously, one standard practice that can make good use of a tool like Subversion is to deploy your application to a server by getting the code directly from source code control. This technique generally assumes that you write your code, test it carefully on your local computer, and only then store the working files in source code control. After that, you issue commands to have your production servers pull the working code out of source code control and onto their local disks. An agile practice that has been adopted by a majority in the Rails community is to automate as much as possible, and deployment is ripe for automation.

The Rails ecosystem includes a great solution for automating application deployment and many other activities: a utility by Jamis Buck called Capistrano. Capistrano is an open source Ruby program, distributed as a gem, that acts as the Ring Master coordinating all of the interactions between your local development computer and one or more remote computers, usually your production servers. In the simplest environments, using Capistrano is as easy as tweaking a few lines in a configuration file to describe where your servers are, and voila, you can start interacting with them.

Once you have Capistrano configured, deploying a new version of your application can be as simple as typing “cap deploy”. This command triggers execution of a script that can stop the server, check the new code out of version control on to the server, set up any required symbolic links, and restart the server.

Akin to its near cousin, the Rake utility, a rich set of recipe scripts is provided with Capistrano that orchestrate deployment tasks, housekeeping tasks, and pretty much anything you want to automate between servers. The cool thing about Capistrano is that it is network enabled. That means you can run your scripts on one or more servers at the same time, without having to type a lot of commands. Also like rake, it is easy for you to add your own tasks to the recipes, so if, for instance, you need to customize movement of files around in a particular way after deploying your application, you can automate that.

Getting set up to do your deployment with Capistrano is more complicated that doing a single manual deployment. But since you’re going to need to deploy over and over again, it is well worth the effort to get the automation in place.

If you have more involved deployment needs, perhaps with multiple servers in production, test, and staging, as well as more complicated interactions and steps in testing and deploying your code, no problem. You can implement Capistrano tasks that handle pretty much any scenario.

Documentation

Up until now, we’ve focused on many of the tools that you use to create your project, automate its deployment and maintenance, store it safely, and even get it into production, so let’s switch gears for a second and talk about making your code easier for others to reuse. Yes, I’m going to talk about the dread “D” word, documentation.

There are many camps when it comes to documentation, and the Rails world is no different with respect to a diversity of opinion. Fortunately, one touted selling point of Ruby can often be true, the code itself can read relatively well, and Rails code in particular usually makes sense at first glance (once you have some experience reading it).

Even if you are comfortable with Ruby’s powerful feature set, at times, features in Ruby and Rails can seem magical. You can take some comfort in the fact that many gems including Rails, as well as plugins built for Rails tend to be pretty well documented. In fact, documenting shared code seems to be a Rails community standard practice, and a good one to emulate, both for your own use, and when you share with others.

The drag about documentation is that it can often become stale or misleading, and many programmers, loath to write doc the first time, have even more problems keeping it fresh and current.

Fortunately, there are tools to help make it easy. Rdoc is a nifty documentation harvesting tool created by Dave Thomas. Even with no programmer written documentation at all, rdoc can walk through a project and extract useful information from your code. It can figure out modules and classes, methods and variables, and even the relationships between some of these.

Even better, if you put in a minimum of comments in your code, as long as they are located next to the item you want to document, they are pulled out and associated with the correct feature of your code. If you want to get fancier, you can supply some simple mark-up in the comments and rdoc will use that to create nicely formatted and linked documentation. Rdoc outputs what it finds a couple of different ways, so, for instance, you can output HTML that is ready to be viewed in your waiting browser or shared with others. The standard API documentation for Ruby and for Rails is generated this way — all the documentation is embedded in and extracted from the source code.

Most of the time you may choose to look at your documentation in a browser, but for those times you need to quickly look something up at a command line, rdoc also can format its output for another Ruby utility called “Ruby Interactive” or “ri” for short. Ri is a command-line documentation reading tool that has one job, display documentation text with no frills. If you watch carefully when you install gems, for instance, you may notice some information scroll by that documentation is being installed, this is usually rdoc at work, saving out files for use by ri.

Logging

Another form of documentation, one that is usually most useful during debugging of problems and monitoring of runtime behavior, is the trusty log message. Ruby on Rails makes it really easy to write out information while your application is running. Rails sets up an object for your application called a logger. The default logger objects writes messages to a log file named after the currently running environment, such as development.log or production.log. Log files typically get written to the log directory created for you when you generate your application.

You can associate different priorities with your messages, so if you only want certain messages to be displayed when you are debugging the application, you can specify that. Other messages that are informational or identify critical issues in the application can also be tagged as such. You can adjust the level of logging that gets done in your application’s environment configuration. By default, the development environment will display all debug and higher priority messages, and the production environment leaves out the debug messages.

If you need more control or focus on some messages, you can create your own logger objects and use them to write messages to different files. You might want to do this to separate out specific kinds of messages. Custom loggers can also send messages to other software, so you could write a logger that sends instant messages, for instance.

Other parts of the Rails ecosystem also generate their own log messages, and these are typically captured in their own files. Web servers such as Apache, application servers like Mongrel, and content indexing services like Ferret all generate their own log files that are useful sources of information.

When you run your Rails application interactively at the command line, or via an IDE, your logging messages sent to the default logger object will scroll by, along with many built in messages that Rails provides and occasionally intermixed with other software, such as Mongrel’s start-up messages. You can always find the logger based messages echoed into the various log files we’ve mentioned previously.

While simple in concept, logging is a critical tool to finding problems and monitoring the health of your program. The standard unix utility tail, which displays the last part of a file and can be set to update continuously, is the standard way of monitoring log files from the command line. Many IDEs, as well as GUI programs like the Mac’s Console application or the Windows application Kiwi Log Viewer (available both as freeware and commercially), are other simple ways to monitor this information.

Debugging

Sometimes, though, just looking through your log messages isn’t enough to find a tricky problem. While you can instrument your application with many logger calls to try to pin point the root cause of a bug, sometimes it is even better to be able to watch the code run, line by line if need be. It is for this kind of analysis that the Ruby debugger comes in handy. While explanations of how to use a debugger are beyond the scope of this podcast, you should be aware that debuggers exist for Ruby, and can be used with Rails applications.

A handy thing about debuggers is that you can freeze your application while it is running, step through lines of code, look at the values of your variables, and even change things on the fly to alter the running behavior of the program. The Ruby ecosystem provides both command line and IDE integrated debugging tools that are well worth learning. The “ruby-debug” core components are gems that can be added to your system that provide much improved performance over the stock Ruby interpreter’s debugger. We believe ruby-debug should be added to your must-install list of tools.

Testing

Of course, how did you end up getting a bug to track down in the first place? Most bugs are written by programmers, not typically intentionally. The Ruby on Rails community has adopted many Agile development practices, and one of those is to do as much automated testing as possible, before putting code into production use. To this end, Ruby on Rails builds in automated testing tools and code, which you can leverage for writing your own tests. We are going to save the topic of testing for another podcast, but we want to make you aware that besides the built in Unit, Functional, and Integration tests that come with Rails, and the means to easily run those tests with rake, many other tools exist to help you exercise your code.

Almost all of the Text Editors and IDEs come with built in support for finding common programming errors, and if you add in testing code that you write, you start to construct a quality safety net for yourself. The time you spend up-front learning these tools and putting in a modicum of tests will pay-off ten-fold down the road when changing your code and trying to track down unexpected side-effects.

Conclusion

We’ve really only begun to touch on the wide variety of tools that exist to support you when building your next application. There are solutions for tracking information like bug tracking, feature tracking, project schedule tracking. There are tools for continually monitoring your files as they get placed into source code control to make sure they run and pass all tests. There are even more tools for working collaboratively with other team members. The list goes on and on. Check the show notes at LearningRails.com for pointers to some examples.

Our goal in this podcast has been to highlight some of the important types of tools in common use in the Ruby on Rails community. There are many choices, and the good news is that in every category, there is usually more than one quality open source solution. (The bad news is that this can making picking the right one for your needs challenging.) If you require the comfort of a commercial package with guaranteed support, more and more vendors are stepping up and joining the Ruby and Rails communities with a tool that might be right for you.

If you want to learn more about other tools, and some of those that we use at BuildingWebApps.com, explore the site and read some of our articles and blog posts on the topic. Tools, as it turns out, is also a topic that raises some passionate dialog in the various Ruby on Rails discussion group and forums, so you’ll always get an opinion from someone in the community.

That’s it for this episode. In our next episode, we’re going to talk about how Rails supports built-in tests for your code, which are a valuable tool for improving the reliability of your applications and protecting your sanity.