Copyright (C) 2013 Free Software Foundation, Inc.
See the end of the file for license conditions.
+The MSYS/MinGW build described here is supported on versions of
+Windows starting with Windows 2000 and newer. Windows 9X are not
+supported (but the Emacs binary produced by this build will run on
+Windows 9X as well).
+
* For the brave (a.k.a. "impatient"):
For those who have a working MSYS/MinGW development environment and
It is always preferable to use --prefix to configure Emacs for
some specific location of its installed tree; the default
- /usr/local is not suitable for Windows.
+ /usr/local is not suitable for Windows (see the detailed
+ instructions for the reasons).
You can pass other options to the configure script. Here's a
typical example (for an in-place debug build):
- CPPFLAGS='-DGLYPH_DEBUG=1' CFLAGS='-O0 -g3' ./nt/msysconfig.sh --prefix=d:/usr/emacs --enable-checking
+ CPPFLAGS='-DGLYPH_DEBUG=1' CFLAGS='-O0 -g3' ./nt/msysconfig.sh --prefix=/d/usr/emacs --enable-checking
3. After the configure script finishes, it should display the
resulting configuration. After that, type
A correct installation makes all the rest almost trivial; a botched
installation will likely make you miserable for quite some time.
-** Installing MinGW
+ There are two alternative to installing MinGW + MSYS: using the GUI
+ installer, called mingw-get, provided by the MinGW project, or
+ manual installation. The next two sections describe each one of
+ these.
+
+** Installing MinGW and MSYS using mingw-get
+
+ A nice installer, called mingw-get, is available for those who don't
+ like to mess with manual installations. You can download it from
+ here:
+
+ https://sourceforge.net/projects/mingw/files/Installer/mingw-get/
+
+ (This installer only supports packages downloaded from the MinGW
+ site; for the rest you will still need the manual method.)
+
+ After installing mingw-get, invoke it to install the packages that
+ are already selected by default on the "Select Components" screen of
+ its wizard.
+
+ After that, use "mingw-get install PACKAGE" to install the following
+ additional packages:
+
+ . msys-base
+ . mingw-developer-toolkit
+
+ (We recommend that you refrain from installing the MSYS Texinfo
+ package, which is part of msys-base, because it might produce mixed
+ EOL format when installing Info files. Instead, install the MinGW
+ port of Texinfo, see the ezwinports URL below. To uninstall the
+ MSYS Texinfo, after installing it as part of msys-base, invoke the
+ command "mingw-get remove msys-texinfo".)
+
+ At this point, you should be ready to configure and build Emacs in
+ its basic configuration. Skip to the "Generating the configure
+ script" section for the build instructions. If you want to build it
+ with image support and other optional libraries, read about the
+ optional libraries near the end of this document, before you start
+ the build. Also, consider installing additional MinGW packages that
+ are required/recommended, especially if you are building from the
+ Bazaar repository, as described in the next section.
+
+** Installing MinGW and MSYS manually
+
+*** MinGW
You will need to install the MinGW port of GCC and Binutils, and the
MinGW runtime and Windows API distributions, to compile Emacs. You
MinGW packages from that page: gcc, binutils, mingw-rt, w32api. You
only need the 'bin' and the 'dll' tarballs of each of the above.
- A nice GUI installer, called mingw-get, is available for those who
- don't like to mess with manual installations. You can download it
- from here:
-
- https://sourceforge.net/projects/mingw/files/Installer/mingw-get/
-
- (This installer only supports packages downloaded from the MinGW
- site; for the rest you will still need the manual method.)
-
- MinGW and MSYS packages are distributed as .tar.lzma compressed
- archives. If you like to install the packages manually, then we
- recommend to use the Windows port of the 'bsdtar' program to unpack
- the tarballs. 'bsdtar' is available as part of the 'libarchive'
- package from here:
+ MinGW packages are distributed as .tar.lzma compressed archives. To
+ install the packages manually, we recommend to use the Windows port
+ of the 'bsdtar' program to unpack the tarballs. 'bsdtar' is
+ available as part of the 'libarchive' package from here:
http://sourceforge.net/projects/ezwinports/files/
C:. A typical example would be D:\usr, with D:\usr\bin holding the
binaries and DLLs (should be added to your Path environment
variable), D:\usr\include holding the include files, D:\usr\lib
- holding the static and import libraries, D:\share holding docs,
+ holding the static and import libraries, D:\usr\share holding docs,
message catalogs, and package-specific subdirectories, etc.
Having all the headers and libraries in a single place will greatly
Additional MinGW packages are required/recommended, especially if
you are building from the Bazaar repository:
- . Texinfo (needed to produce the Info manuals when building from bzr)
+ . Texinfo (needed to produce the Info manuals when building from
+ bzr, and for "make install")
Available from http://sourceforge.net/projects/ezwinports/files/.
Available from http://gnuwin32.sourceforge.net/packages/gzip.htm.
- . pkg-config (needed for building with some optional image libraries)
+ . pkg-config (needed for building with some optional libraries,
+ such as GnuTLS and libxml2)
Available from http://www.gtk.org/download/win32.php
Each package might list other packages as prerequisites on its
download page (under "Runtime requirements"); download those as
- well. (Using the GUI installer mingw-get will fetch those
- prerequisites automatically for you.) A missing prerequisite will
- manifest itself by the program failing to run and presenting a
- pop-up dialog that states the missing or incompatible DLL; be sure
- to find and install these missing DLLs.
+ well. (Using the mingw-get installer will fetch those prerequisites
+ automatically for you.) A missing prerequisite will manifest itself
+ by the program failing to run and presenting a pop-up dialog that
+ states the missing or incompatible DLL; be sure to find and install
+ these missing DLLs.
Once you think you have MinGW installed, test the installation by
building a trivial "hello, world!" program, and make sure that it
builds without any error messages and the binary works when run.
-** Installing MSYS
+*** MSYS
- You will also need a reasonably full MSYS installation. MSYS is an
+ You will need a reasonably full MSYS installation. MSYS is an
environment needed to run the Posix configure scripts and the
resulting Makefile's, in order to produce native Windows binaries
using the MinGW compiler and runtime libraries. Here's the list of
repository): Automake and Autoconf. They are available from
here:
- http://sourceforge.net/projects/ezwinports/files/automake-1.11.6-msys-bin.zip/download
- http://sourceforge.net/projects/ezwinports/files/autoconf-2.65-msys-bin.zip/download
+ http://sourceforge.net/projects/ezwinports/files/automake-1.11.6-msys-bin.zip/download
+ http://sourceforge.net/projects/ezwinports/files/autoconf-2.65-msys-bin.zip/download
+
+ MSYS packages are distributed as .tar.lzma compressed archives. To
+ install the packages manually, we recommend to use the Windows port
+ of the 'bsdtar' program, already mentioned above.
If/when you are confident in your MinGW/MSYS installation, and want
to speed up the builds, we recommend installing a pre-release
These are snapshot builds of many packages, but you only need
make.exe from there. The advantage of this make.exe is that it
supports parallel builds, so you can use "make -j N" to considerably
- speed up your builds
+ speed up your builds.
+
+ Several users reported that MSYS 1.0.18 causes Make to hang in
+ parallel builds. If you bump into this, we suggest to downgrade to
+ MSYS 1.0.17, which doesn't have that problem.
For each of these packages, install the 'bin' and 'dll' tarballs of
their latest stable releases. If there's an 'ext' tarball (e.g.,
Each package might list other packages as prerequisites on its
download page (under "Runtime requirements"); download those as
- well. (Using the GUI installer mingw-get will fetch those
- prerequisites automatically for you.) A missing prerequisite will
- manifest itself by the program failing to run and presenting a
- pop-up dialog that states the missing or incompatible DLL; be sure
- to find and install these missing DLLs.
+ well. (Using the mingw-get installer will fetch those prerequisites
+ automatically for you.) A missing prerequisite will manifest itself
+ by the program failing to run and presenting a pop-up dialog that
+ states the missing or incompatible DLL; be sure to find and install
+ these missing DLLs.
MSYS packages should be installed in a separate tree from MinGW.
For example, use D:\MSYS or D:\usr\MSYS as the top-level directory
need.
At this point, you are ready to build Emacs in its basic
- configuration. If you want to build it with image support, read
- about the optional image libraries near the end of this document.
+ configuration. If you want to build it with image support and other
+ optional libraries, read about that near the end of this document.
-* Generating the configure script.
+* Generating the configure script
If you are building a release or pretest tarball, skip this section,
because the configure script is already present in the tarball.
./nt/msysconfig.sh --prefix=PREFIX ...
Here PREFIX is the place where you eventually want to install Emacs
- once built, e.g. d:/usr.
+ once built, e.g. /d/usr. We recommend to always use --prefix when
+ building Emacs on Windows, because the default '/usr/local' is not
+ appropriate for Windows: it will be mapped by MSYS to something like
+ C:\MSYS\local, and it will defeat the purpose of PREFIX, which is to
+ install programs in a single coherent tree resembling Posix systems.
+ Such a single-tree installation makes sure all the other programs
+ and packages ported from GNU or Unix systems will work seamlessly
+ together. Where exactly is the root of that tree on your system is
+ something only you, the user who builds Emacs, can know, and the
+ Emacs build process cannot guess, because usually there's no
+ '/usr/local' directory on any drive on Windows systems.
+
+ Do NOT use Windows-style x:/foo/bar file names on the configure
+ script command line; use the MSYS-style /x/foo/bar instead. Using
+ Windows-style file names was reported to cause subtle and hard to
+ figure out problems during the build. This applies both to the
+ command switches, such as --prefix=, and to the absolute file name
+ of msysconfig.sh, if you are building outside of the source tree.
You can pass additional options to the configure script, for the
full list type
headers in C:\emacs\libs\jpeg-6b-4-lib\include, you will need to say
something like this:
- CPPFLAGS='-Ic:/emacs/libs/libpng-1.2.37-lib/include -Ic:/emacs/libs/jpeg-6b-4-lib/include' ./nt/msysconfig.sh --prefix=PREFIX
+ CPPFLAGS='-I/c/emacs/libs/libpng-1.2.37-lib/include -I/c/emacs/libs/jpeg-6b-4-lib/include' ./nt/msysconfig.sh --prefix=PREFIX
which is quite a mouth-full, especially if you have more directories
to specify... Perhaps you may wish to revisit your installation
decisions now.
+ If you have a global site-lisp directory from previous Emacs
+ installation, and you want Emacs to continue using it, specify it
+ via the --enable-locallisppath switch to msysconfig.sh, like this:
+
+ ./nt/msysconfig.sh --prefix=PREFIX --enable-locallisppath="/d/usr/share/emacs/VERSION/site-lisp:/d/wherever/site-lisp"
+
+ Use the normal MSYS /d/foo/bar style to specify directories by their
+ absolute file names.
+
A few frequently used options are needed when you want to produce an
unoptimized binary with runtime checks enabled:
Does Emacs use -lxft? no
Does Emacs use toolkit scroll bars? yes
- You are almost there, hand on.
+ You are almost there, hang on.
If the output is significantly different, or if configure finishes
prematurely and displays some error message, you should examine the
This is simple: just type "make" and sit back, watching the fun.
- If you installed a snapshot build of Make, the build will be much
- faster if you type "make -j N" instead, where N is the number of
- independent processing units on your machine. E.g., on a core i7
- system try using N of 6 or even 8.
+ If you installed a snapshot build of Make, the build will be much
+ faster if you type "make -j N" instead, where N is the number of
+ independent processing units on your machine. E.g., on a core i7
+ system try using N of 6 or even 8. (If this hangs, see the notes
+ above about downgrading to MSYS 1.0.17.)
When Make finishes, you can install the produced binaries:
support for svg.
To build Emacs with support for them, the corresponding headers must
- be in the include path when the configure script is run. This is be
- set up using the CPPFLAGS and CFLAGS variable specified on the
- configure command line. The configure script will report whether it
- was able to detect the headers. If the results of this testing
- appear to be incorrect, please look for details in the file
- config.log: it will show the failed test programs and compiler error
- messages that should explain what is wrong. (Usually, any such
- failures happen because some headers are missing due to bad
- packaging of the image support libraries.)
+ be in the include path and libraries should be where the linker
+ looks for them, when the configure script is run. If needed, this
+ can be set up using the CPPFLAGS and CFLAGS variable specified on
+ the configure command line. The configure script will report
+ whether it was able to detect the headers and libraries. If the
+ results of this testing appear to be incorrect, please look for
+ details in the file config.log: it will show the failed test
+ programs and compiler error messages that should explain what is
+ wrong. (Usually, any such failures happen because some headers are
+ missing due to bad packaging of the image support libraries.)
Note that any file path passed to the compiler or linker must use
forward slashes, or double each backslash, as that is how Bash
works.
- If the configure script finds the necessary headers, but they are
- for some reason incompatible, or if you want to omit support for
- some image library that is installed on your system for some other
- reason, use the --without-PACKAGE option to configure, such as
- --without-gif to omit GIF, --without-tiff to omit TIFF, etc.
+ If the configure script finds the necessary headers and libraries,
+ but they are for some reason incompatible, or if you want to omit
+ support for some image library that is installed on your system for
+ some other reason, use the --without-PACKAGE option to configure,
+ such as --without-gif to omit GIF, --without-tiff to omit TIFF, etc.
Passing the --help option to the configure script displays all of
the supported --without-PACKAGE options.
compatible (for example, that they were built with the same compiler).
Binaries for the image libraries (among many others) can be found at
- the GnuWin32 project. PNG, JPEG and TIFF libraries are also
- included with GTK, which is installed along with other Free Software
- that requires it. Note specifically that, due to some packaging
- snafus in the GnuWin32-supplied image libraries, you will need to
- download _source_ packages for some of the libraries in order to get
- the header files necessary for building Emacs with image support.
+ the GnuWin32 project. The PNG libraries are also included with GTK,
+ which is installed along with other Free Software that requires it.
+ Note specifically that, due to some packaging snafus in the
+ GnuWin32-supplied image libraries, you will need to download
+ _source_ packages for some of the libraries in order to get the
+ header files necessary for building Emacs with image support.
For PNG images, we recommend to use versions 1.4.x and later of
libpng, because previous versions had security issues. You can find
* Optional GnuTLS support
- If the configure script finds the gnutls/gnutls.h file in the
- include path, Emacs is built with GnuTLS support by default; to
+ To compile with GnuTLS, you will need pkg-config to be installed, as
+ the configure script invokes pkg-config to find out which compiler
+ switches to use for GnuTLS. See above for the URL where you can
+ find pkg-config for Windows.
+
+ You will also need to install the p11-kit package, which is a
+ dependency of GnuTLS, and its header files are needed for
+ compilation of programs that use GnuTLS. You can find p11-kit on
+ the same site as GnuTLS, see the URL below.
+
+ If the configure script finds the GnuTLS header files and libraries
+ on your system, Emacs is built with GnuTLS support by default; to
avoid that you can pass the argument --without-gnutls.
In order to support GnuTLS at runtime, a GnuTLS-enabled Emacs must
* Optional libxml2 support
- If the configure script finds the libxml/HTMLparser.h file in the
- include path, Emacs is built with libxml2 support by default; to
+ To compile with libxml2, you will need pkg-config to be installed,
+ as the configure script invokes pkg-config to find out which
+ compiler switches to use for libxml2. See above for the URL where
+ you can find pkg-config for Windows.
+
+ If the configure script finds the libxml2 header files and libraries
+ on your system, 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
* Experimental SVG support
+ To compile with SVG, you will need pkg-config to be installed, as
+ the configure script invokes pkg-config to find out which compiler
+ switches to use for SVG. See above for the URL where you can find
+ pkg-config for Windows.
+
SVG support is currently experimental, and not built by default.
Specify --with-rsvg and ensure you have all the dependencies in your
include path. Unless you have built a minimalist librsvg yourself