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

Matt Aimonetti mattaimonetti at gmail.com
Thu Dec 17 17:48:11 PST 2009


For those who don't have the latest repo pulled, here is the output of
Laurent's command:

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

SEE ALSO
     ruby(1) irb(1) ruby_deploy(1)

BSD                            December 16, 2009
BSD



On Thu, Dec 17, 2009 at 5:39 PM, Laurent Sansonetti
<lsansonetti at apple.com>wrote:

> Hi guys,
>
> I just committed an early draft of the macrubyc man-page. Would be nice to
> have some feedback about it. I'm not good at writing English neither at
> documenting stuff :) Please let me know if you find English mistakes or if
> there is something you do not understand, or if something is missing.
>
> http://svn.macosforge.org/repository/ruby/MacRuby/trunk/rubyc.1
>
> To view it:
>
> $ groff -Tascii -man rubyc.1 | more
>
> Thanks,
> Laurent
> _______________________________________________
> MacRuby-devel mailing list
> MacRuby-devel at lists.macosforge.org
> http://lists.macosforge.org/mailman/listinfo.cgi/macruby-devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/macruby-devel/attachments/20091217/27af6dd5/attachment-0001.html>


More information about the MacRuby-devel mailing list