Hacking RStudio

gistfile1.md

Hacking Rstudio

Based on the following discussion: recommendation-for-a-development-cycle-of-rstudio

Setup a build environment

(The following assumes a unix-based machine)

0. Read the INSTALL file for many more details.

1. Fork the RStudio GitHub repository into your own (e.g. https://github.com/MYUSER/rstudio ).

2. On your development machine, clone your repository:

   $ git clone https://github.com/MYUSER/rstudio

3. Install dependencies:

   $ cd rstudio
   $ cd dependencies/linux
   ## on Debian/Ubunto
   $ sudo ./install-dependencies-debian
   ## on RedHat/CentOS
   $ sudo ./install-dependencies-debian
   ## If on other platforms, see other files in 'dependencies'
   $ cd ../..

4. Verify your build environment - by building everything.

   $ cd rstudio
   # Create a clean out-of-tree build directory
   # (see http://msteveb.github.com/autosetup/user/outoftree/ )
   $ rm -rf build && mkdir build
   $ cd build
   # This will take some time...
   $ cmake .. -DRSTUDIO_TARGET=All -DCMAKE_BUILD_TYPE=Debug
   # if all goes well - compile everything
   $ make
   ## on a multi-core machine, parallelize the build to make it faster
   $ make -j 4

Setup a server-side build enviroment

To test the server (CPP) code, building a server-only environment makes development cycle faster.

1. Create a new build directory, and compile the server

   $ cd rstudio
   $ mkdir build_server
   $ cd build_server
   # Unlink the previous 'cmake', 
   # this time only build the server/rsession components
   $ cmake ../src/cpp -DRSTUDIO_TARGET=All -DCMAKE_BUILD_TYPE=Debug
   # make -j 4

2. Run the development version of rserver:

   $ cd rstudio
   $ cd build_server
   $ ./rserver-dev
   ## nothing is printed, but the server is running

   Open your web browser, and visit http://localhost:8787 to connect to the server.

3. Troubleshooting:

   If you see an Address already in use error message, it is likely the TCP port number (default: 8787) is in use (perhaps by another running rserver process?). To change Port number, Add the following line to ./rstudio/build_server/conf/rserver-dev.conf:

   `www-port=8080`
   

   1. The default TCP port is 8787
   2. Ports number smaller than 1024 require root permissions - you don't want to run development rserver as root.
   3. Any port number larger than 1024 will do.

4. Configuration:

   Two relevant configuration files are created: ./rstudio/build_server/conf/rserver-dev.conf and ./rstudio/build_server/conf/rsesession-dev.conf .

   See Rstudio Configuration Options for configuration options.

Changing RStudio code

1. Create your own git branch, to isolate any changes you from the main Rstudio development branch: (See more details about recommended GIT usage: http://nvie.com/posts/a-successful-git-branching-model/ ).

   $ cd rstudio
   $ git checkout -b feature/my_feature master

2. Change any server/session related CPP file.

   $ touch ./rstudio/cpp/r/session/REmbeddedPosix.cpp

3. Rebuild only the relevant parts:

   $ cd rstudio
   $ cd build_server
   # Build all server components
   $ make -j 4
   # Or, build only the server process
   $ make server
   # Or, build only the session process
   $ make rsession

4. Restart the ./rserver-dev script, and the rserver/rsession processes.

   NOTE: The rserver application starts a new process on every connection, so simply stopping the rserver-dev script by hitting CTRL-C is not sufficient. The following command will kill any rserver/rsession related processed (BUT - if you have unrelated rserver processes running, this might kill them as well).

   $ pkill 'rserver|rsession'

5. For some good ol' fashioned printf debugging, sprinkle some LOG_WARNING_MESSAGE("TEXT") into the code.