@@ -20,38 +20,65 @@ FastR is intended eventually to be a drop-in replacement for GNU R. Currently, h
...
@@ -20,38 +20,65 @@ FastR is intended eventually to be a drop-in replacement for GNU R. Currently, h
## Running FastR
## Running FastR
After downloading and unpacking the binary release, or compiling from source, the `bin` directory contains the `R` and `Rscript` commands and these can be used similar to GNU R. N.B. the binary release currently does not support the `R CMD` and related variants, so packages must be installed from the shell using `install.packages`.
After downloading and unpacking the binary release, or compiling from source, the `bin` directory contains the `R` and `Rscript` commands and these can be used in a similar way to GNU R.
## Performance
## Performance
FastR is primarily aimed at long-running applications. The runtime performance behavior is, like Java, based on runtime profiling and runtime compilation of the hot code paths. Therefore, there is an inevitable warmup time before peak performance is achieved when evaluating a given expression. In addition, startup is slower than GNU R, due to the overhead from Java class loading and compilation.
FastR is primarily aimed at long-running applications. The runtime performance behavior is, like Java, based on runtime profiling and runtime compilation of the hot code paths. Therefore, there is an inevitable warm-up time before peak performance is achieved when evaluating a given expression. In addition, startup is slower than GNU R, due to the overhead from Java class loading and compilation.
# Building FastR from Source
# Building FastR from Source
Building FastR from source is supported on Mac OS X (El Capitan onwards), and various flavors of Linux.
FastR uses a build tool called `mx` (cf `maven`) which can be downloaded from [here](http://github.com/graalvm/mx).
FastR uses a build tool called `mx` (cf `maven`) which can be downloaded from [here](http://github.com/graalvm/mx).
`mx` manages software in _suites_, which are normally one-to-one with a `git` repository. FastR depends fundamentally on the [truffle] (http://github.com/graalvm/truffle) suite. However, performance also depends on the [graal compiler](http://github.com/graalvm/graal-core) as without it, FastR operates in intepreted mode only. The conventional way to arrange the Git repos (suites) is as siblings in a parent directory, which we will call `FASTR_HOME`. Use the following sequence of commands to download and build fastr.
`mx` manages software in _suites_, which are normally one-to-one with a `git` repository. FastR depends fundamentally on the [truffle](http://github.com/graalvm/truffle) suite. However, performance also depends on the [graal compiler](http://github.com/graalvm/graal-core) as without it, FastR operates in interpreted mode only. The conventional way to arrange the Git repos (suites) is as siblings in a parent directory, which we will call `FASTR_HOME`.
## Pre-Requisites
FastR shares some code with GnuR, for example, the default packages and the Blas library. Therefore, a version of GnuR (currently
R-3.3.2), is downloaded and built as part of the build. Both GNU R and FastR require access certain tools and packages that must be available
prior to the build. These are:
A jvmci-enabled Java JDK which is available from [pre-built binary](http://www.oracle.com/technetwork/oracle-labs/program-languages/downloads/index.html)
Python version 2.7.x
A Fortran compiler and libraries. Typically gfortran 4.8 or later
The pcre package, version 8.38 or later
The zlib package, version 1.2.8 or later
The bzip2 package, version 1.0.6 or later
The xz package, version 5.2.2 or later
If any of these are missing the GNU R build will fail which will cause the FastR build to fail also. Note that your system may have existing installations of these
packages, possibly in standard system locations, but older versions. These must either be upgraded or newer versions installed with the package manager on your system.
Since different systems use different package managers some of which install packages in directories that are not scanned by default by the C compiler and linker,
it may be necessary to inform the build of these locations using the following environment variables:
PKG_INCLUDE_FLAGS_OVERRIDE
PKG_LDFLAGS_OVERRIDE
For example, on Mac OS, the MacPorts installer places headers in /opt/local/include and libraries in /opt/local/lib, in which case, the above variables must be set to these
values prior to the build. Note that if more than once location must be specified, the environment variable values must be quoted.
## Building FastR
Use the following sequence of commands to download and build an interpreted version of FastR.
$ mkdir $FASTR_HOME
$ mkdir $FASTR_HOME
$ cd $FASTR_HOME
$ git clone http://github.com/graalvm/mx
$ git clone http://github.com/graalvm/mx
$ PATH=$PATH:$FASTR_HOME/mx
$ PATH=$PATH:$FASTR_HOME/mx
$ cd $FASTR_HOME
$ git clone http://github.com/graalvm/fastr
$ git clone http://github.com/graalvm/fastr
$ cd fastr
$ cd fastr
$ mx sforceimports
$ mx build
$ mx build
FastR shares some code with GnuR, for example, the default packages
The build will clone the Truffle repository and also download various required libraries.
and the Blas library. Therefore, a version of GnuR (currently
R-3.2.4), is downloaded and built as part of the first build.
The first build will also download various required libraries.
After building, running the FastR console can be done either with `bin/R` or with `mx r` or `mx R`.
After building, running the FastR console can be done either with `bin/R` or with `mx r` or `mx R`. Using `mx` makes available some additional options that are of interest to FastR developers.
FastR supports the same command line arguments as R, so running an R script is done with `mx R -f <file>`.
FastR supports the same command line arguments as R, so running an R script is done with `bin/R -f <file>` or `bin/Rscript <file>`.
## IDE Usage
## IDE Usage
`mx` supports IDE integration with Eclipse, Netbeans or IntelliJ and creates project metadata with the `ideinit` command (you can limit metadata creation to one IDE by setting the `MX_IDE` environment variable to, say, `eclipse`). After running this command you can import the fastr and truffle projects using the `File->Import` menu.
`mx` supports IDE integration with Eclipse, Netbeans or IntelliJ and creates project metadata with the `ideinit` command (you can limit metadata creation to one IDE by setting the `MX_IDE` environment variable to, say, `eclipse`). After running this command you can import the `fastr` and `truffle` projects using the `File->Import` menu.
## Further Documentation
Further documentation on FastR, its limitations and additional functionality is [here](Index.md).
