Update copyright for years from Emacs 21 to present (mainly adding
[emacs.git] / nt / INSTALL
blob9033153fcae592d0a1b7b4876a950cf6fdf25f1a
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
5     Free Software Foundation, Inc.
6   See the end of the file for copying permissions.
8 * For the impatient
10   Here are the concise instructions for configuring and building the
11   native Win32 binary of Emacs on Windows, for those who want to skip
12   the complex explanations and ``just do it'':
14   1. Change to the `nt' directory (the directory of this file):
16        cd nt
18   2. Run configure.bat.  From the COMMAND.COM/CMD.EXE command prompt:
20        configure
22      from a Unixy shell prompt:
24        cmd /c configure.bat
25      or
26        command.com /c configure.bat
28   3. Run the Make utility suitable for your environment.  If you build
29      with the Microsoft's Visual C compiler:
31        nmake
33      For the development environments based on GNU GCC (MinGW, MSYS,
34      Cygwin - but see notes about Cygwin make below), depending on how
35      Make is called, it could be:
37        make
38      or
39        mingw32-make
40      or
41        gnumake
42      or
43        gmake
45      (If you are building from CVS, say "make bootstrap" or "nmake
46      bootstrap" instead, and avoid using Cygwin make.)
48      With GNU Make, you can use the -j command-line option to have
49      Make execute several commands at once, like this:
51        gmake -j 2 XMFLAGS="-j 2"
53      The XMFLAGS variable overrides the default behavior of GNU Make
54      on Windows, whereby recursive Make invocations reset the maximum
55      number of simultaneous commands to 1.  The above command allows
56      up to 4 simultaneous commands at once in the top-level Make, and
57      up to 3 in each one of the recursive Make's.
59   4. Generate the Info manuals (only if you are building out of CVS, and
60      if you have makeinfo.exe installed):
62      make info
64      (change "make" to "nmake" if you use MSVC).
66   5. Install the produced binaries:
68      make install
70   That's it!
72   If these short instructions somehow fail, read the rest of this
73   file.
75 * Preliminaries
77   If you used WinZip to unpack the distribution, we suggest to
78   remove the files and unpack again with a different program!
79   WinZip is known to create some subtle and hard to debug problems,
80   such as converting files to DOS CR-LF format, not creating empty
81   directories, etc.  We suggest to use djtarnt.exe from the GNU FTP
82   site.
84   If you are building out of CVS, then some files in this directory
85   (.bat files, nmake.defs and makefile.w32-in) may need the line-ends
86   fixing first. The easiest way to do this and avoid future conflicts
87   is to run the following command in this (emacs/nt) directory:
89      cvs update -kb
91   Alternatively, use programs that convert end-of-line format, such as
92   dos2unix and unix2dos available from GnuWin32 or dtou and utod from
93   the DJGPP project.
95   In addition to this file, you should also read INSTALL.CVS in the
96   parent directory, and make sure that you have a version of
97   "touch.exe" in your path, and that it will create files that do not
98   yet exist.
100 * Supported development environments
102   To compile Emacs, you will need either Microsoft Visual C++ 2.0 or
103   later and nmake, or a Windows port of GCC 2.95 or later with MinGW
104   and W32 API support and a port of GNU Make.  You can use the Cygwin
105   ports of GCC, but Emacs requires the MinGW headers and libraries to
106   build (latest versions of the Cygwin toolkit, at least since v1.3.3,
107   include the MinGW headers and libraries as an integral part).
109   Note that building Emacs with Visual Studio 2005 is not supported at
110   this time.
112   The rest of this file assumes you have a working development
113   environment.  If you just installed  such an environment, try
114   building a trivial C "Hello world" program, and see if it works.  If
115   it doesn't work, resolve that problem first!
117   If you use the MinGW port of GCC and GNU Make to build Emacs, there
118   are some compatibility issues wrt Make and the shell that is run by
119   Make, either the standard COMMAND.COM/CMD.EXE supplied with Windows
120   or sh.exe., a port of a Unixy shell.  For reference, below is a list
121   of which builds of GNU Make are known to work or not, and whether
122   they work in the presence and/or absence of sh.exe, the Cygwin port
123   of Bash. Note that any version of Make that is compiled with Cygwin
124   will only work with Cygwin tools, due to the use of cygwin style
125   paths.  This means Cygwin Make is unsuitable for building parts of
126   Emacs that need to invoke Emacs itself (leim and "make bootstrap",
127   for example).  Also see the Trouble-shooting section below if you
128   decide to go ahead and use Cygwin make.
130   In addition, using 4NT as your shell is known to fail the build process,
131   at least for 4NT version 3.01.  Use CMD.EXE, the default Windows shell,
132   instead. MSYS sh.exe also appears to cause various problems. If you have
133   MSYS installed, try "make SHELL=cmd.exe" to force the use of cmd.exe
134   instead of sh.exe.
136                                          sh exists     no sh
138     cygwin b20.1 make (3.75):            fails[1, 5]   fails[2, 5]
139     MSVC compiled gmake 3.77:            okay          okay
140     MSVC compiled gmake 3.78.1:          okay          okay
141     MSVC compiled gmake 3.79.1:          okay          okay
142     mingw32/gcc-2.92.2 make (3.77):      okay          okay[4]
143     cygwin compiled gmake 3.77:          fails[1, 5]   fails[2, 5]
144     cygwin compiled make 3.78.1:         fails[5]      fails[2, 5]
145     cygwin compiled make 3.79.1:         fails[3, 5]   fails[2?, 5]
146     cygwin compiled make 3.80:           fails?[6]     fails?[6]
147     cygwin compiled make 3.81:           fails         fails?[6]
148     mingw32 compiled make 3.79.1:        okay          okay
149     mingw32 compiled make 3.80:          okay          okay[6]
150     mingw32 compiled make 3.81:          okay          okay[7]
152   Notes:
154     [1] doesn't cope with makefiles with DOS line endings, so must mount
155         emacs source with text!=binary.
156     [2] fails when needs to invoke shell commands; okay invoking gcc etc.
157     [3] requires LC_MESSAGES support to build; cannot build with early
158         versions of cygwin.
159     [4] may fail on Windows 9X and Windows ME; if so, install Bash.
160     [5] fails when building leim due to the use of cygwin style paths.
161         May work if building emacs without leim.
162     [6] not recommended; please report if you try this combination.
163     [7] tested only on Windows XP.
165   Other compilers may work, but specific reports from people that have
166   tried suggest that the Intel C compiler (for example) may produce an
167   Emacs executable with strange filename completion behaviour.  Unless
168   you would like to assist by finding and fixing the cause of any bugs
169   like this, we recommend the use of the supported compilers mentioned
170   in the previous paragraph.
172   You will also need a copy of the Posix cp, rm and mv programs.  These
173   and other useful Posix utilities can be obtained from one of several
174   projects:
176   * http://gnuwin32.sourceforge.net/              ( GnuWin32 )
177   * http://www.mingw.org/                         ( MinGW    )
178   * http://www.cygwin.com/                        ( Cygwin   )
179   * http://unxutils.sourceforge.net/              ( UnxUtils )
181   If you build Emacs on Windows 9X or ME, not on Windows 2K/XP or
182   Windows NT, we suggest to install the Cygwin port of Bash.  That is
183   because the native Windows shell COMMAND.COM is too limited; the
184   Emacs build procedure tries very hard to support even such limited
185   shells, but as none of the Windows developers of Emacs work on
186   Windows 9x, we cannot guarantee that it works without a more
187   powerful shell.
189   Additional instructions and help for building Emacs on Windows can be
190   found at the Emacs Wiki:
192     http://www.emacswiki.org/cgi-bin/wiki/WThirtyTwoInstallationKit
194   and at this URL:
196     http://ourcomments.org/Emacs/w32-build-emacs.html
198 * Configuring
200   Configuration of Emacs is now handled by running configure.bat in the
201   `nt' subdirectory.  It will detect which compiler you have available,
202   and generate makefiles accordingly.  You can override the compiler
203   detection, and control optimization and debug settings, by specifying
204   options on the command line when invoking configure.
206   To configure Emacs to build with GCC or MSVC, whichever is available,
207   simply change to the `nt' subdirectory and run `configure.bat' with no
208   options.  To see what options are available, run `configure --help'.
210   N.B.  It is normal to see a few error messages output while configure
211   is running, when gcc support is being tested.  These cannot be
212   surpressed because of limitations in the Windows 9x command.com shell.
214   You are encouraged to look at the file config.log which shows details
215   for failed tests, after configure.bat finishes.  Any unexplained failure
216   should be investigated and perhaps reported as a bug (see the section
217   about reporting bugs in the file README in this directory and in the
218   Emacs manual).
220 * Optional image library support
222   In addition to its "native" image formats (pbm and xbm), Emacs can
223   handle other image types: xpm, tiff, gif, png and jpeg (postscript is
224   currently unsupported on Windows).  To build Emacs with support for
225   them, the corresponding headers must be in the include path when the
226   configure script is run.  This can be setup using environment
227   variables, or by specifying --cflags -I... options on the command-line
228   to configure.bat.  The configure script will report whether it was
229   able to detect the headers.  If the results of this testing appear to be
230   incorrect, please look for details in the file config.log: it will show
231   the failed test programs and compiler error messages that should explain
232   what is wrong.  (Usually, any such failures happen because some headers
233   are missing due to bad packaging of the image support libraries.)
235   To use the external image support, the DLLs implementing the
236   functionality must be found when Emacs first needs them, either on the
237   PATH, or in the same directory as emacs.exe.  Failure to find a
238   library is not an error; the associated image format will simply be
239   unavailable.  Note that once Emacs has determined that a library can
240   not be found, there's no way to force it to try again, other than
241   restarting.  See the variable `image-library-alist' to configure the
242   expected names of the libraries.
244   Some image libraries have dependencies on one another, or on zlib.
245   For example, tiff support depends on the jpeg library.  If you did not
246   compile the libraries yourself, you must make sure that any dependency
247   is in the PATH or otherwise accesible and that the binaries are
248   compatible (for example, that they were built with the same compiler).
250   Binaries for the image libraries (among many others) can be found at
251   the GnuWin32 project.  These are built with MinGW, but they can be
252   used with both GCC/MinGW and MSVC builds of Emacs.  See the info on
253   http://ourcomments.org/Emacs/EmacsW32.html for more details about
254   installing image support libraries.
256 * Building
258   After running configure, simply run the appropriate `make' program for
259   your compiler to build Emacs.  For MSVC, this is nmake; for GCC, it is
260   GNU make.  (If you are building out of CVS, say "make bootstrap" or
261   "nmake bootstrap" instead.)
263   As the files are compiled, you will see some warning messages
264   declaring that some functions don't return a value, or that some data
265   conversions will be lossy, etc.  You can safely ignore these messages.
266   The warnings may be fixed in the main FSF source at some point, but
267   until then we will just live with them.
269   With GNU Make, you can use the -j command-line option to have Make
270   execute several commands at once, like this:
272     gmake -j 4 XMFLAGS="-j 3"
274   The XMFLAGS variable overrides the default behavior of GNU Make on
275   Windows, whereby recursive Make invocations reset the maximum number
276   of simultaneous commands to 1.  The above command allows up to 4
277   simultaneous commands at once in the top-level Make, and up to 3 in
278   each one of the recursive Make's; you can use other numbers of jobs,
279   if you wish.
281   If you are building from CVS, the following commands will produce
282   the Info manuals (which are not part of the CVS repository):
284     make info
285   or
286     nmake info
288   Note that you will need makeinfo.exe (from the GNU Texinfo package)
289   in order for this command to succeed.
291 * Installing
293   To install Emacs after it has compiled, simply run `nmake install'
294   or `make install', depending on which version of the Make utility
295   do you have.
297   By default, Emacs will be installed in the location where it was
298   built, but a different location can be specified either using the
299   --prefix option to configure, or by setting INSTALL_DIR when running
300   make, like so:
302      make install INSTALL_DIR=D:/emacs
304   (for `nmake', type "nmake install INSTALL_DIR=D:/emacs" instead).
306   The install process will run addpm to setup the registry entries, and
307   to create a Start menu icon for Emacs.
309 * Trouble-shooting
311   The main problems that are likely to be encountered when building
312   Emacs stem from using an old version of GCC, or old MinGW or W32 API
313   headers.  Additionally, cygwin ports of GNU make may require the Emacs
314   source tree to be mounted with text!=binary, because the makefiles
315   generated by configure.bat necessarily use DOS line endings.  Also,
316   cygwin ports of make must run in UNIX mode, either by specifying
317   --unix on the command line, or MAKE_MODE=UNIX in the environment.
319   When configure runs, it attempts to detect when GCC itself, or the
320   headers it is using, are not suitable for building Emacs.  GCC version
321   2.95 or later is needed, because that is when the Windows port gained
322   sufficient support for anonymous structs and unions to cope with some
323   definitions from winnt.h that are used by addsection.c.  The W32 API
324   headers that come with Cygwin b20.1 are incomplete, and do not include
325   some definitions required by addsection.c, for instance.  Also, older
326   releases of the W32 API headers from Anders Norlander contain a typo
327   in the definition of IMAGE_FIRST_SECTION in winnt.h, which
328   addsection.c relies on.  Versions of w32api-xxx.zip from at least
329   1999-11-18 onwards are okay.
331   When in doubt about correctness of what configure did, look at the file
332   config.log, which shows all the failed test programs and compiler
333   messages associated with the failures.  If that doesn't give a clue,
334   please report the problems, together with the relevant fragments from
335   config.log, as bugs.
337   If configure succeeds, but make fails, install the Cygwin port of
338   Bash, even if the table above indicates that Emacs should be able to
339   build without sh.exe.  (Some versions of Windows shells are too dumb
340   for Makefile's used by Emacs.)
342   If you are using certain Cygwin builds of GCC, such as Cygwin version
343   1.1.8, you may need to specify some extra compiler flags like so:
345     configure --with-gcc --cflags -mwin32 --cflags -D__MSVCRT__
346       --ldflags -mwin32
348   However, the latest Cygwin versions, such as 1.3.3, don't need those
349   switches; you can simply use "configure --with-gcc".
351   We will attempt to auto-detect the need for these flags in a future
352   release.
354 * Debugging
356   You should be able to debug Emacs using the debugger that is
357   appropriate for the compiler you used, namely DevStudio or Windbg if
358   compiled with MSVC, or GDB if compiled with GCC.
360   When Emacs aborts due to a fatal internal error, Emacs on Windows
361   pops up an Emacs Abort Dialog asking you whether you want to debug
362   Emacs or terminate it.  If Emacs was built with MSVC, click YES
363   twice, and Windbg or the DevStudio debugger will start up
364   automatically.  If Emacs was built with GCC, first start GDB and
365   attach it to the Emacs process with the "gdb -p EMACS-PID" command,
366   where EMACS-PID is the Emacs process ID (which you can see in the
367   Windows Task Manager), type the "continue" command inside GDB, and
368   only then click YES on the abort dialog.  This will pass control to
369   the debugger, and you will be able to debug the cause of the fatal
370   error.
372   Emacs functions implemented in C use a naming convention that reflects
373   their names in lisp.  The names of the C routines are the lisp names
374   prefixed with 'F', and with dashes converted to underscores.  For
375   example, the function call-process is implemented in C by
376   Fcall_process.  Similarly, lisp variables are prefixed with 'V', again
377   with dashes converted to underscores.  These conventions enable you to
378   easily set breakpoints or examine familiar lisp variables by name.
380   Since Emacs data is often in the form of a lisp object, and the
381   Lisp_Object type is difficult to examine manually in a debugger,
382   Emacs provides a helper routine called debug_print that prints out a
383   readable representation of a Lisp_Object.  If you are using GDB,
384   there is a .gdbinit file in the src directory which provides
385   definitions that are useful for examining lisp objects.  Therefore,
386   the following tips are mainly of interest when using MSVC.
388   The output from debug_print is sent to stderr, and to the debugger
389   via the OutputDebugString routine.  The output sent to stderr should
390   be displayed in the console window that was opened when the
391   emacs.exe executable was started.  The output sent to the debugger
392   should be displayed in its "Debug" output window.
394   When you are in the process of debugging Emacs and you would like to
395   examine the contents of a Lisp_Object variable, popup the QuickWatch
396   window (QuickWatch has an eyeglass symbol on its button in the
397   toolbar).  In the text field at the top of the window, enter
398   debug_print(<variable>) and hit return.  For example, start and run
399   Emacs in the debugger until it is waiting for user input.  Then click
400   on the Break button in the debugger to halt execution.  Emacs should
401   halt in ZwUserGetMessage waiting for an input event.  Use the Call
402   Stack window to select the procedure w32_msp_pump up the call stack
403   (see below for why you have to do this).  Open the QuickWatch window
404   and enter debug_print(Vexec_path).  Evaluating this expression will
405   then print out the contents of the lisp variable exec-path.
407   If QuickWatch reports that the symbol is unknown, then check the call
408   stack in the Call Stack window.  If the selected frame in the call
409   stack is not an Emacs procedure, then the debugger won't recognize
410   Emacs symbols.  Instead, select a frame that is inside an Emacs
411   procedure and try using debug_print again.
413   If QuickWatch invokes debug_print but nothing happens, then check the
414   thread that is selected in the debugger.  If the selected thread is
415   not the last thread to run (the "current" thread), then it cannot be
416   used to execute debug_print.  Use the Debug menu to select the current
417   thread and try using debug_print again.  Note that the debugger halts
418   execution (e.g., due to a breakpoint) in the context of the current
419   thread, so this should only be a problem if you've explicitly switched
420   threads.
422 COPYING PERMISSIONS
424   Permission is granted to anyone to make or distribute verbatim copies
425   of this document as received, in any medium, provided that the
426   copyright notice and permission notice are preserved,
427   and that the distributor grants the recipient permission
428   for further redistribution as permitted by this notice.
430   Permission is granted to distribute modified versions
431   of this document, or of portions of it,
432   under the above conditions, provided also that they
433   carry prominent notices stating who last changed them,
434   and that any new or changed statements about the activities
435   of the Free Software Foundation are approved by the Foundation.