On Dec 17, 2009, at 5:48 PM, Matt Aimonetti wrote:

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

Thanks, Matt! Laurent, your English is very good (or at least on part with other man page writers :-). I did have a couple minor suggestions: * technically, isn't rubyc a front-end to the entire compile-and-link process? It might be nice to make that clearer. Not sure how. Perhaps change the second sentence to:

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

A bit wordy, but you get the idea. * alphabetize the options, since otherwise the ordering appears random, which makes it harder to scan * The first paragraph under "EXAMPLES" doesn't seem to fit The rbo magic really seems to be about best practice, not an example of how to use the command itself. I'd suggest you start this section with the brain-dead simple a.out example. Perhaps put the current first paragraph under a "USAGE" section, where you can expand upon ways this would be used in practice. If you do, you should flesh out the example to explain how to compile and package the final binary. * "its machine code will be ran " -> will be _run_ * "will ran upon #require calls" -> will _be run_ Great stuff! -- Ernie P.

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@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@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo.cgi/macruby-devel

_______________________________________________ MacRuby-devel mailing list MacRuby-devel@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo.cgi/macruby-devel

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 $