1 @c This is part of the AUCTeX Manual.
2 @c Copyright (C) 2003, 2004, 2005, 2006, 2007, 2009
3 @c Free Software Foundation, Inc.
4 @c See the file auctex.texi for copying conditions.
9 @subheading In a Nutshell
11 The following are brief installation instructions for the impatient. In
12 case you don't understand some of this, run into trouble of some sort,
13 or need more elaborate information, refer to the detailed instructions
18 Install the prerequisites, i.e. Emacs or XEmacs, MSYS or Cygwin, a
19 @TeX{} system, and Ghostscript.
22 Open the MSYS shell or a Cygwin shell and change to the directory
23 containing the unzipped file contents.
28 For Emacs: Many people like to install @AUCTeX{} into the pseudo file
29 system hierarchy set up by the Emacs installation. Assuming Emacs is
30 installed in @file{C:/Program Files/Emacs} and the directory for local
31 additions of your @TeX{} system, e.g. MiK@TeX{}, is
32 @file{C:/localtexmf}, you can do this by typing the following statement
36 ./configure --prefix='C:/Program Files/Emacs' \
37 --infodir='C:/Program Files/Emacs/info' \
38 --with-texmf-dir='C:/localtexmf'
41 For XEmacs: You can install @AUCTeX{} as an XEmacs package. Assuming
42 XEmacs is installed in @file{C:/Program Files/XEmacs} and the directory
43 for local additions of your @TeX{} system, e.g. MiK@TeX{}, is
44 @file{C:/localtexmf}, you can do this by typing the following command at
48 ./configure --with-xemacs='C:/Program Files/XEmacs/bin/xemacs' \
49 --with-texmf-dir='C:/localtexmf'
52 The commands above are examples for common usage. More on configuration
53 options can be found in the detailed installation instructions below.
55 If the configuration script failed to find all required programs, make
56 sure that these programs are in your system path and add directories
57 containing the programs to the @env{PATH} environment variable if
58 necessary. Here is how to do that in W2000/XP:
61 @cindex Adding to @env{PATH} in Windows
62 @cindex @env{PATH} in Windows
64 On the desktop, right click ``My Computer'' and select properties.
66 Click on ``Advanced'' in the ``System Properties'' window.
68 Select ``Environment Variables''.
70 Select ``path'' in ``System Variables'' and click ``edit''. Move to the
71 front in the line (this might require scrolling) and add the missing
72 path including drive letter, ended with a semicolon.
76 If there were no further error messages, type
82 In case there were, please refer to the detailed description below.
85 Finish the installation by typing
92 @subheading Detailed Installation Instructions
94 Installation of @AUCTeX{} under Windows is in itself not more
95 complicated than on other platforms. However, meeting the prerequisites
96 might require more work than on some other platforms, and feel less
99 If you are experiencing any problems, even if you think they are of your
100 own making, be sure to report them to @email{auctex-devel@@gnu.org} so
101 that we can explain things better in future.
103 Windows is a problematic platform for installation scripts. The main
104 problem is that the installation procedure requires consistent file
105 names in order to find its way in the directory hierarchy, and Windows
106 path names are a mess.
108 The installation procedure tries finding stuff in system search paths
109 and in Emacs paths. For that to succeed, you have to use the same
110 syntax and spelling and case of paths everywhere: in your system search
111 paths, in Emacs' @code{load-path} variable, as argument to the scripts.
112 If your path names contain spaces or other `shell-unfriendly'
113 characters, most notably backslashes for directory separators, place the
114 whole path in @samp{"double quote marks"} whenever you specify it on a
117 Avoid `helpful' magic file names like @samp{/cygdrive/c} and
118 @samp{C:\PROGRA~1\} like the plague. It is quite unlikely that the
119 scripts will be able to identify the actual file names involved. Use
120 the full paths, making use of normal Windows drive letters like
121 @samp{ 'C:/Program Files/Emacs' } where required, and using the same
122 combination of upper- and lowercase letters as in the actual files.
123 File names containing shell-special characters like spaces or
124 backslashes (if you prefer that syntax) need to get properly quoted to
125 the shell: the above example used single quotes for that.
127 Ok, now here are the steps to perform:
131 You need to unpack the @AUCTeX{} distribution (which you seemingly have
132 done since you are reading this). It must be unpacked in a separate
133 installation directory outside of your Emacs file hierarchy: the
134 installation will later copy all necessary files to their final
135 destination, and you can ultimately remove the directory where you
138 Line endings are a problem under Windows. The distribution contains
139 only text files, and theoretically most of the involved tools should get
140 along with that. However, the files are processed by various utilities,
141 and it is conceivable that not all of them will use the same line ending
142 conventions. If you encounter problems, it might help if you try
143 unpacking (or checking out) the files in binary mode, if your tools
146 If you don't have a suitable unpacking tool, skip to the next step: this
147 should provide you with a working @samp{unzip} command.
150 The installation of @AUCTeX{} will require the MSYS tool set from
151 @uref{http://www.mingw.org/} or the Cygwin tool set from
152 @uref{http://cygwin.com/}. The latter is slower and larger (the download
153 size of the base system is about 15 MB) but comes with a package manager
154 that allows for updating the tool set and installing additional packages
155 like, for example, the spell checker @w{aspell}.
157 If Cygwin specific paths like @samp{/cygdrive/c} crop up in the course
158 of the installation, using a non-Cygwin Emacs could conceivably cause
159 trouble. Using Cygwin either for everything or nothing might save
160 headaches, @emph{if} things don't work out.
163 Install a current version of XEmacs from @uref{http://www.xemacs.org/}
164 or @w{Emacs} from @uref{ftp://ftp.gnu.org/gnu/emacs/windows/}.
165 @w{Emacs} is the recommended choice because it is currently the primary
166 platform for @AUCTeX{} development.
169 You need a working @TeX{} installation. One popular installation under
170 Windows is @uref{http://www.miktex.org,MiK@TeX{}}. Another much more
171 extensive system is @uref{http://www.tug.org/texlive,@w{@TeX{} Live}}
172 which is rather close to its Unix cousins.
175 A working copy of @uref{http://www.cs.wisc.edu/~ghost/,Ghostscript} is
176 required for @previewlatex{} operation. Examining the output from
180 on a Windows command line should tell you whether your Ghostscript
181 supports the @code{png16m} device needed for @acronym{PNG} support.
182 MiKTeX apparently comes with its own Ghostscript called @samp{mgs.exe}.
185 @uref{http://www.perl.org,Perl} is needed for rebuilding the
186 documentation if you are working with a copy from @acronym{CVS} or have
187 touched documentation source files in the @previewlatex{} part. If the
188 line endings of the file @file{preview/latex/preview.dtx} don't
189 correspond with what Perl calls @code{\n} when reading text files,
190 you'll run into trouble.
193 Now the fun stuff starts. If you have not yet done so, unpack the
194 @AUCTeX{} distribution into a separate directory after rereading the
195 instructions for unpacking above.
198 Ready for takeoff. Start some shell (typically @command{bash}) capable of
199 running @command{configure}, change into the installation directory and
200 call @command{./configure} with appropriate options.
202 Typical options you'll want to specify will be
204 @item --prefix=@var{drive:/path/to/emacs-hierarchy}
205 which tells @file{configure} where to perform the installation. It may
206 also make @file{configure} find Emacs or XEmacs automatically; if this
207 doesn't happen, try one of @samp{--with-emacs} or @samp{--with-xemacs}
208 as described below. All automatic detection of files and directories
209 restricts itself to directories below the @var{prefix} or in the same
210 hierarchy as the program accessing the files. Usually, directories like
211 @file{man}, @file{share} and @file{bin} will be situated right under
214 This option also affects the defaults for placing the Texinfo
215 documentation files (see also @samp{--infodir} below) and automatically
216 generated style hooks.
218 If you have a central directory hierarchy (not untypical with Cygwin)
219 for such stuff, you might want to specify its root here. You stand a
220 good chance that this will be the only option you need to supply, as
221 long as your @TeX{}-related executables are in your system path, which
222 they better be for @AUCTeX{}'s operation, anyway.
225 if you are installing for a version of Emacs. You can use
226 @samp{--with-emacs=@var{drive:/path/to/emacs}} to specify the name of the
227 installed Emacs executable, complete with its path if necessary (if
228 Emacs is not within a directory specified in your @env{PATH} environment
232 if you are installing for a version of XEmacs. Again, you can use
233 @samp{--with-xemacs=@var{drive:/path/to/xemacs}} to specify the name of the
234 installed XEmacs executable complete with its path if necessary. It may
235 also be necessary to specify this option if a copy of Emacs is found in
236 your @env{PATH} environment setting, but you still would like to install
237 a copy of @AUCTeX{} for XEmacs.
239 @item --with-packagedir=@var{drive:/dir}
240 is an XEmacs-only option giving the location of the package directory.
241 This will install and activate the package. Emacs uses a different
244 @item --with-lispdir=@var{drive:/path/to/site-lisp}
245 This Emacs-only option tells a place in @code{load-path} below which the
246 files are situated. The startup files @file{auctex.el} and
247 @file{preview-latex.el} will get installed here unless a subdirectory
248 @file{site-start.d} exists which will then be used instead. The other
249 files from @AUCTeX{} will be installed in a subdirectory called
252 If you think that you need a different setup, please refer to the full
253 installation instructions in
255 the @file{INSTALL} file.
261 @item --infodir=@var{drive:/path/to/info/directory}
262 If you are installing into an Emacs directory, info files have to be put
263 into the @file{info} folder below that directory. The configuration
264 script will usually try to install into the folder @file{share/info}, so
265 you have to override this by specifying something like
266 @samp{--infodir='C:/Program Files/info'} for the configure call.
268 @item --with-auto-dir=@var{drive:/dir}
269 Directory containing automatically generated information. You should
270 not normally need to set this, as @samp{--prefix} should take care of
273 @item --disable-preview
274 Use this option if your Emacs version is unable to support image
275 display. This will be the case if you are using a native variant of
278 @item --with-texmf-dir=@var{drive:/dir}
279 This will specify the directory where your @TeX{} installation sits. If
280 your @TeX{} installation does not conform to the TDS (@TeX{} directory
281 standard), you may need to specify more options to get everything in
285 For more information about any of the above and additional options, see
287 the `Configure' section in the @file{INSTALL} file.
294 @file{./configure --help=recursive}
295 will tell about other options, but those are almost never required.
297 Some executables might not be found in your path. That is not a good
298 idea, but you can get around by specifying environment variables to
301 GS="@var{drive:/path/to/gswin32c.exe}" ./configure @dots{}
303 should work for this purpose. @file{gswin32c.exe} is the usual name for
304 the required @emph{command line} executable under Windows; in contrast,
305 @file{gswin32.exe} is likely to fail.
307 As an alternative to specifying variables for the @file{configure} call
308 you can add directories containing the required executables to the
309 @env{PATH} variable of your Windows system. This is especially a good
310 idea if Emacs has trouble finding the respective programs later during
314 Run @command{make} in the installation directory.
317 Run @code{make install} in the installation directory.
320 With XEmacs, @AUCTeX{} and @previewlatex{} should now be active by
321 default. With Emacs, activation depends on a working
322 @file{site-start.d} directory or similar setup, since then the startup
323 files @file{auctex.el} and @file{preview-latex.el} will have been placed
324 there. If this has not been done, you should be able to load the
325 startup files manually with
327 (load "auctex.el" nil t t)
328 (load "preview-latex.el" nil t t)
330 in either a site-wide @file{site-start.el} or your personal startup file
331 (usually accessible as @file{~/.emacs} from within Emacs and
332 @file{~/.xemacs/init.el} from within XEmacs).
334 @cindex @file{tex-mik.el}
335 @cindex @file{tex-fptex.el}
336 The default configuration of @AUCTeX{} is probably not the best fit for
337 Windows systems. You might want to add
345 in order to get more appropriate values for MiK@TeX{} and fp@TeX{},
346 respectively after loading @file{auctex.el} and @file{preview-latex.el}.
351 @kbd{M-x customize-group RET AUCTeX RET}
354 in order to customize more stuff, or use the @samp{Customize} menu.
357 Load @file{preview/circ.tex} into Emacs or XEmacs and see if you get the
358 @samp{Command} menu. Try using it to @LaTeX{} the file.
361 Check whether the @samp{Preview} menu is available in this file. Use it
362 to generate previews for the document.
364 If this barfs and tells you that image type @samp{png} is not supported,
365 you can either add @acronym{PNG} support to your Emacs installation or
366 choose another image format to be used by @previewlatex{}.
368 Adding support for an image format usually involves the installation of
369 a library, e.g. from @uref{http://gnuwin32.sf.net/}. If you got your
370 Emacs from @uref{gnu.org} you might want to check its
371 @uref{ftp://ftp.gnu.org/gnu/emacs/windows/README,README file} for
374 A different image format can be chosen by setting the variable
375 @code{preview-image-type}. While it is recommended to keep the
376 @samp{dvipng} or @samp{png} setting, you can temporarily select a
377 different format like @samp{pnm} to check if the lack of @acronym{PNG}
378 support is the only problem with your Emacs installation.
383 (setq preview-image-type 'pnm)
386 to your init file for a quick test. You should remove the line after
387 the test again, because @acronym{PNM} files take away @strong{vast}
388 amounts of disk space, and thus also of load/save time.
391 Well, that about is all. Have fun!