If you are doing a lot of theming in Drupal with Sass and Compass, there's a good chance your stylesheets rely on specific versions of gems to compile properly. Mixins and functions can change, and sometimes gems rely on specific versions of other gems to work properly.
Thankfully, there's an easy solution for managing your ruby gems called Bundler. Bundler allows you to manage the versions of gems that are being used for a specific project. With it, you have a way to manage the versions of gems installed in Ruby without needing to switch Ruby versions for each project. It's a great tool for ensuring teams of people are all working in the same environment, and that you can maintain your own Sass projects over time.
This article explains how to get started with Bundler, what a Gemfile looks like, and how you can incorporate it into your own projects.
I'm going to assume you already installed ruby and rubygems (which is built into ruby since 1.9). If not, there are a ton of great tutorials available for every platform out there.
Installing Bundler is easy The first step is simply to tell rubygems to get a copy of bundler and install it on our system:
$ gem install bundler
This can be done right through the command line. There's no need to download any packages, ruby knows right where to get the latest version.
Creating a Gemfile
Next, we're going to create a file in your project called a Gemfile. The Gemfile specifies what gem versions are required by your project. This applies to Sass and Compass, along with whatever other gems you might be using. For Drupal themes, the Gemfile should live in the root of your theme (i.e. sites/all/themes/my-theme/Gemfile).
Bundler will create the gemfile for you through a simple command. Go to the root directory of your project and run the following.
$ bundle init
Bundler will create a Gemfile for you, using whatever gems it currently finds on your system. For most themes, this would mean it's using whatever versions of Sass and Compass you have installed on your system. Once the file is created, you can specify specific versions of other gems to use with your project.
What's in a Gemfile
A Gemfile contains information about the gems that are being used for your project. It includes the name of the gem, and information about which version to use. It's very similar to a Drupal install profile, in concept and syntax. If you create a Gemfile and open it, you are going to see something similar to the following.
gem 'compass', '~>0.12.2'
gem 'sass', '3.2.8'
In this example, we're saying we need Compass version 0.12.2 or higher, and Sass version 3.2.8. You will notice you can specify a specific version for any project, or a range of versions that are applied. From here, you can add whatever other gems are needed for your project.
This is where Bundler does it's work. When you have a Gemfile, you can tell Bundler to set up all the gems needed for your project for you. It will read the Gemfile and ensure that all the required gems are available, with the right versions for your project. You can install gems by the following command in the same path as your Gemfile.
$ bundle install
Bundler will install the correct versions of the Gem on your system and they will be available when it comes time to work on your project. This will not change the default versions of gems that exist on your system. This ensures you are able to work with gems without needing to make wholesale changes to your environment.
Compiling CSS with Bundler
When it comes time to work with your project, instead of using
compass watch, you will compile your code through Bundler. This makes sure you are using the right versions of gems as part of your project. The command to compile a project using Bundler is the following.
$ bundle exec compass watch
That's it! Bundler will read the contents of the Gemfile and only use the versions you want. Bundler isn't only for compass though; you can use it to control the version of any gem being executed.
Pro tip: It's helpful to leave a comment in your Gemfile telling other developers how to use bundler. You can do this using a # symbol at the start of any line.
There's more information about how to write Gemfiles and specify gem versions available at the Bundler website. Bundler has been a huge time saver for here at Trellon. I hope this advice saves you the frustration of dealing with multiple versions of ruby gems.