This is the README file for the distribution of ESS version 17.11
ESS is a GNU Emacs and XEmacs mode for interactive statistical programming and data analysis. Languages supported: the S family (S, S-PLUS and R), SAS, BUGS/JAGS and Stata. ESS grew out of the desire for bug fixes and extensions to S-mode and SAS-mode as well as a consistent union of their features in one package.
Installation instructions are provided in sections for both Unix and Windows; see below.
The current development team is led by Martin Maechler since August 2004. Former project leader A.J. (Tony) Rossini (firstname.lastname@example.org) did the initial port to XEmacs and has been the primary coder. Martin Maechler (email@example.com) and Kurt Hornik (Kurt.Hornik@R-project.org) have assisted with the S family and XLispStat. Stephen Eglen (firstname.lastname@example.org) has worked mostly on R support. Richard M. Heiberger (email@example.com) has assisted with S/S-PLUS development for Windows. Richard and Rodney A. Sparapani (firstname.lastname@example.org) have done much of the work improving SAS batch and interactive support. Rodney has also extended ESS to support BUGS/JAGS and has an interest in improving Stata support.
We are grateful to the previous developers of S-mode (Doug Bates, Ed Kademan, Frank Ritter, David M. Smith), SAS-mode (Tom Cook) and Stata-mode (Thomas Lumley).
|• Latest Version:|
|• Starting up:|
|• Current Features:|
|• New Features:|
|• Reporting Bugs:|
|• Mailing Lists:|
The source and documentation of ESS is free software. You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.
ESS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License in the file COPYING in the same directory as this file for more details.
All recent released versions are meant to be release-quality versions. While some new features are being introduced, we are cleaning up and improving the interface. We know that there are many remaining opportunities for documentation improvements, but all contributors are volunteers and time is precious. Patches or suggested fixes with bug reports are much appreciated!
ESS is most likely to work with current/recent versions of the following statistical packages: R/S-PLUS, SAS, Stata, OpenBUGS and JAGS.
ESS supports current, and recent, stable versions of GNU Emacs (currently, 24.3 or higher; alpha/beta/pre-release versions are NOT SUPPORTED).
Due to XEmacs lacking some features that ESS requires, ESS support of XEmacs ended with ESS 12.04-4.
To build the PDF documentation, you will need a version of TeX Live or texinfo that includes texi2dvi (BEWARE: recent TeX Live, and some texinfo RPMs, do NOT include texi2dvi).
The latest released version of ESS is always available on the web at: ESS web page or StatLib
For development and experimentation on new ESS features, there is now a GitHub branch for ESS, available at https://github.com/emacs-ess/ESS.
Alternatively you can use
git to fetch the most
recent development version to your local machine with:
git clone https://github.com/emacs-ess/ESS.git /path/to/ESS
cd /path/to/ESS/ make
Without this step, info, pdf and html documentation and reference card will not be available.
make install. You might need administrative privileges:
The files are installed into
/usr/share/emacs directory. For this step to
run correctly on macOS, you will need to adjust the PREFIX
path in Makeconf. The necessary code and instructions are
commented in that file.
make installstep from above, just add
to your ~/.emacs file. Otherwise, you should add /path/to/ESS/lisp/ to your emacs load path and then load ESS with the following lines in your ~/.emacs:
(add-to-list 'load-path "/path/to/ESS/lisp/") (load "ess-site")
Note for Windows and macOS users: The most straightforward way to install Emacs on your machine is by downloading the Emacs binary by Vincent Goulet; either Emacs Modified for macOS or from Emacs Modified for Windows.
Note for XEmacs users: Due to XEmacs lacking some features that ESS requires, ESS support of XEmacs ends with ESS 12.04-4.
To start an S session on Unix or on Windows when you use the Cygwin bash shell, simply type M-x S RET.
To start an S session on Windows when you use the MSDOS prompt shell, simply type M-x S+6-msdos RET.
Changes and New Features in development version:
text-mode. If you want to restore the old behaviour and activate the package mode in all buffers (that have a
default-directorythat is part of a package path), set
lintrpackage (available on CRAN) to use it. Customizable options include
Changes and New Features in 17.11:
(require 'ess-stata-mode)in your init file. This is for experienced Emacs users as this requires setting up autoloads for
.Rfiles manually. We will keep maintaining
ess-sitefor easy loading of all ESS features.
ess-r-package-use-dir. It sets the working directory of the current process to the current package directory.
ess-r-package-source-rootscontains package sub-directories which are searched recursively during the file lookup point. Directories in
ess-tracebug-search-pathare now also searched recursively.
R/directory. This way ESS will not attempt to update function definitions from a package if you are working from e.g. a test file.
Changes and New Features in 16.10:
%op%operators are recognised as sexp. This is useful for code navigation, e.g. with C-M-f and C-M-b.
ess-roxy-fold-examplesto non-nil to automatically fold the examples field when you open a buffer.
ess-roxy-fontify-examplesto non-nil to try it out.
ess-r-devtools-askbound to C-c C-w C-a. It asks with completion for any devtools command that takes
ess-r-package-modeis now activated in non-file buffers as well.
Bug fixes in 16.10:
Changes and New Features in 16.04:
developerfunctionality has been refactored. The new user interface consists of a single command
ess-r-set-evaluation-envbound by default to C-c C-t C-s. Once an evaluation environment has been set with, all subsequent ESS evaluation will source the code into that environment. By default, for file within R packages the evaluation environment is set to the package environment. Set
nilto disable this.
ess-r-package-modeThis development mode provides features to make package development easier. Currently, most of the commands are based on the
devtoolspackages and are accessible with C-c C-w prefix. See the documentation of
ess-r-package-modefunction for all available commands. With C-u prefix each command asks for extra arguments to the underlying devtools function. This mode is automatically enabled in all files within R packages and is indicated with
[pkg:NAME]in the mode-line.
Bug fixes in 16.04:
Changes and New Features in 15.09:
ess-offset-give the actual offsets, those starting with
ess-indent-are control (commonly Boolean) variables, and those starting with
ess-align-are vertical alignment overrides which inhibit default offsets in specific situations. See
ess-style-alistfor detailed description of the new indentation system and provided default indentation styles.
ess-expression-offsetand all delimiter-specific offsets are deprecated. The settings for indentation of continued statements have been replaced by
ess-offset-continuations. It can be set to either
ess-arg-function-offsethas been replaced by
ess-indent-from-lhsand has been generalised to assignments. This setting now works with both statement blocks and expressions and only takes effect for offsets set to
open-delimin order to produce a consistent indentation.
prev-lineis also provided. In addition, the new RRR+ style is equivalent to RRR except it indents blocks in function calls relatively to the opening delimiter. This style does not try to save horizontal space and produces more indentation.
examplesfield without squashing the surrounding code in the comments.
ess-fill-continuations. When activated,
(fill-paragraph)formats your calls and your formulas/continuations while making sure they don’t go past
fill-column. Repeated refills cycle through different styles (see the docstrings for more details). By default, the refilled region blinks. Set
ess-blink-fillingto nil to prevent this.
make, then the latest version of julia-mode.el is downloaded (and so you need an active internet connection to install) during the installation process. Alternatively, if you run ESS without running
make, then ensure that you have the
julia-mode.el, which you can get easily from MELPA for example.
projectile’s project root and it does so when
ess-gen-proc-buffer-name-functionis set to
ess-gen-proc-buffer-name:projectile-or-simpleas by default, or to another value beginning with
Changes and New Features in 15.03-1:
Changes and New Features in 15.03:
requirecalls for better completion caching.
Bug Fixes in 15.03:
ess-smart-commato eldoc message functions.
ess-developer-add-package, remove incorrect ‘wait‘ argument from
ess-kill-buffer-and-gomodified to not restart R
Changes / Selected Bug Fixes in 14.09:
gdbdebugger now works as expected
ess-execute-screen-optionsuses correct screen width in terminal sessions
ess-build-tags-for-directoryworks when no TAGS file name was provided
ess-offset-statement-continuedis now respected everywhere except inside of the
ess-offset-statement-first-continuedfor indentation of the first line in multiline statements.
Changes / Selected Bug Fixes in 13.09-1:
~/.config/ESSR/directory on the remote machine
ess-executeis now bound to C-c C-e C-e in
tailmethods were replaced by
ess-transcript-clean-regionetc. correctly treat multiline statements, i.e., no longer forgets the lines typically preceded by ’+’
ess-sas-edit-keys-toggledefault returns to
prettify-symbols-mode: contribution from Rudiger Sonderfeld https://github.com/emacs-ess/ESS/pull/65
ess-roxy-preview-HTMLis now on C-c C-o C-w and
ess-roxy-preview-textis now on
C-c C-o C-t
make installwas simplified and should work out of the box on most *nix systems
Changes/New Features in 13.09:
ess-developer-packages. The old behavior (activation on per-process basis) is still available on
M-x ess-developerin a process buffer.
devtoolspackage. New command
load_allon the package containing current file.
ess-developer-add-packagenow offers IDO menu completions with available loading methods, currently
load_all. Loading command can be customized with
M-x ess-versionnow reports full loading path and recognizes git and ELPA versions.
font-lock-warning-faceas they should be, (for quite some time these keywords have been hijacked by compilation mode fontification).
ess-rep-regexpshould no longer inf.loop (rarely!), and hence
M-x ess-fix-miscellaneousshould neither.
Changes/New Features in 13.05:
gretl(both editing and sub-process interaction). A contribution of Ahmadou Dicko.
ess-show-tracebackand C-c ~ is bound to
ess-swv-processing-commandto control weaving and tangling.
ess-default-stylehas been changed (from
RRR. Use something like
(setq ess-default-style 'DEFAULT)or
(setq ess-indent-level 2)in your ~/.emacs equivalent before loading ESS, if you do not like this new “incompatible” default style.
ess-use-tracebug’s default has been changed to
t. Set it to nil if you want to keep the previous behavior.
ess-tracebug-mapis an alias to
ess-bp-toggle-state(C-c C-t o) can now be used during the debug session to toggle breakpoints on the fly (suggestion by Ross Boylan).
ess-debug-unflag-for-debuggingwork correctly from the debugging contexts. These commands also recognize non-exported functions for the packages listed in
ess-developer-packages(C-c C-t C-a).
ess-use-eldoc) has become more sophisticated, and hence also more intruding in the interface between the Statistics softare, e.g., R, and the user.
Note that you can turn off ElDoc, by placing
(setq ess-use-eldoc nil)
in your ~/.emacs file, prior to loading ESS,
ess-sas-edit-keys-togglenow defaults to
sas-indent-lineis still broken, i.e. TAB is now bound to
Changes/Bug Fixes in 12.09-2:
ess-switch-to-end-of-proc-buffervariable that controls whether C-c C-z switches to the end of process buffer. The default is
t. You can use prefix argument to C-c C-z to toggle this variable.
ess-eval-linewisethat was causing emacs to hang during R debugging with
ess-eval-linewisethat was causing emacs to recenter the prompt in visible window
ess-switch-processthat was causing
*new*selection to fail.
ess-local-process-namebug in R-dired.
ess-swv-PDFdoesn’t ask for a command to run if there is only one command in
ess-swv-weavegained an universal argument to allow for an interactive choice between available weavers (sweave, knitr).
ess-eval-*-and-stepfunctions go to next empty line at eob, instead of staying at the last line.
Changes/New Features in 12.09-1:
ess-doc-mapbound to C-c C-d;
ess-extra-mapbound to C-c C-e;
ess-dump-object-into-edit-bufferwas moved on C-c C-e C-d
ess-developer) moved on C-c C-t
C-c C-yis deprecated in favor of
C-c C-z C-z
ess-describe-object-at-pointbound to C-c C-d C-e (repeat C-e or e to cycle). It was inspired by Erik Iverson’s
ess-describe-at-point-methodto use tooltip instead of an electric buffer.
ess-build-tags-for-directorybound to C-c C-e C-t for building dialect specific tag tables. After building tags use M-. to navigate to function and objects definitions. By default C-c C-e C-t builds tags based on imenu regular expressions and also include other common languages
.c, .o, .cppetc. But it relies on external
ess-build-tags-commandis defined (for
R), the inferior process is asked to build tags instead.
*new*alternative to start a new process instead of switching to one of the currently running processes.
M-x rename-buffercommand to conveniently rename your process buffers.
procstands for the internal process name and
dirstands for the directory where the process was started in. The default is *proc*. For customization see
ess-eval-visibly-pis deprecated in favor of
nowait. In addition to old
nowaitfor a visible evaluation with no waiting for the process. See
ess-eval-visiblyfor details on evaluation patterns.
ess-switch-to-inferior-or-script-buffercommand bound to C-c C-z in both script and process buffers. If invoked form process buffer it switches to the most recent buffer of the same dialect. It is a single key command.
ess-roxy-refor fontification of cases where the number of leading # differs from
ess-display-demoscommand bound to C-c C-d o and C-c C-d C-o
ess-help-web-searchcommand bound to C-c C-d w and C-c C-d C-w to facilitate interactive search of web resources. Implemented for
Julia. See also
ess-swv-processorfor the default processor.
ess-eval-chunkbound to M-n C-c and M-n C-M-x to mirror standard ess commands in C-c map.
ess-ac-R-argument-suffixto customize the insertion of trailing "=". Defaults to “ = “.
Bug Fixes in 12.09-1:
comint-previous-promptC-c C-p no longer stops on secondary prompt “+”.
options("editor")is now initialized to
emacsclientinstead of the previous
gnuclient. The user may need to add the line
(server-start)to the emacs initialization file.
emacsclienthas been included with emacs since GNU Emacs 22.1.
Rcode injection. It now happens only once at the start of the session.
Changes/New Features in 12.09:
ess-directory-containing-R) to tell ESS where to look for the Rterm.exe executables. The name of the variable and the values it can take are both in beta and subject to change. Prior to this variable, ESS searched only in the default installation directory. Setting this variable now tells ESS how to find Rterm.exe executables when they are installed somewhere else.
Full interaction interface, imenu and basic error referencing are available.
noweb-font-lock-modehave been renamed to
ess-noweb-font-lock-modeto avoid conflicts with the “real”
Each of these functions first evaluates the region whenever the region is active.
ess-eval-*-and-stepfamily of functions are now smarter, and don’t step to end of buffer or end of chunk code (
@) when at the end of the code.
ess-handy-commandsfunction is bound to C-c h
ess-blink-regionto nil to deactivate;
ess-blink-delaygives the duration of the blink. Evaluated region is “blinked” in
ESS font-lock operates with predefined keywords. Default keywords are
inferior-R-font-lock-keywords, which see. The user can easily
customize those by adding new keywords. These variables can also be
interactively accessed and saved through ESS/Font-lock submenu.
Several new fontification keywords have been added. Most notably the keywords for highlighting of function calls, numbers and operators.
ess-use-auto-completeto nil to deactivate.
ac-source-Rnow concatenates “ = “ to function arguments.
ess-tracebugcommands are available by default in
ess-dev-mapwhich is bound to C-c d in ESS and iESS maps.
eldoctruncates long lines whenever
eldoc-echo-area-use-multiline-pis non-nil (the default). Set this variable to t if you insist on multiline eldoc. See also
Sys.sleep(5)no longer stall emacs.
ess-X-post-run-hooks, which are run at the end of subprocess initialization.
ess-arg-function-offset-new-lineis now a list for all the ESS indentation styles, which results in the following indentation after an open “(”:
a <- some.function(other.function( arg1, arg2)
Changes/Bug Fixes in 12.04-3:
M-x ess-versionshows the svn revision even after
lisp, to build the lisp-only part, i.e., not building the docs.
Changes/New Features in 12.04-1:
inferior-STA-program-nameis now “stata” and can be customized.
Bug Fixes in 12.04-1:
ess-eldochelp string filtering and improved argument caching.
M-x ess-versionshould work better.
Changes/New Features in 12.04:
ess-modeno longer completes by default. If you want smart TAB completion in R and S scripts, similarly to iESS behavior, set the variable
t. Also see
ess-first-tab-never-completefor how to customize where first TAB is allowed to complete.
ess-arg-function-offset-new-lineintroduced in ESS(12.03) now accepts a list with the first element a number to indicate that the offset should be computed from the indent of the previous line. For example setting it to ’(2) results in:
a <- some.function( arg1, arg2)
Changes/New Features in 12.03:
ess-arg-function-offset-new-linecontrolling for the indentation of lines immediately following open ’(’. This is useful to shift backwards function arguments after a long function call expression:
a <- some.function( arg1, arg2)
instead of the old
a <- some.function( arg1, arg2)
If ’(’ is not followed by new line the behavior is unchanged:
a <- some.function(arg1, arg2)
This variable should be set as part of indentation style lists, or in ess-mode hook.
yank(C-y) command accepts double argument C-u C-u to paste commands only. It deletes any lines not beginning with a prompt, and then removes the prompt from those lines that remain. Useful to paste code from emails, documentation, inferior ESS buffers or transcript files.
ess-eldoc-abbreviation-stylevariables for how to change the default behavior. Note:
skeleton-pair-insert-maybeprohibits eldoc display, on ( insertion.
ess-modenow indents and completes, if there is nothing to indent. Set
tto make TAB never complete on first invocation. Completion mechanism is similar to the completion in the
inferior-ess-mode– a filename expansion is tried, if not found ESS completes the symbol by querying the process.
completion-at-point. Also in accordance with emacs conventions, ESS doesn’t bind M-TAB for emacs 24 or higher. M-TAB calls the default
Auto Completionmode http://cx4a.org/software/auto-complete . Three AC sources
ac-source-Rare provided. The last one combines the previous two and makes them play nicely together. Set
tto start using it. Refer to documentation string of
ac-use-auto-completefor further information.
ess-get-object-at-point. Eldoc and auto-completion integration are using this system.
ess-switch-to-end-of-ESS(C-c C-z), and
ess-switch-to-ESS(C-c C-y): Automatically start the process whenever needed.
roxyknows about previewing text version of the documentation. Bound to C-c C-e t.
ess-tracebugis now part of ESS:
ess-tracebug-inject-source-pcontrols this behavior - if t, always inject source reference, if
'function, inject only for functions (this is the default), if
nil, never inject.
During the source injection the value of
Rcode directly in the package environment and namespace. It can be toggled on and off with C-c d t. When
ess-developeris on all ESS evaluation commands are redefined to evaluate code in appropriate environments. Add package names to the list of your development packages with C-d a, and remove with C-d r. Source the current file with C-d s.Evaluation function which depend on
`ess-eval-region'ask for the package to source the code into,
ess-eval-functionand alternatives search for the function name in the development packages’ environment and namespace and insert the definition accordingly. See the documentation section “Developing with ESS/ESS developer” for more details.
ess-switch-to-end-of-ESS. This is consistent with emacs behavior help and other special buffers (breaking change).
special-mode-mapas sugested by Sam Steingold.
ess-display-indexbound to i in help mode map.
ess-display-vignettesbound to v in help mode map.
ess-display-help-in-browserbound to w in help mode map. It depends on
ess-help-pop-to-buffer: if non-nil ESS help buffers are given focus on display. The default is
ess-help-kill-bogus-buffersnow defaults to
t. Beware, there may be instances where the default is unsatisfactory such as debugging and/or during R development. Thanks to Ross Boylan for making the suggestion, Sam Steingold for reminding us of this variable and Martin Maechler for the warning.
IDOcompleting read functionality for all the interactive requests. It uses ido completion mechanism whenever available, and falls back on classical completing-read otherwise. You can set
ess-use-idoto nil if you don’t want the IDO completion. See the documentation string of
ess-use-idofor more information about
IDOand ESS configuration.
`ess-smart-commaalso inserts “ “ after comma.
`ess-handy-commands'stores an alist of useful commands which are called by
ess-smart-commain the inferior buffer.
ess-install.packages, etc -
ask for item with completion and execute the correspond
ess-sos is a interface to
findFn function in
sos. If package
sos is not found, ask user for
ess-tracebugand developer status of
ess-developerin all associated buffers.
ess-completing-readmechanism: ESS uses
idocompletions whenever possible. Variable
ess-use-idocontrols whether to use ido completion or not. Active by default.
inferior-ess-S-promptto customize prompt detection regular expression in the inferior ESS buffers. You can customize this variable to enhance comint navigation (
comint-next-prompt) the inferior buffers.
Rcompletion retrieval (
ess-R-complete-object-name) was rewritten and is faster now.
>. This could be overwritten by setting
R: Saved command history: ess-history-file now accepts
nil, or a file name. By setting it to
nilno command line history is saved anymore. ess-history-directory now allows to have the history all saved in one “central” file.
Please send bug reports, suggestions etc. to ESSemail@example.com
The easiest way to do this is within Emacs by typing
This also gives the maintainers valuable information about your installation which may help us to identify or even fix the bug.
If Emacs reports an error, backtraces can help us debug the problem. Type "M-x set-variable RET debug-on-error RET t RET". Then run the command that causes the error and you should see a *Backtrace* buffer containing debug information; send us that buffer.
Note that comments, suggestions, words of praise and large cash donations are also more than welcome.
There is a mailing list for discussions and announcements relating to ESS. Join the list by sending an e-mail with "subscribe ess-help" (or "help") in the body to firstname.lastname@example.org; contributions to the list may be mailed to email@example.com. Rest assured, this is a fairly low-volume mailing list.
The purposes of the mailing list include