Thanks all very much for the feedback :-) I merged I believe
everything in r3132. Ernie: about the examples section, I agree it
needs more work. For the moment I just renamed it USAGE which seems to
fit better.
Following is the new ASCII formatted version. Let me know if you have
feedback again.
Laurent
$ groff -Tascii -man rubyc.1
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 statically compiles Ruby source code into native
machine code
(object files), and can then link it (dynamically or statically)
into
executables or dynamic libraries.
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 it has been compiled down to machine code.
OPTIONS
The rubyc tool accepts the following command-line options:
-a arch, --arch arch
Compile for specified CPU architecture. By default, rubyc
will com-
pile for the current 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.
-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 rubyc, using a default file name
which con-
sists of the source file name with the .rbo file extension. A
MacRuby loadable 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 statement.
--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.
-h, --help
Display a short description of the 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.
--static
Create a standalone, static executable. By default,
executables cre-
ated by rubyc are dynamically linked against the MacRuby
runtime.
This option will generate executables that are statically
linked
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.
-v, --version
Display the version.
-V, --verbose
Print every command line executed by rubyc. This option is
gener-
ally used for internal debugging.
USAGE
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 have the .rbo file extension and can be installed
in the
same directory as the original .rb source files. The MacRuby
runtime will
always pick .rbo files over .rb files upon #require calls. The
source
files can be removed later.
$ find src/lib -name "*.rb" -exec rubyc -C {} \;
When used without options, rubyc will create a binary
executable, like
the C compiler.
$ 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. Its machine code will be run once
the exe-
cutable starts. Other machine code files will be linked into the
exe-
cutable, but only run 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 run 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
SEE ALSO
ruby(1), irb(1), ruby_deploy(1)
BSD December 16,
2009 BSD
$
_______________________________________________
MacRuby-devel mailing list
MacRuby-devel@lists.macosforge.org
http://lists.macosforge.org/mailman/listinfo.cgi/macruby-devel
