Skip to content

Latest commit

 

History

History
308 lines (227 loc) · 12.5 KB

README.org

File metadata and controls

308 lines (227 loc) · 12.5 KB

ESS with Spacemacs

../resources/spacemacs-logo.png

Goals of this presentation

  1. Convey why Spacemacs might be of interest to ESS users
    • What is Spacemacs and why it is useful
  2. Ultra-quick start guide to ESS via Spacemacs
    • Installation to a full R development environment
  3. Give pointers for further Spacemacs use
    • Further resources to extract the most of out this kit.

Who is this for?

Users of R who are interested in the one true editor but not sure where to start, or existing emacs/ESS devotees who want to know what all the fuss about Spacemacs is.

What is Spacemacs?

Spacemacs is a configuration of emacs. It is designed to offer a nice experience out-of-the-box and provides a framework for further customisation. Spacemacs has a consistent interface with an emphasis on mnemonics intended to create discoverable keybindings. The former means that once you learn how to use Spacemacs for working in one language, it is very easy to transfer that knowledge when working with another language. The later means that you don’t need to dig through the documentation to figure out how to perform simple tasks and. As a result you spend more time on your code and less on your coding environment. The design of Spacemacs is largely influenced by four core pillars.

Core pillars

Spacemacs has been designed along the lines of the following core pillars. The following is taken from the documentation.

Four core pillars: Mnemonic, Discoverable, Consistent and “Crowd-Configured”.

If any of these core pillars is violated open an issue and we’ll try our best to fix it.

mnemonics and discoverability

Keybindings start with SPC followed by a sequence of letters related to the function they invoke. For example, you can toggle to the next beautiful colour scheme with SPC T n. There are more keybindings than most people will ever be able to remember, but you can often guess the keybindings for common functionality.

  • buffers SPC b
  • files SPC f
    • find file SPC f f
    • dired jump SPC f j
  • git SPC g for the the magit layer
  • jump to definition in the file with SPC j i
  • modes SPC m
    • go to a definition SPC m g
    • send code to the REPL SPC m s
    • evaluate code SPC m e
  • quit SPC q for the many ways to quit emacs (sorry vim).
  • search SPC s for search
    • search the current buffer with SPC s s
    • search the project with SPC s p
  • windows SPC w

If you can’t guess the keybinding but you know part of the name of the function you can search for the documentation (which includes current bindings) with SPC h d f which you can probably guess stands for help, describe, function. If you want to know the precise function bound to keys there is also SPC h d k.

consistency

Consistency is one of the killer features of Spacemacs, the bindings are very consistent across layers which makes switching between languages very easy and makes it very easy to set up a development environment for a new language.

https://www.spacemacs.org/layers/LAYERS.html

Crowd-configured

There is not enough time to do statistics and to get your emacs configuration perfect. Spacemacs means that you can leverage the work of the community to get a really nice editor.

While writing the document, several members of the Spacemacs community pointed out great features that I wasn’t aware of which have, with hindsight, very obvious bindings. Unfortunately for me, the discoverable nature of this functionality only works if you pay enough attention to recognise it! Lucky for me, there is a thriving Spacemacs community to point these things out.

Are you trying to convert me?

It’s no secret that vim keybindings are popular among Spacemacs users. As the Spacemacs documentation says: “The best editor is neither Emacs nor Vim, it’s Emacs and Vim!” In fact, there is a vim port of Spacemacs: SpaceVim. Don’t worry though, both sets of keybindings are supported as well as mixed versions.

Ultra-quick start guide

There is a proper installation guide on GitHub, but here are the main steps. Followed by a simple example to demonstrate what ESS looks like in Spacemacs.

Clone the Spacemacs repository

WARNING: Please back up any existing configuration files before proceeding. The command below will attempt to clone Spacemacs into a directory, ~/.emacs.d

Cloning the Spacemacs repository from github using the command shown below creates a .emacs.d directory in your home directory. It is this repository that contains the actual Spacemacs configuration. For the most part you can just ignore this though. Emacs will find this information on start up and guide you through the rest of the installation.

git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d

../resources/clone-spacemacs.png

At this point, you may want to double check that the contents of the directory ~/.emacs.d looks like the code on the GitHub page.

Develop is default

Please note that the default branch of Spacemacs is develop, so you will be on this branch when you clone the repository. You should stick to this branch unless you have a good reason not to. There is a master branch, but it has gone stale and should not be consumed.

Start emacs and face the Wizard

When you first start emacs after cloning the Spacemacs repository you should see the Spacemacs logo and there will be a message from a start up wizard in the mode line. The wizard will ask you a two questions: vim or emacs keybindings and do you want a standard or a light installation. The defaults of vim and and standard work well.

../resources/spacemacs-startup-1.png

The wizard will generate another file in your home directory, .spacemacs. This file is useful for finetuning how Spacemacs works and brings us to an important concept in Spacemacs: layers.

An interlude into layers

The documentation describes layers in the following way.

A collected unit of configuration that can be enabled (or disabled) in Spacemacs. A layer typically brings together one or more packages, as well as the glue configuration code required to make them play well with each other and Spacemacs in general.

Layers are sets of major and minor modes that play well together and make it easier to do task X. There is an ESS layer, which includes ESS but also a bunch of other nifty packages that you will likely want to have loaded when doing statistical work.

There are a huge range of layers that have been carefully crafted, you might want to check out the listing to see if there are others that might be useful. If you like language Y, there is probably a layer for that. Moreover, it will probably expose near identical key-bindings to the layer for language Z, which makes it much simpler to use multiple languages.

Open the configuration file: SPC f e d

Okay, so now we know what layers are, how do we tell Spacemacs which ones we want? This is done using the dotspacemacs-configuration-layers variable in the .spacemacs file, which was automagically generated when you installed Spacemacs. You can visit the .spacemacs file using SPC f e d (ie press the space bar, then the f-key, then the e-key then the d-key).

Set up your layers in dotspacemacs-configuration-layers

There are lots of options in the .spacemacs file, and the vast majority can be ignored. The dotspacemacs-configuration-layers variable is defined around line 30. Once you have found the variable, set its value to something like the example below. There will likely be some recommended layers already there, it’s fine to leave them, you just need to make sure you have some layer called shell and the ess layer.

../resources/add-ess-layer.png

Restart: SPC q r

You probably don’t need to restart emacs at this point, you could instead just reload the configuration with SPC f e R, but doing a full restart shouldn’t take long and is more reliable.

Profit!

Amazingly that is all that you needed to do! You now have access to many carefully crafted layers which cover nearly all things you might want to do in emacs, there is even a spotify layer.

Example

Opening a shell and setting up the example

  • SPC ' to start a shell
    • change to the example directory of this repository.
    • use ls to confirm demo.R is there.
  • SPC f f to visit (find) the file demo.R
    • Add an expression to the file, e.g. print("hello world").
    • Save the buffer with SPC f s, i.e. file and save.

../resources/shell-and-new-file.png

Visiting a file and starting a REPL

  • SPC m ' to start a REPL
    • It will ask you to choose the intial working directory
    • Navigate between windows by SPC w and selecting an action
  • Send the whole buffer with SPC s b.
  • Send the selected region with SPC s r.

../resources/buffer-and-repl.png

Kill the REPL

You can use C-x k to select a buffer to kill. For example you could use this and then select the R REPL. Alternatively, there is the more memorable SPC b d which I suppose corresponds to buffer and delete.

More ESS

More IDE features with LSP

The ESS layer has a lot more statistics oriented features. To learn more about these, check out the ESS layer documentation. There are instructions there on setting up LSP, which is surprisingly easy! Just add the LSP layer to your layer list and tell ESS that you want to use LSP with the following.

(ess :variables ess-r-backend 'lsp)

Note that for this to work, you’ll need the R package, languageserver installed. It is available on CRAN. If you use other languages such as Stan and MATLAB, there are links there to the extra languages layer. If at some later point you want to turn off the LSP backend but want to keep the lsp layer for use with other languages, you can set the ess-r-backend value to 'ess.

(ess :variables ess-r-backend 'ess)

More Spacemacs

The Spacemacs community is very friendly, I asked for reviews of this document on gitter and GitHub and got some really nice responses. The following places might be useful starting points to learn a bit more.

Gotchas

Did you really clone Spacemacs?

If you already have a .emacs.d directory, the command to clone Spacemacs may not work as expected. Please double check that the contents of that directory look like the code on GitHub if you are having trouble getting Spacemacs to start.

Vim keybindings while viewing Info pages

I find Info pages confusing in general, but they seem even more confusing via Spacemacs. The keys np[]lrmsb<SPC> all kind of work provided you hit \ first to jump into emacs keybindings. To navigate around the text, you get hjkl by default. The most Spacemacs-ey keybindings for working with Info pages seems to be a topic of debate, but if you are reading this, you might find the persistent which-key approach interesting.

Source Code Pro and fonts in general

Spacemacs seems to like to use source code pro, this beyond the scope of this presentation, but there are good instructions for installing it all over the internet. It appears that Spacemacs works fine even if you do not have Source Code Pro available, so there is no need to get hung up on this. There is a section of the documentation that deals with fonts for Spacemacs: https://develop.spacemacs.org/doc/DOCUMENTATION.html#font

Warnings when updating packages

Whenever I update my packages there are often warnings. For the most part these don’t seem to cause any real problems. It would be nice to address these, but until it breaks I’m reluctant to sink much time into this. I’ve never needed to use the “rollback updates” button, but it is comforting to know it is there…

Acknowledgements

I am grateful to the people who have spent countless hours building the worlds of emacs and R, we stand on the shoulders of giants. I’d also like to thanks the following people for helping to get this document into a reasonable state:

  • Jackson Kwok @kcf-jackson
  • Daniel Nicolai @dalanicolai
  • Lucius Hu @lebensterben
  • Maximilian Wolff @smile13241324
  • Alexey @alexey0308