RUBYC(1) BSD General Commands Manual RUBYC(1)

NAME

rubyc -- MacRuby Ahead-of-Time Compiler

SYNOPSIS

rubyc [options...] files...

DESCRIPTION

rubyc is a command-line interface to the MacRuby Ahead-of-Time (AOT) com-

piler. It allows static compilation of Ruby source code into machine code

objects, dynamic libraries or executables.

The Ahead-of-Time compilation process has two major advantages; the Ruby

code does not need to be parsed and compiled at runtime, which improves

the startup time of the program, and the original Ruby source code is no

longer available as is since it has been compiled down to machine code.

OPTIONS

The rubyc tool accepts the following command-line options:

-o file

Place the output into file. If this option is not given, rubyc will

try to determine a default output file name based on the object file

type that is being generated. For executables, the default is a.out.

For objects, the default is the original source file name with the

object type extension. For dynamic libraries, this option is manda-

tory.

-c Compile and assemble, but do not link. This option produces a Mach-O

object file (.o) for every Ruby source file passed to rubyc, using a

default file name which consists of the source file name with the .o

file extension. Such a file can later be passed to rubyc to create a

dynamic library or executable.

-C Compile, assemble and link a loadable object file. This option pro-

duces a Mach-O MacRuby loadable object bundle (.rbo) for every Ruby

source file passed to using a default file name which consists of

the source file name with the .rbo file extension. A MacRuby load-

able object is a Mach-O bundle compiled with a global constructor

that will evaluate the Ruby machine code once it's loaded by the

dynamic linker, at runtime, generally upon a Ruby #require state-

ment.

--static

Create a standalone, static executable. By default, executables cre-

ated by rubyc are dynamically linking against the MacRuby runtime.

This option will generate executables that are statically linking

against the MacRuby runtime, significantly increasing the binary

size but allowing its distribution on environments where MacRuby is

not installed. This option can only be used when creating executa-

bles.

--dylib

Create a dynamic library instead of an executable. This option com-

piles every Ruby source file passed to rubyc and produces a Mach-O

dynamic library (.dylib). This library is compiled with a global

constructor that will register every Ruby machine code file into the

MacRuby runtime once it's loaded by the dynamic linker, at runtime.

This library is intended to be linked against an executable that

uses the MacRuby runtime, for example executables generated by

rubyc. The -o option must be provided when building dynamic

libraries.

-a arch, --arch arch

Compile for specified CPU architecture. By default, rubyc will com-

pile for the current CPU architecture. This option will compile for

a different architecture. When this option is provided more than

once, rubyc will create a universal binary. At the time of this

writing, only the i386 and x86_64 architectures are supported.

-v, --version

Display the version.

-V, --verbose

Print every command line executed by rubyc. This option is gener-

ally used for internal debugging.

-h, --help

Display a short description of the command line options.

EXAMPLES

The easiest way to compile an existing project is probably to generate

loadable object bundles for every Ruby source file, using the -C option.

These bundles are using the .rbo file extension and can simply be

installed in the same directory as the original .rb source files. The

MacRuby runtime will always pick .rbo files in priority upon #require

calls. The source files can later be removed.

$ find src/lib -name *.rb -exec rubyc -C {} ;

rubyc without any option will create a binary executable, like the C com-

piler.

$ echo "p 42" > test.rb

$ rubyc test.rb

$ ./a.out

When building an executable, the very first file passed to rubyc will be

considered as the main file and its machine code will be ran once the

executable starts. Other machine code files will be linked into the exe-

cutable but only ran upon #require calls.

$ echo "def t1; 21; end" > t1.rb

$ echo "def t2; 21; end" > t2.rb

$ echo "require 't1'; require 't2'; p t1+t2" > test.rb

$ rubyc test.rb t1.rb t2.rb -o test

$ ./test

rubyc is also able to generate a dynamic library (.dylib) out of Ruby

source files, using the --dylib option. Such a library can later be

linked against an executable that uses the MacRuby runtime. Like executa-

bles, the Ruby machine code files will ran upon #require calls. Libraries

can also be passed to rubyc when forming an executable, allowing the com-

pilation of multiple executables sharing common code.

$ rubyc t1.rb t2.rb -o code.dylib --dylib

$ rubyc test.rb code.dylib -o test

$ ./test