More at spreecommerce.com: Features | Support | Blog | Demo | Community | Download

Working with the Source Code

This guide covers obtaining and running the source code. This is primarily for developers who are interested in contributing code to the Spree project or fixing the source code themselves. It is not necessary to have a copy of the source code to run Spree.

1 Git

The Spree source code is currently maintained in a Git repository. Git is a distributed version control system (DVCS) and it allows us to do things never before possible with SVN. If you’re skeptical of Git just remember how skeptical you were of SVN when you were using CVS. The differences are subtle but important and they are best understood by hands on use.

The authoritative git repository is hosted by GitHub and is located here. You can clone the git repository using the following command:

git clone git://github.com/railsdog/spree.git spree

If you are planning on contributing to Spree you should create a fork through Git Hub and initiate a pull request when you’re done. (See the Contributors Guide for details.)

If the official GitHub repo is down you can try our mirror at repo.or.cz

1.1 Browsing the Repository and/or Downloading the Source Code

You can easily browse the repository through Git Hub’s excellent visual interface. Git Hub also contains a link to download a tarball copy of the latest source code as well as links to previous versions.

1.2 Git on Windows

There are some well developed Git clients for Windows now. If you are on a Windows box you might want to check out the msygit project. There is also a screencast available.

2 SVN

There are no immediate plans to support SVN clients. Given that most of the Rails world is moving to git (including the RoR project itself) maybe this is the time for you to jump on the bandwagon.

3 Monitoring Changes in the Source

If you would like to keep up to date on changes to the source you can subscribe to the github RSS feed and you will be notified of all the commits.

4 Building the Gem from the Source

4.1 Motivation

Why bother building the Spree gem from the source? The primary answer is that it allows you to take advantage of all of those great “edge” features without having to wait for the next official release of Spree. Its true that you can always run the latest source by cloning from github but this method has its limitations.

In order to create a new Spree application you will need to run spree which is invoked using the currently installed Spree gem. The spree command is also responsible for setting up your applications environment settings, etc. so if you’re trying to build a new store with the cutting edge features, you’ll want to build the gem locally.

4.2 Prerequisites

  1. Rails 2.3.x
  2. Ruby Gems (1.2.0 is suggested, other earlier versions may or may not work)
  3. Spree gem dependencies (run rake gems to check, rake gems:install to install)

There are also a few gem dependencies needed to run the tests (which are automatically run when building the gem.) Use rake gems:install RAILS_ENV=test to install these.

It is suggested that you get Spree up and running using the source first before attempting to build the gem. This will be the easiest way to make sure you have all of the correct dependencies, etc.

4.3 Database Requirements

The gem build process requires that the tests are able to run successfully. This is turn requires that both a test and development database need to be configured in config/database.yml.

Why are both of these databases needed? Some of the tests require fixtures which are created in the test database. Most of the tests use the RSpec mock_model helper which requires access to the database so that the mock can learn the dynamic database attributes of the model class (even though no data is written to the database in these cases.) Still other tests are using Factory Girl whic also reqiures access to the database.

The tests simply will not not run without these two databases configured and you will not be able to install the gem without passing the tests. So trust us on this one.

4.4 Performing the Actual Build

Use the following command to build and install the gem

rake spree:gem:install

If you are on a Unix style system you may need to use sudo instead

sudo rake spree:gem:install

4.5 Considerations

  • The gem will have a x.y.99 version number. This denotes an “edge” version. You will need to uninstall the edge version later if you want to work with the x.y.z gem once its released.
  • If you want to deploy the gem on multiple machines: the built gem is in the spree source directory, in pkg. Just copy it and install it, eg sudo gem install spree-0.8.99.gem
  • You may want to do rm -rf pkg to clean things up from previous build attempts before building the gem again.