ESS[SAS]: somebody forgot about the SUM statement (probably me)

[ess.git] / doc / README.Windows

----------------------------------------------------
Short guide to install ESS under Windows (28-4-2001)
by Emmanuel Paradis <paradis@isem.univ-montp2.fr>
----------------------------------------------------

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