RStudio Development
This document describes how to configure a Linux, macOS, or Windows system to do RStudio development. After installing required dependencies for your target platform you should install the recommended development tools and review the section on iterative development to understand the optimal development workflow.
You should start by cloning the RStudio repository (either the main repository or a fork you've setup for development). To clone a read-only copy:
git clone https://github.com/rstudio/rstudio.git
If you have push access then you can clone using:
git clone git@github.com:rstudio/rstudio.git
RStudio has a number of dependencies including CMake, Qt, Boost, and a variety of other libraries. You can install all of these dependencies by following the instructions in the Installing RStudio Dependencies article.
We strongly recommend the use of Qt Creator as a C/C++ IDE for RStudio development. It works well on all three target platforms, has very good support for CMake based projects, and has a deep set of features for productive C/C++ development.
Qt Creator is installed automatically as part of installing dependencies, or you can download Qt Creator here: http://qt-project.org/downloads#qt-creator
To create a Qt Creator project for working with RStudio:
- Invoke the File -> Open File or Project... menu
- Choose the following CMake file:
rstudio/src/cpp/CMakeLists.txt
You may also want to change the tab and indentation preferences to match the project standard of using 3 spaces for indentation. Set these manually, or in the Qt Creator C++ code style preferences, you can import settings from:
rstudio/src/cpp/tools/editor-settings/qt-code-style.xml
RStudio uses Google Web Toolkit for development of the Javascript client. This code can be found at:
rstudio
src
gwt
The gwt
directory includes project files for both Eclipse and IntelliJ. If you are using Eclipse then two additional steps are highly recommended:
- Install the Google Web Toolkit Eclipse Plugin
- Go to Preferences -> Google -> Web Toolkit and add the appropriate version of GWT located at
rstudio/src/gwt/lib/gwt
.
Once the plugin is installed, open the project:
- Click File, New, Project
- Select Java Project From Existing Ant Buildfile
- Browse to
rstudio/src/gwt
and selectbuild.xml
- Select the first of the
javac
targets presented
Linux or macOS are strongly recommended for feature development since they support an incremental development model (described below) whereas on Windows you need to do a rebuild and/or relaunch for each iteration.
Before you compile RStudio the first time, you will need to run CMake. Among other things, CMake will set the build directory. Before running CMake, it may be a good idea to change the configured build directory. To do so, navigate to the projects pane on the left hand bar. Under the CMake section you should see a "Build directory:" text edit box. Change the directory to your desired output location.
Now run the CMake build.
There are two additional tweaks to the configuration within Qt Creator that will yield faster builds and more convenient turnarounds on changes:
- Add -j4 to the make command line (to use 4 cores for building, feel free to use 8 if you have them)
- Windows does not support the -j parameter, use Ninja (https://github.com/ninja-build/ninja), configure this under Tools->Options->Kits and click on the 2017 64-bit kit.
- Add a post build command to force suspension of any running rsession processes The Qt Creator Build Settings for these changes look like this:
Finally, run the project build.
To run a local server on Linux or macOS you execute a script within the CMake build directory. For example:
cd rstudio/src/cpp-build
./rserver-dev
This runs an RStudio server on http://localhost:8787.
To do incremental client development (tweak and reload the browser to see changes) you should run the following from the rstudio/src/gwt
directory:
ant devmode
You can then make incremental changes to Java code and they'll be recompiled automatically whenever you reload the browser.
Note that compilation errors are often inscrutable in devmode, since the incremental compiler is very noisy and doesn't tell you the root cause of an error. If you're having trouble with compilation errors in dev mode, try quitting devmode and running ant clean && ant devmode
or ant draft
.
When running in SuperDevMode and using the Chrome browser, it's possible to set debug breakpoints and step through the GWT Java code rather than the generated JavaScript using source mapping. SuperDevMode emits source maps by default, but you need to turn on source map debugging in Chrome to pick them up. Do this (it's one-time setup):
- Open the Chrome dev tools (F12)
- Click the gear icon in the bottom right
- Under Sources check Enable source maps
- Close the preferences and reload RStudio
To debug the Java source once you've done the above:
- Browse to RStudio and open the Chrome dev tools
- Click the Sources tab and open the navigator (small triangle on the upper left)
- Scroll to the bottom of the source list--you'll find the entire Java source tree there
- Open a Java file and set breakpoints as usual
It's possible when compiling the GWT sources that Java will run out of heap space. If this happens the ant
build will fail while building the javac
target with an OutOfMemoryError
. To fix this, it's necessary to get ant
to fork the javac
process that builds the RStudio sources. Add fork = "true"
to the <javac ... >
directive that compiles org/rstudio
. See this StackOverflow answer for details.
To run the desktop application from within the build tree, switch to the main CMake build directory (the one where rserver-dev is run from as described above) and run this command (it's distinct for each platform):
- Linux and macOS:
rstudio-dev
- Windows:
rstudio.bat
Note that RStudio will attempt to launch the copy of RSession.exe
that matches the bit flavor of the default version of R on the system, but by default the makefiles will only produce the 32-bit flavor of RSession.exe
. This means that if you have 64 bit R on your system set as the default, you will need to hold down Control while launching RStudio Desktop for the first time, and select the 32 bit version of R to use with RStudio.
To run using the native OS components (for instance, to use the OS dialogs) run ant desktop
(or ant draft
for release builds) instead of ant devmode
See Unit Tests for information on running RStudio unit tests.
Developing
- Beginners guide
- RStudio Development
- Git conventions
- Accessibility
- Development with Vagrant
- Electron desktop
- GWT
- Internationalization (i18n)
- Node Native Modules
Issues
Personal development environment
- Installing RStudio Dependencies
- M1 Mac Dev Machine Setup
- Visual Markdown Editing
- IDE Development Using Visual Studio Code
Building
Coding standards
Tests
Other topics