Building and Installing Emacs on Windows
(from 95 to 7 and beyond)
- Copyright (C) 2001-2011 Free Software Foundation, Inc.
+ Copyright (C) 2001-2013 Free Software Foundation, Inc.
See the end of the file for license conditions.
* For the impatient
With GNU Make, you can use the -j command-line option to have
Make execute several commands at once, like this:
+ gmake -j 2
+
+ (With versions of GNU Make before 3.82, you need also set the
+ XMFLAGS variable, like this:
+
gmake -j 2 XMFLAGS="-j 2"
- The XMFLAGS variable overrides the default behavior of GNU Make
- on Windows, whereby recursive Make invocations reset the maximum
- number of simultaneous commands to 1. The above command allows
- up to 4 simultaneous commands at once in the top-level Make, and
- up to 3 in each one of the recursive Make's.
+ The XMFLAGS variable overrides the default behavior of version
+ 3.82 and older of GNU Make on Windows, whereby recursive Make
+ invocations reset the maximum number of simultaneous commands to
+ 1. The above command allows up to 4 simultaneous commands at
+ once in the top-level Make, and up to 3 in each one of the
+ recursive Make's.)
4. Generate the Info manuals (only if you are building out of Bazaar,
and if you have makeinfo.exe installed):
WinZip is known to create some subtle and hard to debug problems,
such as converting files to DOS CR-LF format, not creating empty
directories, etc. We suggest to use djtarnt.exe from the GNU FTP
- site.
+ site. For modern formats, such as .tar.xz, we suggest bsdtar.exe
+ from the libarchive package; its precompiled Windows binaries are
+ available from this site:
+
+ http://sourceforge.net/projects/ezwinports/files/
- In addition to this file, you should also read INSTALL.BZR in the
- parent directory, and make sure that you have a version of
- "touch.exe" in your path, and that it will create files that do not
- yet exist.
+ In addition to this file, if you build a development snapshot, you
+ should also read INSTALL.BZR in the parent directory.
* Supported development environments
To compile Emacs, you will need either Microsoft Visual C++ 2.0, or
later and nmake, or a Windows port of GCC 2.95 or later with MinGW
- and W32 API support and a port of GNU Make. You can use the Cygwin
+ and Windows API support and a port of GNU Make. You can use the Cygwin
ports of GCC, but Emacs requires the MinGW headers and libraries to
build (latest versions of the Cygwin toolkit, at least since v1.3.3,
include the MinGW headers and libraries as an integral part).
session.
You can get pre-built binaries (including any required DLL and the
- gnutls.h file) and an installer at http://josefsson.org/gnutls4win/.
+ header files) at http://sourceforge.net/projects/ezwinports/files/.
+
+* Optional libxml2 support
+
+ If configure.bat finds the libxml/HTMLparser.h file in the include path,
+ Emacs is built with libxml2 support by default; to avoid that you can
+ pass the argument --without-libxml2.
+
+ In order to support libxml2 at runtime, a libxml2-enabled Emacs must
+ be able to find the relevant DLLs during startup; failure to do so
+ is not an error, but libxml2 features won't be available to the
+ running session.
+
+ One place where you can get pre-built Windows binaries of libxml2
+ (including any required DLL and the header files) is here:
+
+ http://sourceforge.net/projects/ezwinports/files/
+
+ To compile Emacs with libxml2 from that site, you will need to pass
+ the "--cflags -I/path/to/include/libxml2" option to configure.bat,
+ because libxml2 header files are installed in the include/libxml2
+ subdirectory of the directory where you unzip the binary
+ distribution. Other binary distributions might use other
+ directories, although include/libxml2 is the canonical place where
+ libxml2 headers are installed on Posix platforms.
+
+ You will also need to install the libiconv "development" tarball,
+ because the libiconv headers need to be available to the compiler
+ when you compile with libxml2 support. A MinGW port of libiconv can
+ be found on the MinGW site:
+
+ http://sourceforge.net/projects/mingw/files/MinGW/Base/libiconv/
+
+ You need the libiconv-X.Y.Z-N-mingw32-dev.tar.lzma tarball from that
+ site.
* Experimental SVG support
maybe a problem with the way Cairo or librsvg is using it that
doesn't show up on other platforms.
+* Optional extra runtime checks
+
+ The configure.bat option --enable-checking builds Emacs with some
+ optional extra runtime checks and assertions enabled. This may be
+ useful for debugging.
+
+* Optional extra libraries
+
+ You can pass --lib LIBNAME option to configure.bat to cause Emacs to
+ link with the specified library. You can use this option more than once.
+
* Building
After running configure, simply run the appropriate `make' program for
* Trouble-shooting
The main problems that are likely to be encountered when building
- Emacs stem from using an old version of GCC, or old MinGW or W32 API
+ Emacs stem from using an old version of GCC, or old MinGW or Windows API
headers. Additionally, Cygwin ports of GNU make may require the Emacs
source tree to be mounted with text!=binary, because the makefiles
generated by configure.bat necessarily use DOS line endings. Also,
2.95 or later is needed, because that is when the Windows port gained
sufficient support for anonymous structs and unions to cope with some
definitions from winnt.h that are used by addsection.c.
- Older versions of the W32 API headers that come with Cygwin and MinGW
+ Older versions of the Windows API headers that come with Cygwin and MinGW
may be missing some definitions required by Emacs, or broken in other
ways. In particular, uniscribe APIs were added to MinGW CVS only on
2006-03-26, so releases from before then cannot be used.
the debugger, and you will be able to debug the cause of the fatal
error.
+ The single most important thing to find out when Emacs aborts or
+ crashes is where did that happen in the Emacs code. This is called
+ "backtrace".
+
+ Emacs on Windows uses more than one thread. When Emacs aborts due
+ to a fatal error, the current thread may not be the application
+ thread running Emacs code. Therefore, to produce a meaningful
+ backtrace from a debugger, you need to instruct it to show the
+ backtrace for every thread. With GDB, you do it like this:
+
+ (gdb) thread apply all backtrace
+
+ To run Emacs under a debugger to begin with, simply start it from
+ the debugger. With GDB, chdir to the `src' directory (if you have
+ the source tree) or to a directory with the `.gdbinit' file (if you
+ don't have the source tree), and type these commands:
+
+ C:\whatever\src> gdb x:\path\to\emacs.exe
+ (gdb) run <ARGUMENTS TO EMACS>
+
+ Thereafter, use Emacs as usual; you can minimize the debugger
+ window, if you like. The debugger will take control if and when
+ Emacs crashes.
+
Emacs functions implemented in C use a naming convention that reflects
their names in lisp. The names of the C routines are the lisp names
prefixed with 'F', and with dashes converted to underscores. For