# Quick Start
The following is a quick summary for building Rubinius. It assumes that you
already have required libraries installed. For a more complete guide, see the
next section.
1. Install [ruby 1.8](http://www.ruby-lang.org/en/downloads/)
1. Install [RubyGems](http://rubyforge.org/projects/rubygems)
1. Install Git
1. Clone rubinius: <tt>git clone git://github.com/evanphx/rubinius.git</tt>
1. cd to your rubinius checkout
1. `./configure`
1. `rake`
1. `bin/rbx -v`
# Getting Started
If you are having trouble getting or building Rubinius, the #rubinius IRC
channel on irc://irc.freenode.net can help. You can also ask on the [mailing
list](http://groups.google.com/group/rubinius-dev).
## Installing Required Libraries
There are a few things that you need in order to be able to build and run
Rubinius. Once you have installed the general requirements, install the Gems
needed and then any platform-specific requirements.
### General requirements
* [GCC 4.x (both g++ and gcc)](http://gcc.gnu.org/)
* [GNU Bison](http://www.gnu.org/software/bison/)
* [Ruby version >= 1.8.4 (the Ruby language)](http://www.ruby-lang.org/)
* [RubyGems (Ruby package manager)](http://www.rubygems.org/)
* [Git (source control used by rubinius)](http://git.or.cz/)
* [zlib compression library](http://www.zlib.net/)
Most systems already use GNU Make as their default, but for those using a BSD
Make:
* [gmake (GNU Make)](http://savannah.gnu.org/projects/make/
Each package may have requirements of its own, of course.
If you want to avoid overriding your existing environment, you may want to
install everything under its own prefix (such as /usr/local) and to name
programs so they don't collide with your existing installation (such as naming
gmake 'gmake'). You can then adjust your PATH environment variable as needed
for rubinius development.
### Requirements through RubyGems
* rake
Rake may be obtained with the <tt>gem install</tt> command. See <tt>gem
help</tt> and http://www.rubygems.org for more information.
### System-dependent requirements
#### OS X
In order to view backtrace information in the case of
a crash, you need to have:
* XCode + Tools/Utilities
Then, to enable "developer mode" for crash reporting,
the program to use is usually located at:
/Developer/Applications/Utilities/CrashReporterPrefs.app
#### Debian/Ubuntu family systems
For the build to succeed you will need these packages:
* ruby-dev (or ruby1.8-dev)
* libreadline5-dev
* zlib1g-dev
* libssl-dev
## Getting Rubinius
You need to clone the Rubinius source from the Github repository:
git clone git://github.com/evanphx/rubinius.git
For more information on Rubinius' best practices for git, see
[Using Git](/using_git.html)
## Compiling Rubinius
First, we need to configure rubinius for your system.
If you want to include LLVM for the JIT, you have a couple of choices.
Easiest is to use a prebuilt LLVM if there is one available for your
system. To try this, run:
./configure --update-prebuilt
If you don't get an error, you're ready to go. If not, configure will
try to use an installed version of LLVM by running the 'llvm-config'
command. Rubinius require LLVM version 2.6 or higher. If an installed
version of LLVM is not available, configure will
automatically checkout LLVM from svn and build it for you.
Now, if you wanna go ahead and use LLVM, run:
./configure --enable-llvm
Or if you wanna do without it, run:
./configure
The C++ VM is compiled using Rake. Typically, it will be as simple as:
rake
OR
rake build
If you plan on doing development work, or otherwise need debug access,
use the +debug+ subtask:
rake build:debug
## Running VM Tests
Build and run the tests:
rake vm:test
To run only one test suite, use:
rake vm:test[SomeClass]
If you want to run a single test suite under gdb, use:
SUITE="SomeClass" gdb vm/test/runner
## Running the Specs
Rubinius includes a stable copy of the RubySpecs that is tagged so that a
clean set (i.e. passing 100%) of specs can be run as part of the continuous
integration (CI) process. To run the CI specs:
rake spec
OR
bin/mspec ci
To run the most current version of RubySpec:
rake rubyspec:update
bin/mspec spec/ruby
To run a particular spec file, for example, the Array specs:
bin/mspec spec/ruby/1.8/core/array
## Installing Rubinius
NOTE: You do NOT need to install Rubinius. Rubinius will run perfectly
from the source directory. If you just want to take Rubinius for a test
run, build in the source directory and either run ./bin/rbx directly or
create a symlink to that file somewhere in your PATH directories.
Now, assuming you really want to install Rubinius...
You can configure Rubinius to install into a single directory, or install
the executable, the core and standard libraries, gems, etc. in multiple
directories.
The simplest is the single-directory install. Run
./configure [--enable-llvm] --prefix=/some/path/to/base/dir
rake install
The rake install task depends on the build task, so rake install will
build and then install.
See `./configure --help` for options for setting the other directories.
NOTE: When Rubinius is built, the path to the directory in which it finds
the core and standard library files is compiled into the exectuable. You
should not move the install (or development) directory after you build
Rubinius. If you do, however, you should get a friendly message about how
to run Rubinius by setting the RBX_RUNTIME and RBX_LIB environment variables.
## Running Rubinius
Once compiled, you can verify the VM works:
bin/rbx -v
Rubinius generally works like Ruby from the command-line. For example:
bin/rbx -e 'puts "Hello!"'
To run a ruby file named 'code.rb':
bin/rbx code.rb
To use the interactive prompt (similar to Ruby's IRB):
bin/rbx
## Rubinius Configuration
Rubinius provides a -X command line switch for manipulating the internal
configuration options. For example,
-Xrbx.jit enables the jit if it's supported by the platform
-Xrbx.dyni enables the dynamic interpreter if it's supported
## Troubleshooting
See [Common Problems](/common_problems.html) or ask questions in the #rubinius
IRC channel on irc.freenode.net.
) is private.
