*** empty log message ***
[emacs.git] / nt / INSTALL
blob3157961cd59d98e159cd1dbbc93eeffbbe7fef4d
1                       Building and Installing Emacs
2                 on Windows NT/2K/XP and Windows 95/98/ME
4   Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
5     Free Software Foundation, Inc.
6   See the end of the file for license conditions.
8 * For the impatient
10   Here are the concise instructions for configuring and building the
11   native Windows binary of Emacs, for those who want to skip the
12   complex explanations and ``just do it'':
14   Do not use this recipe with Cygwin.  For building on Cygwin,
15   use the normal installation instructions, ../INSTALL.
17   1. Change to the `nt' directory (the directory of this file):
19        cd nt
21   2. Run configure.bat.  From the COMMAND.COM/CMD.EXE command prompt:
23        configure
25      from a Unixy shell prompt:
27        cmd /c configure.bat
28      or
29        command.com /c configure.bat
31   3. Run the Make utility suitable for your environment.  If you build
32      with the Microsoft's Visual C compiler (but see notes about using
33      VC++ 8.0 and later below):
35        nmake
37      For the development environments based on GNU GCC (MinGW, MSYS,
38      Cygwin - but see notes about Cygwin make below), depending on how
39      Make is called, it could be:
41        make
42      or
43        mingw32-make
44      or
45        gnumake
46      or
47        gmake
49      (If you are building from CVS, say "make bootstrap" or "nmake
50      bootstrap" instead, and avoid using Cygwin make.)
52      With GNU Make, you can use the -j command-line option to have
53      Make execute several commands at once, like this:
55        gmake -j 2 XMFLAGS="-j 2"
57      The XMFLAGS variable overrides the default behavior of GNU Make
58      on Windows, whereby recursive Make invocations reset the maximum
59      number of simultaneous commands to 1.  The above command allows
60      up to 4 simultaneous commands at once in the top-level Make, and
61      up to 3 in each one of the recursive Make's.
63   4. Generate the Info manuals (only if you are building out of CVS, and
64      if you have makeinfo.exe installed):
66      make info
68      (change "make" to "nmake" if you use MSVC).
70   5. Install the produced binaries:
72      make install
74   That's it!
76   If these short instructions somehow fail, read the rest of this
77   file.
79 * Preliminaries
81   If you want to build a Cygwin port of Emacs, use the instructions in
82   the INSTALL file in the main Emacs directory (the parent of this
83   directory).  These instructions are for building a native Windows
84   binary of Emacs.
86   If you used WinZip to unpack the distribution, we suggest to
87   remove the files and unpack again with a different program!
88   WinZip is known to create some subtle and hard to debug problems,
89   such as converting files to DOS CR-LF format, not creating empty
90   directories, etc.  We suggest to use djtarnt.exe from the GNU FTP
91   site.
93   If you are building out of CVS, then some files in this directory
94   (.bat files, nmake.defs and makefile.w32-in) may need the line-ends
95   fixing first. The easiest way to do this and avoid future conflicts
96   is to run the following command in this (emacs/nt) directory:
98      cvs update -kb
100   Alternatively, use programs that convert end-of-line format, such as
101   dos2unix and unix2dos available from GnuWin32 or dtou and utod from
102   the DJGPP project.
104   Additionally, the files lisp/international/uni-*.el and
105   lisp/ldefs-boot.el need Unix line ends due to some embedded ^M
106   characters that are not at the end of the line.  So in the
107   lisp/international directory you should run the following command, or
108   use dos2unix on those files.
110      cvs update -kb uni-*.el
112   and in the lisp directory, use the command:
114      cvs update -kb lisp/ldefs-boot.el
116   In addition to this file, you should also read INSTALL.CVS in the
117   parent directory, and make sure that you have a version of
118   "touch.exe" in your path, and that it will create files that do not
119   yet exist.
121 * Supported development environments
123   To compile Emacs, you will need either Microsoft Visual C++ 2.0, or
124   later up to 7.0, and nmake, or a Windows port of GCC 2.95 or later
125   with MinGW and W32 API support and a port of GNU Make.  You can use
126   the Cygwin ports of GCC, but Emacs requires the MinGW headers and
127   libraries to build (latest versions of the Cygwin toolkit, at least
128   since v1.3.3, include the MinGW headers and libraries as an integral
129   part).
131   Note that building Emacs with Visual Studio 2005 (VC++ 8.0) is not
132   supported at this time, due to changes introduced by Microsoft into
133   the libraries shipped with the compiler.
135   The rest of this file assumes you have a working development
136   environment.  If you just installed  such an environment, try
137   building a trivial C "Hello world" program, and see if it works.  If
138   it doesn't work, resolve that problem first!  If you use Microsoft
139   Visual Studio .NET 2003, don't forget to run the VCVARS32.BAT batch
140   file from the `Bin' subdirectory of the directory where you have
141   installed VS.NET.
143   If you use the MinGW port of GCC and GNU Make to build Emacs, there
144   are some compatibility issues wrt Make and the shell that is run by
145   Make, either the standard COMMAND.COM/CMD.EXE supplied with Windows
146   or sh.exe., a port of a Unixy shell.  For reference, below is a list
147   of which builds of GNU Make are known to work or not, and whether
148   they work in the presence and/or absence of sh.exe, the Cygwin port
149   of Bash. Note that any version of Make that is compiled with Cygwin
150   will only work with Cygwin tools, due to the use of cygwin style
151   paths.  This means Cygwin Make is unsuitable for building parts of
152   Emacs that need to invoke Emacs itself (leim and "make bootstrap",
153   for example).  Also see the Trouble-shooting section below if you
154   decide to go ahead and use Cygwin make.
156   In addition, using 4NT as your shell is known to fail the build process,
157   at least for 4NT version 3.01.  Use CMD.EXE, the default Windows shell,
158   instead. MSYS sh.exe also appears to cause various problems. If you have
159   MSYS installed, try "make SHELL=cmd.exe" to force the use of cmd.exe
160   instead of sh.exe.
162                                          sh exists     no sh
164     cygwin b20.1 make (3.75):            fails[1, 5]   fails[2, 5]
165     MSVC compiled gmake 3.77:            okay          okay
166     MSVC compiled gmake 3.78.1:          okay          okay
167     MSVC compiled gmake 3.79.1:          okay          okay
168     mingw32/gcc-2.92.2 make (3.77):      okay          okay[4]
169     cygwin compiled gmake 3.77:          fails[1, 5]   fails[2, 5]
170     cygwin compiled make 3.78.1:         fails[5]      fails[2, 5]
171     cygwin compiled make 3.79.1:         fails[3, 5]   fails[2?, 5]
172     cygwin compiled make 3.80:           okay[6]       fails?[7]
173     cygwin compiled make 3.81:           fails         fails?[7]
174     mingw32 compiled make 3.79.1:        okay          okay
175     mingw32 compiled make 3.80:          okay          okay[7]
176     mingw32 compiled make 3.81:          okay          okay[8]
178   Notes:
180     [1] doesn't cope with makefiles with DOS line endings, so must mount
181         emacs source with text!=binary.
182     [2] fails when needs to invoke shell commands; okay invoking gcc etc.
183     [3] requires LC_MESSAGES support to build; cannot build with early
184         versions of cygwin.
185     [4] may fail on Windows 9X and Windows ME; if so, install Bash.
186     [5] fails when building leim due to the use of cygwin style paths.
187         May work if building emacs without leim.
188     [6] need to uncomment 3 lines in nt/gmake.defs that invoke `cygpath'
189         (look for "cygpath" near line 85 of gmake.defs).
190     [7] not recommended; please report if you try this combination.
191     [8] tested only on Windows XP.
193   Other compilers may work, but specific reports from people that have
194   tried suggest that the Intel C compiler (for example) may produce an
195   Emacs executable with strange filename completion behavior.  Unless
196   you would like to assist by finding and fixing the cause of any bugs
197   like this, we recommend the use of the supported compilers mentioned
198   in the previous paragraph.
200   You will also need a copy of the Posix cp, rm and mv programs.  These
201   and other useful Posix utilities can be obtained from one of several
202   projects:
204   * http://gnuwin32.sourceforge.net/              ( GnuWin32 )
205   * http://www.mingw.org/                         ( MinGW    )
206   * http://www.cygwin.com/                        ( Cygwin   )
207   * http://unxutils.sourceforge.net/              ( UnxUtils )
209   If you build Emacs on Windows 9X or ME, not on Windows 2K/XP or
210   Windows NT, we suggest to install the Cygwin port of Bash.  That is
211   because the native Windows shell COMMAND.COM is too limited; the
212   Emacs build procedure tries very hard to support even such limited
213   shells, but as none of the Windows developers of Emacs work on
214   Windows 9x, we cannot guarantee that it works without a more
215   powerful shell.
217   Additional instructions and help for building Emacs on Windows can be
218   found at the Emacs Wiki:
220     http://www.emacswiki.org/cgi-bin/wiki/WThirtyTwoInstallationKit
222   and on these URLs:
224     http://ourcomments.org/Emacs/w32-build-emacs.html
225     http://derekslager.com/blog/posts/2007/01/emacs-hack-3-compile-emacs-from-cvs-on-windows.ashx
227   The second URL above includes instructions for building with MSVC,
228   as well as with MinGW, while the first URL covers only MinGW, but
229   has more details about it.
231 * Configuring
233   Configuration of Emacs is now handled by running configure.bat in the
234   `nt' subdirectory.  It will detect which compiler you have available,
235   and generate makefiles accordingly.  You can override the compiler
236   detection, and control optimization and debug settings, by specifying
237   options on the command line when invoking configure.
239   To configure Emacs to build with GCC or MSVC, whichever is available,
240   simply change to the `nt' subdirectory and run `configure.bat' with no
241   options.  To see what options are available, run `configure --help'.
242   Do NOT use the --no-debug option to configure.bat unless you are
243   absolutely sure the produced binaries will never need to be run under
244   a debugger.
246   N.B.  It is normal to see a few error messages output while configure
247   is running, when gcc support is being tested.  These cannot be
248   suppressed because of limitations in the Windows 9x command.com shell.
250   You are encouraged to look at the file config.log which shows details
251   for failed tests, after configure.bat finishes.  Any unexplained failure
252   should be investigated and perhaps reported as a bug (see the section
253   about reporting bugs in the file README in this directory and in the
254   Emacs manual).
256 * Optional image library support
258   In addition to its "native" image formats (pbm and xbm), Emacs can
259   handle other image types: xpm, tiff, gif, png and jpeg (postscript is
260   currently unsupported on Windows).  To build Emacs with support for
261   them, the corresponding headers must be in the include path when the
262   configure script is run.  This can be setup using environment
263   variables, or by specifying --cflags -I... options on the command-line
264   to configure.bat.  The configure script will report whether it was
265   able to detect the headers.  If the results of this testing appear to be
266   incorrect, please look for details in the file config.log: it will show
267   the failed test programs and compiler error messages that should explain
268   what is wrong.  (Usually, any such failures happen because some headers
269   are missing due to bad packaging of the image support libraries.)
271   To use the external image support, the DLLs implementing the
272   functionality must be found when Emacs first needs them, either on the
273   PATH, or in the same directory as emacs.exe.  Failure to find a
274   library is not an error; the associated image format will simply be
275   unavailable.  Note that once Emacs has determined that a library can
276   not be found, there's no way to force it to try again, other than
277   restarting.  See the variable `image-library-alist' to configure the
278   expected names of the libraries.
280   Some image libraries have dependencies on one another, or on zlib.
281   For example, tiff support depends on the jpeg library.  If you did not
282   compile the libraries yourself, you must make sure that any dependency
283   is in the PATH or otherwise accessible and that the binaries are
284   compatible (for example, that they were built with the same compiler).
286   Binaries for the image libraries (among many others) can be found at
287   the GnuWin32 project.  PNG, JPEG and TIFF libraries are also
288   included with GTK, which is installed along with other Free Software
289   that requires it.  These are built with MinGW, but they can be used
290   with both GCC/MinGW and MSVC builds of Emacs.  See the info on
291   http://ourcomments.org/Emacs/w32-build-emacs.html, under "How to Get
292   Images Support", for more details about installing image support
293   libraries.  Note specifically that, due to some packaging snafus in
294   the GnuWin32-supplied image libraries, you will need to download
295   _source_ packages for some of the libraries in order to get the
296   header files necessary for building Emacs with image support.
298   If GTK 2.0 is installed, addpm will arrange for its image libraries
299   to be on the DLL search path for Emacs.
301 * Building
303   After running configure, simply run the appropriate `make' program for
304   your compiler to build Emacs.  For MSVC, this is nmake; for GCC, it is
305   GNU make.  (If you are building out of CVS, say "make bootstrap" or
306   "nmake bootstrap" instead.)
308   As the files are compiled, you will see some warning messages
309   declaring that some functions don't return a value, or that some data
310   conversions will be lossy, etc.  You can safely ignore these messages.
311   The warnings may be fixed in the main FSF source at some point, but
312   until then we will just live with them.
314   With GNU Make, you can use the -j command-line option to have Make
315   execute several commands at once, like this:
317     gmake -j 4 XMFLAGS="-j 3"
319   The XMFLAGS variable overrides the default behavior of GNU Make on
320   Windows, whereby recursive Make invocations reset the maximum number
321   of simultaneous commands to 1.  The above command allows up to 4
322   simultaneous commands at once in the top-level Make, and up to 3 in
323   each one of the recursive Make's; you can use other numbers of jobs,
324   if you wish.
326   If you are building from CVS, the following commands will produce
327   the Info manuals (which are not part of the CVS repository):
329     make info
330   or
331     nmake info
333   Note that you will need makeinfo.exe (from the GNU Texinfo package)
334   in order for this command to succeed.
336 * Installing
338   To install Emacs after it has compiled, simply run `nmake install'
339   or `make install', depending on which version of the Make utility
340   do you have.
342   By default, Emacs will be installed in the location where it was
343   built, but a different location can be specified either using the
344   --prefix option to configure, or by setting INSTALL_DIR when running
345   make, like so:
347      make install INSTALL_DIR=D:/emacs
349   (for `nmake', type "nmake install INSTALL_DIR=D:/emacs" instead).
351   The install process will run addpm to setup the registry entries, and
352   to create a Start menu icon for Emacs.
354 * Make targets
356   The following make targets may be used by users building the source
357   distribution, or users who have checked out of CVS after
358   an initial bootstrapping.
360   make
361   Builds Emacs from the available sources and pre-compiled lisp files.
363   make install
364   Installs programs to the bin directory, and runs addpm to create
365   Start Menu icons.
367   make clean
368   Removes object and executable files produced by the build process in
369   the current configuration.  After make clean, you can rebuild with
370   the same configuration using make.
372   make distclean
373   In addition to the files removed by make clean, this also removes
374   Makefiles and other generated files to get back to the state of a
375   freshly unpacked source distribution. Note that this will not remove
376   installed files, or the results of builds performed with different
377   compiler or optimization options than the current configuration.
378   After make distclean, it is necessary to run configure.bat followed
379   by make to rebuild.
381   make cleanall
382   Removes object and executable files that may have been created by
383   previous builds with different configure options, in addition to
384   the files produced by the current configuration.
386   make realclean
387   Removes the installed files in the bin subdirectory in addition to
388   the files removed by make cleanall.
391   The following targets are intended only for users who have checked out
392   of CVS.
394   make bootstrap
395   Creates a temporary emacs binary with lisp source files and
396   uses it to compile the lisp files.  Once the lisp files are built,
397   emacs is redumped with the compiled lisp.
399   make recompile
400   Recompiles any changed lisp files after a cvs update.  This saves
401   doing a full bootstrap after every update.  If this or a subsequent
402   make fail, you probably need to perform a full bootstrap, though
403   running this target multiple times may eventually sort out the
404   interdependencies.
406   make maintainer-clean
407   Removes everything that can be recreated, including compiled lisp
408   files, to get back to the state of a fresh CVS checkout.  After make
409   maintainer-clean, it is necessary to run configure.bat and make
410   bootstrap to rebuild.  Occasionally it may be necessary to run this
411   target after a cvs update.
414 * Trouble-shooting
416   The main problems that are likely to be encountered when building
417   Emacs stem from using an old version of GCC, or old MinGW or W32 API
418   headers.  Additionally, cygwin ports of GNU make may require the Emacs
419   source tree to be mounted with text!=binary, because the makefiles
420   generated by configure.bat necessarily use DOS line endings.  Also,
421   cygwin ports of make must run in UNIX mode, either by specifying
422   --unix on the command line, or MAKE_MODE=UNIX in the environment.
424   When configure runs, it attempts to detect when GCC itself, or the
425   headers it is using, are not suitable for building Emacs.  GCC version
426   2.95 or later is needed, because that is when the Windows port gained
427   sufficient support for anonymous structs and unions to cope with some
428   definitions from winnt.h that are used by addsection.c.
429   Older versions of the W32 API headers that come with Cygwin and MinGW
430   may be missing some definitions required by Emacs, or broken in other
431   ways.  In particular, uniscribe APIs were added to MinGW CVS only on
432   2006-03-26, so releases from before then cannot be used.
434   When in doubt about correctness of what configure did, look at the file
435   config.log, which shows all the failed test programs and compiler
436   messages associated with the failures.  If that doesn't give a clue,
437   please report the problems, together with the relevant fragments from
438   config.log, as bugs.
440   If configure succeeds, but make fails, install the Cygwin port of
441   Bash, even if the table above indicates that Emacs should be able to
442   build without sh.exe.  (Some versions of Windows shells are too dumb
443   for Makefile's used by Emacs.)
445   If you are using certain Cygwin builds of GCC, such as Cygwin version
446   1.1.8, you may need to specify some extra compiler flags like so:
448     configure --with-gcc --cflags -mwin32 --cflags -D__MSVCRT__
449       --ldflags -mwin32
451   However, the latest Cygwin versions, such as 1.3.3, don't need those
452   switches; you can simply use "configure --with-gcc".
454   We will attempt to auto-detect the need for these flags in a future
455   release.
457 * Debugging
459   You should be able to debug Emacs using the debugger that is
460   appropriate for the compiler you used, namely DevStudio or Windbg if
461   compiled with MSVC, or GDB if compiled with GCC.  (GDB for Windows
462   is available from the MinGW site, http://www.mingw.org/download.shtml.)
464   When Emacs aborts due to a fatal internal error, Emacs on Windows
465   pops up an Emacs Abort Dialog asking you whether you want to debug
466   Emacs or terminate it.  If Emacs was built with MSVC, click YES
467   twice, and Windbg or the DevStudio debugger will start up
468   automatically.  If Emacs was built with GCC, first start GDB and
469   attach it to the Emacs process with the "gdb -p EMACS-PID" command,
470   where EMACS-PID is the Emacs process ID (which you can see in the
471   Windows Task Manager), type the "continue" command inside GDB, and
472   only then click YES on the abort dialog.  This will pass control to
473   the debugger, and you will be able to debug the cause of the fatal
474   error.
476   Emacs functions implemented in C use a naming convention that reflects
477   their names in lisp.  The names of the C routines are the lisp names
478   prefixed with 'F', and with dashes converted to underscores.  For
479   example, the function call-process is implemented in C by
480   Fcall_process.  Similarly, lisp variables are prefixed with 'V', again
481   with dashes converted to underscores.  These conventions enable you to
482   easily set breakpoints or examine familiar lisp variables by name.
484   Since Emacs data is often in the form of a lisp object, and the
485   Lisp_Object type is difficult to examine manually in a debugger,
486   Emacs provides a helper routine called debug_print that prints out a
487   readable representation of a Lisp_Object.  If you are using GDB,
488   there is a .gdbinit file in the src directory which provides
489   definitions that are useful for examining lisp objects.  Therefore,
490   the following tips are mainly of interest when using MSVC.
492   The output from debug_print is sent to stderr, and to the debugger
493   via the OutputDebugString routine.  The output sent to stderr should
494   be displayed in the console window that was opened when the
495   emacs.exe executable was started.  The output sent to the debugger
496   should be displayed in its "Debug" output window.
498   When you are in the process of debugging Emacs and you would like to
499   examine the contents of a Lisp_Object variable, pop up the QuickWatch
500   window (QuickWatch has an eyeglass symbol on its button in the
501   toolbar).  In the text field at the top of the window, enter
502   debug_print(<variable>) and hit return.  For example, start and run
503   Emacs in the debugger until it is waiting for user input.  Then click
504   on the Break button in the debugger to halt execution.  Emacs should
505   halt in ZwUserGetMessage waiting for an input event.  Use the Call
506   Stack window to select the procedure w32_msp_pump up the call stack
507   (see below for why you have to do this).  Open the QuickWatch window
508   and enter debug_print(Vexec_path).  Evaluating this expression will
509   then print out the contents of the lisp variable exec-path.
511   If QuickWatch reports that the symbol is unknown, then check the call
512   stack in the Call Stack window.  If the selected frame in the call
513   stack is not an Emacs procedure, then the debugger won't recognize
514   Emacs symbols.  Instead, select a frame that is inside an Emacs
515   procedure and try using debug_print again.
517   If QuickWatch invokes debug_print but nothing happens, then check the
518   thread that is selected in the debugger.  If the selected thread is
519   not the last thread to run (the "current" thread), then it cannot be
520   used to execute debug_print.  Use the Debug menu to select the current
521   thread and try using debug_print again.  Note that the debugger halts
522   execution (e.g., due to a breakpoint) in the context of the current
523   thread, so this should only be a problem if you've explicitly switched
524   threads.
527 This file is part of GNU Emacs.
529 GNU Emacs is free software: you can redistribute it and/or modify
530 it under the terms of the GNU General Public License as published by
531 the Free Software Foundation, either version 3 of the License, or
532 (at your option) any later version.
534 GNU Emacs is distributed in the hope that it will be useful,
535 but WITHOUT ANY WARRANTY; without even the implied warranty of
536 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
537 GNU General Public License for more details.
539 You should have received a copy of the GNU General Public License
540 along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.