Bamboo Blog

Here we are going cover the install instructions for Merb, RSpec, and DataMapper (0.9) and how to create a bare application. The next post will cover aspects of the framework and introduce the example application we will be building.

Getting Started

Before we get started I'm going to assume you have the following installed:

• Ruby
• A DBMS (we'll use MySQL)
• SVN and git (on OSX, port install git-core worked for me)

Installing Merb

---

If you have an older version of Merb (<0.9.2) you should remove the all the gems before continuing. Use gem list to see your installed gems.

---

Installing the merb gems should be as simple as:

sudo gem install merb --source http://merbivore.org 

Unfortunately we are living right on the edge of development so we'll need to get down and dirty with building our own gems from source. Luckiliy this is much easier than it sounds...

Start by installing the gem dependancies:

sudo gem install rack mongrel json_pure erubis mime-types rspec hpricot \
    mocha rubigen haml markaby mailfactory ruby2ruby

Then download the merb source:

git clone git://github.com/wycats/merb-core.git
git clone git://github.com/wycats/merb-plugins.git
git clone git://github.com/wycats/merb-more.git

Then install the gems via rake:

cd merb-core ; rake install ; cd ..    
cd merb-more ; rake install ; cd ..
cd merb-plugins; rake install ; cd ..

The json_pure gem is needed for merb to install on JRuby (Java implementation of a Ruby Interpreter), otherwise use the json gem as it's faster.

Merb is ORM agnostic, but as the title of this book suggests we'll be using DataMapper. Should you want to stick with ActiveRecord or play with Sequel, check the merb documentation for install instructions.

Installing DataMapper

---

DataMapper is splitting into dm-core and dm-more so datamapper 0.3 will be outdated soon. If you have an older version of datamapper, data_objects, or do_mysql, merb_datamapper (< 0.9) you should remove them first. Remove the merb_datamapper gem before installing dm-merb within dm-more.

---

We will use MySQL in the following example, but you can use either sqlite3 or PostgreSQL, just install the appropriate gem. You will also need to ensure that MySQL is on your system path for the gem to install correctly.

(TODO) - gem instructions for DM 0.9 once they are released

To get the gems from source:

git clone git://github.com/sam/do.git

cd do
cd data_objects
rake install ; cd ..
cd do_mysql  # || do_postgres || do_sqlite3
rake install

git clone git://github.com/sam/dm-core.git
git clone git://github.com/sam/dm-more.git

cd dm-core ; rake install ; cd ..
cd dm-more
cd dm-merb ; rake install ; cd ..    
cd dm-validations ; rake install ; cd ..

To update a gem from source, run git pull and rake install again.

Install RSpec

The rspec gem was installed in the Merb section above. However, if for some reason you didn't install it there, or want to grab the it from source, run the following commands:

gem install rspec
svn checkout http://rspec.rubyforge.org/svn/trunk rspec_trunk

Creating an App

Now that we've got all of that installed, time to create a test Merb application. Merb follows the same naming convention for projects as rails, so 'my_test_app' and 'Test2' are valid names but 'T 3' is not (they need to be valid SQL table names).

merb-gen app test

This will generate an empty Merb app, so lets go in and take a look. You'll notice that the directory structure is similar to Rails, with a few differences.

# expected output
RubiGen::Scripts::Generate
  create  app
  create  app/controllers
  create  app/helpers
  create  app/views
  create  app/views/exceptions
  create  app/views/layout
  create  autotest
  create  config
  create  config/environments
  create  public
  create  public/images
  create  public/stylesheets
  create  spec
  create  app/controllers/application.rb
  create  app/controllers/exceptions.rb
  create  app/helpers/global_helpers.rb
  create  app/views/exceptions/internal_server_error.html.erb
  create  app/views/exceptions/not_acceptable.html.erb
  create  app/views/exceptions/not_found.html.erb
  create  app/views/layout/application.html.erb
  create  autotest/discover.rb
  create  autotest/merb.rb
  create  autotest/merb_rspec.rb
  create  config/rack.rb
  create  config/router.rb
  create  config/init.rb
  create  config/environments/development.rb
  create  config/environments/production.rb
  create  config/environments/rake.rb
  create  config/environments/test.rb
  create  public/merb.fcgi
  create  public/images/merb.jpg
  create  public/stylesheets/master.css
  create  spec/spec.opts
  create  spec/spec_helper.rb
  create  /Rakefile

Configuring Merb

Before we get the server running, you'll need to edit the init.rb file and un-comment the following lines (this is only necessary if you need to connect to a database, which we do in our case):

config/init.rb

use_orm :dm_core

use_test :rspec

Typing merb now in your command line will try and start the server.

Started merb_init.rb ...
No database.yml file found in /Users/work/merb/example_one/config.
A sample file was created called database.sample.yml for you to copy and edit.

As you can see, we forgot to set up the database. A sample file has helpfully been generated for us. Edit this and rename it to database.yml:

# This is a sample database file for the DataMapper ORM
development:
   adapter: mysql
   database: test
   username: root
   password: 
   host: localhost
   socket: /tmp/mysql.sock

Don't forget to specify your socket, if you do not know it's location, you can find it by typing:

mysql_config --socket

Starting Merb again shows that everything is running okay.

The following command will give you access to the Merb console:

merb -i

You'll notice Merb runs on port 4000, but this can be changed with flag -p [port number]. More options can be found by typing:

merb --help

You can even run Merb with any application server that supports rack (thin, evented_mongrel, fcgi, mongrel, and webrick):

merb -a thin