1
----------------------------------------------------
2
Short guide to install ESS under Windows (28-4-2001)
3
by Emmanuel Paradis <paradis@isem.univ-montp2.fr>
4
----------------------------------------------------
6
The following notes are for a Windows system (mainly NT, but this applies
7
to 95/98 too) which has none of Emacs, gnuserv, or ESS installed. Sections
8
1 and 2 are about getting and installing Emacs, sections 3-6 are about
9
getting and installing ESS, section 7 is about getting and installing
10
gnuserv, and section 8 gives a few hints on how to start with ESS.
12
It is assumed that all packages are or will be installed in D:\ (if you
13
choose another location, change accordingly). It is preferable to install
14
these packages (including R) in locations independent of each others, so
15
that they can be updated easily.
17
1. Download a precompiled copy of Emacs v. 20.7 for Windows on Intel machines:
19
ftp://ftp.gnu.org/gnu/windows/emacs/20.7/emacs-20.7-fullbin-i386.tar.gz
21
This is a 13 Mb file that includes precompiled binaries of Emacs, and lisp
22
sources (useful for understanding how packages work, and how they can best
23
be setup or customized).
25
2. Unpack the downloaded file in a directory, e.g., "D:\", then execute the
26
file "D:\emacs-20.7\bin\addpm.exe". Emacs is then installed on your Windows
27
machine, and a shortcut should have been added to your Start menu.
28
Installing Emacs may not be so straightforward depending on the setup of
29
your system. For instance, it may be better to turn virus checkers off
30
(Norton Anti-Virus 2001 breaks this, for example; McAfee virus scanner
31
seems to interact badly with Emacs too). There is a very detailed FAQ for
34
http://www.gnu.org/software/emacs/windows/ntemacs.html
36
Section 3 of this FAQ details the installation process of Emacs under
37
Windows. There are also lots of useful informations on how to customize Emacs.
39
It is also recommended to change the default starting directory for Emacs
40
to your own personal directory to help protect you from accidentally
41
changing files in the Emacs directory. Do so by right-clicking on the Emacs
42
short-cut, go to the "Shortcut" tab, and then change the value in "Start in:".
44
3. Download ESS v. 5.1.18 at:
46
http://ess.stat.wisc.edu/pub/ESS/ESS-5.1.18.tar.gz
50
4. Unpack the downloaded file in its own directory, e.g. "D:\" (of course,
51
keeping the tree structure of the zip archive). Avoid unpacking this
52
archive in the Emacs (sub)-directory(ies) so that you can upgrade Emacs and
53
ESS independently in the future.
55
Also, a useful thing is to rename the current R directory so that it does
56
not have the version number in it, for instance "r". This will avoid the
57
need to change the settings explained below when you install future
58
versions of R (you can of course keep previous versions of R in directories
59
named "r.old", or "rw1021", "rw1020", ... if you have more than two
60
versions). In the followings, it will be assumed this has been done.
62
5. Edit the file "D:\ess-5.1.18\lisp\ess-site.el". In this file, the
63
semicolons indicate comments. Find the line #250 (easy with Emacs...) which
66
;;(setq-default inferior-R-program-name "Rterm") ; msdos systems
68
This line tells ESS where to find the R executable. Thus, uncomment the
69
line, and write with "Rterm" the path to Rterm.exe, for instance,
70
if you installed R v. 1.2.2 for Windows in D:\, and renamed the directory
71
"rw1022" to "r" as above, the line becomes:
73
(setq-default inferior-R-program-name "D:/r/bin/Rterm") ; msdos systems
75
You must use forwardslashes /.Of course, you may delete "; msdos systems".
77
in C:\Program Files (and did not rename its directory), then the line must be:
79
(setq-default inferior-R-program-name "C:/Progra~1/rw1022/bin/Rterm")
81
taking care to use the DOS name of the directory.
83
==> If Rterm.exe is already in the PATH of your system, you do not need to
84
modify this line in ess-site.el, just uncomment it.
86
Under Windows 9x, it seems that Rterm.exe needs to be in the PATH, thus add
87
"D:\r\bin;" to your PATH. Another possibility is to specify the exec-path
88
in your .emacs file by adding this line:
90
(custom-set-variables '(exec-path (quote ("D:/r/bin" "c:/other/paths"))))
92
==> You may use "Rgui" instead of "Rterm", but R's outputs will be
93
displayed in the Rgui console rather than within Emacs (as is the case with
96
6. Edit or create a file called ".emacs" (or "_emacs"). You can read some
97
infos on "What is a .emacs file?" at:
99
http://www.gnu.org/software/emacs/windows/faq3.html#what-startup
101
When Emacs is started, it looks for the .emacs file in your HOME directory.
102
HOME is an environment variable which can be set in several ways. Under
103
Windows NT, open the Control Panel, go to the System panel, and click the
104
"Environment" tab, then add (or modify) the appropriate environment
105
variable. (This procedure gives the possibility to set HOME on a per-user
106
basis.) Under Windows 95, you can set the HOME environment variable in your
107
autoexec.bat file (you will need to reboot then). If no HOME has been set,
108
Emacs will look for .emacs in C:\.
110
Once HOME has been set, add in .emacs the following line:
112
(load-file "d:/ess-5.1.18/lisp/ess-site.el")
114
==> A few precisions on how to create the file .emacs under Windows.
115
Explorer does not accept to (re-)name a file without prefix (but _emacs is
116
possible); you can do it with Notepad, but this editor normally adds the
117
.txt suffix when you name a file. To avoid this, type the name in the 'Save
118
as...' sub-menu within quotes "", e.g. ".emacs" instead of .emacs (the
119
latter will result in .emacs.txt). Yet another possibility is to create the
120
file with any name (say, titi.txt), then go to a DOS command prompt, and type:
122
rename titi.txt .emacs
124
7. ESS is now configured to run with R and Emacs, but it is very useful to
125
install gnuserv, a small program that allows file associations with Emacs
126
(thus loading files into an already running Emacs, or if none, one is
127
launched). More information are at:
129
http://www.gnu.org/software/emacs/windows/faq3.html#assoc
131
where there is also a link to download gnuserv at:
133
http://www.gnu.org/software/emacs/windows/ntemacs/contrib/gnuserv-2.1p1.zip
135
Unpack the dowloaded file, e.g. in D:\, and add in .emacs the following
138
(load-file "d:/gnuserv/gnuserv.el")
142
You also need to have the gnuserv executables and runemacs.exe in your path
143
(under Windows NT, this is done by editing the PATH environment variable in
144
the System panel of the Control Panel; under Windows 9x by modifying the
145
PATH in the autoexec.bat file), in our example, one needs to add
146
"D:\emacs-20.7\bin;D:\gnuserv;" to the PATH.
148
Now, open Explorer, select "options" in the menu "view", select the "file
149
types" tab, click on "New type...", fill the fields (specifying, of course,
150
the .R extension), and under "actions", click "New...", a new window is
151
then open. Under "action" type "open", and in the second field type
153
D:\gnuserv\gnuclientw.exe "%1"
155
where the "%1" allows filenames with blanks in them to be treated as one
156
argument when sent to Emacs. Close all windows by clicking "Ok".
158
==> While you create the R file type, you can specify other "actions", such
159
as "edit" and associate Notepad (or any other editor) with it. This will
160
allow you to edit your R files either with Emacs/ESS (press Enter when the
161
file is selected, or double-click on it), or Notepad (right-click on the
162
file and select "edit"). You can also allow quick view of the R files by
163
ticking the appropriate box under the list of "actions".
165
==> If you do not want to install gnuserv, you can edit several R files in
166
the same running Emacs by opening them from Emacs (Ctrl-x Ctrl-f, which is
167
noted C-x C-f in Emacs's terminology). In this case, you may (or not)
168
create an R file type as described above, and associate the "open" action
171
8. When you open a *.R file, this opens Emacs and ESS. To run R under
172
Emacs, type Alt-x R (M-x R), and then Enter. Within Emacs, you switch
173
between the different files, buffers, processes, ... with the "Buffers"
174
menu or by typing Ctrl and the right button of the mouse. When you edit an
175
R file you can evaluate the R expressions with the "ESS" menu by selecting
176
"eval buffer" (or by typing C-c C-b). Browse this "ESS" menu to see the
177
possibilities: you can evaluate just a line, or a region you have selected
180
Emacs can be customized in several ways that help to edit R files. You can
181
have a look at the Emacs-FAQ within Emacs by the menu Help|Manuals|Emacs
182
FAQ (or C-h F). Here are a few customizations I found useful. These lines
183
must be added in the .emacs file.
185
(setq gnuserv-frame (selected-frame)) ;; open the file in the
186
;; current Emacs frame
187
(show-paren-mode 1) ;; parentheses highlighting
188
(global-font-lock-mode 1) ;; syntax highlighting
189
(setq font-lock-maximum-decoration t) ;; have it maximum!!
190
(setq frame-title-format "%b") ;; put the name of the current
191
;; buffer as the frame name
193
The first line forces Emacs to open a new file in the current frame (rather
194
than opening a new frame outside the current one). The parentheses
195
highlighting is extremely useful when writting a program (even a simple
196
one): when the cursor is on a parenthesis, this highlights in grey both
197
this one and its match. If the match is not found, then the highlight is
198
blue. When first used, this customization may seem a bit irritating, but
199
its usefulness may become quickly apparent.
201
Finally, you can have a look at a list of the many functionalities of ESS
202
in the menu ESS|Describe (or C-h m).
added
removed
doc/README.Windows
