* About CastOff
CastOff is a compiler for Ruby1.9.3.
CastOff compiles Ruby method (method written in Ruby) into C extension (method written in C)
CastOff can reduce Ruby virtual machine overhead, so by use of CastOff,
the performance of compilation target method can improve.

This README document introduce basic functionality of CastOff.
If you have any questions, comments, or suggestions please send email to [email protected],
or use http://github.com/soba1104/CastOff/issues.



* License
Same as the license of Ruby runtime.



* Installation
$gem install cast_off

Command line tool cast_off is available after installation.

Currently, CastOff supports Ruby1.9.3 only.
So, if you attempt to use CastOff, please install CastOff under Ruby1.9.3 runtime. 



* Attention
Currently, CastOff is alpha version. So, you must not use CastOff in critical mission.

** Incompatibility
-Constant redefinition
Currently, CastOff cannot handle constant re-definition.
So, you should not use CastOff to your program which re-defines constants.

-Continuation
CastOff causes problem about capture of continuation (callcc).
So, you should not use CastOff to your program which uses Continuation.

-Built-in functions related with Method and Proc
CastOff compiles Ruby method and proc into C extension.
So, built-in functions related with Method and Proc (such as Method#arity, Proc#arity)
return different values.

# example
class Foo
  def foo(a, b = :b, *c); end
end
f = Foo.new
puts (f.method(:foo).arity) # => -2
CastOff.compile(Foo, :foo)
puts (f.method(:foo).arity) # => -1


** Startup time
When you use CastOff, you pay following extra overhead.
So, you should not use CastOff to your program which takes very small execution time.

-1: Load time of CastOff
CastOff is almost written with Ruby, so load time of CastOff takes msec order time.

-2: Load time of compiled codes.
When CastOff loads compiled codes, CastOff uses Marshal.load many times.


** Compilation time
CastOff is almost written with Ruby, so compilation time is
in seconds(when CastOff compiles simple program) or in minutes(when CastOff compiles complex program).



* Usage
By use of command line tool cast_off, you can improve performance of your Ruby program easily.
If you want to improve performance of your Ruby program, you should execute following command repeatedly.

-----------------------------------------------------
$cast_off PathOfTargetProgram ArgumentsOfTargetProgram
-----------------------------------------------------

For example, when you want to improve performance of Ruby program "foo.rb"
(in this example, "foo.rb" recieves one argument "bar" or "baz"), you should execute following commands.

-----------------------------------------------------
$cast_off foo.rb bar
$cast_off foo.rb baz
-----------------------------------------------------

When you execute these commands, CastOff does followings to compile foo.rb and related libraries.

1: Executes "foo.rb" with argument "bar" to get profile information.
2: Compiles "foo.rb" and related libraries.
3: Executes "foo.rb" with argument "baz" to get and update profile information.
4: Compiles "foo.rb" and related libraries.

After CastOff finishes compilation, you can run target program with --run option.
In above example, you can run target program with compiled codes by use of following command.

$cast_off --run foo.rb bar


*** Command line arguments

cast_off [options] PathOfTargetProgram ArgumentsOfTargetProgram


*** Command line options
--run
Execute target program with compiled methods.

--clear
Clear profile information and delete compiled methods.
If you want to clear profile information and compiled methods of target name "foo",
you should execute following command.
$cast_off --clear --name=foo

--threshold=COUNT
Compile method which is executed more than COUNT.
Default value is 100.

--name=NAME
Name compiled methods NAME.
This name is used for search of compiled methods.
If you don't use this option, CastOff uses File.basename([programfile]) as name.

--verbose
Show compilation progress and internal information.

-h, --help
Show help.

--version
Show version number of CastOff.