Permalink
Browse files

Man pages fixes and additions + small fix in macrubyd help

git-svn-id: http://svn.macosforge.org/repository/ruby/MacRuby/trunk@4129 23306eb0-4c56-4727-a40e-e92c0eb68959
  • Loading branch information...
Thibault Martin-Lagardette
Thibault Martin-Lagardette committed May 21, 2010
1 parent acc6d52 commit 374a50c415f7090f382d5626285a4b3540912f6e
Showing with 83 additions and 32 deletions.
  1. +1 −1 bin/rubyd
  2. +32 −0 ruby_deploy.1
  3. +31 −31 rubyc.1
  4. +19 −0 rubyd.1
View
@@ -213,7 +213,7 @@ next Go to the next expression.
continue Continue the program's execution.
run Start the program's execution.
stop Stop the program's execution.
-list <line> Print the next 10 lines at given or current line.
+list [line] Print the next 10 lines at given or current line.
backtrace Show current backtrace.
backtrace full Show a full backtrace (for every thread).
thread <thread-id> Switch to the given thread.
View
@@ -0,0 +1,32 @@
+.Dd Mac 20, 2010
+.Dt MACRUBY_DEPLOY 1
+.Os
+.Sh NAME
+.Nm macruby_deploy
+.Nd Embed the MacRuby runtime inside an application bundle
+.Sh SYNOPSIS
+.Nm macruby_deploy
+.Op Ar options
+.Ar application-bundle
+.Sh DESCRIPTION
+.Nm macruby_deploy
+is a command-line tool that embeds the MacRuby runtime inside a specific application bundle, thus allowing the deployment of the application on computers that do not have MacRuby installed.
+.Sh OPTIONS
+.Nm macruby_deploy
+accepts the following arguments:
+.Bl -tag -width "123"
+.It Fl -compile
+Compile the bundle source code
+.It Fl -embed
+Embed MacRuby inside the bundle
+.It Fl -no-stdlib
+Do not embed the standard library (creates smaller bundles)
+.It Fl -stdlib Ar lib
+Embed only
+.Ar lib
+from the standard library
+.It Fl -verbose
+Log actions to standard out
+.It Fl v , Fl -version
+Display the version
+.El
View
62 rubyc.1
@@ -1,50 +1,50 @@
.Dd December 16, 2009
-.Dt RUBYC 1
+.Dt MACRUBYC 1
.Os
.Sh NAME
-.Nm rubyc
+.Nm macrubyc
.Nd MacRuby Ahead-of-Time Compiler
.Sh SYNOPSIS
-.Nm rubyc
+.Nm macrubyc
.Op Ar options...
.Ar files...
.Sh DESCRIPTION
-.Nm rubyc
+.Nm macrubyc
is a command-line interface to the MacRuby Ahead-of-Time (AOT) compiler. 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. It is typically invoked from
.Nm ruby_deploy
rather than being called directly.
.Pp
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.
.Sh OPTIONS
The
-.Nm rubyc
+.Nm macrubyc
tool accepts the following command-line options:
.Bl -tag -width "123" -compact
.Pp
.It Fl a Ar arch , Fl -arch Ar arch
Compile for specified CPU architecture. By default,
-.Nm rubyc
+.Nm macrubyc
will compile for the current architecture. This option will compile for a different architecture. When this option is provided more than once,
-.Nm rubyc
+.Nm macrubyc
will create a universal binary. At the time of this writing, only the i386 and x86_64 architectures are supported.
.Pp
.It Fl c
Compile and assemble, but do not link. This option produces a Mach-O object file (.o) for every Ruby source file passed to
-.Nm rubyc ,
+.Nm macrubyc ,
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
-.Nm rubyc
+.Nm macrubyc
to create a dynamic library or executable.
.Pp
.It Fl C
Compile, assemble, and link a loadable object file. This option produces a Mach-O MacRuby loadable object bundle (.rbo) for every Ruby source file passed to
-.Nm rubyc ,
+.Nm macrubyc ,
using a default file name which consists 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.
.Pp
.It Fl -dylib
Create a dynamic library instead of an executable. This option compiles every Ruby source file passed to
-.Nm rubyc
+.Nm macrubyc
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
-.Nm rubyc .
+.Nm macrubyc .
The
.Fl o
option must be provided when building dynamic libraries.
@@ -56,72 +56,72 @@ Display a short description of the command line options.
Place the output into
.Ar file .
If this option is not given,
-.Nm rubyc
+.Nm macrubyc
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 mandatory.
.Pp
.It Fl -static
Create a standalone, static executable. By default, executables created by
-.Nm rubyc
+.Nm macrubyc
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 executables.
.Pp
.It Fl v, Fl -version
Display the version.
.Pp
.It Fl V, Fl -verbose
Print every command line executed by
-.Nm rubyc .
+.Nm macrubyc .
This option is generally used for internal debugging.
.El
.Sh EXAMPLES
When used without options,
-.Nm rubyc
+.Nm macrubyc
will create a binary executable, like the C compiler.
.Pp
.Dl $ echo """p 42""" > test.rb
-.Dl $ rubyc test.rb
+.Dl $ macrubyc test.rb
.Dl $ ./a.out
.Pp
When building an executable, the very first file passed to
-.Nm rubyc
+.Nm macrubyc
will be considered as the main file. Its machine code will be run once the executable starts. Other machine code files will be linked into the executable, but only run upon #require calls.
.Pp
.Dl $ echo """def t1; 21; end""" > t1.rb
.Dl $ echo """def t2; 21; end""" > t2.rb
.Dl $ echo """require 't1'; require 't2'; p t1+t2""" > test.rb
-.Dl $ rubyc test.rb t1.rb t2.rb -o test
+.Dl $ macrubyc test.rb t1.rb t2.rb -o test
.Dl $ ./test
.Pp
-.Nm rubyc
+.Nm macrubyc
is also able to generate a dynamic library (.dylib) out of Ruby source files, using the
.Fl -dylib
option. Such a library can later be linked against an executable that uses the MacRuby runtime. Like executables, the Ruby machine code files will run upon #require calls. Libraries can also be passed to
-.Nm rubyc
+.Nm macrubyc
when forming an executable, allowing the compilation of multiple executables sharing common code.
.Pp
-.Dl $ rubyc t1.rb t2.rb -o code.dylib --dylib
-.Dl $ rubyc test.rb code.dylib -o test
+.Dl $ macrubyc t1.rb t2.rb -o code.dylib --dylib
+.Dl $ macrubyc test.rb code.dylib -o test
.Dl $ ./test
.Pp
.Sh USAGE
Generally, you should use
-.Nm ruby
+.Nm macruby
and
-.Nm irb
+.Nm macirb
during development, and
-.Nm ruby_deploy
+.Nm macruby_deploy
(via the Xcode target) when deploying Cocoa applications. However, calling
-.Nm rubyc
+.Nm macrubyc
provides greater control, and allows you to create libraries and standalone executables.
.Pp
The easiest way to compile an existing project is to generate loadable object bundles for every Ruby source file, e.g., using the
.Fl C
option and the find command:
.Pp
-.Dl $ find ./lib -name """*.rb""" -exec rubyc -C {} \e;
+.Dl $ find ./lib -name """*.rb""" -exec macrubyc -C {} \e;
.Pp
This creates bundles with the .rbo file extension 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 then be removed.
.Pp
.Sh SEE ALSO
-.Xr ruby 1 ,
-.Xr irb 1 ,
-.Xr ruby_deploy 1
+.Xr macruby 1 ,
+.Xr macirb 1 ,
+.Xr macruby_deploy 1
View
19 rubyd.1
@@ -0,0 +1,19 @@
+.Dd May 20, 2010
+.Dt MACRUBYD 1
+.Os
+.Sh NAME
+.Nm macrubyd
+.Nd MacRuby Debugger
+.Sh SYNOPSIS
+.Nm macrubyd
+.Ar path_to_ruby_file
+.Op Ar arguments...
+.Sh DESCRIPTION
+.Nm macrubyd
+can be used to debug your MacRuby scripts
+.Pp
+Please run
+.Ar help
+within
+.Nm macrubyd
+to get the list of available commands

0 comments on commit 374a50c

Please sign in to comment.