README for Ra
-------------

The file ra/NOTES has some additional documentation.  The "ra"
directory under the R root contains some Ra specific bits and pieces,
including this file.  Grep for "RA_TODO" in the sources for things
that need attention.

Summary of the process used to build Ra from the sources:

    a. Copy the R-2.13.1 sources into a new directory
    b. Install the "jit" package into the new directory
    c. Untar the Ra files in the new directory (this will
       overwrite and add some files)
    d. Build R in the new directory

Step b can actually be performed at any time after a, c, or d.


To build in a Windows environment
---------------------------------

I assume you are familiar with building R from the sources.  The Ra
build process will be streamlined in due course, but for now perform
the following steps.

1. Build a clean R from the R-2.13.1 sources in a new directory
       make all recommended
   The make is not strictly necessary but it does ensure that R
   can be built in the new directory.

2. cd to your build root
   To confirm: ls -CF should show COPYING, bin/ doc/ etc.

3. Using your existing installed R-2.13.1 (32-bit or 64-bit, it doesn't
   matter), download and install the "jit" package from CRAN.  Do it like
   this (or use the "Install package(s)..." menu in the R GUI to do
   the same thing):
       > install.packages("jit")

4. Copy the jit directory from the installed R-2.13.1 library directory
   to the library directory under your new build root.
   Use something this like this to do the copy:
       cp -r "C:/Program Files/R/R-2.13.1/library/jit" library
   To check, run the R you just built in step 1 above and use:
       > library(jit)
       > ?jit

5. Check that you are still in your build root directory and execute:
       gzip -d ra-x.x.x.tar.gz  (change x.x.x to the Ra version)
       tar -xvf ra-x.x.x.tar
   This will overwrite Makefile.win, Internal.h, eval.c, and others.
   It will create new files jit.h, jit.c, and others

6. cd to src/gnuwin32

7. Rebuild R:
       make clean  (important but it is ok not to delete recommended packages)
       make all recommended
   This will write the executables into bin -- the new executables
   will have jitting enabled.
   R.version.string and friends will report that it is a Ra build.

8. Steps 8 and 9 can be done in any order.

   Test the new build in the ra\tests directory:
       ..\..\bin\Rterm --vanilla <test-jit.R >test-jit.Rout 2>&1
       diff test-jit.Rout.save test-jit.Rout
   The diff should show no differences except for the build date.
   (The "2>&1" redirects stderr to stdout.)

   You can also do a  "make check-all".  All tests should be no worse
   than running make check-all on your standard R build, except for
   a warning while checking base ("undocumented code object jit").
   This warning is under investigtation.

9. Try some things with the new executable.  For example:
       > library(jit)
       > example(jit)
   There are a some batch files for doing timing tests in
   the ra\tests directory.



To build in other environments
------------------------------

Dirk Eddelbuettel has done an official Debian port.

People report that Ra builds without issues in other environments.
The procedure is to untar the Ra files over a standard R directory
tree and then do a build as usual.