---------------------------------------------------- Short guide to install ESS under Windows (28-4-2001) by Emmanuel Paradis ---------------------------------------------------- The following notes are for a Windows system (mainly NT, but this applies to 95/98 too) which has none of Emacs, gnuserv, or ESS installed. Sections 1 and 2 are about getting and installing Emacs, sections 3-6 are about getting and installing ESS, section 7 is about getting and installing gnuserv, and section 8 gives a few hints on how to start with ESS. It is assumed that all packages are or will be installed in D:\ (if you choose another location, change accordingly). It is preferable to install these packages (including R) in locations independent of each others, so that they can be updated easily. 1. Download a precompiled copy of Emacs v. 20.7 for Windows on Intel machines: ftp://ftp.gnu.org/gnu/windows/emacs/20.7/emacs-20.7-fullbin-i386.tar.gz This is a 13 Mb file that includes precompiled binaries of Emacs, and lisp sources (useful for understanding how packages work, and how they can best be setup or customized). 2. Unpack the downloaded file in a directory, e.g., "D:\", then execute the file "D:\emacs-20.7\bin\addpm.exe". Emacs is then installed on your Windows machine, and a shortcut should have been added to your Start menu. Installing Emacs may not be so straightforward depending on the setup of your system. For instance, it may be better to turn virus checkers off (Norton Anti-Virus 2001 breaks this, for example; McAfee virus scanner seems to interact badly with Emacs too). There is a very detailed FAQ for Emacs on Windows at: http://www.gnu.org/software/emacs/windows/ntemacs.html Section 3 of this FAQ details the installation process of Emacs under Windows. There are also lots of useful informations on how to customize Emacs. It is also recommended to change the default starting directory for Emacs to your own personal directory to help protect you from accidentally changing files in the Emacs directory. Do so by right-clicking on the Emacs short-cut, go to the "Shortcut" tab, and then change the value in "Start in:". 3. Download ESS v. 5.1.18 at: http://ess.stat.wisc.edu/pub/ESS/ESS-5.1.18.tar.gz It is a 558 Kb file. 4. Unpack the downloaded file in its own directory, e.g. "D:\" (of course, keeping the tree structure of the zip archive). Avoid unpacking this archive in the Emacs (sub)-directory(ies) so that you can upgrade Emacs and ESS independently in the future. Also, a useful thing is to rename the current R directory so that it does not have the version number in it, for instance "r". This will avoid the need to change the settings explained below when you install future versions of R (you can of course keep previous versions of R in directories named "r.old", or "rw1021", "rw1020", ... if you have more than two versions). In the followings, it will be assumed this has been done. 5. Edit the file "D:\ess-5.1.18\lisp\ess-site.el". In this file, the semicolons indicate comments. Find the line #250 (easy with Emacs...) which is like this: ;;(setq-default inferior-R-program-name "Rterm") ; msdos systems This line tells ESS where to find the R executable. Thus, uncomment the line, and write with "Rterm" the path to Rterm.exe, for instance, if you installed R v. 1.2.2 for Windows in D:\, and renamed the directory "rw1022" to "r" as above, the line becomes: (setq-default inferior-R-program-name "D:/r/bin/Rterm") ; msdos systems You must use forwardslashes /.Of course, you may delete "; msdos systems". If you installed R in C:\Program Files (and did not rename its directory), then the line must be: (setq-default inferior-R-program-name "C:/Progra~1/rw1022/bin/Rterm") taking care to use the DOS name of the directory. ==> If Rterm.exe is already in the PATH of your system, you do not need to modify this line in ess-site.el, just uncomment it. Under Windows 9x, it seems that Rterm.exe needs to be in the PATH, thus add "D:\r\bin;" to your PATH. Another possibility is to specify the exec-path in your .emacs file by adding this line: (custom-set-variables '(exec-path (quote ("D:/r/bin" "c:/other/paths")))) ==> You may use "Rgui" instead of "Rterm", but R's outputs will be displayed in the Rgui console rather than within Emacs (as is the case with Rterm). 6. Edit or create a file called ".emacs" (or "_emacs"). You can read some infos on "What is a .emacs file?" at: http://www.gnu.org/software/emacs/windows/faq3.html#what-startup When Emacs is started, it looks for the .emacs file in your HOME directory. HOME is an environment variable which can be set in several ways. Under Windows NT, open the Control Panel, go to the System panel, and click the "Environment" tab, then add (or modify) the appropriate environment variable. (This procedure gives the possibility to set HOME on a per-user basis.) Under Windows 95, you can set the HOME environment variable in your autoexec.bat file (you will need to reboot then). If no HOME has been set, Emacs will look for .emacs in C:\. Once HOME has been set, add in .emacs the following line: (load-file "d:/ess-5.1.18/lisp/ess-site.el") ==> A few precisions on how to create the file .emacs under Windows. Explorer does not accept to (re-)name a file without prefix (but _emacs is possible); you can do it with Notepad, but this editor normally adds the .txt suffix when you name a file. To avoid this, type the name in the 'Save as...' sub-menu within quotes "", e.g. ".emacs" instead of .emacs (the latter will result in .emacs.txt). Yet another possibility is to create the file with any name (say, titi.txt), then go to a DOS command prompt, and type: rename titi.txt .emacs 7. ESS is now configured to run with R and Emacs, but it is very useful to install gnuserv, a small program that allows file associations with Emacs (thus loading files into an already running Emacs, or if none, one is launched). More information are at: http://www.gnu.org/software/emacs/windows/faq3.html#assoc where there is also a link to download gnuserv at: http://www.gnu.org/software/emacs/windows/ntemacs/contrib/gnuserv-2.1p1.zip Unpack the dowloaded file, e.g. in D:\, and add in .emacs the following three lines: (load-file "d:/gnuserv/gnuserv.el") (require 'gnuserv) (gnuserv-start) You also need to have the gnuserv executables and runemacs.exe in your path (under Windows NT, this is done by editing the PATH environment variable in the System panel of the Control Panel; under Windows 9x by modifying the PATH in the autoexec.bat file), in our example, one needs to add "D:\emacs-20.7\bin;D:\gnuserv;" to the PATH. Now, open Explorer, select "options" in the menu "view", select the "file types" tab, click on "New type...", fill the fields (specifying, of course, the .R extension), and under "actions", click "New...", a new window is then open. Under "action" type "open", and in the second field type D:\gnuserv\gnuclientw.exe "%1" where the "%1" allows filenames with blanks in them to be treated as one argument when sent to Emacs. Close all windows by clicking "Ok". ==> While you create the R file type, you can specify other "actions", such as "edit" and associate Notepad (or any other editor) with it. This will allow you to edit your R files either with Emacs/ESS (press Enter when the file is selected, or double-click on it), or Notepad (right-click on the file and select "edit"). You can also allow quick view of the R files by ticking the appropriate box under the list of "actions". ==> If you do not want to install gnuserv, you can edit several R files in the same running Emacs by opening them from Emacs (Ctrl-x Ctrl-f, which is noted C-x C-f in Emacs's terminology). In this case, you may (or not) create an R file type as described above, and associate the "open" action with "runemacs.exe". 8. When you open a *.R file, this opens Emacs and ESS. To run R under Emacs, type Alt-x R (M-x R), and then Enter. Within Emacs, you switch between the different files, buffers, processes, ... with the "Buffers" menu or by typing Ctrl and the right button of the mouse. When you edit an R file you can evaluate the R expressions with the "ESS" menu by selecting "eval buffer" (or by typing C-c C-b). Browse this "ESS" menu to see the possibilities: you can evaluate just a line, or a region you have selected with the mouse, etc. Emacs can be customized in several ways that help to edit R files. You can have a look at the Emacs-FAQ within Emacs by the menu Help|Manuals|Emacs FAQ (or C-h F). Here are a few customizations I found useful. These lines must be added in the .emacs file. (setq gnuserv-frame (selected-frame)) ;; open the file in the ;; current Emacs frame (show-paren-mode 1) ;; parentheses highlighting (global-font-lock-mode 1) ;; syntax highlighting (setq font-lock-maximum-decoration t) ;; have it maximum!! (setq frame-title-format "%b") ;; put the name of the current ;; buffer as the frame name The first line forces Emacs to open a new file in the current frame (rather than opening a new frame outside the current one). The parentheses highlighting is extremely useful when writting a program (even a simple one): when the cursor is on a parenthesis, this highlights in grey both this one and its match. If the match is not found, then the highlight is blue. When first used, this customization may seem a bit irritating, but its usefulness may become quickly apparent. Finally, you can have a look at a list of the many functionalities of ESS in the menu ESS|Describe (or C-h m). EP