Wednesday, November 7, 2007

Merb & Datamapper: Getting Rolling

Today we want to take a look at Merb and DataMapper.

NOTE: I'm doing this run through on OS X. If you are using a different OS, some of the instructions may need modifications (specifically in regards to path locations). This post also assumes that you are using MySQL, which you should already have installed (including the MySQL gem).

Merb: A Web Framework.
Yesterday marked the 0.4 release of Merb. At this point it should be fairly stable. Stable enough to make it, at the very least, worth a run through. A few months have passed since the original tutorial, and since then Merb has released versions 0.4.1, 0.4.2, 0.5.0, 0.5.1, 0.5.2 and 0.5.3. Since 0.5.3 there has been a large amount of work done in putting together the 0.9.x release. At the time of this update, 0.9 is a "developer" release. I will be updating these instructions soon.

Merb, like Ruby on Rails, is an MVC web framework. The Merb project has goals of being performance oriented and providing flexibility through plugins. This should allow a developer to better mix and match available tool sets to the specific needs of any given project.

One of the areas of flexibility that Merb provides is in the use of an Object Relational Mapper (ORM). You may have heard of, or be familiar with, ActiveRecord which is the ORM provided by default within the Ruby on Rails framework. You can use ActiveRecord with Merb, but you also have other ORM options such as DataMapper and Sequel.

So let's get started.

Installation (outdated - still is 0.4 based)
First off you need to get Merb & DataMapper installed on your machine. Assuming that you already have Ruby and Gems installed on your system, installation is as simple as:

sudo gem install merb --include-dependencies
sudo gem install datamapper
sudo gem install ruby2ruby --include-dependencies
sudo gem install merb_datamapper ??
UPDATE: Merb does depend on the json gem (json_pure if you want to use it on jruby). This "should" be installed when you install "merb --include-dependencies", but some readers have reported that it wasn't. So just to be safe, run:
sudo gem install json
Lastly, we need to make sure DataObjects.rb drivers are installed. You should now be able to install as a gem:
sudo gem install do_mysql
UPDATE (12/11/07): benr75 reports: "The do_mysql gem is currently broken and refers to an absolute path for MySQL that may not exist on users systems. Fix instructions here."

Other possibly useful resources are: post on Blog::Heimidal and the DataMapper Getting Started page.

Assuming everything went smoothly for you, we are now ready to roll.

Generate & Configure Your New Merb Project (updated to 0.9)
Next we will be generating the default framework files.

Change to the directory where you wish to create your Merb project. For me that was:
cd /Users/justin/programming/projects/
Similar to Rails, to generate the framework code we simply run:
merb-gen project_name
cd project_name
As mentioned before we need to configure our Merb application to let it know that we want to use the DataMapper ORM, and setup our database. Pretty simple stuff. Just a few text edits in 2 files.

First, open config/init.rb and find and uncomment the following line as below:
### Uncomment for DataMapper ORM
use_orm :datamapper
The only other file we need to setup is our database configuration file. When you initially generated your project code Merb did not create this file. Why? Because you hadn't yet told it what ORM you wanted to use.

Since we have edited the dependencies.rb file to indicate we will be using the DataMapper ORM, all we now need to do is load the Merb framework and it will auto-generate a sample database configuration file for us. This sample file will be based on the specific requirements of the ORM we have chosen. So from the command line run:
merb
Easy. Merb saw that you wanted to use DataMapper, but no database has been configured. Automatically the database.sample.yml file was then generated. Now let's finish up our configuration of Merb. Open config/database.sample.yml and edit it according to your specific setup. For example mine looks like:
---
# This is a sample database file for the DataMapper ORM
:development: &defaults
:adapter: mysql
:database: merbtest_development
:username: root
:password:
:host: localhost

:test:
<<: *defaults :database: merbtest_test :production: <<: *defaults :database: merbtest_production
Don't forget to copy or rename the file to database.yml.

Also, the databases that you just configured in database.yml need to actually exist, so if you haven't done so already please take a moment to create them now.

That's It!
With those two simple configuration steps, our bare bones application should now be ready to roll. To start up, from within your application directory type:
merb
By default Merb is setup to run on port 4000 of host 0.0.0.0. So open up your browser and point it to:
http://0.0.0.0:4000/
You should now see the Merb default page before you.

If you wish to adjust the IP address or port number that Merb runs on, that is configurable from the config/merb.yml config/init.rb file.

That's it for this post. In the next post we will actually make our Merb app do something.

Until then you can get some basic ideas of how to wire things together in this post on PaulBarry.com

4 comments:

  1. Seems Merb also uses JSON, which if you don't have installed will cause it to fail when you start the server. A simple "gem install json" solved the problem.

    ReplyDelete
  2. Andrew:

    Thanks! Yes, Merb has quite a list of dependencies.

    When I went through and installed using:

    gem install merb --include-dependencies

    I thought that it installed the json-pure gem, which is a jRuby friendly version of json.

    ReplyDelete
  3. Yeah, I ran the install to include dependencies but for me it missed that one. Using your command to install the drivers threw some wonky depreciation errors too but still installed just fine. I was up and running in about 15 minutes!

    EDIT: corrected grammar error.

    ReplyDelete
  4. The do_mysql gem is currently broken and refers to an absolute path for MySQL that may not exist on users systems. Fix instructions here.

    ReplyDelete