== Compilation Process

Compilation of Ruby source code to Rubinius machine byte code proceeds through
the following steps:

* Source code is parsed into {S-expressions
  (sexps)}[http://en.wikipedia.org/wiki/S-expressions] representing the
  structure of the Ruby code. The grammar of a Ruby program is currently
  defined in +grammar.y+ under shotgun/lib, which was copied from MRI.
* Sexps are compiled into a string representation of Rubinius assembly language
  by +compiler.rb+, which is found under lib/compiler/bytecode.
* The generalised assembly language is translated into specific lower-level
  machine op-codes by +assembler.rb+. Thus, instructions such as +push+ are
  converted to specific push instructions depending on the type of item being
  pushed, and literal references are converted to indexes into the literals
  tuples.
* The low-level assembly is encoded as byte-codes that can actually be run by
  shotgun by +encoder.rb+.

=== Machine OpCodes

The Rubinius virtual machine op codes are listed in the frame to the left.
Click on an item to see documentation about that op code.

==== Notes on Source Code

The documentation for each op code includes an extract of the Shotgun source
code that implements that op. This is usually sufficient to determine how the
op code functions, but the following additional pointers will aid in
understanding:

* The functions +next_int+ and +next_literal+ will be seen in many op code's
  source listings. These functions are used to retrieve the next argument that
  was specified to the op codes that take one or two arguments. +next_int+ sets
  the variable +_int+ to the value of the next argument, and is used when the
  argument value is an integer. +next_literal+ is used to retrieve the index of
  the specified literal.
* All opcodes that require arguments take only integers as the values of those
  args. However, often in the compiler, the arguments that are specified are
  literal values, such as the name of a local variable, an object, class, etc.
  Following the compilation step, these literals are gathered into a single
  literals tuple within the method or block context, and the literal references
  are replaced with the index of the literal within this literals tuple.

=== Documentation Completeness

Some opcodes have only partial documentation.  Feel free to update undocumented
opcodes by adding RDoc in shotgun/lib/instructions.rb.  Be sure to follow the
same order as existing RDoc.  Run `rake doc:vm:html` to regenerate the HTML.

