This document describes requirements, installation and basic usage of the Ruby
to PHP translator.

================================================================================
REQUIREMENTS
================================================================================

Operating System
----------------
The translator is currently supported only on the Linux operating system.  It
was successfully tested with Ubuntu 8.04.1 on the IA-32 architecture.  During
the development, the translator was also tested on Windows and Mac OS X
platforms, but compatibility issues appeared on both.  As a result, the
translator is able to run on Windows on Mac OS X with some limitations, but it
is not supported officially.

Ruby
----
The translator requires Ruby 1.8.6 installed together with rake, activesupport
and diff-lcs gems (the diff-lcs gem is not needed for normal usage, only for
running the translator tests).  It was successfully tested with Ruby 1.8.6-p111,
rake 0.8.1, activesupport 2.1.0 and diff-lcs 1.1.2.

To install Ruby, visit http://www.ruby-lang.org/ and follow the installation
instructions for your platform.  You can also use the package manager of your
operating system.  Make sure that you install the latest 1.8 version, not the
1.9 development branch (you can always check the installed Ruby version using
the ruby -v command).

To install the RubyGems tool (needed to install the required gems), visit
http://www.rubygems.org/ and follow the installation instructions in the user
guide. Note that if you install Ruby using the one-click installer for
Windows, RubyGems is preinstalled already.


To install the required gems, use following commands:

  gem install -y rake
  gem install -y activesupport
  gem install -y diff-lcs

PHP
---
The generated PHP programs require PHP 4.4.x or 5.2.x.  The translator was
successfully tested with PHP 4.4.8 and PHP 5.2.6.  Older or newer versions of
PHP than specified may work too.

The generated PHP programs are able to run both in PHP executed from the
command-line or running on the web server.  PHP must be configured to allow
call-time pass-by-reference specification (this can be enabled in php.ini by
setting the "allow_call_time_pass_reference" configuration option to "On".

To install PHP, visit http://www.php.net/ and follow the installation
instructions for your platform in the documentation.  You can also use the
package manager of your operating system.

================================================================================
INSTALLATION
================================================================================

To install the translator, just copy contents of the Implementation directory on
the CD to any directory.

================================================================================
USAGE
================================================================================

The translator can be invoked via the "compiler/bin/r2p" script.  (To execute
the script in Unix environment, just type its name in the shell.  On Windows,
you have to execute it using the "ruby" command (e.g. "ruby compiler/bin/r2p")).

The translator accepts the Ruby source code to translate on the standard input
and outputs the generated PHP code on the standard output.  Alternatively, you
can specify a file with the Ruby source code on the command line, in which case
the output will be written into a file with the same name but the extension
changed to .php.  Several files with sample programs to translate can be found
in the "examples" directory.

For example, to translate the "examples/hello_world.rb" sample program, execute
following command:

  ruby compiler/bin/r2p examples/hello_world.rb

The "hello_world.php" file will be created, which can be executed by PHP:

  php examples/hello_world.php

The translator accepts several command-line options.  For a full list, see the
translator help, which can by displayed using the --help command-line option.

Note that the generated PHP programs require the PHP runtime, whose PHP source
code can be found in the "runtime/lib" directory.  The translator embeds correct
relative path to the PHP runtime into the generated PHP files (this can be
overridden using the --runtime-path command-line option).  When copying the
generated PHP files into different location, either copy the PHP runtime too or
edit the path to the PHP runtime inside the generated PHP files.

