How to use Compass in Eclipse on Windows

Compass is an open-source CSS3 authoring framework. It is based around SASS and helps make CSS3 code cleaner and more re-useable. Unfortunately, it’s mostly command-line based, an area I guess a lot of Windows users don’t feel that comfortable with. So here’s my step-by step guide to getting Compass working on Windows. You can stop at the end of step 5 if you’re happy with the command-line approach, or carry on to the end if you use Eclipse and want automated builds from there.


If you think this is all a bit hard work, then perhaps you should check out Scout or for an easier install.

Step 1: Install Ruby

Compass runs on Ruby. It’s a programming language, but not one that’s installed by default on Windows. You’ll need to get this up and running first.

As of writing, the latest version of Ruby (2.0.0) is available for download here, and this is the version I’ll be using in this walk through. Newer versions may be available by the time you read this. Go ahead and download the appropriate installer for your computer, then run it. I chose the option to add the ruby executable to PATH so that I don’t have to worry too much about installation directories later.

Finished? Excellent.

Step 2: Install RubyGems

Now load the Command Prompt. I’m using Windows 8, so just hit the Windows key and begin typing ‘command prompt’. You’ll see it soon enough. Users of other versions of windows should find Command Prompt in the start menu. Type:

gem update --system
gem install rubygems-update

This will get everything bang up to date and install RubyGems, a package manager for Ruby. Note, you may need to be an Administrator for this to work.

Step 3: Install Compass

gem install compass

Should do it. On my computer this gives no feedback as to what’s going on at all, so give it a while as it might look like it’s crashed!

You’re now ready to use Compass!

Step 4: Create a Compass Project

Eclipse users can now skip on to Step 6. Those who love command lines should stick with steps 4 & 5.

It’s time to give Compass a whirl! Still using the command prompt, navigate to a folder where you wish to create your Compass project. (Type ‘cd Desktop’ from the default Command Prompt directory if you wish to see the files created on your Windows desktop.)

compass create <myproject>

Replace <myproject> with whatever the name of your project is. Compass will create a default files and directory structure.

Using Compass with an Existing SASS Web Project

Of course, you might want to use Compass with an existing project that you’ve created, using a different directory structure to the default Compass layout. In this case, simply cd to your existing project directory and use the command below, replacing directory names as appropriate:

compass install compass --sass-dir "<sass-directory>" --css-dir "<css-directory>" --javascripts-dir "<js-directory>" --images-dir "<img-directory>"

Step 5: Watch Your Project for Changes

So now you’ve got a Compass project. You can edit the SCSS files to your hearts content using whichever text editor you’re familiar with. Check out the SASS website for tutorials and documentation.

There’s one final step: Watch the project.

Watching the project will make Compass automatically rebuild the CSS files every time you edit the SCSS files. Dead easy! From within the project directory on the Command Line type:

compass watch

If you’re not interested in web development using Eclipse, you can stop here. Ruby and Compass are installed and you know how to create a Compass project and watch it for changes.


Step 6: Build the SCSS Automatically in Eclipse

My project layout for a Compass web project using eclipse

My project layout for a Compass web project using eclipse

I’ll assume you’re already using eclipse for web design. If not, you can download it from here. I’d go with the Classic version, and then install the Web Tools Project (WTP) from within the program.

I’ve set up a Static Web Project in Eclipse using the Eclipse Web Tools Platform. In the WebContent directory I’ve created all my usual css, img, js, etc, etc directories. I’m going to keep my SCSS files outside of the WebContent directory, and I’ve created an scss directory there containing the _base.scss and compasstest.scss files.

Eclipse contains a brilliant feature called Builders. A builder can be run automatically every time you save a file, or manually if you prefer. For me, during web development the automatic option is easily the best.

Create new builders in Eclipse from this dialog

Create a new builder in Eclipse

To create a new builder in Eclipse, make sure you have the relevant project selected, or open a file from within that project. Then go to Project > Properies in the menu. This will bring up the builders dialog (see right). Click “New…” to open the builder creator, and then choose “Program” from the list of options.

Main options dialog for an Eclipse builder

Main options dialog for an Eclipse builder

Now for the difficult bit! Firstly, you need to specify the location of Compass on your hard drive. Click “Browse File System…” under the “Location” option. I installed Ruby using the defaults, so compass is located at C:\Ruby200-x64\bin\compass.bat. The “Working Directory” should be set to ${workspace_loc:/<your project name>}  Obviously replace <your project name>!

The “Arguments” will specify where our SCSS files are stored, and where the CSS should be output. You’ll need to edit the following to fit your project:

compile --sass-dir "${project_loc}/scss" --css-dir "${project_loc}/WebContent/css" --javascripts-dir "${project_loc}/WebContent/js" --images-dir ${project_loc}/WebContent/img"

The ${project_loc} variable will be replaced by Eclipse with the directory of your project, so it’s only the local directory structure after that that you’ll need to edit.

Refresh options in the Eclipse builder configuration

Refresh options in the Eclipse builder configuration

There are a few other options that you’ll need to set. Under the “Refresh” tab you set which resources will be reloaded once this build has taken place. As we’ll only have modified CSS files, I’ve chosen “Specific Resources” and selected the CSS output directory of my project.

Build options under Eclipse Builder Configuration

Build options under Eclipse Builder Configuration

The “Build Options” tab specifies when this builder should be run. Remove the “Allocate Console” selection unless you want to be notified every time Compass is executed.

Select the “During auto builds” option to get this to run automatically.

Again, we’re only interested in running it when the SCSS files are changed, so choose “Specify working set of relevant resources” and select your sass folder (scss in my case)

That’s it! You now have an Eclipse project that’s configured to compile CSS from SCSS automatically.

Further Development

I think it’d be good to configure the Compass build using a configuration file rather than all those arguments in the builder. This would be much easier to update and move between projects.  See this post.

Perhaps it’d also be good to output a human readable CSS file outside the web directory, and a compressed production-ready CSS file within it?

Your thoughts are, as ever, welcome in the comments.


Suggested Reading

Of course, all this is only any use if you know what you’re doing! I’d suggest reading the SASS Website to get to grips with the language, there are tutorials there too.

The Compass Reference will keep you informed about the Compass framework. Please note, these tutorials include lots of information on Blueprint which is being removed from the core Compass soon, so I’m really not sure it’s worth learning about that?

If you’re looking for a grid system, you should check out SUSY. It’s got a Getting Started / Installation guide there too to get you going.


The following resources have been very useful during the compilation of this article

Compass Website – specifically the Command Line Documentation and Getting Started pages.

Ruby Website and the RubyGems Installation page