auctex: Installation under MS Windows
1.2.7 Installation under MS Windows
-----------------------------------
In a Nutshell
.............
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.
1. Install the prerequisites, i.e. GNU Emacs, MSYS or Cygwin, a TeX
system, and Ghostscript.
2. Open the MSYS shell or a Cygwin shell and change to the directory
containing the unzipped file contents.
3. Configure AUCTeX:
For 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' \
--infodir='C:/Program Files/Emacs/info' \
--with-texmf-dir='C:/localtexmf'
The commands above is example 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. Here is how to do that in W2000/XP:
1. On the desktop, right click "My Computer" and select
properties.
2. Click on "Advanced" in the "System Properties" window.
3. Select "Environment Variables".
4. Select "path" in "System Variables" and click "edit". Move to
the front in the line (this might require scrolling) and add
the missing path including drive letter, ended with a
semicolon.
4. If there were no further error messages, type
make
In case there were, please refer to the detailed description below.
5. Finish the installation by typing
make install
Detailed Installation Instructions
..................................
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:
1. You need to unpack the AUCTeX distribution (which you seemingly
have done since you are reading this). It must be unpacked in a
separate installation directory outside of your Emacs file
hierarchy: the installation will later copy all necessary files to
their final destination, and you can ultimately remove the
directory where you unpacked the files.
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.
2. The installation of AUCTeX will require the MSYS tool set from
<http://www.mingw.org/> or the Cygwin tool set from
<http://cygwin.com/>. The latter is slower and larger (the
download size of the base system is about 15 MB) but comes with a
package manager that allows for updating the tool set and
installing additional packages like, for example, the spell checker
aspell.
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.
3. Install a current version of Emacs from
<ftp://ftp.gnu.org/gnu/emacs/windows/>.
4. You need a working TeX installation. One popular installation
under Windows is MiKTeX (http://www.miktex.org). Another much more
extensive system is TeX Live (http://www.tug.org/texlive) which is
rather close to its Unix cousins.
5. A working copy of Ghostscript (http://www.cs.wisc.edu/~ghost/) is
required for preview-latex operation. Examining the output from
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'.
6. Perl (http://www.perl.org) is needed for rebuilding the
documentation if you are working with a copy from Git or have
touched documentation source files in the preview-latex part. If
the line endings of the file 'preview/latex/preview.dtx' don't
correspond with what Perl calls '\n' when reading text files,
you'll run into trouble.
7. Now the fun stuff starts. If you have not yet done so, unpack the
AUCTeX distribution into a separate directory after rereading the
instructions for unpacking above.
8. 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-HIERARCHY'
which tells 'configure' where to perform the installation. It
may also make 'configure' find Emacs automatically; if this
doesn't happen, try '--with-emacs' 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 (see also '--infodir' below) 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-lispdir=DRIVE:/PATH/TO/SITE-LISP'
This 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.
'--infodir=DRIVE:/PATH/TO/INFO/DIRECTORY'
If you are installing into an Emacs directory, info files have
to be put into the 'info' folder below that directory. The
configuration script will usually try to install into the
folder 'share/info', so you have to override this by
specifying something like '--infodir='C:/Program Files/info''
for the configure call.
'--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.
'--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.
9. Run 'make' in the installation directory.
10. Run 'make install' in the installation directory.
11. With Emacs, activation of AUCTeX and preview-latex depends on a
working 'site-start.d' directory or similar setup, since then the
startup files 'auctex.el' and 'preview-latex.el' will have been
placed there. If this has not been done, you should be able to
load the startup files manually with
(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' or '~/.emacs.d/init.el' from
within Emacs).
The default configuration of AUCTeX is probably not the best fit
for Windows systems with MiKTeX. You might want to add
(require 'tex-mik)
after loading 'auctex.el' and 'preview-latex.el' in order to get
more appropriate values for some customization options.
You can always use
M-x customize-group RET AUCTeX RET
in order to customize more stuff, or use the 'Customize' menu.
12. Load 'preview/circ.tex' into Emacs and see if you get the
'Command' menu. Try using it to LaTeX the file.
13. Check whether the 'Preview' menu is available in this file. Use
it to generate previews for the document.
If this barfs and tells you that image type 'png' is not supported,
you can either add PNG support to your Emacs installation or choose
another image format to be used by preview-latex.
Adding support for an image format usually involves the
installation of a library, e.g. from <http://gnuwin32.sf.net/>.
If you got your Emacs from <http://www.gnu.org> you might want to
check its README file (ftp://ftp.gnu.org/gnu/emacs/windows/README)
for details.
A different image format can be chosen by setting the variable
'preview-image-type'. While it is recommended to keep the 'dvipng'
or 'png' setting, you can temporarily select a different format
like 'pnm' to check if the lack of PNG support is the only problem
with your Emacs installation.
Try adding the line
(setq preview-image-type 'pnm)
to your init file for a quick test. You should remove the line
after the test again, because PNM files take away *vast* amounts of
disk space, and thus also of load/save time.
Well, that about is all. Have fun!
Info Catalog
auctex: Advice for non-privileged users
auctex: Installation
auctex: Customizing