- Author: Thomas Girke
- Last update: 16-Mar-2022
- Note: this repos replaces old Nvim-R-Tmux Tutorial on Gist.
This page gives an overview of the installation and usage of the new Nvim-R plugin from Jakson Alves de Aquino, the developer of the original vim-R plugin. The new plugin now also supports the new extension of Vim called Neovim. The main advantages of Neovim compared to Vim are its better performance and its built-in terminal emulator facilitating the communication among Neovim and interactive programming environments such as R. Since the Vim and Neovim environments are managed independently, one can run them in parallel on the same system without interfering with each other. The Nvim-R project page can be found here and its main manual is here. The usage section below introduces how to use the plugin with or without Tmux.
Animated Screenshot of Nvim-R (from here):
The following provides a quick convenience install for configuring the Nvim-R-Tmux environment in a user's home directory. This assumes that recent versions of Neovim and optionally Tmux are already pre-installed on a user's system. If this is not the case, then steps 2.2 (or 5.2) and 2.3 (or 5.3) need to be completed first.
Note, executing the
Install_Nvim-R_Tmux.sh
script as shown below will activate custom config files/directories in a user's home
directory, including: .bashrc, .tmux.conf, .Rprofile, .config/ and
.local/. Prior to executing Install_Nvim-R_Tmux.sh, users want to make
sure that they want these changes performed in their home account.
Instructions how to undo these changes, in case something goes wrong, are printed
to the screen. An alternative is to install the individual components stepwise
by executing the lines in
Install_Nvim-R_Tmux.sh
individually, or to proceed with the manual configuration outlined in the subsequent sections.
git clone git@github.com:tgirke/Nvim-R_Tmux.gitThis installs the entire Nvim-R_Tmux environment into a users home account.
cd Nvim-R_Tmux
bash Install_Nvim-R_Tmux.shNeovim Version >= 0.1.7 is required for Nvim-R. For the installation, follow the instructions here. A sample config file for controlling Neovim, called init.vim, is given below. This or a similar init.vim file should be downloaded and saved to a user's home under ~/.config/nvim/init.vim.
Advanced: for more advanced users it may often become important to install the latest Neovim version. For this it can be very useful to download Neovim from its GitHub repos, and then install it from source following these instructions. Using a package management software available on a user's system may be more convenient, but this will often only allow the installation of older Neovim versions. More detailed instructions for installing Neovim from source are given below.
The usage of Tmux with Nvim-R is highly recommended on Linux or OS X systems but not absolutely necessary. Supported Tmux versions are >=2.0. To upgrade Tmux to a more recent version, one can follow the instructions here. To install it from source, consult see intructions below here. If you get on Ubuntu 16.04 a locale-gen en_US.UTF-8 error, then the last step here fixes it. A sample config file for controlling Tmux, called .tmux.conf, is given below. This or a similar .tmux.conf file should be downloaded and saved to a user's home under ~/.tmux.conf.
The R package colorout is available on GitHub here. If it is not yet installed in an R environment, one can install it from within R via the devtools package as follows:
devtools::install_github("jalvesaq/colorout")Download the latest *.vmb from here. Then open the downloaded file with nvim (neovim), and then run from nvim's command mode the following commands:
:packadd vimball
:so %
# press space bar a few times until install is complete!When new features become available in Nvim-R then one can get them immediately by installing the Nvim-R plugin from its GitHub repos directly. After downloading the repos, one can move its content (files and directories) manually to ~/.config/nvim or install it with a Neovim plugin manager that includes GitHub support. The following uses vim-plug as plugin manager. After installing vim-plug for neovim as outlined here one can install plugins by listing them at the end of the ~/.config/nvim/init.vim file as follows:
" Plugins will be downloaded under the specified directory.
call plug#begin(has('nvim') ? stdpath('data') . '/plugged' : '~/.vim/plugged')
" Declare the list of plugins.
Plug 'jalvesaq/Nvim-R'
Plug 'preservim/nerdtree'
Plug 'jalvesaq/vimcmdline'
Plug 'nvim-treesitter/nvim-treesitter'
Plug 'lukas-reineke/indent-blankline.nvim'
" List ends here. Plugins become visible to Vim after this call.
call plug#end() After this, the vim commands :PlugInstall, :PlugUpdate and :PlugClean will install, update and remove plugins accordingly. Note, when using vim-plug, the init.vim config file remains under .config/nvim and the plugins will be installed under ~/.local/share/nvim/plugged/.
The version information for the Nvim-R plugin can be returned from vim's command mode as follows.
:help nvim-rDownload the NERDTree vim plugin from here. Then extract to ~/.config/nvim with the following command. Note, if vim-plug is used as outlined here then Nerdtree will be installed automatically.
unzip NERD_tree.zip -d ~/.config/nvimJakson Alves de Aquino has developed the southernlights color scheme that works well with Nvim-R. To enable it, users want to save the file southernlights.vim from this repos to ~/.config/nvim/colors/ and add the recommended bash configurations to your .bashrc as described here. Note, this color scheme should be installed under ~/.config/nvim/colors/ even if a plugin manager is used that installs other plugins under ~/.local/share/nvim/plugged/.
Vertical indentation lines (guides) are useful for tracking context in code. To enable indentation lines in nvim, one can use the indent-blankline.nvim plugin. When using it the nvim-treesitter plugin should also be installed. Both are included in the vim-plug install example above (see 2.5.2). When nvim is configured with an init.vim file instead of init.lua, it is important to enclose lua parameter code (e.g. for indentation guides here) in init.vim with the start/end tags given below. For details on init.vim and init.lua, see here. Note, when the plugin is installed, then the indentation guides show by default. To toggle them on/off, use :IndentBlanklineToggle or additional commands of this plugin starting with Indent....
lua <<EOF
---lua lines
EOFNeovim and Tmux are already installed systemwide on the HPCC, but need to be loaded from the module system (step 1). What remains to be installed in each user's account are the plugins and configuration files as outlined below under steps 2-5. Alternatively, all required resources will be installed automatically by executing the command Install_Nvim-R_Tmux (old version was install_nvimRtmux) in a user's HPCC account.
- Add to your
.bashrcthe following lines
if [ -n "$MODULESHOME" ]; then
module load neovim/0.6.0
module load tmux/3.3
fi- Install Nvim-R plugin for Neovim as instructed here
- Save this
init.vimsample file to~/.config/nvim/init.vim - Install NERDTree plugin as instructed here
- Install
southernlightscolor scheme as instructed here - Now log out of the system and in again. After this start tmux and then open a
.Ror.Rmdfile withnvimcommand. Next open a connected R session with the key combination\rfand then follow the usage instructions given here.
The usage of Neovim is almost identical to Vim. Two important differences are:
- The command for opening Neovim is
nviminstead ofvim. - Plugins are usually stored under
~/.config/nvim/and the counter part of the.vimrcconfig file isinit.vimlocated at~/.config/nvim/init.vim.
Open a *.R or *.Rmd file with nvim and intialize a connected R session with \rf. This command can be remapped to other key combinations, e.g. uncommenting lines 10-12 in init.vim will remap it to the F2 key. Note, the resulting split window among Nvim and R behaves like a split viewport in nvim or vim meaning the usage of Ctrl-w w followed by i and Esc is important for navigation.
Important keybindings for nvim (vim):
\rf: opens vim-connected R session (R version toggle is outlined below)spacebar: sends code from vim to R; here remapped ininit.vimfrom default\l:splitor:vsplit: splits viewport (similar to pane split in tmux)gz: maximizes size of viewport in normal mode (similar to Tmux'sCtrl-a zzoom utility)Ctrl-w w: jumps cursor to R viewport and back; toggle between insert (i) and command (Esc) mode is required for navigation and controlling the environment.Ctrl-w r: swaps viewportsCtrl-w =: resizes splits to equal sizeCtrl-w 5< or 5>: resizes splits to left or right by 5 steps; change number as neededCtrl-w HorCtrl-w K: toggles between horizontal/vertical splitsCtrl-spacebar: omni completion for R objects/functions when nvim is in insert mode. Note, this has been remapped ininit.vimfrom difficult to type defaultCtrl-x Ctrl-o.:h nvim-R: opens nvim-R's user manual; navigation works the same as for any Vim/Nvim help document:Rhelp fct_name: opens help for a function from nvim's command mode with text completion supportCtrl-s and Ctrl-x: freezes/unfreezes vim (some systems)
To run R in a separate Tmux pane, include the following two lines in your init.vim. Note: with Neovim's built-in terminal emulator this option is not so important anymore, since Neovim's vim-r split is more robust and feature-rich. To incorporate the features of a terminal multiplexer like Tmux, one simply runs the environment within a Tmux session, where the vim-r splits are handled by Neovim rather than Tmux. Yet, running R in a sparate Tmux pane is still possible as outlined below.
- `let R_in_buffer=0`
- `let R_tmux_split=1`
Open a *.R or *.Rmd file with nvim and start R with \rf. Similarly as above, the \rf command can be remapped to other key combinations, e.g. uncommenting three lines containing F2 in init.vim will remap it to the F2 key. To navigate among the Nvim and R panes, the key combination Ctrl-w-o is important.
Important keybindings for Tmux panes:
Ctrl-a o: jumps cursor to next pane e.g. from Nvim to R console paneCtrl-a Ctrl-o: swaps panesCtrl-a z: maximizes (zooms into) active paneCtrl-a d: detaches from current sessiontmux a: attaches to tmux sessiontmux attach -t <id>: attaches to specific tmux session
Note, closing R in this setup will also close the corresponding Tmux pane. This is different from the behavior of the older vim-R plugin where the R pane stayed open and returned a shell after quitting R. This behavior can be useful to open a different R version or ssh into remote systems while maintaining the connected Nvim pane from where code can still be sent to the original pane. To achieve a similar behavior with the new Nvim-R plugin, one can use the following workaround:
- Switch cursor scope to R esssion (with
Ctrl-a o) and then execute from R panesystem("tmux set remain-on-exit on") - Quit R with
q(). This gives a dead pane that can be reactivated by starting a shell in it with the commandsCtrl-aand:respawn-pane bash
Important key bindings for NERDTree usage:
zz or :NERDTreeToggle: opens NERDTree ('zz' requires corresponding setting in .config/nvim/init.vim):NERDTreeFind: finds current file in tree?: opens NERDTree helpI(shifti): toggle between showing and hiding hidden files/directoriesq: closes NERDTreeCtrl-w-w: jump cursor to next viewport including the one for NERDTreeo or <enter>: opens selected filet: opens file in new tabgt and gT: switches between tabsi: opens file with horizontal splits: opens file in vertical splitm: opens menu mode for creating/deleting files,Ctrl-cexits out of this modeB: shows bookmarks:Bookmark <name>: creates bookmark for selected tree branchD: deletes selected bookmark
The following config files (or similar custom versions) should be saved to the following locations in a user's home directory:
This section is only relevant for advanced users who require a high level of customization, e.g. for R package development.
Different R versions installed on a system can be loaded via specific
keybinding in Nvim-R. The example below loads one of two R versions (e.g. R-release
or R-development) with the keybindings \r1 or \r2, respectively. With a Tmux pane split
both R versions can be loaded in a single terminal window simultaneously.
Screenshot of two different R versions loaded in one terminal window:
Note, the R version keybinding toggle was added by Jakson Alves de Aquino in April-2020.
To obtain this feature, one needs to first download an Nvim-R version from Github
(here) from April-2020 or later, and then
move it to ~/.config/nvim, or use a Neovim plugin manager with GitHub support.
Subsequently, the following lines need to be added to the ~/.config/nvim/init.vim
file where \r1 and \r2 can be customized as needed, and the associated paths need to point to
the corresponding R load bash scripts installed on a system. Currently, the latter
need to be named explicitly 'R' to work with Nvim-R. To allow calling specific R
versions from the command-line (outside of Nvim), one can use an alias in ~/.bashrc.
For instance, include the following alias setting to open R's development version by typing
R-dev on the command-line: alias R-dev='/usr/local/lib/R-devel/bin/R'. Optionally, one can also provide
a custom path for packages installed in a user's home directory like this: alias R-dev='R_LIBS_USER=R_LIBS_USER=~/R/%p-library/%v_<my_subdir> /usr/local/lib/R-devel/bin/R'. The latter can be important for managing several Bioconductor versions that use the same R version (see here for additional details).
Lines to include in init.vim:
function StartRFromPath(path)
let g:R_path = a:path
let $R_LIBS_USER='~/R/%p-library/%v' " default path for packages installed in a user's home directory
call StartR("R")
endfunction
nmap \r1 :call StartRFromPath('/usr/bin')<CR>
nmap \r2 :call StartRFromPath('/usr/local/lib/R-devel/bin/')<CR>To manage several Bioconductor versions for the same R version, one can define two or more R start up functions, e.g. one for release (StartRFromPath) and one for development (StartRdevFromPath), where R_LIBS_USER is assigned the corresponding path for packages installed in a user's home directory, e.g. ~/R/%p-library/%v_Bioc3.14 for development version.
Note, one can also load specific R versions manually by enabling
one of the following two lines. The first one is enabled here in combination
with the above R version toggle to allow loading of the default R version
with Nvim-R's default keybinding \rf if that version's load script is located
in /usr/bin/.
let R_path = '/usr/bin/' "to load default R (here release)
"let R_path = '/usr/local/lib/R-devel/bin/' "to load R-development
General instructions for installing Neovim from source are available here. The corresponding prerequisites for the install are outlined here.
The following provides additional details that were required for installing the latest Neovim on Debian/Stretch, Debian/Buster and Ubuntu/18.04 systems (here nvim v0.5.0). Installs on other Linux systems will be similar, but the required dependency packages added in the first step may differ. The best way to find out is to install according to the official instruction guidelines here, and then address the depencies according to possible warning and/or error messages occuring during the install.
1. Install dependencies
sudo apt install cmake clang libtool libtool-bin libboost-all-dev gettext2. Download latest Neovim from GitHub
git clone https://github.com/neovim/neovim.git3. Build Neovim from source (paths below install into ~/bin)
cd neovim
rm -r build/ # clear the CMake cache if 'build' is present from previous install
make CMAKE_EXTRA_FLAGS="-DCMAKE_INSTALL_PREFIX=$HOME/bin/neovim"
make install4. Include these lines in your .bashrc to load custom built Neovim with vim or nvim
export PATH="$HOME/bin/neovim/bin:$PATH"
alias vim=nvim5. Now open Neovim and check from command mode its version
:version # type from command mode
NVIM v0.5.0-427-g1f56f9a4b # first returned line from 9-Apr-2020 installUse the following steps to build and install tmux from source on Debian and/or Ubuntu. These instructions are derived from here.
cd ~/bin # optional step to manage custom installs under ~/bin
VERSION=3.3-rc # select tmux version to install from here: https://github.com/tmux/tmux/releases
sudo apt-get -y remove tmux
sudo apt-get -y install wget tar libevent-dev libncurses-dev
wget https://github.com/tmux/tmux/releases/download/${VERSION}/tmux-${VERSION}.tar.gz
tar xf tmux-${VERSION}.tar.gz
rm -f tmux-${VERSION}.tar.gz
cd tmux-${VERSION}
./configure
make
sudo make install
cd -
sudo rm -rf /usr/local/src/tmux-*
sudo mv tmux-${VERSION} /usr/local/srcCurrent and historical versions of R can be downloaded for all common operating systems from CRAN here. Install instructions via binaries and OS specific package managers are given in the corresponding OS specific subdirectories of the same page. This is usually the preferred install solution for most users.
A basic workflow for installing and upgrading to a specific version of R (here for R-4.0.x under Debian Buster) would look like this. First, add the following line to your /etc/apt/sources.list file: deb http://cloud.r-project.org/bin/linux/debian buster-cran40/. If not available yet, add the proper key to your keyserver. For example: sudo apt-key adv --keyserver keys.gnupg.net --recv-key 'E19F5F87128899B192B1A2C2AD5F960A256A04AF' Next, run these commands, where the first two lines will install some typical dependencies. For additional details, open the CRAN instructions for installing R for your specific operating system here.
sudo apt install libcurl4-openssl-dev
sudo apt-get install libcurl4-openssl-dev
sudo apt update
sudo apt upgrade
# sudo apt install -t buster-cran40 r-base r-base-dev # run this line if previous one doesn't trigger R installNow continue under section 5.4.5 with the installation of important dependencies and R packages.
Instructions for installing R from source are provided in the corresponding install manuals from CRAN and RStudio. Source installs are mainly relevant for R package development routines to test code on specific R versions (e.g. development version). Typical R users not involved in package development may not need this and can follow the instructions linked under installing pre-built R versions.
The following outlines how to install any R version from source on Debian/Ubuntu systems. The given example
installs the latest R development version after downloading it via svn or ftp/http. For comparison, a similar but not identical R source install setup by a user is described here.
1. Install dependencies (these may be installed already)
sudo apt install r-base r-base-dev \
subversion \
ccache \
xorg-dev \
default-jdk \
libx11-dev \
libcurl4-openssl-dev2. Download R source via svn or ftp/http from the corresponding source download page, and save it to a target directory. The below svn command downloads the development version of R from trunk, and saves it to a directory called R-devel. The latter directory name can be customized as needed. An advantage of the svn download appoach is that it makes it easier to keep up with future incremental version updates during a develpment/release cycle. The R version options downloadable via svn can be looked up here: https://svn.r-project.org/R/.
mkdir ~/svn
cd ~/svn
svn co https://svn.r-project.org/R/trunk R-devel # downloads developer version of R from trunk
## Alternatively, look up latest R version and download it
# wget ftp://ftp.stat.math.ethz.ch/Software/R/R-devel_yyyy-mm-dd.tar.gz
# gunzip R-devel_yyyy-mm-dd.tar.gz; tar -xvf R-devel_yyyy-mm-dd.tar3. Build and install R
The following will build and install the R source stored under ~/svn/R-devel in /usr/local/lib/R-devel. The latter path is defined under '--prefix' below. This path can be changed to the desired install location on a system. For instance, installing R under /opt/ or in a user account under ~/bin/ would be common alternative locations. When installing it in your own user account, then drop sudo in the corresponding command(s) below. For tracking purposes it may be most convenient to generate for the below install commands a *.sh script named after a specific R version install (e.g. R_devel_4_1.sh). This way it will be easier to customize and track the install commands used for each instance of an R source install.
mkdir ~/svn/R-devel-build # in case of svn build in dedicated directory
cd ~/svn/R-devel-build
../R-devel/configure \
--prefix=/usr/local/lib/R-devel \
--enable-R-shlib \
--enable-BLAS-shlib \
--enable-shared \
--enable-static \
--with-blas \
--with-lapack \
--with-libpng \
--with-jpeglib \
--with-cairo \
--with-x \
--without-recommended-packages
make
sudo make install Troubleshooting: if you get under make an error like libR.so: undefined reference to drot_ (e.g. on Ubuntu 18.04) then drop in configure the line:--with-blas. Most likely OpenBlas was already installed via sudo apt install lipopenblas-base. In this case the default OpenBlas will be used on a system.
To update the R development version via svn, run the following update steps, and then re-run under the ~/svn/R-devel-build directory the install of the previous code box.
cd ~/svn/R-devel
svn update
./tools/rsync-recommendedTo check which optional features have been enabled for building R, one can do this from within R with:
capabilities()4. Starting specific R versions
Add the following alias definition lines to your ~/.bashrc file. The first two lines may be optional if it is the default setting in a user's $PATH.
alias R='/usr/bin/R'
alias Rscript='/usr/bin/Rscript'
alias R-dev='/usr/local/lib/R-devel/bin/R'
alias Rscript-dev='/usr/local/lib/R-devel/bin/Rscript'Now, one can load the release or development versions of R by typing on the command-line R or R-dev, respectively. In addition, the same R versions are called with Rscript and Rscript-dev, respectively.
5. Install common system dependencies
This installs a variety of system dependencies that are required by many R packages. Note, the texlive-full package is
very large (5.2GB). If disk space is limited then one may want to skip its install or just install texlive instead (270MB).
sudo apt install build-essential \
libcurl4-gnutls-dev \
openjdk-7-* \
libxml2-dev \
libssl-dev \
texlive-full \
librsvg2-dev \
libcairo2-dev \
libxt-dev \
libgsl-devFor R Markdown one will need to have the command-line tool pandoc installed. On Debian/Ubuntu systems it can be installed via apt get install pandoc pandoc-citeproc. Alternatively, installing RStudio will include a pandoc version recommended by R Markdown. If command-line R cannot locate RStudio's pandoc version, then one can set the proper path in any R/Rmd script or in a user's .Rprofile file with Sys.setenv(RSTUDIO_PANDOC="<insert_path>"). The path (here <insert_path>) can be identified by running from RStudio: Sys.getenv("RSTUDIO_PANDOC").
6. Install common R packages
The R package collection devtools is required for many development tasks including the install of other R packages from GitHub directly. In addition, tidyverse is a collection of packages that are often required for many routine tasks, including ggplot2, dplyr and more.
Run the following package installs from R.
install.packages(c("devtools", "tidyverse"))Now install Bioconductor's package manager from R.
if (!requireNamespace("BiocManager", quietly = TRUE))
install.packages("BiocManager")
BiocManager::install()After this one can install Bioconductor packages from R as follows.
BiocManager::install(c("GenomicFeatures", "AnnotationDbi"))The Bioconductor version can be returned with this command.
BiocManager::version()For additional details see Bioconductor's package install page.
7. Simple uninstall
To remove the above R source installation, one can simply remove the following directories.
/usr/local/lib/<R-devel>
~/R/x86_64-pc-linux-gnu-library/<X.X> # Present when R packages were installed in user's home 8. Troubleshooting
a. Graphics: X11 font problem
If certain R graphics libraries, such as ggplot2 or lattice, return X11 font problems (like 'X11 font -adobe-helvetica ... not found'), then it may be necessary to include the following or a similar X11 default setting in your ~/.Rprofile file. For additional details on this issue, these user postings may be helpful: post1 and post2. Note, the last line, options(bitmapType = 'cairo'), is necessary to address this rmarkdown::render() issue. Alternatively, for building R Markdown vignettes, this line can be included at the beginning of a vignette's YAML header under parameter: vignette:.
# default X11() setting
setHook(packageEvent("grDevices", "onLoad"),
function(...) grDevices::X11.options(width = 8, height = 8, xpos = 0, pointsize = 10, type = "cairo"))
options(bitmapType = 'cairo')On shared user systems, one can define these settings system-wide by including them in an Rprofile.site file under file.path(R.home(), "etc/Rprofile.site"). The content in the Rprofile.site file could look like this:
local({
setHook(packageEvent("grDevices", "onLoad"),
function(...) grDevices::X11.options(type='cairo'))
options(device='x11')
})Additinal details on this is available in R's main documentation here.
b. ...
...