[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Installing AUCTeX should be simple: merely ./configure
,
make
, and make install
for a standard site-wide
installation (most other installations can be done by specifying a
`--prefix=…' option).
On many systems, this will already activate the package, making its modes the default instead of the built-in modes of Emacs. If this is not the case, consult Loading the package. Please read through this document fully before installing anything. The installation procedure has changed as compared to earlier versions. Users of MS Windows are asked to consult See section Installation under MS Windows.
2.1 Prerequisites | ||
2.2 Configure | ||
2.3 Build/install | ||
2.4 Loading the package | ||
2.5 Providing AUCTeX as a package | ||
2.6 Installation for non-privileged users | ||
2.7 Installation under MS Windows | ||
2.8 Customizing |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Emacs 20 is no longer supported, and neither is XEmacs with a
version of xemacs-base
older than 1.84 (released in sumo from
02/02/2004). Using preview-latex requires a version of Emacs compiled
with image support. This means that Emacs 21 will work only in the
version for X11: for Windows and MacOSX, you need to use Emacs 22
(which is not yet released) or a developer version. Since the developer
version is quite stable by now and features four more years of
development and bugfixes, we recommend its use even for X11-based
platforms. You can get it here:
Precompiled versions are available from http://www.crasseux.com/emacs/ and http://nqmacs.sf.net/.
A precompiled version including an installer as well as preinstalled versions of AUCTeX and preview-latex is available from http://yaced.sf.net/. A different port is http://home.att.ne.jp/alpha/z123/emacs-mac-e.html.
Debian provides `emacs-snapshot' and `emacs-snapshot-gtk' packages in its `unstable' distribution.
Compiling Emacs yourself requires a C compiler and a number of tools and development libraries. Details are beyond the scope of this manual. Instructions for checking out the source code can be found at http://savannah.gnu.org/cvs/?group=emacs.
If you really need to use Emacs 21 on platforms where this implies missing image support, you should disable the installation of preview-latex (see below).
While XEmacs (version 21.4.15, 21.4.17 or later) is supported, doing this in a satisfactory manner has proven to be difficult. This is mostly due to technical shortcomings and differing API's which are hard to come by. If AUCTeX is your main application for XEmacs, you are likely to get better results and support by switching to Emacs. Of course, you can improve support for your favorite editor by giving feedback in case you encounter bugs.
Well, AUCTeX would be pointless without that. Processing documentation requires TeX, LaTeX and Texinfo during installation. preview-latex requires Dvips for its operation in DVI mode. The default configuration of AUCTeX is tailored for teTeX-based distributions, but can be adapted easily.
This is needed for operation of preview-latex in both DVI and PDF mode. Most versions of Ghostscript nowadays in use should work fine (version 7.0 and newer). If you encounter problems, check (preview-latex)Problems with Ghostscript section `Problems with Ghostscript' in the preview-latex manual.
texinfo
package
Strictly speaking, you can get away without it if you are building from the distribution tarball, have not modified any files and don't need a printed version of the manual: the pregenerated info file is included in the tarball. At least version 4.0 is required.
For some known issues with various software, see (preview-latex)Known problems section `Known problems' in the preview-latex manual.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The first step is to configure the source code, telling it where various files will be. To do so, run
./configure options |
(Note: if you have fetched AUCTeX from CVS rather than a regular release, you will have to first follow the instructions in `README.CVS').
On many machines, you will not need to specify any options, but if
configure
cannot determine something on its own, you'll need to
help it out with one of these options:
--prefix=`/usr/local'
All automatic placements for package components will be chosen from sensible existing hierarchies below this: directories like `man', `share' and `bin' are supposed to be directly below prefix.
Only if no workable placement can be found there, in some cases an alternative search will be made in a prefix deduced from a suitable binary.
`/usr/local' is the default prefix, intended to be suitable for a site-wide installation. If you are packaging this as an operating system component for distribution, the setting `/usr' will probably be the right choice. If you are planning to install the package as a single non-priviledged user, you will typically set prefix to your home directory.
--with-emacs[=/path/to/emacs]
If you are using a pretest which isn't in your $PATH
, or
configure
is not finding the right Emacs executable, you can
specify it with this option.
--with-xemacs[=/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.
--with-packagedir=/dir
This XEmacs-only option configures the directory for XEmacs packages. A typical user-local setting would be `~/.xemacs/xemacs-packages'. If this directory exists and is below prefix, it should be detected automatically. This will install and activate the package.
--without-packagedir
This XEmacs-only option switches the detection of a package directory and corresponding installation off. Consequently, the Emacs installation scheme will be used. This might be appropriate if you are using a different package system/installer than the XEmacs one and want to avoid conflicts.
The Emacs installation scheme has the following options:
--with-lispdir=/dir
This Emacs-only option specifies the location of the `site-lisp' directory within `load-path' under which the files will get installed (the bulk will get installed in a subdirectory). `./configure' should figure this out by itself.
--with-auctexstartfile=`auctex.el'
--with-previewstartfile=`preview-latex.el'
This is the name of the respective startup files. If lispdir contains a subdirectory `site-start.d', the start files are placed there, and `site-start.el' should load them automatically. Please be aware that you must not move the start files after installation since other files are found relative to them.
--with-packagelispdir=`auctex'
This is the directory where the bulk of the package gets located. The startfile adds this into load-path.
--with-auto-dir=/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.
--help
This is not an option specific to AUCTeX. A number of standard
options to configure
exist, and we do not have the room to
describe them here; a short description of each is available, using
--help
. If you use `--help=recursive', then also
preview-latex-specific options will get listed.
--disable-preview
This disables configuration and installation of preview-latex. This option is not actually recommended. If your Emacs does not support images, you should really upgrade to a newer version. Distributors should, if possible, refrain from distributing AUCTeX and preview-latex separately in order to avoid confusion and upgrade hassles if users install partial packages on their own.
--with-texmf-dir=/dir
--without-texmf-dir
This option is used for specifying a TDS-compliant directory
hierarchy. Using --with-texmf-dir=/dir
you can specify
where the TeX TDS directory hierarchy resides, and the
TeX files will get installed in
`/dir/tex/latex/preview/'.
If you use the --without-texmf-dir
option, the TeX-related
files will be kept in the Emacs Lisp tree, and at runtime the
TEXINPUTS
environment variable will be made to point there. You
can install those files into your own TeX tree at some later time
with M-x preview-install-styles RET.
--with-kpathseasep=`[:|;]'
Set this option if you use --without-texmf-dir
and the
configuration routine cannot figure out itself the directory separator
used by the kpathsea library.
--with-tex-dir=/dir
If you want to specify an exact directory for the preview TeX files,
use --with-tex-dir=/dir
. In this case, the files will be
placed in `/dir', and you'll also need the following option:
--with-doc-dir=/dir
This option may be used to specify where the TeX documentation goes.
It is to be used when you are using --with-tex-dir=/dir
,
but is normally not necessary otherwise.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Once configure
has been run, simply enter
make |
at the prompt to byte-compile the lisp files, extract the TeX files and build the documentation files. To install the files into the locations chosen earlier, type
make install |
You may need special privileges to install, e.g., if you are installing into system directories.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can detect the successful activation of AUCTeX and preview-latex in the menus after loading a LaTeX file like `preview/circ.tex': AUCTeX then gives you a `Command' menu, and preview-latex gives you a `Preview' menu.
For XEmacs, if the installation occured into a valid package directory (which is the default), then this should work out of the box.
With Emacs (or if you explicitly disabled use of the package system),
the startup files `auctex.el' and `preview-latex.el' may
already be in a directory of the `site-start.d/' variety if your
Emacs installation provides it. In that case they should be
automatically loaded on startup and nothing else needs to be done. If
not, they should at least have been placed somewhere in your
load-path
. You can then load them by placing the lines
(load "auctex.el" nil t t) (load "preview-latex.el" nil t t) |
into your `~/.emacs' file.
If you explicitly used --with-lispdir
, you may need to add the
specified directory into Emacs' load-path
variable by adding
something like
(add-to-list 'load-path "~/elisp") |
before the above lines into your Emacs startup file.
For site-wide activation in GNU Emacs, see See section Providing AUCTeX as a package.
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
There are people that prefer the built-in Emacs modes for editing TeX files, in particular plain TeX users. There are various ways to tell AUCTeX even after auto-activation that it should not get used, and they are described in Introduction to AUCTeX.
So if you have users that don't want to use the preinstalled AUCTeX, they can easily get rid of it. Activating AUCTeX by default is therefore a good choice.
If the installation procedure did not achieve this already by placing `auctex.el' and `preview-latex.el' into a possibly existing `site-start.d' directory, you can do this by placing
(load "auctex.el" nil t t) (load "preview-latex.el" nil t t) |
in the system-wide `site-start.el'.
If your package is intended as an XEmacs package or to accompany a
precompiled version of Emacs, you might not know which TeX system
will be available when preview-latex gets used. In this case you
should build using the --without-texmf-dir
option described
previously. This can also be convenient for systems that are intended
to support more than a single TeX distribution. Since more often than
not TeX packages for operating system distributions are either much
more outdated or much less complete than separately provided systems
like TeX Live, this method may be generally preferable when
providing packages.
The following package structure would be adequate for a typical fully supported Unix-like installation:
Style files and documentation for `preview.sty', placed into a TeX tree where it is accessible from the teTeX executables usually delivered with a system. If there are other commonly used TeX system packages, it might be appropriate to provide separate packages for those.
This package will require the installation of `preview-tetex' and will record in `TeX-macro-global' where to find the TeX tree. It is also a good idea to run
emacs -batch -f TeX-auto-generate-global |
when either AUCTeX or teTeX get installed or upgraded. If your users might want to work with a different TeX distribution (nowadays pretty common), instead consider the following:
This package will be compiled with `--without-texmf-dir' and will consequently contain the `preview' style files in its private directory. It will probably not be possible to initialize `TeX-macro-global' to a sensible value, so running `TeX-auto-generate-global' does not appear useful. This package would neither conflict with nor provide `preview-tetex'.
Those are the obvious XEmacs equivalents. For XEmacs, there is the
additional problem that the XEmacs sumo package tree already possibly
provides its own version of AUCTeX, and the user might even have used
the XEmacs package manager to updating this package, or even installing
a private AUCTeX version. So you should make sure that such a
package will not conflict with existing XEmacs packages and will be
at an appropriate place in the load order (after site-wide and
user-specific locations, but before a distribution-specific sumo package
tree). Using the --without-packagedir
option might be one idea
to avoid conflicts. Another might be to refrain from providing an
XEmacs package and just rely on the user or system administrator to
instead use the XEmacs package system.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Often people without system administration privileges want to install
software for their private use. In that case you need to pass more
options to the 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.
The main expedient is using the `--prefix' option to the `configure' script, and let it point to the personal home directory. In that way, resulting binaries will be installed under the `bin' subdirectory of your home directory, manual pages under `man' and so on. It is reasonably easy to maintain a bunch of personal software, since the prefix argument is supported by most `configure' scripts.
You'll have to add something like
`/home/myself/share/emacs/site-lisp' to your load-path
variable, if it isn't there already.
XEmacs users can achieve the same end by pointing configure
at an
appropriate package directory (normally
`--with-packagedir=~/.xemacs/xemacs-packages' will serve). The
package directory stands a good chance at being detected automatically
as long as it is in a subtree of the specified prefix.
Now here is another thing to ponder: 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 `~myself/' anywhere where you specify paths to something installed in your personal subdirectories, not merely `~/', 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 `.profile' resp. `.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 `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:
In GNU Emacs, it should be sufficient if people just do
(load "~myself/share/emacs/site-lisp/auctex.el" nil t t) (load "~myself/share/emacs/site-lisp/preview-latex.el" nil t t) |
where the path points to your personal installation. The rest of the package should be found relative from there without further ado.
In XEmacs, you should ask the other users to add symbolic links in the subdirectories `lisp', `info' and `etc' of their `~/.xemacs/xemacs-packages/' directory. (Alas, there is presently no easy programmatic way to do this, except to have a script do the symlinking for them.)
For making the info files accessible from within Elisp, something like the following might be convenient to add into your or other people's startup files:
(eval-after-load 'info '(add-to-list 'Info-directory-list "~myself/info")) |
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 INFOPATH
anyway, for the
sake of standalone readers outside of XEmacs. (The info files in XEmacs
are normally in `~/.xemacs/xemacs-packages/info'.)
If you want others to be able to share your installation, you should configure it using `--without-texmf-dir', in which case things should work as well for them as for you.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following are brief installation instructions for the impatient. In case you don't understand some of this, run into trouble of some sort, or need more elaborate information, refer to the detailed instructions further below.
For GNU Emacs: Many people like to install AUCTeX into the pseudo file system hierarchy set up by the Emacs installation. Assuming Emacs is installed in `C:/Program Files/Emacs' and the directory for local additions of your TeX system, e.g. MikTeX, is `C:/localtexmf', you can do this by typing the following statement at the shell prompt:
./configure --prefix='C:/Program Files/Emacs' \ --with-texmf-dir='C:/localtexmf' |
For XEmacs: You can install AUCTeX as an XEmacs package. Assuming XEmacs is installed in `C:/Program Files/XEmacs' and the directory for local additions of your TeX system, e.g. MikTeX, is `C:/localtexmf', you can do this by typing the following command at the shell prompt:
./configure --with-xemacs='C:/Program Files/XEmacs/bin/xemacs' \ --with-texmf-dir='C:/localtexmf' |
The commands above are examples for common usage. More on configuration options can be found in the detailed installation instructions below.
If the configuration script failed to find all required programs, make
sure that these programs are in your system path and add directories
containing the programs to the PATH
environment variable if
necessary.
make |
In case there were, please refer to the detailed description below.
make install |
Installation of AUCTeX under Windows is in itself not more complicated than on other platforms. However, meeting the prerequisites might require more work than on some other platforms, and feel less natural.
If you are experiencing any problems, even if you think they are of your own making, be sure to report them to auctex-devel@gnu.org so that we can explain things better in future.
Windows is a problematic platform for installation scripts. The main problem is that the installation procedure requires consistent file names in order to find its way in the directory hierarchy, and Windows path names are a mess.
The installation procedure tries finding stuff in system search paths
and in Emacs paths. For that to succeed, you have to use the same
syntax and spelling and case of paths everywhere: in your system search
paths, in Emacs' load-path
variable, as argument to the scripts.
If your path names contain spaces or other `shell-unfriendly'
characters, most notably backslashes for directory separators, place the
whole path in `"double quote marks"' whenever you specify it on a
command line.
Avoid `helpful' magic file names like `/cygdrive/c' and `C:\PROGRA~1\' like the plague. It is quite unlikely that the scripts will be able to identify the actual file names involved. Use the full paths, making use of normal Windows drive letters like ` 'C:/Program Files/Emacs' ' where required, and using the same combination of upper- and lowercase letters as in the actual files. File names containing shell-special characters like spaces or backslashes (if you prefer that syntax) need to get properly quoted to the shell: the above example used single quotes for that.
Ok, now here are the steps to perform:
Line endings are a problem under Windows. The distribution contains only text files, and theoretically most of the involved tools should get along with that. However, the files are processed by various utilities, and it is conceivable that not all of them will use the same line ending conventions. If you encounter problems, it might help if you try unpacking (or checking out) the files in binary mode, if your tools allow that.
If you don't have a suitable unpacking tool, skip to the next step: this should provide you with a working `unzip' command.
If Cygwin specific paths like `/cygdrive/c' crop up in the course of the installation, using a non-Cygwin Emacs could conceivably cause trouble. Using Cygwin either for everything or nothing might save headaches, if things don't work out.
If you don't want to use a developer version and Emacs 22 has not yet been released, it is also possible to use an Emacs 21 binary from http://ftp.gnu.org/pub/gnu/windows/emacs/, but then you should disable the installation of preview-latex (it will not work). Since the developer version has seen quite a few improvements relevant also for other features of AUCTeX, we really recommend you give it a try.
gswin32c -h |
on a Windows command line should tell you whether your Ghostscript
supports the png16m
device needed for PNG support.
MikTeX apparently comes with its own Ghostscript called `mgs.exe'.
\n
when reading text files,
you'll run into trouble.
bash
) capable of
running configure
, change into the installation directory and
call ./configure
with appropriate options.
Typical options you'll want to specify will be
--prefix=drive:/path/to/emacs-hierarchy
which tells `configure' where to perform the installation. It may also make `configure' find Emacs or XEmacs automatically; if this doesn't happen, try one of `--with-emacs' or `--with-xemacs' as described below. All automatic detection of files and directories restricts itself to directories below the prefix or in the same hierarchy as the program accessing the files. Usually, directories like `man', `share' and `bin' will be situated right under prefix.
This option also affects the defaults for placing the Texinfo documentation files and automatically generated style hooks.
If you have a central directory hierarchy (not untypical with Cygwin) for such stuff, you might want to specify its root here. You stand a good chance that this will be the only option you need to supply, as long as your TeX-related executables are in your system path, which they better be for AUCTeX's operation, anyway.
--with-emacs
if you are installing for a version of Emacs. You can use
`--with-emacs=drive:/path/to/emacs' to specify the name of the
installed Emacs executable, complete with its path if necessary (if
Emacs is not within a directory specified in your PATH
environment
setting).
--with-xemacs
if you are installing for a version of XEmacs. Again, you can use
`--with-xemacs=drive:/path/to/xemacs' to specify the name of the
installed XEmacs executable complete with its path if necessary. It may
also be necessary to specify this option if a copy of Emacs is found in
your PATH
environment setting, but you still would like to install
a copy of AUCTeX for XEmacs.
--with-packagedir=drive:/dir
is an XEmacs-only option giving the location of the package directory. This will install and activate the package. Emacs uses a different installation scheme:
--with-lispdir=drive:/path/to/site-lisp
This Emacs-only option tells a place in load-path
below which the
files are situated. The startup files `auctex.el' and
`preview-latex.el' will get installed here unless a subdirectory
`site-start.d' exists which will then be used instead. The other
files from AUCTeX will be installed in a subdirectory called
`auctex'.
If you think that you need a different setup, please refer to the full installation instructions in Configure.
--with-auto-dir=drive:/dir
Directory containing automatically generated information. You should not normally need to set this, as `--prefix' should take care of this.
--disable-preview
Use this option if your Emacs version is unable to support image display. This will be the case if you are using a native variant of Emacs 21.
--with-texmf-dir=drive:/dir
This will specify the directory where your TeX installation sits. If your TeX installation does not conform to the TDS (TeX directory standard), you may need to specify more options to get everything in place:
For more information about any of the above and additional options, see Configure.
Calling `./configure --help=recursive' will tell about other options, but those are almost never required.
Some executables might not be found in your path. That is not a good idea, but you can get around by specifying environment variables to `configure':
GS="drive:/path/to/gswin32c.exe" ./configure … |
should work for this purpose. `gswin32c.exe' is the usual name for the required command line executable under Windows; in contrast, `gswin32.exe' is likely to fail.
As an alternative to specifying variables for the `configure' call
you can add directories containing the required executables to the
PATH
variable of your Windows system. This is especially a good
idea if Emacs has trouble finding the respective programs later during
normal operation.
make
in the installation directory.
make install
in the installation directory.
(load "auctex.el" nil t t) (load "preview-latex.el" nil t t) |
in either a site-wide `site-start.el' or your personal startup file (usually accessible as `~/.emacs' from within Emacs and `~/.xemacs/init.el' from within XEmacs).
The default configuration of AUCTeX is probably not the best fit for Windows systems. You might want to additionally use
(require 'tex-mik) |
or
(require 'tex-fptex) |
in order to get more appropriate values for MikTeX and fpTeX, respectively.
You can always use
M-x customize-group RET AUCTeX RET |
in order to customize more stuff, or use the `Customize' menu.
If this barfs and tells you that image type `png' is not supported, try adding the line
(setq preview-image-type 'pnm) |
at the end of your installed version of `preview-latex.el'. If this helps, complain to wherever you got your Emacs from: all current Emacs/XEmacs versions capable of running preview-latex by now can be compiled to support PNG images. Which is important, because PNM files take away vast amounts of disk space, and thus also of load/save time.
Well, that about is all. Have fun!
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 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 `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 M-x customize-variable RET <variable> RET.
Directories containing the site's TeX style files.
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 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 `kpsewhich'. In this case you normally don't have to alter anything.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by root on March, 14 2007 using texi2html 1.76.