evanphx / rubinius

Rubinius, the Ruby VM

rubinius / doc / getting_started.txt
raw normal view history
9a496b9a » brixen 2008-11-21 Migrated docs from Lighthou... 1 # Quick Start
2
3 The following is a quick summary for building Rubinius. It assumes that you
4 already have required libraries installed. For a more complete guide, see the
5 next section.
6
7 1. Install [ruby 1.8](http://www.ruby-lang.org/en/downloads/)
773527dc » brixen 2008-11-28 Added docs about (un)instal... 8 1. Install [RubyGems](http://rubyforge.org/projects/rubygems)
9 1. Install Git
10 1. Clone rubinius: <tt>git clone git://github.com/evanphx/rubinius.git</tt>
11 1. cd to your rubinius checkout
11923e8e » cypher 2009-10-28 You have to run ./configure... 12 1. `./configure`
773527dc » brixen 2008-11-28 Added docs about (un)instal... 13 1. `rake`
14 1. `bin/rbx -v`
9a496b9a » brixen 2008-11-21 Migrated docs from Lighthou... 15
16
17 # Getting Started
18
19 If you are having trouble getting or building Rubinius, the #rubinius IRC
20 channel on irc://irc.freenode.net can help. You can also ask on the [mailing
21 list](http://groups.google.com/group/rubinius-dev).
22
23
24 ## Installing Required Libraries
25
26 There are a few things that you need in order to be able to build and run
27 Rubinius. Once you have installed the general requirements, install the Gems
28 needed and then any platform-specific requirements.
29
30
31 ### General requirements
32
33 * [GCC 4.x (both g++ and gcc)](http://gcc.gnu.org/)
34 * [GNU Bison](http://www.gnu.org/software/bison/)
35 * [Ruby version >= 1.8.4 (the Ruby language)](http://www.ruby-lang.org/)
36 * [RubyGems (Ruby package manager)](http://www.rubygems.org/)
37 * [Git (source control used by rubinius)](http://git.or.cz/)
38 * [zlib compression library](http://www.zlib.net/)
39
40 Most systems already use GNU Make as their default, but for those using a BSD
41 Make:
42
43 * [gmake (GNU Make)](http://savannah.gnu.org/projects/make/
44
45 Each package may have requirements of its own, of course.
46
47 If you want to avoid overriding your existing environment, you may want to
48 install everything under its own prefix (such as /usr/local) and to name
49 programs so they don't collide with your existing installation (such as naming
50 gmake 'gmake'). You can then adjust your PATH environment variable as needed
51 for rubinius development.
52
53
54 ### Requirements through RubyGems
55
56 * rake
57
58 Rake may be obtained with the <tt>gem install</tt> command. See <tt>gem
59 help</tt> and http://www.rubygems.org for more information.
60
61 ### System-dependent requirements
62
63
13e9ab62 » rue 2009-12-11 Added note about "developer... 64 #### OS X
65
66 In order to view backtrace information in the case of
67 a crash, you need to have:
68
69 * XCode + Tools/Utilities
70
71 Then, to enable "developer mode" for crash reporting,
72 the program to use is usually located at:
73
74 /Developer/Applications/Utilities/CrashReporterPrefs.app
75
76
9a496b9a » brixen 2008-11-21 Migrated docs from Lighthou... 77 #### Debian/Ubuntu family systems
78
79 For the build to succeed you will need these packages:
80
81 * ruby-dev (or ruby1.8-dev)
82 * libreadline5-dev
83 * zlib1g-dev
bc7320e6 » mernen 2009-06-28 Added libssl-dev to Debian/... 84 * libssl-dev
9a496b9a » brixen 2008-11-21 Migrated docs from Lighthou... 85
86
87 ## Getting Rubinius
88
89 You need to clone the Rubinius source from the Github repository:
90
91 git clone git://github.com/evanphx/rubinius.git
92
93 For more information on Rubinius' best practices for git, see
94 [Using Git](/using_git.html)
95
96
97 ## Compiling Rubinius
98
1f045bd5 » evanphx 2009-09-30 Update getting_started.txt ... 99 First, we need to configure rubinius for your system.
100
101 If you want to include LLVM for the JIT, you have a couple of choices.
102 Easiest is to use a prebuilt LLVM if there is one available for your
103 system. To try this, run:
104
105 ./configure --update-prebuilt
106
107 If you don't get an error, you're ready to go. If not, configure will
108 try to use an installed version of LLVM by running the 'llvm-config'
109 command. Rubinius require LLVM version 2.6 or higher. If an installed
110 version of LLVM is not available, configure will
111 automatically checkout LLVM from svn and build it for you.
112
113 Now, if you wanna go ahead and use LLVM, run:
114
115 ./configure --enable-llvm
116
117 Or if you wanna do without it, run:
118
119 ./configure
120
9a496b9a » brixen 2008-11-21 Migrated docs from Lighthou... 121 The C++ VM is compiled using Rake. Typically, it will be as simple as:
122
773527dc » brixen 2008-11-28 Added docs about (un)instal... 123 rake
124 OR
125 rake build
9a496b9a » brixen 2008-11-21 Migrated docs from Lighthou... 126
127 If you plan on doing development work, or otherwise need debug access,
128 use the +debug+ subtask:
129
773527dc » brixen 2008-11-28 Added docs about (un)instal... 130 rake build:debug
9a496b9a » brixen 2008-11-21 Migrated docs from Lighthou... 131
132
b08b45f0 » brixen 2008-12-09 Migrated README-DEVELOPERS ... 133 ## Running VM Tests
134
135 Build and run the tests:
136
137 rake vm:test
138
139 To run only one test suite, use:
140
141 rake vm:test[SomeClass]
142
143 If you want to run a single test suite under gdb, use:
144
145 SUITE="SomeClass" gdb vm/test/runner
146
147
148 ## Running the Specs
149
150 Rubinius includes a stable copy of the RubySpecs that is tagged so that a
151 clean set (i.e. passing 100%) of specs can be run as part of the continuous
152 integration (CI) process. To run the CI specs:
153
154 rake spec
155
156 OR
157
158 bin/mspec ci
159
160 To run the most current version of RubySpec:
161
162 rake rubyspec:update
163 bin/mspec spec/ruby
164
165 To run a particular spec file, for example, the Array specs:
166
167 bin/mspec spec/ruby/1.8/core/array
168
169
9a496b9a » brixen 2008-11-21 Migrated docs from Lighthou... 170 ## Installing Rubinius
171
17ba3573 » brixen 2009-11-25 Updated install instructions. 172 NOTE: You do NOT need to install Rubinius. Rubinius will run perfectly
173 from the source directory. If you just want to take Rubinius for a test
174 run, build in the source directory and either run ./bin/rbx directly or
175 create a symlink to that file somewhere in your PATH directories.
6bada3e5 » evanphx 2009-07-13 Remove the runtime stack po... 176
17ba3573 » brixen 2009-11-25 Updated install instructions. 177 Now, assuming you really want to install Rubinius...
9a496b9a » brixen 2008-11-21 Migrated docs from Lighthou... 178
17ba3573 » brixen 2009-11-25 Updated install instructions. 179 You can configure Rubinius to install into a single directory, or install
180 the executable, the core and standard libraries, gems, etc. in multiple
181 directories.
182
183 The simplest is the single-directory install. Run
184
185 ./configure [--enable-llvm] --prefix=/some/path/to/base/dir
186 rake install
187
188 The rake install task depends on the build task, so rake install will
189 build and then install.
190
191 See `./configure --help` for options for setting the other directories.
192
193 NOTE: When Rubinius is built, the path to the directory in which it finds
194 the core and standard library files is compiled into the exectuable. You
195 should not move the install (or development) directory after you build
196 Rubinius. If you do, however, you should get a friendly message about how
197 to run Rubinius by setting the RBX_RUNTIME and RBX_LIB environment variables.
9a496b9a » brixen 2008-11-21 Migrated docs from Lighthou... 198
199 ## Running Rubinius
200
201 Once compiled, you can verify the VM works:
202
773527dc » brixen 2008-11-28 Added docs about (un)instal... 203 bin/rbx -v
9a496b9a » brixen 2008-11-21 Migrated docs from Lighthou... 204
205 Rubinius generally works like Ruby from the command-line. For example:
206
773527dc » brixen 2008-11-28 Added docs about (un)instal... 207 bin/rbx -e 'puts "Hello!"'
9a496b9a » brixen 2008-11-21 Migrated docs from Lighthou... 208
b08b45f0 » brixen 2008-12-09 Migrated README-DEVELOPERS ... 209 To run a ruby file named 'code.rb':
210
211 bin/rbx code.rb
212
fb6b228e » sandal 2009-05-22 Add note about interactive ... 213 To use the interactive prompt (similar to Ruby's IRB):
214
215 bin/rbx
9a496b9a » brixen 2008-11-21 Migrated docs from Lighthou... 216
1bcfb537 » brixen 2009-01-08 Doc -X switches and coding ... 217 ## Rubinius Configuration
218
219 Rubinius provides a -X command line switch for manipulating the internal
220 configuration options. For example,
221
222 -Xrbx.jit enables the jit if it's supported by the platform
223 -Xrbx.dyni enables the dynamic interpreter if it's supported
224
225
9a496b9a » brixen 2008-11-21 Migrated docs from Lighthou... 226 ## Troubleshooting
227
228 See [Common Problems](/common_problems.html) or ask questions in the #rubinius
229 IRC channel on irc.freenode.net.