2 We now discuss installation, which might happen under Unix or
3 Microsoft Windows. First, we discuss Unix installation.
4 @xref{Unix installation}.
6 For Microsoft Windows Installation please skip to the
7 @xref{Microsoft Windows installation}.
9 @node Unix installation, Microsoft Windows installation, , Installation
10 @comment node-name, next, previous, up
11 @section Unix installation
16 cd to a directory where you want to install ESS, creating it if necessary.
17 This directory will be referred to below as ESSDIR.
18 @comment It will contain,
19 @comment at the end, the tar file @file{ess-VERSION.tar.gz}, and a directory for
20 @comment the ESS source, which will be termed "the ESS-VERSION source directory".
21 @comment Note that the .elc files may be installed elsewhere (as specified in the
22 @comment Makefile) if desired.
25 Retrieve the latest version from
26 @uref{http://ess.r-project.org/downloads/ess, ESS downloads area}
30 Decompress/unarchive the files from the disribution.
32 gunzip ess-VERSION.tar.gz
33 tar xvf ess-VERSION.tar
36 (or: @code{gunzip < ess-VERSION.tar.gz | tar xvf -} ).
37 (or using GNU tar: @code{tar zxvf ess-VERSION.tar.gz}).
40 The @code{tar} command will create the subdirectory ess-VERSION and unarchive
43 @comment If you are using GNU Emacs 19.29, decompress/unarchive
44 @comment @file{ESSDIR/ess-VERSION/lisp/19.29.tar.gz},
45 @comment read @file{ESSDIR/ess-VERSION/lisp/19.29/README}, follow the instructions
46 @comment and you might be able to get ESS to work.
47 @comment @emph{Please note that GNU Emacs 19.29 is no longer supported}.
48 @comment For a list of supported versions of emacs, see @xref{Requirements}.
51 Edit the file @file{ESSDIR/ess-VERSION/lisp/ess-site.el} as explained in the
52 comments section of that file.
53 @comment Installations that are using ESS only for S-Plus
54 @comment 6.x will probably not need to make any changes. Installations that also
55 @comment have one or more of (S4, S+3/4/5/6/7, R, SAS, BUGS, XLispStat, Stata)
56 @comment may need to uncomment corresponding lines in @file{ESSDIR/ess-VERSION/lisp/ess-site.el}.
61 (load "ESSDIR/ess-VERSION/lisp/ess-site")
63 to your user or system installation file
64 (GNU Emacs uses @file{$HOME/.emacs} and XEmacs uses @file{$HOME/.xemacs/init.el}
65 for the user initialization file. GNU Emacs uses default.el or site-init.el and
66 XEmacs uses site-start.el for the system installation file).
68 Alternatively, if ess-site.el is in your current Lisp path, you can do:
72 to configure emacs for ESS.
75 That's it! If you are installing just a local copy of ESS for yourself,
76 ESS is now ready to be used. (The remaining step below is for
77 advanced installation.) To edit statistical programs, load the files
78 with the requiste extensions (".sas" for SAS, ".S" for S-PLUS, ".R" for
79 R, and ".lsp" for XLispStat). To start a statistical process within
80 Emacs, such as R, type @code{M-x R}.
83 @c (OPTIONAL) If you are running S-PLUS or R, you might consider
84 @c installing the database files. From within emacs, @code{C-x d} to the
85 @c directory containing ESS. Now:
89 @c to get S running. Once you see the SPLUS prompt, do:
91 @c M-x ess-create-object-name-db
93 @c (this will create the file @file{ess-sp6-namedb.el}; if it isn't in the
94 @c ESS directory, move it there).
96 @c Then, completions will be autoloaded and will not be regenerated for
99 @c For R, do the same, using
103 @c and then @code{M-x ess-create-object-name-db} creating
104 @c @file{ess-r-namedb.el}; if it isn't in the ESS directory, move it there).
107 @b{(OPTIONAL) READ THIS ITEM THOROUGHLY BEFORE STARTING}:
109 If you want to place the compiled files in other locations edit the LISPDIR and INFODIR
110 entries in @file{Makeconf} in the ESSDIR/ess-VERSION directory (if you are using XEmacs,
111 then you also need to edit the EMACS entry as follows: EMACS=xemacs).
113 You can compile those files by:
118 When that completes successfully, install the compiled files:
123 This will install the compiled info files and lisp files. If you are an
124 XEmacs user, then you should be done. If not, then you may have to
125 edit/create the file @file{dir} that is found in the directory specified
126 by @code{INFODIR}: see the sample @file{dir} in ESSDIR/ess-VERSION/doc/info.
127 If @file{dir} does not exist in @code{INFODIR}, then the sample
128 @file{dir} will be installed.
130 @emph{Note:} ESS can be installed for XEmacs as an XEmacs package
131 much more easily than what has been described anywhere above. However,
132 the latest ESS version will not be available at the same time as an
133 XEmacs package; generally, it can take weeks or months to appear in the
134 latter format. For more information on installing ESS as an XEmacs
135 package see @uref{http://www.xemacs.org/Documentation/packageGuide.html, Quickstart Package Guide}.
137 @comment An alternative, if you are running XEmacs and have access to the
138 @comment XEmacs system directories, would be to place the directory in the
139 @comment site-lisp directory, and simply type @code{make all} (and copy the
140 @comment documentation as appropriate).
142 @comment For GNU Emacs, you would still have to move the files into the top level
143 @comment site-lisp directory.
147 @c >>>> FIXME (see comment in ess.texi): error in ``makeinfo readme.texi''
148 @c @node Microsoft Windows installation, , Unix installation, Installation
149 @node Microsoft Windows installation, Requirements, Unix installation, Installation
150 @comment node-name, next, previous, up
151 @section Microsoft Windows installation
153 For @b{Microsoft Windows installation}, please follow the next steps:
154 (see separate instructions above for UNIX @xref{Unix installation}.
159 cd to a directory where you keep emacs lisp files, or create a new
160 directory (for example, @file{c:\emacs\}) to hold the distribution. This
161 directory will be referred to below as "the ESS distribution
162 directory". It will contain, at the end, either the tar file
163 @file{ess-VERSION.tar.gz} or the zip file @file{ess-VERSION.zip}, and a
165 for the ESS source, which will be termed "the ESS-VERSION source
169 Retrieve the compressed tar file @file{ess-VERSION.tar.gz} or the
170 zipped file @file{ess-VERSION.zip} from one of the FTP or WWW
172 via FTP (or HTTP). Be aware that http browsers on Windows
173 frequently change the "." and "-" characters in filenames to other
174 punctuation. Please change the names back to their original form.
177 Copy @file{ess-VERSION.tar.gz} to the location where you want the
178 ess-VERSION directory, for example to
179 @file{c:\emacs\ess-VERSION.tar.gz}, and cd there. For example,
185 Extract the files from the distribution, which will unpack
186 into a subdirectory, @file{ess-VERSION}.
188 gunzip ess-VERSION.tar.gz
189 tar xvf ess-VERSION.tar
190 (or: @code{gunzip < ess-VERSION.tar.gz | tar xvf -} ).
191 (or: from the zip file: @code{unzip ess-VERSION.zip})
194 The @code{tar} command will extract files into the current directory.
196 Do not create @file{ess-VERSION} yourself, or you will get an extra level
197 of depth to your directory structure.
200 Windows users will usually be able to use the `lisp/ess-site.el'
201 as distributed. Only rarely will changes be needed.
204 Windows users will need to make sure that the directories for the
205 software they will be using is in the PATH environment variable. On
206 Windows 9x, add lines similar to the following to your
207 @file{c:\autoexec.bat}
210 path=%PATH%;c:\progra~1\spls2000\cmd
212 On Windows NT/2000/XP, add the directories to the PATH using the
213 @code{My Computer/Control Panel/System/Advanced/Environment Variables} menu.
214 Note that the directory containing the program is
215 added to the PATH, not the program itself. One such line is needed
216 for each software program. Be sure to use the abbreviation
217 @code{progra~1} and not the long version with embedded blanks. Use
223 (load "/PATH/ess-site")
225 to your .emacs (or _emacs) file (or default.el or site-init.el, for
226 a site-wide installation). Replace @code{/PATH} above with the
227 value of ess-lisp-directory as defined in @file{ess-site.el}. Use
228 forwardslashes @code{/}.
229 (GNU Emacs uses the filename @file{%HOME%/.emacs} and
230 XEmacs uses the filename @file{%HOME%/.xemacs/init.el}
231 for the initialization file.)
234 To edit statistical programs, load the files with the requisite
235 extensions (".sas" for SAS, ".S" or "s" or "q" or "Q" for S-PLUS,
236 ".r" or ".R" for R, and ".lsp" for XLispStat).
239 To run statistical processes under emacs:
241 To start the S-PLUS [67].x GUI from ESS under emacs:
247 asked for a pathname ("S starting data directory?"), from which to
248 start the process. The prompt will propose your current directory
249 as the default. ESS will start the S-PLUS GUI. There will be
250 slight delay during which emacs is temporarily frozen. ESS will arrange for
251 communication with the S-PLUS GUI using the DDE protocol.
252 Send lines or regions
253 from the emacs buffer containing your S program (for example,
254 @file{myfile.s}) to the S-PLUS Commands Window with the
255 @code{C-c C-n} or @code{C-c C-r} keys.
256 (If you are still using S-PLUS 4.x or 2000, then use @code{M-x S+4}.)
258 To start an S-PLUS [67].x session inside an emacs buffer---and
259 without the S-PLUS GUI:
262 (or @code{M-x Sqpe+6}).
264 You will then be asked for a pathname ("S starting data
265 directory?"), from which to start the process. The prompt will
266 propose your current directory as the default.
267 You get Unix-like behavior, in particular the entire
268 transcript is available for emacs-style search commands.
269 Send lines or regions from the emacs buffer containing your S
270 program (for example, @file{myfile.s}) to the *S+6* buffer with the
271 @code{C-c C-n} or @code{C-c C-r} keys.
272 Interactive graphics are available with Sqpe by using the java
273 library supplied with S-PLUS 6.1 and newer releases.
279 Graphs can be saved from the @code{java.graph} device
280 in several formats, but not PostScript. If you
281 need a PostScript file you will need to open a separate
282 @code{postscript} device.
283 (If you are still using S-PLUS 4.x or 2000, then use @code{M-x Sqpe+4}.)
285 To connect to an already running S-PLUS GUI (started, for example,
286 from the S-PLUS icon):
291 asked for a pathname ("S starting data directory?"), from which to
292 start the process. The prompt will propose your current directory
293 as the default. ESS will arrange for
294 communication with the already running S-PLUS GUI using the DDE protocol.
295 Send lines or regions
296 from the emacs buffer containing your S program (for example,
297 @file{myfile.s}) to the S-PLUS Commands Window with the
298 @code{C-c C-n} or @code{C-c C-r} keys.
299 (If you are still using S-PLUS 4.x or 2000, then use @code{M-x S+4-existing}.)
301 If you wish to run R, you can start it with:
306 XLispStat can not currently be run with
310 Hopefully, this will change. However, you can still edit with
311 emacs, and cut and paste the results into the XLispStat
312 *Listener* Window under Microsoft Windows.
314 @comment SAS for Windows uses the batch access with function keys that is
315 @comment described in
316 @comment @file{doc/README.SAS}.
317 @comment @xref{ESS(SAS)--MS Windows}.
318 @comment The user can also edit SAS files
319 @comment in an @code{ESS[SAS]} buffer and than manually copy and paste them into
320 @comment an Editor window in the SAS Display Manager.
322 @comment For Windows, inferior SAS in an @code{iESS[SAS]} buffer does not work
323 @comment on the local machine. It does work over a network connection to
324 @comment SAS running on a remote Unix computer.
326 @comment Reason: we use ddeclient to interface with programs and SAS doesn't
327 @comment provide the corresponding ddeserver capability.
330 @c (OPTIONAL) If you are running Sqpe or R, you might consider
331 @c installing the database files. From within emacs, @code{C-x d} to
332 @c the directory containing ESS. Now:
336 @c to get S running. Once you see the SPLUS prompt, do:
338 @c M-x ess-create-object-name-db
340 @c (this will create the file @file{ess-s+6-namedb.el}; if it isn't in the
341 @c ESS directory, move it there).
343 @c Then, completions will be autoloaded and will not be regenerated
344 @c for every session.
346 @c For R, do the same, using
350 @c and then @code{M-x ess-create-object-name-db} creating
351 @c @file{ess-r-namedb.el}; if it isn't in the ESS directory, move it
357 @comment Requirements duplicated?
358 @comment @node Requirements, , Microsoft Windows installation, Installation
359 @comment node-name, next, previous, up
360 @comment @section Requirements
361 @comment @include requires.texi