Last updated November 22, 2013. Created by banghouse on March 8, 2013.
Edited by Voix, fubhy, Cellar Door, brst t. Log in to edit this page.

PLEASE NOTE: Omega 4.x does not require that you use Sass or any of its related frameworks, however the ease of creating layouts and the time saved while doing so by using Sass is invaluable. Therefore it is not only encouraged that you embrace Sass, but also these other development tools for managing your local environment and Ruby gems.

What is Sass, Ruby, and Ruby gems and why do I need them?

Sass is an extension of CSS3 which adds nested rules, variables, mixins, selector inheritance, and many other features. It’s translated to well-formatted, standard CSS using the command line tool or a web-framework plugin and is compiled with Ruby. Ruby is the programming language behind Sass and all the things that extend it. Ruby Gems like Compass, Susy, and Singularity GS, are basically software packages written in Ruby.

Sass and all the other Ruby Gems that extend its functionality are development tools that you install on your (optimally local) development machine. You then compile your stylesheets from .scss/.sass to .css from the command line.

Development setup and the software requirements.

The best possible way to install Ruby and the required Ruby Gems (and manage them properly in the future) is to run Ruby through RVM (Ruby Version Manager) from http://rvm.io/. You may like to learn more about RVM, or be interested in using an RVM GUI like Jewelry Box. See also the 'Gem Management' section at http://rvm.io

If you are on a Mac, you'll require a package manager like Homebrew and the latest version of XCode Development Tools, as well as the Xcode Command Line Tools. Although Mac comes with Ruby, it may not be the right version. Install RVM with Ruby with \curl -L https://get.rvm.io | bash -s stable --ruby. (more install options here)

After installing RVM, run rvm requirements in your terminal to see if anything else is required to install Ruby and Rails.

The installation of RVM automatically installs two more important things together with actual Ruby: rubygems (the requirement for working with Ruby Gems), and bundler, though you may install RVM without either. RVM also creates a new completely separate gem directory for each version of ruby.

Bundler is a tool that helps you to manage and automatically install groups of Gems specified in a so called "Gemfile", helping future-proof sites that invariably will end up using different gems or different versions of gems.

Once you have an Omega subtheme installed, you can find that file in your subtheme (if properly generated using Drush). In addition to that you will find two files (.ruby-version and .ruby-gemset) in your subtheme. These files are essential for a RVM workflow. It tells RVM that the current folder is an "isolated" ruby (.ruby-version) and gem (.ruby-gemset) environment when navigating to the subtheme folder in your Command Line, making every following command (here and in every sub-folder) specific to your subtheme. This is very important to understand.

Note that .rvmrc is nearly the same as a .ruby-version file. Learn more about the differences.

This ensures that every "Ruby" or "Gem" command that you run from within this folder causes the desired action (installing a gem, removing a gem, etc.) to only affect your subtheme. This is very useful as it prevents conflicts between gems in different projects and different versions of Ruby.

Take a look inside the generated .ruby-version and .ruby-gemset files in your subtheme directory. They include the name of your subtheme to identify them on your system.

Navigate to your Omega 4.x subtheme directory and run rvm list in the terminal. This should list your local environment there and state which versions of Ruby are installed, as well as the version your subtheme is using, which is specified in the .ruby-version file.
rvm gemset list will show you the active "gemset", which is specified in the .ruby-gemset file. Here is a quick cheat sheet for using RVM commands.

Make sure that the used gemset and ruby version match those defined in your .ruby-version and .ruby-gemset file.

If something did not work, see this comment.

Why is this functionality important?

Most of the Sass Ruby Gems (Susy, Breakpoint, etc.) have rather short-lived versions. They are constantly upgraded and sometimes new versions break the backwards compatibility, i.e., causing some of the mixins syntax to change. This means that when upgrading the gems for Project A, Project B might suddenly not compile properly anymore. Hence, we explicitly separate and specifically install the Gems on a per-project basis.

So now we have separate Ruby and Gem environments. But we don't have the Gems installed yet! Here's where "Bundler" comes in. Due to the Gemfile specified in your subtheme you can install all the cool Sass Gems in one go. Simply run bundle install in your subtheme folder (from the Command Line) and it will read the Gems specified in the Gemfile and install them (and all their dependencies) one by one. You may need to change the initial bundle stack size with peflags -X409600 `which ruby` if the stack level is too deep.

This will create a new file called Gemfile.lock that specifies the versions of the various gems you have used. This will help those that come after you replicate the environment you used to create the theme, by keeping track of the explicit version numbers of the Gems that you just installed.

Running bundle install again (i.e. in case you want to work on two computers or you have multiple developers in your team for which you need to install the Gems) ensures that it installs the exact same versions on all of the developer machines that work with this project.

Together with the isolated environments, this allows for perfectly clean environments for everyone on your team (or all your machines). The Gemfile.lock should ideally end up in your git repository as well so even when you come back a year later (at which point you probably already deleted the project from your computer) and you install all the Ruby stuff again you get the exact same versions of the Gems that you had back when you first worked on the project. This ensures that all of the .scss/.sass re-compiles exactly the same way as it did a year ago. Fancy!

Now that everything is properly installed and managed (Ruby via RVM and your Gems via Bundler), you'll want to start working with Sass. Sass, as mentioned before, is a compiler for .scss/.sass files that outputs .css files. This compiler can be invoked in multiple ways. By default, when using Compass (a Sass framework), you can use the command compass compile to compile your stylesheets (in terminal) from Sass to CSS based on what is specified in your "config.rb" file (note, the config.rb file defines HOW and WHERE the compiler should operate).

This process compass compile can be automated by using the terminal command compass watch which triggers the compiler every time a .scss/.sass file in your project is changed. This means your stylesheets are automatically recompiled every time you change a project file.

Read this for more information on Ruby and Bundler and how it helps you in your development.

In a following chapter we will explain how to further automate your environment with Grunt or Guard including things like LiveReload and UglifyJS and how you can manage your theme's dependencies with Bower.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

The section talking about bundler makes various references to your sub theme, and suggests running a command from your subtheme's directory, but given this is the installation page a user following the getting started guide won't have a subtheme yet.

I'd suggest much of this content of this page should be moved to a new page later in the getting started guide (I'm still getting started myself, so I'm not sure where exactly yet).

Seems, that the context of this page is unknown, lets assume, that I am a beginner Omega 4.x user, who runs BOA - Barracuda Aegir on Ubuntu/Debian and want to develop sub-theme with the help of SASS.
Documentation could be a continuation of "Sub-theme with Drush" in the same, easy to understand for first time users style

drupal+me are capable of: jewelers portfolio

Ha! You describe me!

And I am stuck with ruby 1.8 and it seems I need 1.9.3, don't know where to go next.
And can I install rvm safely in the BOA enviroment?

If you've read these instructions and have gotten stuck, here's how I managed to get past the speed bumps. What follows may work on other systems, but I was on Mac OS X. You'll need to work with Terminal for most of this - if you get any permissions errors, remember to prefix the commands with 'sudo'.

1) Install Xcode.

https://developer.apple.com/xcode/

This is an application (IDE to be specific) for Mac developers. Fortunately, you don't have to do much with it, but you need it installed. If you're on Windows or Linux, I have no idea what the alternatives might be.

2) Install Xcode Command Line Tools.

Once you get Xcode installed you need to install the Command Line Tools. Go into "Preferences" and look under "Downloads". You only need to install these, not actually do anything with them.

3) Install Homebrew.

Another case of install it and forget it - at least for me, so far. You can get it here:

http://brew.sh/

4) Install Bundler.

You can download here:

http://bundler.io/

5) Install RVM with latest stable Ruby. Mac comes with Ruby installed, but it may not be the right version (wasn't for me). Another thing that may happen is that as you're installing some of the above, you may be prompted to install additional items or alternate versions. Go ahead and do so.

To install RVM with latest version of Ruby:

\curl -L https://get.rvm.io | bash -s stable --ruby

More install options here: https://rvm.io/rvm/install

6) Go to your theme folder in Terminal and run:

bundle install

This will create a new file called Gemfile.lock that specifies the versions of the various gems you have used. This will help those that come after you replicate the environment you used to create the theme.

Huge pain in the ass, right? I worry this may chase people away from Omega. Seems like a potential barrier to entry for designers and hybrid designer/devs like myself.

This goes way beyond the basic Sass + Compass set up many are familiar with. Just got it working myself - after several hours of troubleshooting - and hopefully it will simply be a matter of running 'bundle install' in the theme directory for future projects.

Hope this helps someone else avoid the headaches and cryptic error messages I ran into. Whew! Now I need a drink!

UPDATE:

Here's some additional information from fubhy that really helps clarify things:

https://drupal.org/node/2009540#comment-7485186

John Hannah
Friendly Machine