@include macros.texi
@node Installation
@chapter Installing @AUCTeX{}

Installing @AUCTeX{} should be simple: merely @command{./configure},
@command{make}, and @code{make install}. This does not yet activate the
package, but merely makes it available. See @ref{Loading the package}
for the activation. Please read through this document fully before
installing anything.  The installation procedure has changed as
compared to earlier versions.  In particular, note that there is some
additional information for @w{MS Windows} installations in
@ifset rawfile
the file @file{INSTALL.windows}.
@end ifset
@ifclear rawfile
@xref{Installation under MS Windows}.
@end ifclear

@ifclear rawfile
@menu
* Prerequisites::
* Configure::
* Build/install::
* Loading the package::
* Advice for package providers::
* Advice for non-privileged users::
* Installation under MS Windows::
* Customizing::
@end menu
@end ifclear

@node Prerequisites
@section Prerequisites

@itemize @bullet
@item A recent version of @w{Emacs 21}, alternatively @w{XEmacs 21}.

Support for @w{Emacs 20} has been dropped in favor of getting more
important work done.  For XEmacs, you need at least version 1.84 of the
@code{xemacs-base} package (released on 01/27/2004) or a sumo tarball
dated 02/02/2004 or newer for compiling @AUCTeX{} because of non-trivial
changes in @file{easy-mmode.el}: please use the XEmacs package system
for upgrading if necessary.  The current developers don't have the
resources for providing backward compatibility to earlier versions.

@item A working @LaTeX{} installation

This is not really needed to @emph{install} the package, but will be
required for useful operation of it. The elisp of @AUCTeX{} will probably
run without @LaTeX{}, but you will find relatively little use for it.

@item The @code{texinfo} package

This is needed for building the documentation. If you don't have this,
or you have a too old version of it (try building and you'll find out),
you may download a separate tar file with the prebuilt documentation
from Savannah and install it over the main unpacked tar archive.
@end itemize

@ignore
For some known issues with various software, see
@ifset rawfile
the @file{PROBLEMS} file.
@end ifset
@ifclear rawfile
@ref{Known problems}.
@end ifclear
@end ignore

@node Configure
@section Configure

The first step is to configure the source code, telling it where
various files will be.  To do so, run

@example
./configure @var{options}
@end example

(Note: if you have fetched @AUCTeX{} from @acronym{CVS} rather than
a regular release, you will have to first generate @command{./configure} by
running @command{autogen.sh} in the @file{auctex} directory.)

On many machines, you will not need to specify any options, but if
@command{configure} cannot determine something on its own, you'll need to
help it out with one of these options:

@table @code
@item --with-emacs[=@var{/path/to/emacs}]
If you are using a pretest which isn't in your @code{$PATH}, or
@command{configure} is not finding the right Emacs executable, you can
specify it with this option.

@item --with-xemacs[=@var{/path/to/xemacs}]
Configure for generation under XEmacs (Emacs is the default).  Again,
the name of the right XEmacs executable can be specified, complete with
path if necessary.

@item --with-lispdir=@var{/dir}
This tells where to install the lisp files, note that most of @AUCTeX{}
will be installed in a subdirectory. Normally, this option is
unnecessary, but may be used if you don't like the directory that
configure is suggesting.

@item --with-packagedir=@var{/dir}
This tells where to install the XEmacs Package.  Again, this option is
normally unnecessary, but may be used if you don't like the directory
that configure is suggesting, and you know that XEmacs regards the
directory you specify as a package directory.

If you are installing @AUCTeX{} for a single user, and you have
installed no XEmacs packages as that user before, then @command{configure}
may try to install @AUCTeX{} in the systemwide package directory
(that it cannot write to), causing installation to fail.  In that case,
a good value for this option is @file{~/.xemacs/xemacs-packages}, as
XEmacs looks there for per-user packages by default.

@item --with-auto-dir=@var{/dir}
You can use this option to specify the directory containing
automatically generated information.  It is not necessary for most
@TeX{} installs, but may be used if you don't like the directory that
configure is suggesting.

@item --help
This is not an option specific to @AUCTeX{}. A number of standard
options to @command{configure} exist, and we do not have the room to
describe them here; a short description of each is available, using
@code{--help}.

@end table

@node Build/install
@section Build/install

@cindex Installation
@cindex Make

Once @command{configure} has been run, simply enter

@example
make
@end example
@noindent
at the prompt to byte-compile the lisp files, and build the
documentation files. To install the files into the locations chosen
earlier, type

@example
make install
@end example

@noindent
You may need special privileges to install, e.g., if you are installing
into system directories.

@node Loading the package
@section Loading the package

@cindex @file{.emacs}

First you should make sure that @AUCTeX{} gets loaded.  You then need to
place a few lines in your personal @file{.emacs} file (or a site-wide
configuration file).

For XEmacs, if you specified a valid package directory during
installation, or none at all, then XEmacs installation should do
everything necessary in order to install @AUCTeX{} as a package
and activate it.  Restarting XEmacs should then make the package
visible, and @kbd{C-c C-c} should give you a command prompt.

If you used @code{--with-packagedir}, you have to make sure that the
directory @file{lisp/auctex} under the directory you specified is in
XEmacs' @code{load-path} variable.

For GNU Emacs, the recommended way to activate @AUCTeX{} is to add the
following line to your @file{.emacs} file:

@example
(require 'tex-site)
@end example

If you used @code{--with-lispdir}, you have to make sure that the
directory specified is in Emacs' @code{load-path} variable, so that you
would instead use, e.g.,

@example
(setq load-path (cons "~/elisp" load-path))
(require 'tex-site)
@end example

For site-wide activation in GNU Emacs, see
@ifset rawfile
below.
@end ifset
@ifclear rawfile
@xref{Advice for package providers}.
@end ifclear

That is all.  There are other ways of achieving the equivalent thing,
but we don't mention them here any more since they are not better, and
people got confused into trying everything at once.

@node Advice for package providers
@section Providing @AUCTeX{} as a package

As a package provider, you should make sure that your users will be
served best according to their intentions, and keep in mind that a
system might be used by more than one user, with different preferences.
The use of packages should in general not impact performance negatively
if a user chooses not to employ it, but should be as convenient as
possible. The policy with regard to @AUCTeX{} has been to @emph{refrain}
from activating it automatically when it is installed as a package. This
is reasonable because

@itemize @bullet
@item Emacs comes with a simpler default @TeX{} mode with different
keybindings.  Some users might prefer that.
@item @AUCTeX{} is activated via @code{(require 'tex-site)}.  Once this
has happened, it is not possible to get back the original @TeX{} mode.
A site-wide default would for this reason be hard to override.
@end itemize

If, however, you are certain that the users all prefer @AUCTeX{}, you
may place the following line in @file{default.el}:

@example
(require 'tex-site)
@end example

XEmacs uses a package system.  The default @AUCTeX{} installation
should cater for everything necessary in that case.

@ignore
For @acronym{RPM} files we include a @file{preview-latex.spec} file in
the tarball distribution, suitable for recent RedHat systems, that
should do just that.
@end ignore

@node Advice for non-privileged users
@section Installation for non-privileged users

Often people without system administration privileges want to install
software for their private use.  In that case you need to specify more
options top the @command{configure} script.  For XEmacs users, this is
fairly easy, because the XEmacs package system has been designed to make
this sort of thing practical: but GNU Emacs users (and XEmacs users for
whom the package system is for some reason misbehaving) may need to do a
little more work.

GNU Emacs users can solve this problem by using the @option{--prefix}
option to the @command{configure} script, and let it point to the personal
home directory.  In that way, resulting binaries will be installed under
the @file{bin} subdirectory of your home directory, manual pages under
@file{man} and so on.  That way, it is reasonably easy to maintain a
bunch of additional packages, since the prefix argument is supported by
most @command{configure} scripts.

You'll have to add something like
@file{/home/myself/share/emacs/site-lisp} to your @code{load-path}
variable, if it isn't there already.

XEmacs users can achieve the same end by pointing @command{configure} at an
appropriate package directory (normally
@option{--with-packagedir=~/.xemacs/xemacs-packages} will serve).  This
should only need to be done once, and should be needed fairly rarely; if
you have installed any personal XEmacs packages before, @command{configure}
should detect that, and automatically install @AUCTeX{} there too;
equally, if you have installed @AUCTeX{} somewhere searched by
XEmacs, @AUCTeX{} should be automatically reinstalled over that
copy.

(@command{configure} may guess wrong if the site administrator has
installed @AUCTeX{} somewhere else: if so, just use the
@option{--with-packagedir} option to override @command{configure}'s
choice.)

But there is another problem: perhaps you want to make it easy for other
users to share parts of your personal Emacs configuration.  In general,
you can do this by writing @samp{~myself/} anywhere where you specify
paths to something installed in your personal subdirectories, not merely
@samp{~/}, since the latter, when used by other users, will point to
non-existent files.

For yourself, it will do to manipulate environment variables in your
@file{.profile} resp.@: @file{.login} files.  But if people will be
copying just Elisp files, their copies will not work.  While it would
in general be preferable if the added components where available from
a shell level, too (like when you call the standalone info reader, or
try using @file{preview.sty} for functionality besides of Emacs
previews), it will be a big help already if things work from inside
of Emacs.

Here is how to do the various parts:

@subheading Making the Elisp available

In XEmacs, you should ask the other users to add symbolic links in their
@file{~/.xemacs/xemacs-packages/lisp},
@file{~/.xemacs/xemacs-packages/info} and
@file{~/.xemacs/xemacs-packages/etc} directories. (Alas, there is
presently no easy programmatic way to do this, except to have a script
do the symlinking for them.)

In GNU Emacs, you'll want the invocation lines described
@ifset rawfile
above.
@end ifset
@ifclear rawfile
in @xref{Loading the package}.
@end ifclear
In addition, you'll want a line such as

@lisp
(add-to-list 'load-path "~myself/share/emacs/site-lisp/preview")
@end lisp

@subheading Making the Info files available

While for yourself, you'll probably want to manipulate the
@samp{INFOPATH} variable; for access inside of Elisp something like
the following might be convenient:

@lisp
(eval-after-load 'info
   '(add-to-list 'Info-directory-list "~myself/info"))
@end lisp

In XEmacs, as long as XEmacs can see the package, there should be no
need to do anything at all; the info files should be immediately
visible.  However, you might want to set @samp{INFOPATH} anyway, for the
sake of standalone readers outside of XEmacs. (The info files in XEmacs
are normally in @file{~/.xemacs/xemacs-packages/info}.)

@ifclear rawfile
@node Installation under MS Windows
@section Installation under MS Windows
@include wininstall.texi
@end ifclear

@node Customizing
@section Customizing
@cindex Site initialization
@cindex Initialization
@cindex @file{tex-site.el}
@cindex Personal customization
@cindex Site customization
@cindex Customization
@cindex Customization, personal
@cindex Customization, site
Most of the site-specific customization should already have happened
during configuration of @AUCTeX{}.  Any further customization can be
done with customization buffers directly in Emacs.  Just type @kbd{M-x
customize-group RET AUCTeX RET} to open the customization group for
@AUCTeX{} or use the menu entries provided in the mode menus.  Editing
the file @file{tex-site.el} as suggested in former versions of @AUCTeX{}
should not be done anymore because the installation routine will
overwrite those changes.

You might check some variables with a special significance.  They are
accessible directly by typing @kbd{M-x customize-variable RET <variable>
RET}.

@defopt TeX-lisp-directory
The directory where you installed the @AUCTeX{} lisp files.
@end defopt

This variable is set automatically during configuration.  If you don't
issue a @code{make install}, for example if you don't want to install
@AUCTeX{} in a different place, you will have to set this variable
manually to the location of the compiled files.  It is generally
advisable to do a full installation including @code{make install}
because program and documentation files will be copied to their proper
places.

@defopt TeX-macro-global
Directories containing the site's @TeX{} style files.
@end defopt

Normally, @AUCTeX{} will only allow you to complete macros and
environments which are built-in, specified in @AUCTeX{} style files or
defined by yourself.  If you issue the @kbd{M-x
TeX-auto-generate-global} command after loading @AUCTeX{}, you will be
able to complete on all macros available in the standard style files
used by your document.  To do this, you must set this variable to a list
of directories where the standard style files are located.  The
directories will be searched recursively, so there is no reason to list
subdirectories explicitly.  Automatic configuration will already have
set the variable for you if it could use the program @samp{kpsewhich}.
In this case you normally don't have to alter anything.

@section Contributed files

There are several files that are not part of @AUCTeX{} proper, but
included in the distribution in case they are useful.

@table @file
@item bib-cite.el
Better support for bibliographies and much more.

@item tex-jp.el
Support for Japanese.

@end table

They can be installed together with @AUCTeX{} by executing @command{make
contrib} and @command{make install-contrib}.  Read the comments in the
start of each file for more information about how to use the files, what
they do, and who wrote and maintains them.
