# Installing RhoConnect

This section discusses how to install the development environment for RhoConnect. For those who have developed a RhoConnect application, and now wish to deploy that RhoConnect application on a server, refer to the instructions for deploying a RhoConnect application, such as [preparing a RhoConnect app for production](/rhoconnect/preparing-production) and [deploying a RhoConnect application](/rhoconnect/deploying).

## Installing RhoConnect with RhoStudio

The most common way to install RhoConnect on a Windows or Macintosh platform is to install RhoMobile Suite. The RhoMobile Suite installer installs Rho products, such as Rhodes, RhoConnect, RhoElements, and RhoStudio. RhoStudio is an Eclipse installation that facilitates development of native smartphone applications.

[Click here for the RhoMobile Suite installation instructions](/rhomobile-install).

NOTE: The rest of this chapter consists of instructions for installing RhoConnect from the command line, without using the RhoMobile Suite installer. You do not need to perform those instructions if you installed using the RhoMobile Suite installer.

## Installing RhoConnect from the Command Line

To install RhoConnect on Linux, and to install RhoConnect on Windows or Mac OS using the command line (this does not install RhoStudio), you need to install the Rhodes gem. Download and install:

1. [Ruby v1.9.3](http://www.ruby-lang.org/en/downloads/).

	* On Windows, [RubyInstaller](http://rubyinstaller.org) is a convenient way to install Ruby; you should check "Add Ruby executables to your PATH" and "Associate .rb and .rbw files with this Ruby installation".

	* On Macintosh, Ruby is already installed, but this version is outdated and isn't compatible with RhoStudio: install [Ruby Version Manager](https://rvm.io//) (RVM) and then use RVM to install Ruby version 1.9.3.

2. Ruby Web Server - We tested with [thin](http://code.macournoyer.com/thin/), and [passenger](http://www.modrails.com/). WEBrick, the web server that ships with ruby, is known to cause issues with HTTP headers/cookies and is ***not*** recommended.

3. [Redis](http://redis.io/) - RhoConnect includes a simple [rhoconnect task](/rhoconnect/command-line#rhoconnect-cli-rhoconnect-v32) `rhoconnect redis-install` to install redis, covered in the [Rhoconnect CLI section](/rhoconnect/command-line#rhoconnect-cli-rhoconnect-v32). Alternatively, you can [install redis directly](http://redis.io/download).

4. Install the RhoConnect Gem.

Run this command to install the RhoConnect Gem.

	:::term
	$ gem install rhoconnect

NOTE: If you get any `no such file to load -- something` messages while running the rhoconnect or rhodes commands, this can usually be resolved by putting "sudo" in front of the command, as in `sudo gem install something`.

NOTE: Windows doesn't come with the necessary build tools to install gems ('make', for example). There are various ways to get these tools, but the GnuWin32 project at http://gnuwin32.sourceforge.net/ provides the tools, and can be conveniently installed via the GetGnuWin32 installer at http://sourceforge.net/projects/getgnuwin32/files/. You should follow the GetGnuWin32 instructions carefully.

## Setting the Location of the RhoStudio Workspace Directory

When you start RhoStudio, you can set the location of the workspace directory. The path to the workspace directory should not contain space symbols: if the path has spaces, a RhoConnect application created with RhoStudio will not work properly.

## Standalone Ruby Installation and Ruby Version Manager

Do not install Ruby as a standalone if you also use Ruby Version Manager (rvm) to install Ruby. If you need only one version of Ruby, you can install Ruby as a standalone. If you need more than one version of Ruby, you should uninstall standalone Ruby and then install Ruby with Ruby Version Manager. Mixed standalone Ruby and rvm-controlled Ruby installations can conflict and cause runtime issues in Rhodes applications.

## Migrating to OS X Mountain Lion from the command line

If you had a workable RhoConnect environment on Macintosh OS X Lion, then after you upgrade to Mountain Lion, you need to do some extra steps to restore your workable environment.

### Getting Xcode and Command Line Tools Installed

You can get Xcode from the Mac App Store. You’ll need at least version 4.4 of Xcode for it to work with OS X Mountain Lion. After the installation, open Xcode in your /Applications folder. Then go to Xcode -> Preferences -> Downloads tab and install the “Command Line Tools.”

### Installing Homebrew and GCC

If you need to install any Ruby that’s older than 1.9.3, such as 1.9.2, 1.8.7 or REE, you’ll need to install GCC 4.2. Apple does not ship the Command Line Tools with gcc-4.2 compiler anymore (you can check by running `which gcc-4.2`), so you need to install it via Homebrew by enabling [homebrew-dupes](https://github.com/Homebrew/homebrew-dupes) repository and installing GCC.

	:::term
	$ brew tap homebrew/dupes
	$ brew install apple-gcc42

Apple has removed X11 support from their operating system, but the X11 package is needed to
compile 1.8.7 or REE. You can get the X11 package from [XQuartz]( http://xquartz.macosforge.org/landing). By default, it installs in the /opt/X11 folder.

If you had Homebrew already installed, then you need only update it

	:::term
	$ brew update
	$ brew doctor

If the `brew doctor` command complains about the `/usr/local/bin` path, then edit the `/etc/paths` file to move `/usr/local/bin` line to the top of it.

### Updating RVM (Ruby Version Manager) with Ruby 1.9.3

Because the OS X Mountain Lion toolchain is changed, you should use Ruby Version Manager to reinstall existing Ruby 1.9.3.

	:::term
	$ rvm get stable
	$ rvm reinstall 1.9.3

### Installing legacy rubies

Run the following commands to install legacy rubies:

	:::term
	$ export CPPFLAGS=-I/opt/X11/include
	$ CC=/usr/local/bin/gcc-4.2 rvm reinstall 1.8.7
	$ CC=/usr/local/bin/gcc-4.2 rvm reinstall ree

## Upgrading an Existing Application

If you have an existing application, upgrading to the latest version of RhoConnect is simple.

Open the `Gemfile` of your application and find the rhoconnect line, it should look something like:

	:::ruby
	gem 'rhoconnect', '3.3.6'

Change this to the latest release version, which you can find on [rubygems.org](http://rubygems.org/gems/rhoconnect), for example if it is 3.4.0:

	:::ruby
	gem 'rhoconnect', '3.4.0'

Run the following command from the root application directory:

	:::term
	$ bundle install

Now update your application's RhoConnect dependency manifest:

	:::term
	$ rhoconnect update

## Upgrading previous versions to RhoConnect 3.4+

If you have an existing RhoConnect application using version < 3.4 and want to upgrade it to RhoConnect 3.4+, then
you need to update the `Gemfile` file to properly use the latest RhoConnect runtime dependencies.

First, follow the instructions described in the [previous section](/rhoconnect/install#upgrading-an-existing-application).

Next, make sure your `Gemfile` looks like the following example, replacing the version as necessary.
The `rhoconnect update` command will generate a reference `Gemfile.new` which you can use to replace your `Gemfile`:

	:::ruby
	source 'http://rubygems.org'

	gem 'rhoconnect', '<put correct version here>'
	gemfile_path = File.join(File.dirname(__FILE__), ".rcgemfile")

	begin
		eval(IO.read(gemfile_path))
	rescue Exception => e
		puts "ERROR: Couldn't read RhoConnect .rcgemfile"
		puts e.message
		exit 1
	end

	# DON'T FORGET to add your application specific gems after this line ...
	# ...

Finally, run `bundle install` to install any missing dependencies:

	:::term
	$ bundle install