This is a member of CategoryESS
I worked up some lecture notes on Emacs and ESS, “Emacs has No Learning Curve” ( http://pj.freefaculty.org/guides/Rcourse/emacs-ess). For Windows users, I made a Youtube video that demonstrates some editors, emphasizing Emacs: (
"StartR-02", http://www.youtube.com/watch?v=lNlJFEpdytc). Even if you only use a Mac, you might want to watch that in order to get a visual impression of what Emacs with ESS is all about.
I have more experience with Windows than I do with Macintosh, but I’ve worked on both. The key advice, which applies on all operating systems, is that one should not start R from the system menu/desktop icon/Finder. Instead, navigate in a file manager to the place where the R code file is, and launch an editor there. That generally allows R to detect the working directory properly, and there will be no need for “setwd()” at the beginning of the program.
If you have a Mac system, it is perhaps good enough to use the editor R.app that R itself provides. I think you will be happier over the long run using Emacs, but that decision is up to you. On Windows, on the other hand, the editor that R provides is not adequate, and thus you are urged to give Emacs a try.
There are a few little details that people miss.
1. Install R from http://www.r-project.org. On Windows, users have a choice of where to install R. The default will suggest a folder that is R version dependent, like
C:\Program Files\R\R-3.0.2. Some other programs are taught to look for R in that location, so a novice might be wise to leave R in that location. However, there are good reasons I generally prefer to cut off the version, and just install to
C:\Program Files\R and some experts, especially ones who integrate R with programming languages like C++, suggest we install in a place with no spaces in the directory structure. Either way, I recommend that users learn how to add the R bin\x86 subdirectory to the system path, so that Rterm.exe will be found by other programs.
After you install R, you have the problem of installing additional packages from CRAN. I have a script called
R_InstallFaves-2.R that I run inside R. It downloads a ton of packages. If you don’t know how to run that inside R, then I’d suggest that should be your first homework assignment. (Either paste the whole program into an open R session or read ?source inside R.)
2. Install the newest version of Professor Goulet’s Emacs Modified for Windows or macOS. It has ESS (Emacs Speaks Statistics) setup inside there, along with other handy Emacs addons. Professor Goulet’s effort to package all of that amazes me.
Because I administer so many Windows systems, I generally keep a copy of that at http://pj.freefaculty.org/software/WinProgs.
On Windows: Inside the Emacs installation, notice there is a bin directory with a program called “addpm.exe”. Run that to add known file types to your Windows Registry. I also suggest starting emacs from a right-click “open with” on R files, so the system learns that is what you want to do.
Here’s the basic idea. You open a file named whatever.R in Emacs, Emacs notices the suffix, it adds some menus and pulldowns. You start R from inside Emacs, and the R terminal is displayed in an Emacs buffer. That is very customizable, which is the next topic.
3. Get my customized startup configuration file for Emacs. I’ve revised this over the years, improvements in Emacs and ESS have rendered some of my customizations unnecessary or harmful.
You can force that configuration to be used in all user accounts in a computer if you install it in your Emacs directory. It MUST go under site-lisp/site.start.d. You don’t have to be as brutish as that. After you experiment with Emacs a bit, you will see it creates a custom user configuration folder in your home directory, generally called “.emacs.d”, and you can copy the init.el file into that folder.
In case I change my web host, perhaps it is wise to just show you what I have. This is the September, 2013 version. Note I have a lot of stuff commented out here. It used to be needed, but they’ve made a lot of changes in Emacs and ESS. Some fancy stuff I liked (framepop) conflicted with ESS → SAS usage, so I had to stop that. Also, it appears the file chooser menus in Windows have been fixed, so I don’t need to work around that either.
;; Paul Johnson ;; 2013-09-30 ;; Workaround for shift-enter trouble on Windows ;; UPDATE: Because Emacs ESS changes made this MUCH easier, my ;; re-work gets shorter :=) ;; INSTRUCTIONS. Put this file in ~/.emacs, or in ~/emacs.d/init.el, ;; or in the Emacs site-start.d folder. ;; R USER PREVIEW. ;; Here are my special features related to ESS with R. ;; 1. Indentation policy follows Programming R Extensions Manual ;; UPDATE 2013-07-10. No longer needed. This is ESS default as of version 13-05 ;; 2. Shift+Enter will send the current line to R, and it will start R ;; if it is not running. ESS 13-05 chose instead CTL+Enter, which I ;; DO NOT want because it conflicts with CUA mode. ;; 3. R will assume the current working directory is the document directory. ;; 4. R runs in its own "frame" ;; 5. Emacs help pops up in its own frame. ;; JUSTIFICATION. The intention is to make Emacs work more like a ;; "modern" GUI editor. ;; See my companion lecture ;; "Emacs Has No Learning Curve" ;; http://pj.freefaculty.org/guides/Rcourse ;; Paul Johnson <firstname.lastname@example.org> ;; 2012-11-24 ;; ;; Conflicts between Emacs-ESS and SAS usage forced me to make ;; some changes. And for no benefit, as SAS mode still not great. ;; I had to cut out a lot of framepop stuff. ;; ;; Section I. Windows OS work-arounds ;;(if (eq system-type 'windows-nt) ;; (setq use-file-dialog nil)) ;; There's been a chronic problem with file selection dialogs on Windows ;; Maybe you commment previous out and see if your Windows is fixed. ;; Section II. Keyboard and mouse customization ;; IIA: make mouse selection work in the usual Mac/Windows way ;; 2013-07-10 Comment these out ;; (setq shift-select-mode t) ; is default in Emacs 23+, replaces pc-select ;; (transient-mark-mode t) ; highlight text selection, is default Emacs 23+ (delete-selection-mode t) ; delete selected text when typing ;; http://ergoemacs.org/emacs/emacs24_features.html ;; after copy Ctrl+c in X11 apps, you can paste by `yank' in emacs ;; (setq x-select-enable-clipboard t) ;; after mouse selection in X11, you can paste by `yank' in emacs ;;(setq x-select-enable-primary t) ;; This seems not reliable to me (2013-07-10) ;; TODO: ;; Figure out Emacs-24 trouble with mouse selections. I need to ;; figure out where the truth lies ;; In Linux, I see weirdness in Emacs 24 with paste and clipboard. Confusing! ;; http://stackoverflow.com/questions/13036155/how-to-to-combine-emacs-primary-clipboard-copy-and-paste-behavior-on-ms-windows (setq select-active-regions t) (global-set-key [mouse-2] 'mouse-yank-primary) ; make mouse middle-click only paste from primary X11 selection, not clipboard and kill ring. ;;(setq mouse-drag-copy-region t) ;; See following http://emacswiki.org/emacs/CopyAndPaste ;; where there is a ton of really confusing advice. ;; highlight does not alter KILL ring (setq mouse-drag-copy-region nil) ;; IIB: keyboard customization ;; CUA mode is helpful not only for copy and paste, but also C-Enter is rectangle select (cua-mode t) ; windows style binding C-x, C-v, C-c, C-z (setq cua-auto-tabify-rectangles nil) ;; Don't tabify after rectangle commands ;;20130717(setq cua-keep-region-after-copy t) ;; Selection remains after C-c ;; write line numbers on left of window ;; Caution: if you do this, it makes Emacs much slower! ;;(global-linum-mode 1) ; always show line numbers ;; Section III. Programming conveniences: (show-paren-mode t) ; light-up matching parens (global-font-lock-mode t) ; turn on syntax highlighting (setq text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify))) ;; Section IV. ESS Emacs Statistics ;; start R in current working directory, don't let R ask user (setq ess-ask-for-ess-directory nil) ;; ESS 13.05 default C-Ret conflicts with CUA mode rectangular selection. ;; Change shortcut to use Shift-Return ;; Suggested by Vitalie Spinu ESS-help email 2013-05-15 ;; worked in Linux, not Windows 2013-09-29 ;;(define-key ess-mode-map [(control return)] nil) ;;(define-key ess-mode-map [(shift return)] 'ess-eval-region-or-line-and-step) ;; cause "Shift+Enter" to send the current line to *R* (defun my-ess-eval () (interactive) (if (and transient-mark-mode mark-active) (call-interactively 'ess-eval-region) (call-interactively 'ess-eval-line-and-step))) (add-hook 'ess-mode-hook '(lambda() (local-set-key [(shift return)] 'my-ess-eval))) ;; create a new frame for each help instance ;; (setq ess-help-own-frame t) ;; If you want all help buffers to go into one frame do: (setq ess-help-own-frame 'one) ;; I want the *R* process in its own frame ;; This was a broken feature in ESS, fixed now. Helps massively! (setq inferior-ess-own-frame t) ;;(setq inferior-ess-same-window nil) ;; See no beauty in this. Test: move pointer into a function ;; Run C-c C-d C-e to see effect ;;(setq ess-describe-at-point-method 'tooltip) ;; PJ 2013-07-10 Following commented out ;; PJ 2012-03-21 because ESS 13.05 made it default ;; Indentation per Programming R Extensions ;; (add-hook 'ess-mode-hook ;; (lambda () ;; (ess-set-style 'C++ 'quiet) ;; (add-hook 'local-write-file-hooks ;; (lambda () ;; (ess-nuke-trailing-whitespace))))) ;;;;(setq ess-nuke-trailing-whitespace-p 'ask) ;;;; or even ;;(setq ess-nuke-trailing-whitespace-p t) ;;; Perl ;;(add-hook 'perl-mode-hook ;; (lambda () (setq perl-indent-level 4))) ;; End ESS ;; In Spring 2012, we noticed ESS SAS mode doesn't work well ;; at all on Windows, that lead to removal of lots of stuff ;; I really liked. Even then, we couldn't get much satisfaction. ;; ;; Following was needed for that, otherwise, it is not needed ;; (load "ess-site") ;; (ess-sas-global-unix-keys) ;; PJ 2013-02-28 ;; stops suggestions in R when tabbing. Quiets noise, but ruins feature ;; (setq completion-auto-help nil) ;; ;; ;; Section V. Customize the use of Frames. Try to make new content ;; ;; ;; appear in wholly new frames on screen. ;; ;; ;; ;; ;; ;; V.A: Discourage Emacs from splitting "frames", encourage it to pop up new ;; ;; ;; frames for new content. (setq split-window-preferred-function nil) ;discourage horizontal splits ;; V.C: Make files opened from the menu bar appear in their own ;; frames. This overrides the default menu bar settings. Opening an ;; existing file and creating new one in a new frame are the exact ;; same operations. adapted from Emacs menu-bar.el (defun menu-find-existing () "Edit the existing file FILENAME." (interactive) (let* ((mustmatch (not (and (fboundp 'x-uses-old-gtk-dialog) (x-uses-old-gtk-dialog)))) (filename (car (find-file-read-args "Find file: " mustmatch)))) (if mustmatch (find-file-other-frame filename) (find-file filename)))) (define-key menu-bar-file-menu [new-file] '(menu-item "Open/Create" find-file-other-frame :enable (menu-bar-non-minibuffer-window-p) :help "Create a new file")) (define-key menu-bar-file-menu [open-file] '(menu-item ,(purecopy "Open File...") menu-find-existing :enable (menu-bar-non-minibuffer-window-p) :help ,(purecopy "Read an existing file into an Emacs buffer"))) ;; V.D Open directory list in new frame. (define-key menu-bar-file-menu [dired] '(menu-item "Open Directory..." dired-other-frame :help "Read a directory; operate on its files (Dired)" :enable (not (window-minibuffer-p (frame-selected-window menu-updating-frame))))) ;; Section VI: Miscellaneous convenience ;; Remove Emacs "splash screen" ;; http://fuhm.livejournal.com/ (defadvice command-line-normalize-file-name (before kill-stupid-startup-screen activate) (setq inhibit-startup-screen t)) (setq inhibit-splash-screen t) ;; Show file name in title bar ;; http://www.thetechrepo.com/main-articles/549 (setq frame-title-format "%b - Emacs") ;; Make Emacs scroll smoothly with down arrow key. ;; 2011-10-14 ;; faq 5.45 http://www.gnu.org/s/emacs/emacs-faq.html#Modifying-pull_002ddown-menus (setq scroll-conservatively most-positive-fixnum) ;; adjust the size of the frames, uncomment this, adjust values ;;(setq default-frame-alist '((width . 90) (height . 65))) ;; Remember password when connected to remote sites via Tramp ;; http://stackoverflow.com/questions/840279/passwords-in-emacs-tramp-mode-editing ;; Emacs "tramp" service (ssh connection) constantly ;; asks for the log in password without this (setq password-cache-expiry nil) ;; Section : Emacs shells work better ;; http://snarfed.org/why_i_run_shells_inside_emacs (setq ansi-color-for-comint-mode 'filter) (setq comint-prompt-read-only t) (setq comint-scroll-to-bottom-on-input t) (setq comint-scroll-to-bottom-on-output t) (setq comint-move-point-for-output t)
This has many features that will help a Windows user who is picking up Emacs for the first time. As of 2014-01-20, so far as I know, the Windows-specific menu dialogue problems have been solved.
The Emacs-cua mode has a super handle “column rectangle” cut and paste procedure that is initiated with Ctl-Enter. This contradicts the new ESS use of Ctl-Enter that sends lines from the R code buffer to the R session. My setup sends code with SHIFT-Enter instead. I’ve been doing it that way since 2006, don’t hate me for being old fashioned.
In particular, the changes I recommend for new Emacs users are intended to make Emacs behave like an ordinary Windows program, so it
- does not use horizontal splits
- opens R in a new separate frame
- starts R help items in separate frames
- uses the mouse to select regions in the usual way
- uses Control-x, Control-v in the usual way (cua mode)
4. I have some other information on configuring windows. In particular, you should
- make windows file explorer always show full file names (turn off "hide known extensions")
- add "Open with Emacs" as a right click menu option for all files. We have a Windows registry hack for that.
5. Here’s the best way to get started writing R programs in Emacs
Create a new folder where you want to do your work. In my systems, it is a hierarchy like
or, for Mac
but you can do whatever you like. It is best to NOT use spaces in your names here.
Download an example R file from my page (http://pj.freefaculty.org/R/WorkingExamples) and put it into the directory you just created. Try the barplot files. Fun and informative! If you can’t find my folder of R working examples, type this in a file.
x <- rpois(100, lambda=10) xtab <- table(x) barplot(xtab, xlab = "Observed Counts")
We want to open that R file in Emacs. On Windows, use the right click “open with,” look under “bin” in the Emacs program folder, and choose the file “runemacs.exe”. Don’t choose “emacs.exe”. DO choose “runemacs.exe”.
Emacs will open with barplot.R in front of you. There are many ways to start the R session, such as
1. Alt-x R
2. Click the big blue R in the toolbar.
3. Try to execute any line in barplot.R (Shift-Enter)
The customized emacs startup file I recommend tells R it should start in the current working directory, so once the R buffer is visible, type this command to make sure:
you should see that R is using your folder as its working space. That means it will write files there and it will look for input files there by default.
– Paul E. Johnson email: pauljohn -at- ku -dot- edu