Commit 7605d081 authored by Glenn Morris's avatar Glenn Morris
Browse files

Update nt installation instructions to point to supported method

* nt/INSTALL: Rename from INSTALL.MSYS.

* nt/INSTALL.OLD: Rename from INSTALL.

* nt/configure.bat: Update for INSTALL name changes.

* make-dist: Update for nt/INSTALL* changes.
parent 0a357e98
2013-08-31 Glenn Morris <>
* make-dist: Update for nt/INSTALL* changes.
2013-08-28 Paul Eggert <>
* (SHELL): Now @SHELL@, not /bin/sh,
......@@ -762,12 +762,10 @@ meant to be used by other packages.
* Changes in Emacs 24.4 on Non-Free Operating Systems
** Emacs for MS-Windows can now be built by running the configure script
using the MSYS environment and MinGW development tools.
This is from now on the preferred method of building Emacs on
MS-Windows. The Windows-specific configure.bat and makefile.w32-in
files are deprecated. See the file nt/INSTALL.MSYS for detailed
** The procedure for building Emacs on MS-Windows has changed.
It is now built by running the same configure script as on all other
platforms. This requires the MSYS environment and MinGW development
tools. See the updated instructions in nt/INSTALL for details.
Using the Posix configure script and Makefile's also means a change in
the directory structure of the Emacs installation on Windows. It is
......@@ -404,7 +404,7 @@ echo "Making links to \`nt'"
ln config.nt emacsclient.rc emacs-src.tags ../${tempdir}/nt
ln nmake.defs gmake.defs subdirs.el [a-z]*.bat [a-z]*.[ch] ../${tempdir}/nt
ln ../${tempdir}/nt
ln epaths.nt INSTALL.MSYS ../${tempdir}/nt
ln epaths.nt INSTALL.OLD ../${tempdir}/nt
ln ChangeLog INSTALL README README.W32 makefile.w32-in ../${tempdir}/nt)
echo "Making links to \`nt/inc' and its subdirectories"
2013-08-31 Glenn Morris <>
* configure.bat: Update for INSTALL name changes.
2013-08-25 Vincent Belaïche <>
* configure.bat: Rather than disabling, make configure.bat produce
Building and Installing Emacs on Windows
(from 95 to 7 and beyond)
Building and Installing Emacs on MS-Windows
using the MSYS and MinGW tools
Copyright (C) 2001-2013 Free Software Foundation, Inc.
Copyright (C) 2013 Free Software Foundation, Inc.
See the end of the file for license conditions.
*** This method of building Emacs is no longer supported. ***
Instead, see INSTALL.MSYS.
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 impatient
* For the brave (a.k.a. "impatient"):
Here are the concise instructions for configuring and building the
native Windows binary of Emacs, for those who want to skip the
complex explanations and ``just do it'':
For those who have a working MSYS/MinGW development environment and
are comfortable with running Posix configure scripts, here are the
concise instructions for configuring and building the native Windows
binary of Emacs with these tools.
Do not use this recipe with Cygwin. For building on Cygwin,
use the normal installation instructions, ../INSTALL.
Do not use this recipe with Cygwin. For building on Cygwin, use the
normal installation instructions, ../INSTALL.
Do not use these instructions with MSYS environment. For building
the native Windows binary with MinGW and MSYS, follow the
instructions in the file INSTALL.MSYS in this directory.
0. Start the MSYS Bash window. Everything else below is done from
that window's Bash prompt.
For building without MSYS, if you have a Cygwin or MSYS port of Bash
on your Path, you will be better off removing it from PATH. (For
details, search for "MSYS sh.exe" below.)
0a. If you are building from the development trunk (as opposed to a
release tarball), produce the configure script, by typing from
the top-level Emacs source directory:
1. Change to the `nt' directory (the directory of this file):
cd nt
1. If you want to build Emacs outside of the source tree
(recommended), create the build directory and chdir there.
2. Run configure.bat.
2. Invoke the MSYS-specific configure script:
2a.If you use MSVC, set up the build environment by running the
SetEnv.cmd batch file from the appropriate SDK directory. (Skip
this step if you are using MinGW.) For example:
- If you are building outside the source tree:
"C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.cmd" /x86 /Debug
if you are going to compile a debug version, or
- If you are building in-place, i.e. inside the source tree:
"C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.cmd" /x86 /Release
./nt/ --prefix=PREFIX ...
if you are going to compile an optimized version.
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 (see the detailed
instructions for the reasons).
2b.From the COMMAND.COM/CMD.EXE command prompt type:
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/ --prefix=/d/usr/emacs --enable-checking
From a Unixy shell prompt:
3. After the configure script finishes, it should display the
resulting configuration. After that, type
cmd /c configure.bat
or /c configure.bat
3. Run the Make utility suitable for your environment. If you build
with the Microsoft's Visual C compiler:
Use "make -j N" if your MSYS Make supports parallel execution;
the build will take significantly less time in that case. Here N
is the number of simultaneous parallel jobs; use the number of
the cores on your system.
4. Install the produced binaries:
For the development environments based on GNU GCC (MinGW, MSYS,
Cygwin - but see notes about Cygwin make below), depending on how
Make is called, it could be:
make install
If you want the installation tree to go to a place that is
different from the one specified by --prefix, say
(If you are building from Bazaar, say "make bootstrap" or "nmake
bootstrap" instead, and avoid using Cygwin make.)
make install prefix=/where/ever/you/want
With GNU Make, you can use the -j command-line option to have
Make execute several commands at once, like this:
That's it!
gmake -j 2
If these short instructions somehow fail, read the rest of this
(With versions of GNU Make before 3.82, you need also set the
XMFLAGS variable, like this:
* Installing MinGW and MSYS
gmake -j 2 XMFLAGS="-j 2"
Make sure you carefully read the following two sections in their
entirety and install/configure the various packages as instructed.
A correct installation makes all the rest almost trivial; a botched
installation will likely make you miserable for quite some time.
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.)
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
4. Generate the Info manuals (only if you are building out of Bazaar,
and if you have makeinfo.exe installed):
** Installing MinGW and MSYS using mingw-get
make info
A nice installer, called mingw-get, is available for those who don't
like to mess with manual installations. You can download it from
(change "make" to "nmake" if you use MSVC).
5. Install the produced binaries:
(This installer only supports packages downloaded from the MinGW
site; for the rest you will still need the manual method.)
make install
After installing mingw-get, invoke it to install the packages that
are already selected by default on the "Select Components" screen of
its wizard.
That's it!
After that, use "mingw-get install PACKAGE" to install the following
additional packages:
If these short instructions somehow fail, read the rest of this
. msys-base
. mingw-developer-toolkit
* Preliminaries
(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".)
If you want to build a Cygwin port of Emacs, use the instructions in
the INSTALL file in the main Emacs directory (the parent of this
directory). These instructions are for building a native Windows
binary of Emacs.
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.
If you used WinZip to unpack the distribution, we suggest to
remove the files and unpack again with a different program!
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. For modern formats, such as .tar.xz, we suggest bsdtar.exe
from the libarchive package; its precompiled Windows binaries are
available from this site:
** 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
can find these on the MinGW download/Base page:
In general, install the latest stable versions of the following
MinGW packages from that page: gcc, binutils, mingw-rt, w32api. You
only need the 'bin' and the 'dll' tarballs of each of the above.
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:
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 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).
The rest of this file assumes you have a working development
environment. If you just installed such an environment, try
building a trivial C "Hello world" program, and see if it works. If
it doesn't work, resolve that problem first! If you use Microsoft
Visual Studio .NET 2003, don't forget to run the VCVARS32.BAT batch
file from the `Bin' subdirectory of the directory where you have
installed VS.NET. With other versions of MSVC, run the SetEnv.cmd
batch file from the `Bin' subdirectory of the directory where you
have the SDK installed.
If you use the MinGW port of GCC and GNU Make to build Emacs, there
are some compatibility issues wrt Make and the shell that is run by
Make, either the standard COMMAND.COM/CMD.EXE supplied with Windows
or sh.exe, a port of a Unixy shell. For reference, below is a list
of which builds of GNU Make are known to work or not, and whether
they work in the presence and/or absence of sh.exe, the Cygwin port
of Bash. Note that any version of Make that is compiled with Cygwin
will only work with Cygwin tools, due to the use of Cygwin style
paths. This means Cygwin Make is unsuitable for building parts of
Emacs that need to invoke Emacs itself (leim and "make bootstrap",
for example). Also see the Trouble-shooting section below if you
decide to go ahead and use Cygwin make.
In addition, using 4NT or TCC as your shell is known to fail the
build process, at least since 4NT version 3.01. Use CMD.EXE, the
default Windows shell, instead. MSYS sh.exe also appears to cause
various problems, e.g., it is known to cause failures in commands
like "cmd /c FOO" in the Makefiles, because it thinks "/c" is a
Unix-style file name that needs conversion to the Windows format.
If you have MSYS installed, try "make SHELL=cmd.exe" to force the
use of cmd.exe instead of the MSYS sh.exe.
sh exists no sh
cygwin b20.1 make (3.75): fails[1, 5] fails[2, 5]
MSVC compiled gmake 3.77: okay okay
MSVC compiled gmake 3.78.1: okay okay
MSVC compiled gmake 3.79.1: okay okay
mingw32/gcc-2.92.2 make (3.77): okay okay[4]
cygwin compiled gmake 3.77: fails[1, 5] fails[2, 5]
cygwin compiled make 3.78.1: fails[5] fails[2, 5]
cygwin compiled make 3.79.1: fails[3, 5] fails[2?, 5]
cygwin compiled make 3.80: okay[6] fails?[7]
cygwin compiled make 3.81: fails fails?[7]
mingw32 compiled make 3.79.1: okay okay
mingw32 compiled make 3.80: okay okay[7]
mingw32 compiled make 3.81: okay okay[8]
[1] doesn't cope with makefiles with DOS line endings, so must mount
emacs source with text!=binary.
[2] fails when needs to invoke shell commands; okay invoking gcc etc.
[3] requires LC_MESSAGES support to build; cannot build with early
versions of Cygwin.
[4] may fail on Windows 9X and Windows ME; if so, install Bash.
[5] fails when building leim due to the use of cygwin style paths.
May work if building emacs without leim.
[6] need to uncomment 3 lines in nt/gmake.defs that invoke `cygpath'
(look for "cygpath" near line 85 of gmake.defs).
[7] not recommended; please report if you try this combination.
[8] tested only on Windows XP.
Other compilers may work, but specific reports from people that have
tried suggest that the Intel C compiler (for example) may produce an
Emacs executable with strange filename completion behavior. Unless
you would like to assist by finding and fixing the cause of any bugs
like this, we recommend the use of the supported compilers mentioned
in the previous paragraph.
You will also need a copy of the POSIX cp, rm and mv programs. These
and other useful POSIX utilities can be obtained from one of several
* ( GnuWin32 )
* ( MinGW )
* ( Cygwin )
* ( UnxUtils )
If you build Emacs on 16-bit versions of Windows (9X or ME), we
suggest to install the Cygwin port of Bash. That is because the
native Windows shell COMMAND.COM is too limited; the Emacs build
procedure tries very hard to support even such limited shells, but
as none of the Windows developers of Emacs work on Windows 9X, we
cannot guarantee that it works without a more powerful shell.
Additional instructions and help for building Emacs on Windows can be
found at the Emacs Wiki:
and on these URLs:
Both of those pages were written before Emacs switched from CVS to
Bazaar, but the parts about building Emacs still apply in Bazaar.
The second URL has instructions for building with MSVC, as well as
with MinGW, while the first URL covers only MinGW, but has more
details about it.
* Configuring
Configuration of Emacs is now handled by running configure.bat in the
`nt' subdirectory. It will detect which compiler you have available,
and generate makefiles accordingly. You can override the compiler
detection, and control optimization and debug settings, by specifying
options on the command line when invoking configure.
To configure Emacs to build with GCC or MSVC, whichever is available,
simply change to the `nt' subdirectory and run `configure.bat' with no
options. To see what options are available, run `configure --help'.
Do NOT use the --no-debug option to configure.bat unless you are
absolutely sure the produced binaries will never need to be run under
a debugger.
Because of limitations of the stock Windows command shells, special
care is needed to pass some characters in the arguments of the
--cflags and --ldflags options. Backslashes should not be used in
file names passed to the compiler and linker via these options. Use
forward slashes instead. If the arguments to these two options
include the `=' character, like when passing a -DFOO=bar preprocessor
option, the argument with the `=' character should be enclosed in
quotes, like this:
configure --cflags "-DFOO=bar"
Support for options that include the `=' character require "command
extensions" to be enabled. (They are enabled by default, but your
system administrator could have changed that. See "cmd /?" for
details.) If command extensions are disabled, a warning message might
be displayed informing you that "using parameters that include the =
character by enclosing them in quotes will not be supported."
You may also use the --cflags and --ldflags options to pass
additional parameters to the compiler and linker, respectively; they
are frequently used to pass -I and -L flags to specify supplementary
include and library directories. If a directory name includes
spaces, you will need to enclose it in quotes, as follows
-I"C:/Program Files/GnuTLS-2.10.1/include". Note that only the
directory name is enclosed in quotes, not the entire argument. Also
note that this functionality is only supported if command extensions
are available. If command extensions are disabled and you attempt to
use this functionality you may see the following warning message
"Error in --cflags argument: ... Backslashes and quotes cannot be
used with --cflags. Please use forward slashes for filenames and
paths (e.g. when passing directories to -I)."
N.B. It is normal to see a few error messages output while configure
is running, when gcc support is being tested. These cannot be
suppressed because of limitations in the Windows 9X shell.
You are encouraged to look at the file config.log which shows details
for failed tests, after configure.bat finishes. Any unexplained failure
should be investigated and perhaps reported as a bug (see the section
about reporting bugs in the file README in this directory and in the
Emacs manual).
The recommended place to install these packages is a single tree
starting from some directory on a drive other than the system drive
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:\usr\share holding docs,
message catalogs, and package-specific subdirectories, etc.
Having all the headers and libraries in a single place will greatly
reduce the number of -I and -L flags you will have to pass to the
configure script (see below), as these files will be right where the
compiler expects them.
We specifically do NOT recommend installing packages below
"C:\Program Files" or "C:\Program Files (x86)". These directories
are protected on versions of Windows from Vista and on, and you will
have difficulties updating and maintaining your installation later,
due to UAC elevation prompts, file virtualization, etc. You *have*
been warned!
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, and for "make install")
Available from
. gzip (needed to compress files during "make install")
Available from
. pkg-config (needed for building with some optional libraries,
such as GnuTLS and libxml2)
Available from
Each package might list other packages as prerequisites on its
download page (under "Runtime requirements"); download those as
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.
*** MSYS
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
MSYS packages that are required:
. All the packages from the MSYS Base distribution, listed here:
. Additional packages listed below, from the MSYS Extension
distribution here:
- flex
- bison
- m4
- perl
- mktemp
These should only be needed if you intend to build development
versions of Emacs from the Bazaar repository.
. Additional packages (needed only if building from the Bazaar
repository): Automake and Autoconf. They are available from
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
version of Make from here:
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.
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.,
msysCORE and Coreutils have it), download and install those as well.
Each package might list other packages as prerequisites on its
download page (under "Runtime requirements"); download those as
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
from which you unpack all of the MSYS packages.
Do NOT add the MSYS bin directory to your Windows Path! Only the
MinGW bin directory should be on Path. When you install MSYS, it
creates a shortcut on your desktop that invokes the MSYS Bash shell
in a Command Prompt window; that shell is already set up so that the
MSYS bin directory is on PATH ahead of any other directory. Thus,
Bash will find MSYS executables first, which is exactly what you
At this point, you are ready to build Emacs in its basic
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
If you are building a release or pretest tarball, skip this section,
because the configure script is already present in the tarball.
To build a development snapshot from the Emacs Bazaar repository,
you will first need to generate the configure script and a few other
auto-generated files. (If this step, described below, somehow
fails, you can use the files in the autogen/ directory instead, but
they might be outdated, and, most importantly, you are well advised
not to disregard any failures in your local build procedures, as
these are likely to be symptoms of incorrect installation that will
bite you down the road.)
To generate the configure script, type this at the MSYS Bash prompt
from the top-level directory of the Emacs tree:
If successful, this command should produce the following output:
$ ./
Checking whether you have the necessary tools...
(Read INSTALL.BZR for more details on building Emacs)
Checking for autoconf (need at least version 2.65)...
Checking for automake (need at least version 1.11)...
Your system has the required tools, running autoreconf...
You can now run `./configure'.
* Configuring Emacs for MinGW:
Now it's time to run the configure script. You can do that either
from a separate build directory that is outside of the Emacs source
tree (recommended), or from inside the source tree. The former is
recommended because it allows you to have several different builds,
e.g., an optimized build and an unoptimized one, of the same
revision of the source tree; the source tree will be left in its
pristine state, without any build products.
You invoke the configure script like this:
or, if you are building in-place, i.e. inside the source tree:
./nt/ --prefix=PREFIX ...
Here PREFIX is the place where you eventually want to install Emacs
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, if you are building outside of the source tree.
You can pass additional options to the configure script, for the
full list type
./nt/ --help
As explained in the help text, you may need to tell the script what
are the optional flags to invoke the compiler. This is needed if
some of your headers and libraries, e.g., those belonging to
optional image libraries, are installed in places where the compiler
normally doesn't look for them. (Remember that advice above to
avoid such situations? here's is where you will start paying for
disregarding that recommendation.) For example, if you have libpng
headers in C:\emacs\libs\libpng-1.2.37-lib\include and jpeg library