@c This is part of the AUCTeX Manual. @c Copyright (C) 1994, 1996, 2003-2007, 2012-2013, @c 2015, 2017, 2018, 2020, 2021 Free Software Foundation, Inc. @c See the file auctex.texi for copying conditions. @ifset rawfile @include macros.texi @node Installation,,(dir),(dir) @top Installing @AUCTeX{} @end ifset @ifclear rawfile @node Installation @chapter Installing @AUCTeX{} @end ifclear The modern and strongly recommended way of installing @AUCTeX{} is by using the Emacs package manager integrated in Emacs 24 and greater (@acronym{ELPA}). Simply do @kbd{M-x list-packages @key{RET}}, mark the auctex package for installation with @kbd{i}, and hit @kbd{x} to execute the installation procedure. That's all. @code{use-package} users can use this simple recipe in their @code{user-init-file} which essentially does the same as the manual installation explained above. @lisp (use-package tex :ensure auctex) @end lisp Using the @acronym{ELPA} version has several advantages. Besides being platform and @acronym{OS} independent, you will receive intermediate bugfix releases between major @AUCTeX{} releases conveniently. For past @acronym{ELPA} releases, see @url{https://elpa.gnu.org/packages/auctex.html}. @ifclear rawfile Once the installation is completed, you can skip the rest of this section and proceed to @ref{Quick Start}. @end ifclear The remainder of this section is about installing @AUCTeX{} from a release tarball or from a checkout of the @AUCTeX{} repository. Installing @AUCTeX{} should be simple: merely @command{./configure}, @command{make}, and @code{make install} for a standard site-wide installation (most other installations can be done by specifying a @option{--prefix=@dots{}} 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 @ref{Loading the package}. Please read through this document fully before installing anything. The installation procedure has changed as compared to earlier versions. Users of @w{MS Windows} are asked to consult @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 and uninstall:: * Loading the package:: * Advice for package providers:: * Advice for non-privileged users:: * Installation under MS Windows:: * Customizing:: @end menu @end ifclear @ifset rawfile @menu * Prerequisites:: * Configure:: * Build/install and uninstall:: * Loading the package:: * Advice for package providers:: * Advice for non-privileged users:: * Customizing:: @end menu @end ifset @ifset rawfile @node Prerequisites @chapter Prerequisites @raisesections @end ifset @ifclear rawfile @node Prerequisites @section Prerequisites @end ifclear @itemize @bullet @item GNU Emacs 24.3 or higher Using @previewlatex{} requires a version of Emacs compiled with image support. @table @b @item Windows Precompiled versions are available from @uref{https://ftp.gnu.org/gnu/emacs/windows/}. @item macOS For an overview of precompiled versions of Emacs for macOS see for example @uref{https://www.emacswiki.org/emacs/EmacsForMacOS}. @item GNU/Linux Most GNU/Linux distributions nowadays provide a recent variant of Emacs via their package repositories. @item Self-compiled 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 @uref{https://savannah.gnu.org/git/?group=emacs}. @end table @item A working @TeX{} installation Well, @AUCTeX{} would be pointless without that. Processing documentation requires @TeX{}, @LaTeX{} and Texinfo during installation. @previewlatex{} requires Dvips or @command{dvipng} for its operation in @acronym{DVI} mode. The default configuration of @AUCTeX{} is tailored for @w{@TeX{} Live}-based distributions, but can be adapted easily. @item A recent Ghostscript This is needed for operation of @previewlatex{} in both @acronym{DVI} and @acronym{PDF} mode. Ghostscript version 7.07 or newer is required. @item GNU make Recent @AUCTeX{} uses GNU make specific capabilities in the Makefiles. If your @acronym{OS}'s default @command{make} command is not GNU make, you have to obtain it in order to build @AUCTeX{} by yourself. GNU make is sometimes provided under the name @command{gmake} in your @acronym{OS}'s binary package system. @item The 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 @w{version 4.0} is required. @end itemize For some known issues with various software, see @ifset rawfile the @file{PROBLEMS.preview} file. @end ifset @ifclear rawfile @ref{Known problems,,,preview-latex,the @previewlatex{} manual}. @end ifclear @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 Git rather than a regular release, you will have to first follow the instructions in @file{README.GIT}). 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 --prefix=@var{prefix} All automatic placements for package components will be chosen from sensible existing hierarchies below this: directories like @file{man}, @file{share} and @file{bin} are supposed to be directly below @var{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. @file{/usr/local} is the default @var{prefix}, intended to be suitable for a site-wide installation. If you are packaging this as an operating system component for distribution, the setting @file{/usr} will probably be the right choice. See @ref{Advice for package providers} for detail. If you are planning to install the package as a single non-priviledged user, you will typically set @var{prefix} to your home directory. Consult @ref{Advice for non-privileged users} for addtional instructions. @item --with-emacs=@var{/path/to/emacs} If you are using a pretest which isn't in your @env{PATH}, or @command{configure} is not finding the right Emacs executable, you can specify it with this option. @item --with-lispdir=@var{lispdir} This option specifies the location of the @file{site-lisp} directory within @code{load-path} under which the files will get installed (the bulk will get installed in a subdirectory). @command{./configure} should figure this out by itself. @item --with-auctexstartfile=@file{auctex.el} @itemx --with-previewstartfile=@file{preview-latex.el} This is the name of the respective startup files. If @var{lispdir} contains a subdirectory @file{site-start.d}, the start files are placed there, and @file{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 @emph{relative} to them. @item --with-packagelispdir=@file{auctex} This is the directory where the bulk of the package gets located. The startfile adds this into @code{load-path}. @item --with-auto-dir=@var{/dir} You can use this option to specify the directory containing automatically generated information by @kbd{M-x TeX-auto-generate-global @key{RET}}. 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 @option{--help}. @c FIXME: It seems this no longer holds. @c If you use @samp{--help=recursive}, then also @previewlatex{}-specific @c options will get listed. @item --disable-preview This disables configuration and installation of @previewlatex{}. 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 @previewlatex{} separately in order to avoid confusion and upgrade hassles if users install partial packages on their own. @item --with-texmf-dir=@var{/dir} @itemx --without-texmf-dir @cindex preview-install-styles This option is used for specifying a @acronym{TDS}-compliant directory hierarchy. Using @code{--with-texmf-dir=@var{/dir}} you can specify where the @TeX{} @acronym{TDS} directory hierarchy resides, and the @TeX{} files will get installed in @file{@var{/dir}/tex/latex/preview/}. If you use the @option{--without-texmf-dir} option, the @TeX{}-related files will be kept in the Emacs Lisp tree, and at runtime the @env{TEXINPUTS} environment variable will be made to point there. You can install those files into your own @TeX{} tree at some later time with @kbd{M-x preview-install-styles @key{RET}}. @item --with-tex-dir=@var{/dir} If you want to specify an exact directory for the preview @TeX{} files, use @code{--with-tex-dir=@var{/dir}}. In this case, the files will be placed in @file{@var{/dir}}, and you'll also need the following option: @item --with-doc-dir=@var{/dir} This option may be used to specify where the @TeX{} documentation goes. It is to be used when you are using @code{--with-tex-dir=@var{/dir}}, but is normally not necessary otherwise. @end table @node Build/install and uninstall @section Build/install and uninstall @cindex Installation @cindex Make @cindex Uninstallation Once @command{configure} has been run, simply enter @example make @end example @noindent 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 @example make install @end example @noindent You may need special privileges to install, e.g., if you are installing into system directories. Should you want to completely remove the installed package, in the same directory you built @AUCTeX{} run @example make uninstall @end example @noindent You will need administration privileges if you installed the package into system directories. @node Loading the package @section Loading the package @cindex @file{init.el} @cindex @file{.emacs} You can detect the successful activation of @AUCTeX{} and @previewlatex{} in the menus after loading a @LaTeX{} file like @file{circ.tex}: @AUCTeX{} then gives you a @samp{Command} menu, and @previewlatex{} gives you a @samp{Preview} menu. @cindex @file{auctex.el} @cindex @file{tex-site.el} With Emacs (or if you explicitly disabled use of the package system), the startup files @file{auctex.el} and @file{preview-latex.el} may already be in a directory of the @file{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 @code{load-path}. You can then load them by placing the lines @lisp (load "auctex.el" nil t t) (load "preview-latex.el" nil t t) @end lisp @noindent into your init file such as @file{init.el} or @file{.emacs}. If you explicitly used @code{--with-lispdir}, you may need to add the specified directory into Emacs' @code{load-path} variable by adding something like @lisp (add-to-list 'load-path "~/elisp") @end lisp @noindent before the above lines into your Emacs startup file. For site-wide activation in GNU Emacs, see @ifset rawfile below. @end ifset @ifclear rawfile @xref{Advice for package providers}. @end ifclear Once activated, the modes provided by @AUCTeX{} are used per default for all supported file types. If you want to change the modes for which it is operative instead of the default, use @example @kbd{M-x customize-option @key{RET} TeX-modes @key{RET}} @end example If you want to remove a preinstalled @AUCTeX{} completely before any of its modes have been used, @lisp (unload-feature 'tex-site) @end lisp @noindent should accomplish that. @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. 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 @ifset rawfile the @file{README} file. @end ifset @ifclear rawfile @ref{Introduction,,Introduction to @AUCTeX{}}. @end ifclear 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 @file{auctex.el} and @file{preview-latex.el} into a possibly existing @file{site-start.d} directory, you can do this by placing @lisp (load "auctex.el" nil t t) (load "preview-latex.el" nil t t) @end lisp @noindent in the system-wide @file{site-start.el}. The @option{--without-texmf-dir} option can 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 @w{@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: @c FIXME: teTeX is much outdated now. @table @samp @item preview-tetex Style files and documentation for @file{preview.sty}, placed into a @TeX{} tree where it is accessible from the te@TeX{} 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. @item auctex-emacs-tetex This package will require the installation of @samp{preview-tetex} and will record in @code{TeX-macro-global} where to find the @TeX{} tree. It is also a good idea to run @example emacs -batch -f TeX-auto-generate-global @end example when either @AUCTeX{} or te@TeX{} get installed or upgraded. If your users might want to work with a different @TeX{} distribution (nowadays pretty common), instead consider the following: @item auctex-emacs This package will be compiled with @option{--without-texmf-dir} and will consequently contain the @samp{preview} style files in its private directory. It will probably not be possible to initialize @code{TeX-macro-global} to a sensible value, so running @code{TeX-auto-generate-global} does not appear useful. This package would neither conflict with nor provide @samp{preview-tetex}. @end table @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 pass more options to the @command{configure} script. The main expedient is 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. It is reasonably easy to maintain a bunch of personal software, since the prefix argument is supported by most @command{configure} scripts. You often need to specify @option{--with-lispdir} option as well. If you haven't installed Emacs under your home directory and use Emacs installed in system directories, the @command{configure} script might not be able to figure out suitable place to install lisp files under your home directory. In that case, the @command{configure} script would silently choose, by default, the @file{site-lisp} directory within @code{load-path} for the place, where administration privileges are usually required to put relevant files. Thus you will have to tell the @command{configure} script explicitly where to put those files by, e.g., @code{--with-lispdir=@samp{/home/myself/share/emacs/site-lisp}}. You'll have to add something like @samp{/home/myself/share/emacs/site-lisp} to your @code{load-path} variable, if it isn't there already. In addition, you will have to tell @command{configure} script where to install @TeX{}-related files such as @file{preview.sty} if @previewlatex{} isn't disabled. It is enough to specify @option{--with-texmf-dir=@file{$HOME/texmf}} for most typical cases, but you have to create the direcotry @file{$HOME/texmf} in advance if it doesn't exist. If this prescription doesn't work, consider using one or more of the options @code{--with-texmf-dir=@var{/dir}}, @code{--without-texmf-dir}, @code{--with-tex-dir=@var{/dir}} and @code{--with-doc-dir=@var{/dir}}. See @ref{Configure} for detail of these options. 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 @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 GNU Emacs, it should be sufficient if people just do @lisp (load "~myself/share/emacs/site-lisp/auctex.el" nil t t) (load "~myself/share/emacs/site-lisp/preview-latex.el" nil t t) @end lisp @noindent where the path points to your personal installation. The rest of the package should be found relative from there without further ado. @subheading Making the Info files available 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: @lisp (eval-after-load 'info '(add-to-list 'Info-directory-list "~myself/info")) @end lisp @subheading Making the @LaTeX{} style available If you want others to be able to share your installation, you should configure it using @option{--without-texmf-dir}, in which case things should work as well for them as for you. @subsection Using @AUCTeX{} from local Git repo With the techniques described above, it is also possible to use @AUCTeX{} directly from a local Git repository. Let's assume you have your Git repositories under @samp{~/development/}. First, you have to fetch a copy of the @AUCTeX{} Git repository. In a shell, change directory to @samp{~/development/} and do: @example git clone https://git.savannah.gnu.org/git/auctex.git @end example Now change directory to @samp{~/development/auctex} and run @samp{./autogen.sh}. Next thing is to run @command{configure} like this: @example ./configure --without-texmf-dir --with-lispdir=. @end example @noindent When finished, simply enter @example make @end example @noindent and you're finished. Note that the @samp{make install} step is not necessary. Now you have to tell Emacs about the plan. The following variables must be set in your init file because their normal values are only correct when @AUCTeX{} is installed: @lisp (setq TeX-data-directory "~/development/auctex" TeX-lisp-directory TeX-data-directory) @end lisp @noindent The info files will be available with this: @lisp (eval-after-load 'info '(add-to-list 'Info-additional-directory-list "~/development/auctex/doc")) @end lisp @noindent Now you're ready to load @file{auctex.el} and @file{preview-latex.el} out of this directory: @lisp (load "~/development/auctex/auctex.el" nil t t) (load "~/development/auctex/preview-latex.el" nil t t) @end lisp @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 @key{RET} AUCTeX @key{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 options with a special significance. They are accessible directly by typing @kbd{M-x customize-option @key{RET}