Source

ess / texi / inst_tar.texi


We now discuss installation, which might happen under Unix or
Microsoft Windows.  First, we discuss Unix installation.  
@xref{Unix installation}.

For Microsoft Windows Installation please skip to the
@xref{Microsoft Windows installation}.

@node Unix installation, Microsoft Windows installation, , Top
@comment  node-name,  next,  previous,  up
@section Unix installation
@enumerate 
@item
cd to a directory where you keep emacs lisp files, or create a new
directory to hold the distribution.  This directory will be referred
to below as "the ESS distribution directory".  It will contain,
at the end, the tar file @file{ess-@essver{}.tar.gz}, and a directory for
the ESS source, which will be termed "the ESS-@essver{} source directory".

Note that the .elc files may be installed elsewhere (as specified in the
Makefile) if desired.
@item
Retrieve the gzipped tar file or zipped file from
@url{http://software.biostat.washington.edu/statsoft/ess/essDL}
@item
Copy @file{ess-@essver{}.tar.gz} to the location where you want the
ESS-@essver{} directory, and cd there.  Extract the files from the
distribution, which will unpack into a subdirectory, ess-@essver{}.
@example
gunzip ess-@essver{}.tar.gz
tar vxf ess-@essver{}.tar
@end example
@display
(or: @code{gunzip < ess-@essver{}.tar.gz | tar vxf -} ).
(or using GNU tar:  @code{tar zvxf ess-@essver{}.tar.gz}).
@end display

The @code{tar} command will extract files into the current directory.
Do not create ess-@essver{} yourself, or you will get an extra level of
depth to your directory structure.

Note if you have a very ancient version of GNU emacs (@emph{and}  really
can not upgrade to Emacs 20 or higher!) you can unpack the
@file{lisp/19.29.tar.gz} file, read the ensuing @file{lisp/19.29/README}
and you may succeed...

@item
Edit the file @file{lisp/ess-site.el} as explained in the comments
section of that file.  Installations that are using ESS only for S-Plus
6.x will probably not need to make any changes.  Installations that also
have one or more of (S+5 S4 S+4 S+3 R SAS XLispStat Stata)
may need to uncomment corresponding lines in @file{ess-site.el}.
@item
@b{READ THIS ITEM THOROUGHLY BEFORE STARTING}:

In the ess-@essver{} directory, edit the file @file{Makeconf} (only if you
want to place the executables in other locations; see LISPDIR and
INFODIR) and then type:
@example
make
@end example

If this works, then you might try:
@example
make install
@end example
Note that the latter does the former as well, so if you are feeling
lucky, you might want to skip it.

This will install the info files (and the lisp files, if they are to go
in another directory).  Don't forget to edit the file @file{dir} in the
info directory specified by @code{INFODIR} in @file{doc/Makefile}.  See
the sample @file{dir} file for an example of the line to add.

If you are using XEmacs, you might do:
@example
make EMACS=xemacs
@end example

and then
@example
make EMACS=xemacs install
@end example
instead of editing the Makefile.

@emph{Note} that you might need to use @b{GNU make} for everything to
work properly

An alternative, if you are running XEmacs and have access to the
XEmacs system directories, would be to place the directory in the
site-lisp directory, and simply type @code{make} (and copy the
documentation as appropriate).

For Emacs, you would still have to move the files into the top level
site-lisp directory.
@item
 Add the line
@example
(load "/PATH/ess-site")
@end example
to your .emacs file (or default.el or site-init.el, for a site-wide
installation).  Replace `/PATH' above with the value of
ess-lisp-directory as defined in ess-site.el.

Alternatively, if ess-site.el is in your current Lisp path, you can
do:
@example
(require 'ess-site)
@end example
to configure Emacs for ESS.
@item
(OPTIONAL) If you are running S-PLUS or R, you might consider
installing the database files.  From within (X)Emacs, @code{C-x d} to the
directory containing ESS.  Now:
@example
M-x S+6
@end example
get running.  once you have reached the SPLUS
prompt, do: 
@example
M-x ess-create-object-name-db
@end example
(this will create the file @file{ess-s+6-namedb.el}; if it isn't in the
ESS directory, move it there).

Then, completions will be autoloaded and will not be regenerated for
every session.

For R, do the same, using
@example
M-x R
@end example
and then @code{M-x ess-create-object-name-db} creating
@file{ess-r-namedb.el}; if it isn't in the ESS directory, move it there).
@item
For more information on using ESS in your daily work, see the files
README.S, README.SAS, and README.XLispStat.

For the impatient, the quick version of usage follows:
@item
To edit statistical programs, load the files with the requiste
extensions  (".sas" for SAS, ".S" for S-PLUS, ".R" for R, and ".lsp"
for XLispStat).
@item
To run statistical processes under (X)Emacs:

Run S-PLUS 6.x with:
@example
M-x S+6
@end example
(or M-x S  using backwards compatibility).  You will then be asked
for a pathname ("S starting data directory?"), from which to start
the process.

If you wish to run R, you can start it with:
@example
M-x R
@end example

XLispStat can be run with
@example
M-x XLS
@end example

An interactive SAS can be run in an @code{iESS[SAS]} buffer with:
@example
M-x SAS
@end example
This works when SAS is running on a Unix machine, either the local
machine or over a network connection.  M-x SAS does not work when
SAS is running on a Windows machine.

@item
That's it!
@end enumerate

@node Microsoft Windows installation, System dependent, Unix installation, Top
@comment  node-name,  next,  previous,  up
@section Microsoft Windows installation

For @b{Microsoft Windows installation}, please follow the next steps:
(see separate instructions above for UNIX @xref{Unix installation}.

@enumerate

@item

cd to a directory where you keep emacs lisp files, or create a new
directory (for example, @file{c:\emacs\}) to hold the distribution.  This
directory will be referred to below as "the ESS distribution
directory".  It will contain, at the end, either the tar file
@file{ess-@essver{}.tar.gz} or the zip file @file{ess-@essver{}.zip}, and a
directory 
for the ESS source, which will be termed "the ESS-@essver{} source
directory".

@item

Retrieve the compressed tar file @file{ess-@essver{}.tar.gz} or the
zipped file @file{ess-@essver{}.zip} from one of the FTP or WWW
archive sites 
via FTP (or HTTP).  Be aware that http browsers on Windows
frequently change the "." and "-" characters in filenames to other
punctuation.  Please change the names back to their original form.

@item

Copy @file{ess-@essver{}.tar.gz} to the location where you want the
ess-@essver{} directory, for example to
@file{c:\emacs\ess-@essver{}.tar.gz}, and cd there.  For example,

@example
cd c:\emacs
@end example

Extract the files from the distribution, which will unpack
into a subdirectory, @file{ess-@essver{}}.
@example
gunzip ess-@essver{}.tar.gz
tar vxf ess-@essver{}.tar
(or: @code{gunzip < ess-@essver{}.tar.gz | tar vxf -} ).
(or: from the zip file: @code{unzip ess-@essver{}.zip})
@end example

The @code{tar} command will extract files into the current directory.

Do not create @file{ess-@essver{}} yourself, or you will get an extra level
of depth to your directory structure.

@item
Windows users will usually be able to use the `lisp/ess-site.el'
as distributed.  Only rarely will changes be needed.
@item

Windows users will need to make sure that the directories for the
software they will be using is in the PATH environment variable.  On
Windows 9x, add lines similar to the following to your
@file{c:\autoexec.bat} 
file:
@example
path=%PATH%;c:\progra~1\spls2000\cmd
@end example
On Windows NT/2000, add the directories to the PATH using the
MyComputer menu.  Note that the directory containing the program is
added to the PATH, not the program itself.  One such line is needed
for each software program.  Be sure to use the abbreviation
@code{progra~1} and not the long version with embedded blanks.  Use
backslashes "\".

@item

Add the line 
@example        
(load "/PATH/ess-site")
@end example
to your .emacs (or _emacs) file (or default.el or site-init.el, for
a site-wide installation).  Replace @code{/PATH} above with the
value of ess-lisp-directory as defined in @file{ess-site.el}.  Use
forwardslashes @code{/}.

@item

(OPTIONAL) If you are running Sqpe or R, you might consider
installing the database files.  From within (X)Emacs, @code{C-x d} to
the   directory containing ESS.  Now:
@example
M-x Sqpe+6
@end example
(get running.  once you have reached the SPLUS prompt, do:)
@example
M-x ess-create-object-name-db
@end example
(this will create the file @file{ess-s+6-namedb.el}; if it isn't in the
ESS directory, move it there).

Then, completions will be autoloaded and will not be regenerated
for every session.

For R, do the same, using
@example
M-x R
@end example
and then @code{M-x ess-create-object-name-db} creating
@file{ess-r-namedb.el}; if it isn't in the ESS directory, move it
there).

@item

For more information on using ESS in your daily work, see the
files doc/README.SPLUS4WIN, doc/README.S, doc/README.SAS, and
doc/README.XLispStat.

For the impatient, the quick version of usage follows:
@item

To edit statistical programs, load the files with the requisite
extensions  (".sas" for SAS, ".S" or "s" or "q" or "Q" for S-PLUS,
".r" or ".R" for R, and ".lsp"   for XLispStat).
@item

To run statistical processes under (X)Emacs:

Run S-PLUS 6.x or 2000 with:
@example
M-x S+6
(or @code{M-x S}).
@end example
You will then be
asked for a pathname ("S starting data directory?"), from which to
start the process.  The prompt will propose your current directory
as the default.  Similarly for S-PLUS 6.x.  Send lines or regions
from the emacs buffer containing your S program (for example,
@file{myfile.s}) to the S-Plus Commands Window with the 
@code{C-c C-n} or @code{C-c C-r} keys.

Run S-PLUS 6.x or 2000 inside an emacs buffer
@example
M-x Sqpe+6
@end example
You will then be asked for a pathname ("S starting data
directory?"), from which to start the process.  The prompt will
propose your current directory as the default.  Similarly for S-PLUS
6.x.  Send lines or regions from the emacs buffer containing your S
program (for example, @file{myfile.s}) to the *S+6* buffer with the
@code{C-c C-n} or @code{C-c C-r} keys.  You do not have access to
interactive graphics in 
this mode.  You get Unix-like behavior, in particular the entire
transcript is available for emacs-style search commands.

If you wish to run R, you can start it with:
@example
M-x R
@end example

XLispStat can not currently be run with
@example
M-x XLS
@end example
Hopefully, this will change.  However, you can still edit with
Emacs, and cut and paste the results into the XLispStat
*Listener* Window under Microsoft Windows.

SAS for Windows uses the batch access with function keys that is
described in @file{doc/README.SAS}.  The user can also edit SAS files
in an @code{ESS[SAS]} buffer and than manually copy and paste them into
an Editor window in the SAS Display Manager.

For Windows, inferior SAS in an @code{iESS[SAS]} buffer does not work
on the local machine.  It does work over a network connection to
SAS running on a remote Unix computer.

Reason:  we use ddeclient to interface with programs and SAS doesn't
provide the corresponding ddeserver capability.

@item That's it!

@end enumerate