What We at Least Imagine to be Frequently Asked Questions

Getting started

What do I read before even touching the FAQ?

• Start with the installation documentation and follow the path from there.

General FAQs

Can it run Rails?

• Yes, it generally runs some rails apps, for instance, the AWDWR demo app. However, there is likely a number of issues that still need to be resolved. You can help out by trying to run your Rails application and report issues you encounter.

Can it run rake?

• Yes. Though, again, there may still be issues.

What other things run?

• It is self-hosting; i.e., it runs itself.
• The spec suite which as of this time has over 22,700 "examples," of the Ruby language and libraries roughly the equivalent of assertions.
• RubyGems, another big milestone.
• A substantial part of the Stdlib.
• Slightly modified Merb.
• Countless other libraries.

OK, so why still issues with Rails?

• Rails (ab)uses every single part of the Ruby language from the mundane to the arcane. Unless specifically working from the perspective of getting Rails to work (probably using quite a few temporary kludges along the way), basically running Rails means you are done. This is obviously not literally true, but from an implementation completeness standpoint fairly close to it.

Who is using rubinius now?

• Rubinius is not used in production anywhere, so largely the userbase are those either actively developing Rubinius, studying it or possibly using it as a pre-emptive test for their own (or favourite) libraries.

What platforms should rubinius run on?

1. Generally any UNIXy/POSIXy platform although some configuration may be necessary.
2. The likeliest problem would probably arise from the FFI layer which must generate machine code at runtime. Rubinius uses libffi which does support a lot of platforms.

Which platforms has Rubinius been tested on?

• Various x86 and x86_64 systems, both in 32-bit and 64-bit mode. The main development platforms--and thereby the most stable--are x86 Mac OS X (Leopard usually), x86[_64] GNU/Linux (anything from Arch to Gentoo to Ubuntu) and x86[_64] *BSD (mainly FreeBSD.)

Any platforms or operating systems I should try if I enjoy such tasks (and have access to)?

• Intel's IA64 (Itanium) might be a good one (all new Intels use EM64-T which is essentially x86_64.)
• UltraSPARC, other Sun hardware.
• MIPS, RISC, ARM architectures or a mainframe AS/360, the more obscure the more fun, right?

Will it run on Windows?

• No, but it will eventually. All "official" development so far has been targeting UNIXy systems and that remains the intention for the initial release. A few individuals have experimented building and identifying problems on Windows platforms. If you are interested in this area, you are most welcome to explore. We will help however we can.

What about Cygwin or MSys?

• In theory, both should allow building and running Rubinius just fine. Some folks have reported successful builds but there are still runtime issues that we have not addressed (see previous.)

Can I complain when rubinius crashes trying to run my favorite application?

1. You can quietly complain to yourself while you fix it/Rubinius to get it to work.
2. Let us know what you tried, how it failed, any ideas you may have. Try to isolate the failing part and write a spec for it!

Can I complain because Rubinius has failing specs?

1. No, we'd prefer you help to make the specs not fail.
   
2. We have failing specs checked in so we have goals to work towards.

Can I complain when the CI-Specs fail?

• Absolutely, let us know ASAP.

Getting involved

What can I do to help?

1. Run the specs and help write code in kernel/ to make the specs pass.
   
2. If you're up on your C skills, ask in the IRC channel about helping work on the VM.
   
3. Tell your friends about the project, get the buzz going.
   
4. Provide moral support for other developers in any form.
   

I want to get involved! What is a good place to start?

1. A fun way to get in is to pick an application or library that you have written--or one that you frequently use--and try to run it. If it works, great! If, as is still quite possible if not even likely, it does not work, you have a good spot to start from. Try to isolate the source of

the failure and write a spec for it.

1. The other popular way is to just either run the specs and see what still fails, or to identify and add missing specs.

Either way, once you have a spec to work on, you can see if you can identify where the implementation is wrong and possibly fix it! If it turns out the problem is too tricky for you to solve, you should just move onto a different issue and maybe return to the original later (ed. note: Trust me, it still happens to us all continuously. If you do not know X, someone else will and if someone else does not know Y, you might. Teamwork and communication are paramount! --rue.)

Can I ask for help?

1. Yes, absolutely. Anything that we can do to help, we will.
2. Make sure to do your own research too, if possible! We will certainly accept and appreciate simple bug reports, but it is extremely helpful if you can actively help us identify (and maybe even fix) the problem.

It is all so confusing! There is the VM, the kernel, the libraries, the specs, polymorphic caches, pneumatic stegosauruses.. how can I possibly understand all of this?

• You do not need to know or understand everything immediately. You should just have a great time exploring the codebase, not feel like it is some kind of an exam cram. In fact, it is highly recommended that you start off focusing on a narrow area and work your way to how it fits in the big picture. While Rubinius is actually an exceptionally straightforward and elegant VM and language implementation (MatzRuby 1.9, for example, is two orders of magnitude larger), there is still a lot of information to discover and absorb. Ask questions!

I don't like the style of the specs or the kernel or the vm, can I clean it up and you'll accept the patch?

1. No.
   
2. The implementation is pretty straightforward and idiomatic Ruby (or C++.) However, out of necessity many parts of the kernel are implemented using simple constructs and could perhaps be expressed more succintly. There is almost always a good reason for this, ranging from compiler support to maybe not having a certain method or class available yet. If it really bothers you, ask us first, we'll discuss it.

Will you reject my patch if my style is "more Rubyesque"?

• If the patch works (e.g. does not use features that cannot be guaranteed to exist in all cases), it will not be rejected based on a stylistic qualm. The code is most welcome. But "clever" or obscure code is not.

Running

How do I run it?

• Running ./shotgun/rubinius without any other arguments will drop you in irb (the same irb that MatzRuby uses--but with all of Rubinius' features available to you!)

How do I run script.rb?

• ./shotgun/rubinius script.rb

Does -e work?

• Yes.

What about -r or -I or -p or ...?

• Most of these work as expected, some do not (notably the -p and -n style processing.) Type ./shotgun/rubinius -h for up-to-date information.

I saw ./shotgun/rubinius compile somefile.rb somewhere. What does that mean?

• Rubinius implements what could be thought of as subcommands in this manner. For example, what happens when the above line is entered is that Rubinius starts scanning its arguments normally (you could, in fact, stick a -r before the compile for example.) If it finds a non-option argument (i.e., something not starting with @-@ or --), it first tries to check whether it is an existing file. If so, it is run normally. However, as in the case above, if the argument does not match to a file and it does not have the .rb extension, the name is checked for in the ./lib/bin directory. Various programs or subcommands live here. As an example, compile is a program that knows how to compile a .rb file into a .rbc file--or to compile an extension into a shared object that can then be loaded. Other examples are @describe@, which shows information about the parse tree or Sexp of a file and gem which, quite obviously, is the RubyGems command. Many of these are only used internally, but take a look and see what is available.

Making changes

I've changed something in ./kernel (the Core libraries), how do I make the change actually become effective?

• Run @rake build@; the task will recompile any changed files and incorporate them into the "runtime." Once this completes, you can access the new or changed functionality everywhere.

Wait, should I be changing this stuff? What if my change breaks the compiler? Then I cannot even fix it!

• Not to worry! The compiler actually uses what are known as "Stables": a known-good set of Core libraries that are specially built for it. The Stables can actually lag behind the ./kernel directory quite a bit because they are only updated when absolutely necessary (this is not something you will run into when making your first change.) So let us say your change accidentally breaks Array; you will see this very soon when you run the specs! All you need to do is undo your change whether manually, using your editor undo or by using git to checkout the original versions, and after that you can just do rake build again: it just recompiles a "new" version of the libraries using the old-new bug-free implementation and you are good to go.
• Even if we did use the "edge" Core in the compiler so that you could not recompile your changes back out, you could use git to restore those files instead. git has the capacity to salvage almost any kind of an error and return to where you started from.