2. Installing AUCTeX

Installing AUCTeX should be simple: merely ./configure, make, and make install. This does not yet activate the package, but merely makes it available. See 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 MS Windows installations in See section Installation under MS Windows.

2.1 Prerequisites

• A recent version of Emacs 21, alternatively XEmacs 21.

  Support for Emacs 20 has been dropped in favor of getting more important work done. For XEmacs, you need at least version 1.84 of the 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 ‘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.

• A working LaTeX installation

  This is not really needed to 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.

• The 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.

2.2 Configure

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 generate ./configure by running autogen.sh in the ‘auctex’ directory.)

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:

--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-lispdir=/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.

--with-packagedir=/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 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 ‘~/.xemacs/xemacs-packages’, as XEmacs looks there for per-user packages by default.

--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.

2.3 Build/install

Once configure has been run, simply enter

make

at the prompt to byte-compile the lisp 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.

2.4 Loading the package

First you should make sure that AUCTeX gets loaded. You then need to place a few lines in your personal ‘.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 C-c C-c should give you a command prompt.

If you used --with-packagedir, you have to make sure that the directory ‘lisp/auctex’ under the directory you specified is in XEmacs’ load-path variable.

For GNU Emacs, the recommended way to activate AUCTeX is to add the following line to your ‘.emacs’ file:

(require 'tex-site)

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

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

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.

2.5 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 refrain from activating it automatically when it is installed as a package. This is reasonable because

• Emacs comes with a simpler default TeX mode with different keybindings. Some users might prefer that.
• AUCTeX is activated via (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.

If, however, you are certain that the users all prefer AUCTeX, you may place the following line in ‘default.el’:

(require 'tex-site)

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

2.6 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 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 ‘--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. That way, it is reasonably easy to maintain a bunch of additional packages, 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). This should only need to be done once, and should be needed fairly rarely; if you have installed any personal XEmacs packages before, 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.

(configure may guess wrong if the site administrator has installed AUCTeX somewhere else: if so, just use the ‘--with-packagedir’ option to override 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 ‘~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:

Making the Elisp available

In XEmacs, you should ask the other users to add symbolic links in their ‘~/.xemacs/xemacs-packages/lisp’, ‘~/.xemacs/xemacs-packages/info’ and ‘~/.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 in See section Loading the package. In addition, you’ll want a line such as

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

Making the Info files available

While for yourself, you’ll probably want to manipulate the ‘INFOPATH’ variable; for access inside of Elisp something like the following might be convenient:

(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’.)

2.7 Installation under MS Windows

Installation of AUCTeX is a bit more complicated, but we are working to resolve the issues involved. Please report success/failure to us at ‘auc-tex@sunsite.dk’. Here are the steps to perform:

1. The installation of AUCTeX will require the MSYS tool set from http://www.mingw.org. If you have the Cygwin tool set from http://cygwin.com installed, that should do just fine as well, but it is quite larger and slower.

   If you are installing AUCTeX with one of those sets for an Emacs compiled in a different one, you should try to avoid tool-specific path names like ‘/cygwin/c’. Instead, use the ‘c:’ syntax. It might also help to use forward slashes instead of the backward slashes more typical for MS Windows: while backward slashes are supposed to work if properly escaped in the shell, this is one area easily overlooked by the developers. The same holds for file or directory names with spaces in them. Of course, we want to hear about any problems in that area.

   Compiling Emacs is outside of the scope of this manual. AUCTeX itself does not require a C compiler for installation.

2. Install GNU Emacs from http://ftp.gnu.org/pub/gnu/windows/emacs/ or XEmacs from http://www.xemacs.org.
3. You need a working TeX installation. One popular installation under Windows is MikTeX. Another much more extensive system is TeX live which is rather close to its Unix cousins.
4. Now the fun stuff starts. Unpack the AUCTeX distribution into some installation directory. Do not unpack it right into your Emacs’ own directories: the installation will copy the material that needs to be placed there. Keep the installation directory separate: you can remove its contents after installation completes. Since you are reading this, you probably have already unpacked AUCTeX, but it should still be easy to move it elsewhere now.
5. Ready for takeoff. Start some shell (typically 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-directory

   which makes sure that (1) the AUCTeX manual will be installed in the ‘info/’ directory of your Emacs installation and (2) the automatically generated global style hooks will be installed in the ‘var/’ directory of your Emacs installation. If you are collecting stuff like that in a central directory hierarchy (not untypical with Cygwin), you might want to specify that here instead. 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=/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=/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-lispdir=/dir

   This may be needed for GNU Emacs installation, but hopefully configure should figure this out by itself. Don’t use this for XEmacs, rather use

   --with-packagedir=/dir

   which gives the location of the package directory for XEmacs where stuff should be installed. Again, hopefully this is not necessary to specify.

   --with-auto-dir=/dir

   Directory containing automatically generated information. You should not normally need to set this, as ‘--prefix’ should take care of this.

   Some additional information about the above options may be found in Configure.

6. If you need to use the prebuilt documentation (see above), now is the time to unpack it over the rest of the installation directory.
7. Run make in the installation directory (we have had one report that Emacs did not manage to byte compile the Elisp files, and that had to be done by hand. No idea about what might have gone wrong there).
8. Run make install in the installation directory.
9. For GNU Emacs, the recommended way to activate AUCTeX is to add the following line to your ‘.emacs’ file:

   (require 'tex-site)

   The configuration for Windows systems is probably not quite fitting. Instead of loading ‘tex-site.el’ in that manner, you might want to load ‘tex-mik.el’ (for MikTeX) or ‘tex-fptex’ (for fpTeX) instead. Those will lead to somewhat more appropriate values for your system. You can always use

   M-x customize-group <RET> AUCTeX <RET>

   in order to customize more stuff, or use the ‘Customize’ menu.

10. Load a ‘.tex’ file Emacs or XEmacs and see if you get the ‘Command’ menu. Try using that to LaTeX the file.

Well, that about is all. Have fun!

2.8 Customizing

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.

User Option: TeX-lisp-directory

The directory where you installed the AUCTeX lisp files.

This variable is set automatically during configuration. If you don’t issue a 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 make install because program and documentation files will be copied to their proper places.

User Option: TeX-macro-global

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.

2.9 Contributed files

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

‘bib-cite.el’

Better support for bibliographies and much more.

‘tex-jp.el’

Support for Japanese.

They can be installed together with AUCTeX by executing make contrib and 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.

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.