Gumstix - Getting Started

Yesterday I received my Gumstix order in the mail. It took all of about 2-3 hours to get working. The pack I got was the Wifistix, Audiostix2 and the Connex400 (no bluetooth). After clicking the pieces together, I powered up the device and blammo. It works. The Wifistix registered the computer on the network and all is well so far.

For those who are trying this configuration in an environment such as mine where there are dozens of wireless networks available, my strategy was to boot the Gumstix in very close proximity to the wireless router... this way, when the Wifistix tries to register the network, it chooses yours. Otherwise of course, it will register itself with any old wifi network it comes across.

More later.

How To Setup Ruby, Rails, and Oracle 10g on Solaris 10

Introduction

Here is the list of what you will need to have installed to run a Ruby on Rails application on Solaris 10.

* Ruby 1.8.4\+
* Oracle 10g client full install
* RubyGems
* Rails
* Mongrel
* Ruby OCI8 libraries

There are a number of dependencies in order to get these items installed which are detailed in the following sections.

This tutorial is going to assume that any Solaris machine that you are attempting installation on will be totally devoid of any software tools that would make an installation painless.

My first suggestion for this installation process is: *DO NOT use Sun's Download center*.
There is nothing simple about Sun's installations. I only tried one (gcc) and it placed the binaries in a folder that was outside of the default search path. Brilliant, thanks Sun.

Instead visit http://sunfreeware.com and search for packages for the platform in question.
In the following, I have linked to the files where possible, but in the case that you are not installing this on Solaris 10 with a Sparc processor, use the above link to get the packages.
There may be better places, but this site had all the packages I needed and better than that, it worked. If at all possible, you should be using a package manager in general, and for this, I used Sun's package manager which is pretty basic. Also, you should get the packages, NOT the src files for teh packages. If you get the src files you will need to build the packages before you install them which could be a pain. But I digress... onward!

1. Install the Oracle Client

 You \*must\* have a full install of the Oracle client for the Ruby OCI8 driver to work. This is not an option. I have gotten the OCI8 driver to compile with the Oracle Express Edition client (XE), but if at all possible, install the full client.
Check to see that you have the "oci.h" file that the Ruby OCI8 driver will want to use (which is installed with the Oracle client).

$ locate oci.h
    /opt/local/oracle/product/10.2.0/client_1/rdbms/public/oci.h

This file should be somewhere like the path above - in a "public" folder.
If you do not have this file or it is in a "demo" folder, you dont have a full install of the client - stop right here and go get one installed.

1. Prerequisites

You will need to install a handful of libraries and whatnot before Ruby will work correctly.
Download these to the temporary directory of your choice.

* libiconv-1.11 (gcc dependency)
* gcc-3.4.6 or higher (requires libiconv-1.11)
* wget-1.102 not required, but it will make your life easier (requires gcc)
* openssl-0.9.8d(I have no idea why, but gem installation would not work without this package)
* readline-5.2(fixes input problem with IRB)

Also be sure that you have "make" installed. At the very least this is usually on even the most crippled system, but just check (which make).

Once you have downloaded the packages, gunzip them and install,

# pkgadd -d gcc-3.4.6-sol10-sparc-local
# pkgadd -d openssl-0.9.8d-sol10-sparc-local
# pkgadd -d wget-1.10.2-sol10-sparc-local
# pkgadd -d readline-5.2-sol10-sparc-local

or something like that...
if you want to remove the packages after installation, use pkgrm

2. Install Ruby

Download ruby-1.8.4 and install.

# wget ftp://ftp.sunfreeware.com/pub/freeware/sparc/10/ruby-1.8.4-sol10-sparc-local.gz
# pkgadd -d ruby-1.8.4-sol10-sparc-local

Make sure everything is there ($ which ruby, $ which irb) - or better yet, fire up IRB and make sure Ruby works. Just type a few lines and exit.

$ irb
irb(main):001:0> quit

3. Install RubyGems

Congratulations, you have Ruby installed (right?). Now you will want to install RubyGems, the Ruby package manager which functions alot like Yum or MacPorts or any other intelligent package management system. On Solaris, you will need to build this from source.

Get the latest distribution of RubyGems from http://rubyforge.org/frs/?group_id=126
Or install using wget like so,

$ wget http://rubyforge.org/frs/download.php/11289/rubygems-0.9.0.tgz
$ tar -zxf rubygems-0.9.0.tgz
$ ruby setup.rb

Check the [reference manual|http://docs.rubygems.org/read/chapter/3] if necessary.

4. Install Ruby OCI8 driver

I cannot stress this enough: make sure you have an Oracle 10g Client installed.
If you are absolutely sure that you have it, download and gunzip/untar the source code:

$ wget http://rubyforge.org/frs/download.php/12559/ruby-oci8-0.1.16.tar.gz
$ gzip ruby-oci8-0.1.16.tar.gz | tar xvf -
$ cd ruby-oci8-0.1.16

You are now prepared to compile and install the Ruby OCI8 library.

1. Check the following:

* ruby and make (or nmake on MSVC) are in the environment variable PATH.
* sqlplus runs correctly

2. Check library search path.

If sqlplus runs correctly, the environments variables are okay in general.
But if Oracle is 64-bit and ruby is 32-bit, make sure $ORACLE_HOME/lib32
in 32-bit library search path. (LD_LIBRARY_PATH_32 on Solaris, SHLIB_PATH
on HP-UX PA-RISC.)

3. make and install

$ make
$ make install

Common sources of errors:

* Oracle client is incomplete/ cannot find oci.h
* Oracle environment variables are not set correctly
* gcc is not installed correctly or cannot be found

May the force be with you.

5. Install Rails and Mongrel

Welcome to the easy life.

$ gem install rails --include-dependencies
$ gem install mongrel --include-dependencies

Actually there is a bug in the configuration of Mongrel on Solaris that you will need to fix here.

For any Rails application, you can include the Rails libraries in the application itself so an external library in the Ruby search path is not necessary. If there is a copy of the Rails libraries, a "rails" folder, in the "vendor" folder of the Rails application you want to run, the application will use that copy of Rails instead of the gem installation. As a best practice, a copy of Rails should be included in any deployed application. The reason for this is simple: Rails changes. It is quite possible that an updated Rails gem will break your application in some unexpected way. As long as your Rails application has a checkout of Rails in its vendor folder, everything should run as expected. For more on the topic of "GemRails" and "EdgeRails", see the [Rails wiki|http://wiki.rubyonrails.com/rails/pages/EdgeRails].

Beginning ChucK

What a lovely language, this ChucK.

While it might seem like a detriment that the language is still incomplete and under heavy development, the situation is actually quite dreamy. The language is still in a state of simplicity. You can learn the majority of ChucK and its functions in a single day. It is decently well documented. But beyond all that, it works... well, most of the time. Let me contrast this for a moment with ChucK's conceptual older sibling, SuperCollider.

I have been trying to wrap my head around SuperCollider for the past few years and just now feel like I understand the syntax. I have spent days on SuperCollier trying to get a single sample to play over and over on a trigger without much success. Search the SC mailing list archives turns up very little, and I personally find the wikis and documention on the language and its usage scattered, incomplete, and downright confusing... not that the community has not tried to get it together. For my own purposes, the final blow was the lack of a SC command line interface. As far as I can tell, you must use the SuperCollider language environment to execute scripts and send them to servers.

I will write more about ChucK as I get further into it, but on first blush I'm smitten. For all its incompleteness it is a simple and expressive language (although required semicolons are lame).

How To Setup Ruby, Rails, and Oracle 10g on Ubuntu 6 (Dapper)

My recent move to Ubuntu (Linux) has been a relatively painless affair. I was up and running in full development capacity in about a full day. In fact, the installation of Ubuntu was trivial and took a fraction of the time it takes to install Windows, even with the requisite updating of installed packages. I would highly recommend Ubuntu to anyone new to Linux, though I also have friends who use Fedora (4) and Suse.

So first things first, get a copy of Ubuntu, install it, and then update the packages as the OS tells you to do. Once you have a fresh OS, we will install Ruby and friends from the command line using apt-get (though you could probably just as soon use the Synaptic Package Manager GUI).

Install Ruby & Friends

Installing Ruby, Rails, and RubyGems is a relatively straight forward affair and can be done with apt-get commands. The following was taken from this tutorial and may be redundant but is included here for completeness. There is also a nice thread on this on TxD. So lets get to it.

Install the GCC compilers and developer tools.

$ sudo apt-get install build-essential

Now we’ll install Ruby and friends. In this command, I am including version numbers which may not be necessary (see this thread).

$ sudo apt-get install ruby1.8-dev ruby1.8 ri1.8 rdoc1.8 irb1.8 libreadline-ruby1.8 libruby1.8

Next we need to make some symlinks for basic Ruby commands (assuming that you installed using the method above).

$ sudo ln -s /usr/bin/ruby1.8 /usr/local/bin/ruby
$ sudo ln -s /usr/bin/ri1.8 /usr/local/bin/ri
$ sudo ln -s /usr/bin/rdoc1.8 /usr/local/bin/rdoc
$ sudo ln -s /usr/bin/irb1.8 /usr/local/bin/irb

Install RubyGems

$ wget http://rubyforge.org/frs/download.php/11289/rubygems-0.9.0.tgz
$ tar xvzf rubygems*
$ cd rubygems*
$ ruby setup.rb

Now you are all set to install Rails and Mongrel (which I adore for use as a development server).

$ sudo gem install rails
$ sudo gem install mongrel

Now that we have Ruby and Rails installed, let's take a look at getting an Oracle client on our fresh Ubuntu installation.

Oracle Clients for Ubuntu

Information regarding an appropriate Oracle client for use with 10g databases is somewhat scant, especially with regards to Rails. But read on, an Oracle client that works with Rails is available for Ubuntu from the package manager!

In order to get Rails to talk to an Oracle database, you must have two things installed. 1) You must install an Oracle client and 2) You must install the Ruby OCI8 driver. It seems that the OCI8 driver piggybacks on top of the functionality of the Oracle client - at least on Linuxm, but the assumption is that it functions the same on Windows.

Among the clients apparently able to connect to a 10g database are the Oracle 10g client (full installation), Oracle Instant Client, and to my suprise (and my DBA's), the Oracle Express Edition (XE) Client. The installation that I was able to get working was using the Express Edition, but these instructions should also work with the full client install (though that seems to be an extremely complicated option at the present moment). I'm afraid you are on your own with the Instant Client, though it should not be that had once you understand what is involved.

While you can download the .deb package directly from Oracle, for Ubuntu, I recommend using the Synaptic Package Manager included in the Ubuntu installation to get the Oracle packages. The first thing you will need to do is add the repository to the file /etc/apt/sources.list. Simply add the following line to the bottom of the file and save it.

deb http://oss.oracle.com/debian unstable main non-free

The package "oracle-xe-client" should now appear in the package listing. Mark it for installation and apply the changes. This should install the XE client. In my experience, this was placed in /usr/lib/oracle/. This path will be important for environment variables.

Setting Environment Variables

Now that you have the Oracle XE client successfully installed, you need to make sure your environment variables are set so that the Ruby OCI8 install scripts can find the necessary files. I had problems getting the local ~/.bash_profile file to load at all on Ubuntu, and it seems this is not unusual. I have been too lazy to track down the cause of this or its solution, so I modified the /etc/profile instead (you must be root user). So these are the variables that you should set:

export ORACLE_HOME=/usr/lib/oracle/xe/app/oracle/product/10.2.0/client
export TNS_ADMIN=$ORACLE_HOME
export PATH=$PATH:$ORACLE_HOME/bin:$PATH
export NLS_LANG=$ORACLE_HOME/bin/nls_lang.sh
export LD_LIBRARY_PATH=$ORACLE_HOME/lib
export SQL_PATH=/usr/lib/oracle/xe/app/oracle/product/10.2.0/lib

Another thing to note about using Oracle is that you must have a file called "tnsnames.ora" somewhere it can be found ($ORACLE_HOME). Chances are if you are reading this, you are talking to a DBA who has this file for you. Mine had one for me. This file tells your client where the databases are.

Install Ruby OCI8

Get your copy of Ruby OCI8, decompress it, and read the README. Follow the instructions for the "Full Client Install". There are only 3 steps and it basically boils down to doing a make; make install;.

While this sounds trivial, it is definitely not. On Ubuntu this is the most tedious part of the entire process. Oracle is a monster. There are dozens of things that need to be in place before the OCI8 driver will complile correctly (see the previous section), including environment variables and above all, a complete installation of the client. I mention this because while trying to install the Ruby OCI 8 driver on Red Hat with a partial client install (I dont know why it was like this... "enterprise") I got nothing but errors. So make sure that you have the development files that are included with the full install (like oci.h!).

When you finish, its worth checking the installation by firing up the irb and typing:

> require "oci8"
=> true

If you get "false" as a response, something has gone wrong in the installation and you should try again.

Configure Rails

Now all thats left to do is to configure Rails. To use Oracle from within Rails, you should have your "database.yml" file setup correctly. My file looks something like this:

development:
  adapter: oci
  host: hostname
  username: username
  password: password

Conclusion

This post is assuredly incomplete. For the moment, this is intended to document my process of installing Ubuntu and using Rails with an Oracle database from scratch. If you try this as well, please post a comment or two.

Next time I will post the long promised lib file for executing Oracle stored procedures in Rails.