|
1 | | -# FastR |
| 1 | +A high performance implementation of the R programming language., built on the GraalVM by Oracle Labs. |
2 | 2 |
|
3 | | -FastR is an implementation of the [R Language](http://www.r-project.org/) in Java atop [Truffle](https://github.com/graalvm/), a framework for building self-optimizing AST interpreters. |
| 3 | +FastR aims to be: |
| 4 | +* [efficient](https://medium.com/graalvm/faster-r-with-fastr-4b8db0e0dceb#4ab6): executing R language scripts faster than any other R runtime. |
| 5 | +* [polyglot](https://medium.com/graalvm/faster-r-with-fastr-4b8db0e0dceb#0f5c): allowing [polyglot interoperability](https://www.graalvm.org/docs/reference-manual/polyglot/) with other languages in the GraalVM ecosystem. |
| 6 | +* [compatible](https://medium.com/graalvm/faster-r-with-fastr-4b8db0e0dceb#fff5): providing support for existing packages and the R native interface. |
| 7 | +* [embeddable](https://github.com/graalvm/examples/tree/master/r_java_embedding): allowing integration using the R embedding API or the GraalVM polyglot embedding SDK. |
4 | 8 |
|
5 | | -FastR is: |
| 9 | + ## Getting Started |
| 10 | +See the documentation on the GraalVM website on how to [get GraalVM](https://www.graalvm.org/docs/getting-started/) and [install and use FastR](http://www.graalvm.org/docs/reference-manual/languages/r/). |
6 | 11 |
|
7 | | -* polyglot |
8 | | - |
9 | | -..R is very powerful and flexible, but certain tasks are best solved by using R in combination with other programming languages. |
10 | | -..Interfaces to languages, e.g., Java, Fortran and C/C++, incur a significant overhead, which is caused, to a large degree, by the different execution strategies employed by different languages, e.g., compiled vs. interpreted, and by incompatible internal data representations. |
11 | | - |
12 | | -..The Truffle framework addresses these issues at a very fundamental level, and builds the necessary polyglot primitives directly into the runtime. |
13 | | -..Consequently, FastR leverages this infrastructure to allow multiple languages to interact transparently and seamlessly. |
14 | | -..All parts of a polyglot application can be compiled by the same optimizing compiler, and can be executed and debugged simultaneously, with little to no overhead at the language boundary. |
15 | | - |
16 | | -* efficient |
17 | | - |
18 | | -..R is a highly dynamic language that employs a unique combination of data type immutability, lazy evaluation, argument matching, large amount of built-in functionality, and interaction with C and Fortran code. |
19 | | -..Consequently, applications that spend a lot of time in R code often have performance problems. |
20 | | -..Common solutions are to try to apply primitives to large amounts of data at once and to convert R code to a native language like C. |
21 | | - |
22 | | -..FastR makes extensive use of the dynamic optimization features provided by the Truffle framework to remove the abstractions that the R language introduces, and can use the Graal compiler to create optimized machine code on the fly. |
23 | | - |
24 | | -* compatible |
25 | | - |
26 | | -..The hardest challenge for implementations of the R language is the tradeoff between compatibility and performance. |
27 | | -..If an implementation is very compatible, e.g., by using the traditional internal data layout, it cannot perform optimizations that imply a radically different internal structure. |
28 | | -..If an implementation is very efficient, e.g., by adapting internal data structures to the current requirements, it will find it difficult to implement some parts of the GNUR system that are interfacing with applications and packages. |
29 | | - |
30 | | -FastR employs many different solution strategies in order to overcome these problems. |
31 | | -It also explores possible solutions at a grander scale, like evolution and emulation of R’s native interfaces. |
32 | | - |
33 | | -## Getting FastR |
34 | | - |
35 | | -FastR is available in two forms: |
36 | | - |
37 | | -1. As a [pre-built binary](http://www.graalvm.org/downloads/). Note that this also includes (Truffle) implementations of JavaScript and optionally Ruby and Python. The pre-built binaries are available for Linux and Mac OS X. There is no Windows version available. The binary release is updated monthly. |
38 | | -2. As a source release on [GitHub](https://github.com/graalvm/fastr) for developers wishing to contribute to the project and/or study the implementation. The source release is updated regularly and always contains the latest tested version. |
39 | | - * Note: there is a comunity provided and maintained [Dockerfile](https://github.com/nuest/fastr-docker) for FastR. |
| 12 | +``` |
| 13 | +$ $GRAALVM/bin/R |
| 14 | +Type 'q()' to quit R. |
| 15 | +> print("Hello R!") |
| 16 | +[1] "Hello R!" |
| 17 | +> |
| 18 | +``` |
40 | 19 |
|
41 | 20 | ## Documentation |
42 | 21 |
|
43 | | -Reference manual for FastR, its limitations, compatibility and additional functionality is |
44 | | -available at [GraalVM website](http://www.graalvm.org/docs/reference-manual/languages/r/). |
45 | | - |
46 | | -Further documentation is in the [documentation folder](documentation/Index.md) of this repository. |
47 | | - |
48 | | -# Building FastR from Source |
49 | | - |
50 | | -Building FastR from source is supported on Mac OS X (El Capitan onwards), and various flavors of Linux. |
51 | | -FastR uses a build tool called `mx` (cf `maven`) which can be downloaded from [here](http://github.com/graalvm/mx). |
52 | | -`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/graal) suite. However, performance also depends on the [Graal compiler](http://github.com/graalvm/graal) 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`. |
53 | | - |
54 | | -## Pre-Requisites |
55 | | -FastR shares some code with GnuR, for example, the default packages and the Blas library. Therefore, a version of GnuR (currently |
56 | | -R-3.4.0), is downloaded and built as part of the build. Both GNU R and FastR require access certain tools and packages that must be available |
57 | | -prior to the build. These are: |
58 | | - |
59 | | - A jvmci-enabled Java JDK which is available from [pre-built binary](http://www.oracle.com/technetwork/oracle-labs/program-languages/downloads/index.html) |
60 | | - Python version 2.7.x |
61 | | - A Fortran compiler and libraries. Typically gfortran 4.8 or later |
62 | | - A C compiler and libraries. Typically gcc or clang |
63 | | - The pcre package, version 8.38 or later |
64 | | - The zlib package, version 1.2.8 or later |
65 | | - The bzip2 package, version 1.0.6 or later |
66 | | - The xz package, version 5.2.2 or later |
67 | | - The curl package, version 7.50.1 or later |
68 | | - |
69 | | -If any of these are missing the GNU R build will fail which will cause the FastR build to fail also. If the build fails, more details can be found in log files in |
70 | | -the `libdownloads/R-{version}` directory. Note that your system may have existing installations of these packages, possibly in standard system locations, |
71 | | -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 |
72 | | -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 |
73 | | -locations using the following environment variables: |
| 22 | +The reference manual for FastR, which explains its advantages, its current limitations, compatibility and additional functionality is available on the [GraalVM website](http://www.graalvm.org/docs/reference-manual/languages/r/). |
74 | 23 |
|
75 | | - PKG_INCLUDE_FLAGS_OVERRIDE |
76 | | - PKG_LDFLAGS_OVERRIDE |
| 24 | +Further documentation, including contributor/developer-oriented information, is in the [documentation folder](documentation/Index.md) of this repository. |
77 | 25 |
|
78 | | -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 |
79 | | -values prior to the build, e.g.: |
| 26 | +## Current Status |
80 | 27 |
|
81 | | - export PKG_INCLUDE_FLAGS_OVERRIDE=-I/opt/local/include |
82 | | - export PKG_LDFLAGS_OVERRIDE=-L/opt/local/lib |
| 28 | +The goal of FastR is to be a drop-in replacement for GNU-R, the reference implementation of the R language. |
| 29 | +FastR faithfully implements the R language, and any difference in behavior is considered to be a bug. |
83 | 30 |
|
84 | | - Note that if more than once location must be specified, the values must be quoted, e.g., as in `export PKG_LDFLAGS_OVERRIDE="-Lpath1 -Lpath2"`. |
| 31 | +FastR is capable of running binary R packages built for GNU-R as long as those packages properly use the R extensions C API (for best results, it is recommended to install R packages from source). |
| 32 | +FastR supports R graphics via the grid package and packages based on grid (like lattice and ggplot2). |
| 33 | +We are currently working towards support for the base graphics package. |
| 34 | +FastR currently supports many of the popular R packages, such as ggplot2, jsonlite, testthat, assertthat, knitr, Shiny, Rcpp, rJava, quantmod and more… |
85 | 35 |
|
86 | | - The environment variable `JAVA_HOME` must be set to the location of the jvmci-enabled Java JDK. |
| 36 | +Moreover, support for dplyr and data.table are on the way. |
| 37 | +We are actively monitoring and improving FastR support for the most popular packages published on CRAN including all the tidyverse packages. |
| 38 | +However, one should take into account the experimental state of FastR, there can be packages that are not compatible yet, and if you try it on a complex R application, it can stumble on those. |
87 | 39 |
|
88 | | -## Building FastR |
89 | | -Use the following sequence of commands to download and build an interpreted version of FastR. |
| 40 | +## Stay connected with the community |
90 | 41 |
|
91 | | - $ mkdir $FASTR_HOME |
92 | | - $ cd $FASTR_HOME |
93 | | - $ git clone http://github.com/graalvm/mx |
94 | | - $ PATH=$PATH:$FASTR_HOME/mx |
95 | | - $ git clone http://github.com/graalvm/fastr |
96 | | - $ cd fastr |
97 | | - $ mx build |
98 | | - |
99 | | -The build will clone the Truffle repository and also download various required libraries, including GNU R, which is built first. Any problems with the GNU R configure step likely relate |
100 | | -to dependent packages, so review the previous section. For FastR development, GNU R only needs to be built once, but an `mx clean` will, by default remove it. This can be prevented by setting |
101 | | -the `GNUR_NOCLEAN` environment variable to any value. |
102 | | - |
103 | | -It is possible to build FastR in "release mode" which builds and installs the GNU R "recommended" packages and also creates a `fastr-release.jar` file that contains everything that is needed to |
104 | | -run FastR, apart from a Java VM. In particular it captures the package dependencies, e.g., `pcre` and `libgfortran`, so that when the file is unpacked on another system it will work regardless of whether the packages are installed on that system. For some systems that depend on FastR, e.g., GraalVM, it is a requirement to build in release mode as they depend on this file. To build in release mode, set the `FASTR_RELEASE` environment variable to any value. Note that this can be done at any time without doing a complete clean and rebuild. Simply set the variable and execute `mx build`. |
105 | | - |
106 | | -## Running FastR |
107 | | - |
108 | | -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. |
109 | | -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>`. |
110 | | - |
111 | | -## IDE Usage |
112 | | - |
113 | | -`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. |
114 | | - |
115 | | -## Contributing |
| 42 | +See [graalvm.org/community](https://www.graalvm.org/community/) on how to stay connected with the development community. |
| 43 | +The discussion on [gitter](https://gitter.im/graalvm/graal-core) is a good way to get in touch with us. |
116 | 44 |
|
117 | 45 | We would like to grow the FastR open-source community to provide a free R implementation atop the Truffle/Graal stack. |
118 | 46 | We encourage contributions, and invite interested developers to join in. |
119 | 47 | Prospective contributors need to sign the [Oracle Contributor Agreement (OCA)](http://www.oracle.com/technetwork/community/oca-486395.html). |
120 | | -The access point for contributions, issues and questions about FastR is the [GitHub repository ](https://github.com/graalvm/fastr) |
121 | | - |
122 | | -## Troubleshooting |
123 | | - |
124 | | -### GNU-R build fails |
125 | | - |
126 | | -GNU-R is built as part of the FastR build and therefore all GNU-R dependencies are required. |
127 | | -The output from GNU-R configuration is logged in `libdownloads/R-3.4.0/gnur_configure.log`. |
| 48 | +The access point for contributions, issues and questions about FastR is the [GitHub repository](https://github.com/oracle/fastr). |
128 | 49 |
|
129 | | -### Build fails when generating R grammar |
| 50 | +## Authors |
130 | 51 |
|
131 | | -This problem manifests by the following error message in the build output: |
| 52 | +FastR is developed by Oracle Labs and is based on [the GNU-R runtime](http://www.r-project.org/). |
| 53 | +It contains contributions by researchers at Purdue University ([purdue-fastr](https://github.com/allr/purdue-fastr)), Northeastern University, JKU Linz, TU Dortmund and TU Berlin. |
132 | 54 |
|
133 | | -`Parser failed to execute command` |
| 55 | +## License |
134 | 56 |
|
135 | | -followed by a series of parser errors, such as: |
| 57 | +FastR is available under a GPLv3 license. |
136 | 58 |
|
137 | | -`error(170): R.g:<LINE>:<COL>: the .. range operator isn't allowed in parser rules` |
138 | | - |
139 | | -It seems to be an ANTLR issue occurring when `LANG`, `LC_ALL` and `LC_CTYPE` environment |
140 | | -variables are not set to the same value. |
141 | | - |
142 | | -The solution is to set those variables to the same value, e.g. |
143 | | - |
144 | | -``` |
145 | | -export LANG=en_US.UTF-8 |
146 | | -export LC_ALL=en_US.UTF-8 |
147 | | -export LC_CTYPE=en_US.UTF-8 |
148 | | -``` |
149 | | - |
150 | | -Note: you may need to install `locale` and run the following before setting the above env variables: |
151 | | - |
152 | | -``` |
153 | | -locale en_US.UTF-8 |
154 | | -``` |
155 | 59 |
|
0 commit comments