[MacRuby-devel] need review for macrubyc man-page

Laurent Sansonetti lsansonetti at apple.com
Fri Dec 18 14:26:08 PST 2009


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
$



More information about the MacRuby-devel mailing list