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.

The development environment for processing SASS will depend on what starterkit you utilize:

Dusty

Dusty is the rather outdated starterkit leveraging the Ruby Sass preprocessor. Comes with a well organized Sass setup with heavy use of partials. Ruby is the programming language originally behind Sass and all the things that extend it. Ruby Gems like Compass, Susy, and Singularity GS, are basically software packages written in Ruby.

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.

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.

Default also contains a grunt file called Gruntfile.js. Grunt is a task manager which will run all the important tasks with just a simple command. Read the gruntfile to learn the specific tasks. For example running
grunt watch
in your theme directory runs compass, drush clears the them registry and runs uglify and jshint.

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

Comments

ianthomas_uk’s picture

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).

PlayfulWolf’s picture

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

Lowell’s picture

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?

friendlymachine’s picture

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

PMorris’s picture

I didn't end up with any (.ruby-version and .ruby-gemset) in my sub theme after using omega-wizard. I eventually realized the default option in the wizard "Default: Slim bleeding edge starter kit." doesn't actually use ruby! The instructions should be updated because they kind of make is seem like ruby has to be part of your development environment and that something went wrong if you don't have the gemset files showing in the sub theme.

Melissamcewen’s picture

Added info about the new libsass starterkit, which is now known is default. I'm by no means an expert, though I've been using it extensively.

I do question why we have so much info about installing rvm and the like here. Shouldn't we just link to rvm's official documentation since it's not Drupal specific and adds a lot of clutter here?

ultrabob’s picture

There seems to be a whole lot of info here on Dusty, after a brief statement that requirements will vary based on starterkit. There is a heading for Dusty, so I scroll down the page looking for default, but to no avail. There is a paragraph at the end that mentions default, but it is unclear whether I need all the information above, or just what is in that paragraph.

don@robertson.net.nz’s picture

Hard to know what to do - don't get a Gemfile, .ruby files ... whole thing seems a bit half baked. Thinking it is time to pull the plug on Omega

Don Robertson
Christchurch, New Zealand
don@robertson.net.nz
021 294 1542