== Rubinius Compiled (.rbc) Files

With Rubinius, Ruby source files (.rb files) are compiled into platform
independent .rbc files, which contain the byte codes needed to execute the
source Ruby code on the Rubinius virtual machine (see shotgun[shotgun.html]
for a description of the Rubinius VM).

Since Rubinius is available on many platforms, and .rbc files are platform
independent, an .rbc file compiled on one platform will execute under Rubinius
on another platform without modification.

=== File Layout

Compiled .rbc files are written in big-endian format, i.e. for a 4-byte
integer, the high-order (big end) byte appears first, and the low-order (little
end) byte appears last. Thus, the value 0x10fe4d05 would appear similar to how
it is written, as 10 fe 4d 05.

An .rbc file consists of:
* a 4-byte header containing the magic constant 'RBIX' (older versions used
  'RBIS', and omitted a version field)
* a 4-byte field specifying the version number of the .rbc file (currently 5)
* a variable number of number of marshaled objects

Objects are marshaled using a scheme whereby each object type is identified by
a single-byte tag, followed by 0 or more bytes containing the object data. The
following table specifies the values and formats for each tag:

[Fixnum (i)]
  * 1 byte indicating the sign ('n' for negative, 'p' for positive)
  * 4 bytes specifying the integer value
[String (s)]
  * 4 bytes that specify the string size
  * the characters (single bytes) that make up the string
[Symbol (x)]
  * 4 bytes that specify the symbol string size
  * the characters (single byte) that make up the symbol string
[Tuple (p)]
  * 4 bytes that specify the tuple size, i.e. number of elements in the tuple
  * the marshaled objects that represent each value in the tuple
[ByteArray (b)]
  * 4 bytes that specify the size of the byte array
  * the raw bytes of the byte array
[InstructionSequence (I)]
  * a single byte character that indicates whether the instruction sequence is
    in big-endian or little-endian format; big-endian is indicated by the value
    'b', while little-endian is indicated by an 'l'. Currently, only big-endian
    format is used for marshaling instruction sequences.
  * 4 bytes that specify the size of the instruction sequence
  * the raw bytes that make up the instruction sequence.
  
  When unmarshaling an instruction sequence, the instruction sequence is
  flipped if necessary to convert it to the endian-ness of the host platform.
[CompiledMethod (M)]
  * 4 bytes that specify the version number of the CompiledMethod that has been
    marshaled. As of this writing, CompiledMethod has 17 fields, but only the
    first 16 are marshaled (the 17th field contains the translated instruction
    sequence, which is not persisted).
  * the marshaled value of each field, where the fields are:
    1. <tt>\_\_ivars__</tt>
    1. primitive
    1. required
    1. serial
    1. bytecodes
    1. name
    1. file
    1. locals
    1. literals
    1. arguments
    1. scope
    1. exceptions
    1. lines
    1. path
    1. cache
    1. bonus
[CompiledMethod (m)]
  <b>Note: This tag has been deprecated, in favour of 'M' (see above).</b> The
  tag is followed by:
  
  * 4 bytes that specify the number of fields in the compiled method (presently
    16)
  * the marshaled value of each field, where the fields are:
    1. <tt>\_\_ivars__</tt>
    1. primitive
    1. required
    1. serial
    1. bytecodes
    1. name
    1. file
    1. locals
    1. literals
    1. arguments
    1. scope
    1. exceptions
    1. lines
    1. path
    1. cache
    1. bonus
[Bignum (B)]
  * 4 bytes that specify the size of the string representation of the Bignum
  * the string representation of the Bignum
  * a 0 byte to create a null-terminated string.
[Float (d)]
  * 4 bytes that specify the size of the string representation of the Float
  * the string representation of the Float
  * a 0 byte to create a null-terminated string.
[Object (r)]
  * 4 bytes that specify the number of fields in the object
  * the marshaled value of each field.
[NilClass (n)]
  * "nil"
[TrueClass (t)]
  * "true"
[FalseClass (f)]
  * "false"

=== Disassembler

A disassembler is provided in <tt>compiler/bytecode/disassembler.rb</tt>, and
it can be used to examine the contents of an .rbc file.

