(url-queue-parallel-processes): Increase the default to 6, since 2 seems too conserva...
[emacs.git] / nt / INSTALL
blobb4a97011922be07ccdca0779767c1b58125f4d7a
1                     Building and Installing Emacs on Windows
2                           (from 95 to 7 and beyond)
4   Copyright (C) 2001-2011  Free Software Foundation, Inc.
5   See the end of the file for license conditions.
7 * For the impatient
9   Here are the concise instructions for configuring and building the
10   native Windows binary of Emacs, for those who want to skip the
11   complex explanations and ``just do it'':
13   Do not use this recipe with Cygwin.  For building on Cygwin,
14   use the normal installation instructions, ../INSTALL.
16   If you have a Cygwin or MSYS port of Bash on your Path, you will be
17   better off removing it from PATH.  (For details, search for "MSYS
18   sh.exe" below.)
20   1. Change to the `nt' directory (the directory of this file):
22        cd nt
24   2. Run configure.bat.  From the COMMAND.COM/CMD.EXE command prompt:
26        configure
28      from a Unixy shell prompt:
30        cmd /c configure.bat
31      or
32        command.com /c configure.bat
34   3. Run the Make utility suitable for your environment.  If you build
35      with the Microsoft's Visual C compiler (but see notes about using
36      VC++ 8.0 and later below):
38        nmake
40      For the development environments based on GNU GCC (MinGW, MSYS,
41      Cygwin - but see notes about Cygwin make below), depending on how
42      Make is called, it could be:
44        make
45      or
46        mingw32-make
47      or
48        gnumake
49      or
50        gmake
52      (If you are building from Bazaar, say "make bootstrap" or "nmake
53      bootstrap" instead, and avoid using Cygwin make.)
55      With GNU Make, you can use the -j command-line option to have
56      Make execute several commands at once, like this:
58        gmake -j 2 XMFLAGS="-j 2"
60      The XMFLAGS variable overrides the default behavior of GNU Make
61      on Windows, whereby recursive Make invocations reset the maximum
62      number of simultaneous commands to 1.  The above command allows
63      up to 4 simultaneous commands at once in the top-level Make, and
64      up to 3 in each one of the recursive Make's.
66   4. Generate the Info manuals (only if you are building out of Bazaar,
67      and if you have makeinfo.exe installed):
69      make info
71      (change "make" to "nmake" if you use MSVC).
73   5. Install the produced binaries:
75      make install
77   That's it!
79   If these short instructions somehow fail, read the rest of this
80   file.
82 * Preliminaries
84   If you want to build a Cygwin port of Emacs, use the instructions in
85   the INSTALL file in the main Emacs directory (the parent of this
86   directory).  These instructions are for building a native Windows
87   binary of Emacs.
89   If you used WinZip to unpack the distribution, we suggest to
90   remove the files and unpack again with a different program!
91   WinZip is known to create some subtle and hard to debug problems,
92   such as converting files to DOS CR-LF format, not creating empty
93   directories, etc.  We suggest to use djtarnt.exe from the GNU FTP
94   site.
96   In addition to this file, you should also read INSTALL.BZR in the
97   parent directory, and make sure that you have a version of
98   "touch.exe" in your path, and that it will create files that do not
99   yet exist.
101 * Supported development environments
103   To compile Emacs, you will need either Microsoft Visual C++ 2.0, or
104   later up to 7.0, and nmake, or a Windows port of GCC 2.95 or later
105   with MinGW and W32 API support and a port of GNU Make.  You can use
106   the Cygwin ports of GCC, but Emacs requires the MinGW headers and
107   libraries to build (latest versions of the Cygwin toolkit, at least
108   since v1.3.3, include the MinGW headers and libraries as an integral
109   part).
111   Note that building Emacs with Visual Studio 2005 (VC++ 8.0) and
112   later is not supported at this time, due to changes introduced by
113   Microsoft into the libraries shipped with the compiler.
115   The rest of this file assumes you have a working development
116   environment.  If you just installed  such an environment, try
117   building a trivial C "Hello world" program, and see if it works.  If
118   it doesn't work, resolve that problem first!  If you use Microsoft
119   Visual Studio .NET 2003, don't forget to run the VCVARS32.BAT batch
120   file from the `Bin' subdirectory of the directory where you have
121   installed VS.NET.
123   If you use the MinGW port of GCC and GNU Make to build Emacs, there
124   are some compatibility issues wrt Make and the shell that is run by
125   Make, either the standard COMMAND.COM/CMD.EXE supplied with Windows
126   or sh.exe, a port of a Unixy shell.  For reference, below is a list
127   of which builds of GNU Make are known to work or not, and whether
128   they work in the presence and/or absence of sh.exe, the Cygwin port
129   of Bash.  Note that any version of Make that is compiled with Cygwin
130   will only work with Cygwin tools, due to the use of Cygwin style
131   paths.  This means Cygwin Make is unsuitable for building parts of
132   Emacs that need to invoke Emacs itself (leim and "make bootstrap",
133   for example).  Also see the Trouble-shooting section below if you
134   decide to go ahead and use Cygwin make.
136   In addition, using 4NT or TCC as your shell is known to fail the
137   build process, at least since 4NT version 3.01.  Use CMD.EXE, the
138   default Windows shell, instead.  MSYS sh.exe also appears to cause
139   various problems, e.g., it is known to cause failures in commands
140   like "cmd /c FOO" in the Makefiles, because it thinks "/c" is a
141   Unix-style file name that needs conversion to the Windows format.
142   If you have MSYS installed, try "make SHELL=cmd.exe" to force the
143   use of cmd.exe instead of the MSYS sh.exe.
145                                          sh exists     no sh
147     cygwin b20.1 make (3.75):            fails[1, 5]   fails[2, 5]
148     MSVC compiled gmake 3.77:            okay          okay
149     MSVC compiled gmake 3.78.1:          okay          okay
150     MSVC compiled gmake 3.79.1:          okay          okay
151     mingw32/gcc-2.92.2 make (3.77):      okay          okay[4]
152     cygwin compiled gmake 3.77:          fails[1, 5]   fails[2, 5]
153     cygwin compiled make 3.78.1:         fails[5]      fails[2, 5]
154     cygwin compiled make 3.79.1:         fails[3, 5]   fails[2?, 5]
155     cygwin compiled make 3.80:           okay[6]       fails?[7]
156     cygwin compiled make 3.81:           fails         fails?[7]
157     mingw32 compiled make 3.79.1:        okay          okay
158     mingw32 compiled make 3.80:          okay          okay[7]
159     mingw32 compiled make 3.81:          okay          okay[8]
161   Notes:
163     [1] doesn't cope with makefiles with DOS line endings, so must mount
164         emacs source with text!=binary.
165     [2] fails when needs to invoke shell commands; okay invoking gcc etc.
166     [3] requires LC_MESSAGES support to build; cannot build with early
167         versions of Cygwin.
168     [4] may fail on Windows 9X and Windows ME; if so, install Bash.
169     [5] fails when building leim due to the use of cygwin style paths.
170         May work if building emacs without leim.
171     [6] need to uncomment 3 lines in nt/gmake.defs that invoke `cygpath'
172         (look for "cygpath" near line 85 of gmake.defs).
173     [7] not recommended; please report if you try this combination.
174     [8] tested only on Windows XP.
176   Other compilers may work, but specific reports from people that have
177   tried suggest that the Intel C compiler (for example) may produce an
178   Emacs executable with strange filename completion behavior.  Unless
179   you would like to assist by finding and fixing the cause of any bugs
180   like this, we recommend the use of the supported compilers mentioned
181   in the previous paragraph.
183   You will also need a copy of the POSIX cp, rm and mv programs.  These
184   and other useful POSIX utilities can be obtained from one of several
185   projects:
187   * http://gnuwin32.sourceforge.net/              ( GnuWin32 )
188   * http://www.mingw.org/                         ( MinGW    )
189   * http://www.cygwin.com/                        ( Cygwin   )
190   * http://unxutils.sourceforge.net/              ( UnxUtils )
192   If you build Emacs on 16-bit versions of Windows (9X or ME), we
193   suggest to install the Cygwin port of Bash.  That is because the
194   native Windows shell COMMAND.COM is too limited; the Emacs build
195   procedure tries very hard to support even such limited shells, but
196   as none of the Windows developers of Emacs work on Windows 9X, we
197   cannot guarantee that it works without a more powerful shell.
199   Additional instructions and help for building Emacs on Windows can be
200   found at the Emacs Wiki:
202     http://www.emacswiki.org/cgi-bin/wiki/WThirtyTwoInstallationKit
204   and on these URLs:
206     http://ourcomments.org/Emacs/w32-build-emacs.html
207     http://derekslager.com/blog/posts/2007/01/emacs-hack-3-compile-emacs-from-cvs-on-windows.ashx
209   Both of those pages were written before Emacs switched from CVS to
210   Bazaar, but the parts about building Emacs still apply in Bazaar.
211   The second URL has instructions for building with MSVC, as well as
212   with MinGW, while the first URL covers only MinGW, but has more
213   details about it.
215 * Configuring
217   Configuration of Emacs is now handled by running configure.bat in the
218   `nt' subdirectory.  It will detect which compiler you have available,
219   and generate makefiles accordingly.  You can override the compiler
220   detection, and control optimization and debug settings, by specifying
221   options on the command line when invoking configure.
223   To configure Emacs to build with GCC or MSVC, whichever is available,
224   simply change to the `nt' subdirectory and run `configure.bat' with no
225   options.  To see what options are available, run `configure --help'.
226   Do NOT use the --no-debug option to configure.bat unless you are
227   absolutely sure the produced binaries will never need to be run under
228   a debugger.
230   Because of limitations of the stock Windows command shells, special
231   care is needed to pass some characters in the arguments of the
232   --cflags and --ldflags options.  Backslashes should not be used in
233   file names passed to the compiler and linker via these options.  Use
234   forward slashes instead.  If the arguments to these two options
235   include the `=' character, like when passing a -DFOO=bar preprocessor
236   option, the argument with the `=' character should be enclosed in
237   quotes, like this:
239     configure --cflags "-DFOO=bar"
241   Support for options that include the `=' character require "command
242   extensions" to be enabled.  (They are enabled by default, but your
243   system administrator could have changed that.  See "cmd /?" for
244   details.)  If command extensions are disabled, a warning message might
245   be displayed informing you that "using parameters that include the =
246   character by enclosing them in quotes will not be supported."
248   You may also use the --cflags and --ldflags options to pass
249   additional parameters to the compiler and linker, respectively; they
250   are frequently used to pass -I and -L flags to specify supplementary
251   include and library directories.  If a directory name includes
252   spaces, you will need to enclose it in quotes, as follows
253   -I"C:/Program Files/GnuTLS-2.10.1/include".  Note that only the
254   directory name is enclosed in quotes, not the entire argument.  Also
255   note that this functionality is only supported if command extensions
256   are available.  If command extensions are disabled and you attempt to
257   use this functionality you may see the following warning message
258   "Error in --cflags argument: ... Backslashes and quotes cannot be
259   used with --cflags.  Please use forward slashes for filenames and
260   paths (e.g. when passing directories to -I)."
261   
262   N.B.  It is normal to see a few error messages output while configure
263   is running, when gcc support is being tested.  These cannot be
264   suppressed because of limitations in the Windows 9X command.com shell.
266   You are encouraged to look at the file config.log which shows details
267   for failed tests, after configure.bat finishes.  Any unexplained failure
268   should be investigated and perhaps reported as a bug (see the section
269   about reporting bugs in the file README in this directory and in the
270   Emacs manual).
272 * Optional image library support
274   In addition to its "native" image formats (pbm and xbm), Emacs can
275   handle other image types: xpm, tiff, gif, png, jpeg and experimental
276   support for svg.
278   To build Emacs with support for them, the corresponding headers must
279   be in the include path when the configure script is run.  This can
280   be setup using environment variables, or by specifying --cflags
281   -I... options on the command-line to configure.bat.  The configure
282   script will report whether it was able to detect the headers.  If
283   the results of this testing appear to be incorrect, please look for
284   details in the file config.log: it will show the failed test
285   programs and compiler error messages that should explain what is
286   wrong.  (Usually, any such failures happen because some headers are
287   missing due to bad packaging of the image support libraries.)
289   Note that any file path passed to the compiler or linker must use
290   forward slashes; using backslashes will cause compiler warnings or
291   errors about unrecognized escape sequences.
293   To use the external image support, the DLLs implementing the
294   functionality must be found when Emacs first needs them, either on the
295   PATH, or in the same directory as emacs.exe.  Failure to find a
296   library is not an error; the associated image format will simply be
297   unavailable.  Note that once Emacs has determined that a library can
298   not be found, there's no way to force it to try again, other than
299   restarting.  See the variable `dynamic-library-alist' to configure the
300   expected names of the libraries.
302   Some image libraries have dependencies on one another, or on zlib.
303   For example, tiff support depends on the jpeg library.  If you did not
304   compile the libraries yourself, you must make sure that any dependency
305   is in the PATH or otherwise accessible and that the binaries are
306   compatible (for example, that they were built with the same compiler).
308   Binaries for the image libraries (among many others) can be found at
309   the GnuWin32 project.  PNG, JPEG and TIFF libraries are also
310   included with GTK, which is installed along with other Free Software
311   that requires it.  These are built with MinGW, but they can be used
312   with both GCC/MinGW and MSVC builds of Emacs.  See the info on
313   http://ourcomments.org/Emacs/w32-build-emacs.html, under "How to Get
314   Images Support", for more details about installing image support
315   libraries.  Note specifically that, due to some packaging snafus in
316   the GnuWin32-supplied image libraries, you will need to download
317   _source_ packages for some of the libraries in order to get the
318   header files necessary for building Emacs with image support.
320   If GTK 2.0 is installed, addpm will arrange for its image libraries
321   to be on the DLL search path for Emacs.
323   For PNG images, we recommend to use versions 1.4.x and later of
324   libpng, because previous versions had security issues.  You can find
325   precompiled libraries and headers on the GTK download page for
326   Windows (http://www.gtk.org/download-windows.html).
328   Versions 1.4.0 and later of libpng are binary incompatible with
329   earlier versions, so Emacs will only look for libpng libraries which
330   are compatible with the version it was compiled against.  That
331   version is given by the value of the Lisp variable `libpng-version';
332   e.g., 10403 means version 1.4.3.  The variable `dynamic-library-alist'
333   is automatically set to name only those DLL names that are known to
334   be compatible with the version given by `libpng-version'.  If PNG
335   support does not work for you even though you have the support DLL
336   installed, check the name of the installed DLL against
337   `dynamic-library-alist' and the value of `libpng-version', and
338   download compatible DLLs if needed.
340 * Optional GnuTLS support
342   If configure.bat finds the gnutls/gnutls.h file in the include path,
343   Emacs is built with GnuTLS support by default; to avoid that you can
344   pass the argument --without-gnutls.
346   In order to support GnuTLS at runtime, a GnuTLS-enabled Emacs must
347   be able to find the relevant DLLs during startup; failure to do so
348   is not an error, but GnuTLS won't be available to the running
349   session.
351   You can get pre-built binaries (including any required DLL and the
352   gnutls.h file) and an installer at http://josefsson.org/gnutls4win/.
354 * Experimental SVG support
356   SVG support is currently experimental, and not built by default.
357   Specify --with-svg and ensure you have all the dependencies in your
358   include path.  Unless you have built a minimalist librsvg yourself
359   (untested), librsvg depends on a significant chunk of GTK+ to build,
360   plus a few Gnome libraries, libxml2, libbz2 and zlib at runtime.  The
361   easiest way to obtain the dependencies required for building is to
362   download a pre-bundled GTK+ development environment for Windows.
363   GTK puts its header files all over the place, so you will need to
364   run pkgconfig to list the include path you will need (either passed
365   to configure.bat as --cflags options, or set in the environment).
367   To use librsvg at runtime, ensure that librsvg and its dependencies
368   are on your PATH.  If you didn't build librsvg yourself, you will
369   need to check with where you downloaded it from for the
370   dependencies, as there are different build options.  If it is a
371   short list, then it most likely only lists the immediate
372   dependencies of librsvg, but the dependencies themselves have
373   dependencies - so don't download individual libraries from GTK+,
374   download and install the whole thing.  If you think you've got all
375   the dependencies and SVG support is still not working, check your
376   PATH for other libraries that shadow the ones you downloaded.
377   Libraries of the same name from different sources may not be
378   compatible, this problem was encountered with libbzip2 from GnuWin32
379   with libcroco from gnome.org.
381   If you can see etc/images/splash.svg, then you have managed to get
382   SVG support working.  Congratulations for making it through DLL hell
383   to this point.  You'll probably find that some SVG images crash
384   Emacs.  Problems have been observed in some images that contain
385   text, they seem to be a problem in the Windows port of Pango, or
386   maybe a problem with the way Cairo or librsvg is using it that
387   doesn't show up on other platforms.
389 * Building
391   After running configure, simply run the appropriate `make' program for
392   your compiler to build Emacs.  For MSVC, this is nmake; for GCC, it is
393   GNU make.  (If you are building out of Bazaar, say "make bootstrap" or
394   "nmake bootstrap" instead.)
396   As the files are compiled, you will see some warning messages
397   declaring that some functions don't return a value, or that some data
398   conversions will be lossy, etc.  You can safely ignore these messages.
399   The warnings may be fixed in the main FSF source at some point, but
400   until then we will just live with them.
402   With GNU Make, you can use the -j command-line option to have Make
403   execute several commands at once, like this:
405     gmake -j 4 XMFLAGS="-j 3"
407   The XMFLAGS variable overrides the default behavior of GNU Make on
408   Windows, whereby recursive Make invocations reset the maximum number
409   of simultaneous commands to 1.  The above command allows up to 4
410   simultaneous commands at once in the top-level Make, and up to 3 in
411   each one of the recursive Make's; you can use other numbers of jobs,
412   if you wish.
414   If you are building from Bazaar, the following commands will produce
415   the Info manuals (which are not part of the Bazaar sources):
417     make info
418   or
419     nmake info
421   Note that you will need makeinfo.exe (from the GNU Texinfo package)
422   in order for this command to succeed.
424 * Installing
426   To install Emacs after it has compiled, simply run `nmake install'
427   or `make install', depending on which version of the Make utility
428   do you have.
430   By default, Emacs will be installed in the location where it was
431   built, but a different location can be specified either using the
432   --prefix option to configure, or by setting INSTALL_DIR when running
433   make, like so:
435      make install INSTALL_DIR=D:/emacs
437   (for `nmake', type "nmake install INSTALL_DIR=D:/emacs" instead).
439   The install process will run addpm to setup the registry entries, and
440   to create a Start menu icon for Emacs.
442 * Make targets
444   The following make targets may be used by users building the source
445   distribution, or users who have checked out of Bazaar after
446   an initial bootstrapping.
448   make
449   Builds Emacs from the available sources and pre-compiled lisp files.
451   make install
452   Installs programs to the bin directory, and runs addpm to create
453   Start Menu icons.
455   make clean
456   Removes object and executable files produced by the build process in
457   the current configuration.  After make clean, you can rebuild with
458   the same configuration using make.
460   make distclean
461   In addition to the files removed by make clean, this also removes
462   Makefiles and other generated files to get back to the state of a
463   freshly unpacked source distribution.  Note that this will not remove
464   installed files, or the results of builds performed with different
465   compiler or optimization options than the current configuration.
466   After make distclean, it is necessary to run configure.bat followed
467   by make to rebuild.
469   make cleanall
470   Removes object and executable files that may have been created by
471   previous builds with different configure options, in addition to
472   the files produced by the current configuration.
474   make realclean
475   Removes the installed files in the bin subdirectory in addition to
476   the files removed by make cleanall.
478   make dist
479   Builds Emacs from the available sources and pre-compiled lisp files.
480   Packages Emacs binaries as full distribution and barebin distribution.
482   The following targets are intended only for use with the Bazaar sources.
484   make bootstrap
485   Creates a temporary emacs binary with lisp source files and
486   uses it to compile the lisp files.  Once the lisp files are built,
487   emacs is redumped with the compiled lisp.
489   make recompile
490   Recompiles any changed lisp files after an update.  This saves
491   doing a full bootstrap after every update.  If this or a subsequent
492   make fail, you probably need to perform a full bootstrap, though
493   running this target multiple times may eventually sort out the
494   interdependencies.
496   make maintainer-clean
497   Removes everything that can be recreated, including compiled lisp
498   files, to get back to the state of a fresh Bazaar tree.  After make
499   maintainer-clean, it is necessary to run configure.bat and make
500   bootstrap to rebuild.  Occasionally it may be necessary to run this
501   target after an update.
503 * Creating binary distributions
505   Binary distributions (full and barebin distributions) can be
506   automatically built and packaged from source tarballs or a bzr
507   checkout.
509   When building Emacs binary distributions, the --distfiles argument
510   to configure.bat specifies files to be included in the bin directory
511   of the binary distributions. This is intended for libraries that are
512   not built as part of Emacs, e.g. image libraries.
514   For example, specifying
516         --distfiles D:\distfiles\libXpm.dll
518   results in libXpm.dll being copied from D:\distfiles to the
519   bin directory before packaging starts.
521   Multiple files can be specified using multiple --distfiles arguments:
523         --distfiles D:\distfiles\libXpm.dll --distfiles C:\jpeglib\jpeg.dll
525   For packaging the binary distributions, the 'dist' make target uses
526   7-Zip (http://www.7-zip.org), which must be installed and available
527   on the Windows Path.
530 * Trouble-shooting
532   The main problems that are likely to be encountered when building
533   Emacs stem from using an old version of GCC, or old MinGW or W32 API
534   headers.  Additionally, Cygwin ports of GNU make may require the Emacs
535   source tree to be mounted with text!=binary, because the makefiles
536   generated by configure.bat necessarily use DOS line endings.  Also,
537   Cygwin ports of make must run in UNIX mode, either by specifying
538   --unix on the command line, or MAKE_MODE=UNIX in the environment.
540   When configure runs, it attempts to detect when GCC itself, or the
541   headers it is using, are not suitable for building Emacs.  GCC version
542   2.95 or later is needed, because that is when the Windows port gained
543   sufficient support for anonymous structs and unions to cope with some
544   definitions from winnt.h that are used by addsection.c.
545   Older versions of the W32 API headers that come with Cygwin and MinGW
546   may be missing some definitions required by Emacs, or broken in other
547   ways.  In particular, uniscribe APIs were added to MinGW CVS only on
548   2006-03-26, so releases from before then cannot be used.
550   When in doubt about correctness of what configure did, look at the file
551   config.log, which shows all the failed test programs and compiler
552   messages associated with the failures.  If that doesn't give a clue,
553   please report the problems, together with the relevant fragments from
554   config.log, as bugs.
556   If configure succeeds, but make fails, install the Cygwin port of
557   Bash, even if the table above indicates that Emacs should be able to
558   build without sh.exe.  (Some versions of Windows shells are too dumb
559   for Makefile's used by Emacs.)
561   If you are using certain Cygwin builds of GCC, such as Cygwin version
562   1.1.8, you may need to specify some extra compiler flags like so:
564     configure --with-gcc --cflags -mwin32 --cflags -D__MSVCRT__
565       --ldflags -mwin32
567   However, the latest Cygwin versions, such as 1.3.3, don't need those
568   switches; you can simply use "configure --with-gcc".
570   We will attempt to auto-detect the need for these flags in a future
571   release.
573 * Debugging
575   You should be able to debug Emacs using the debugger that is
576   appropriate for the compiler you used, namely DevStudio or Windbg if
577   compiled with MSVC, or GDB if compiled with GCC.  (GDB for Windows
578   is available from the MinGW site, http://www.mingw.org/download.shtml.)
580   When Emacs aborts due to a fatal internal error, Emacs on Windows
581   pops up an Emacs Abort Dialog asking you whether you want to debug
582   Emacs or terminate it.  If Emacs was built with MSVC, click YES
583   twice, and Windbg or the DevStudio debugger will start up
584   automatically.  If Emacs was built with GCC, first start GDB and
585   attach it to the Emacs process with the "gdb -p EMACS-PID" command,
586   where EMACS-PID is the Emacs process ID (which you can see in the
587   Windows Task Manager), type the "continue" command inside GDB, and
588   only then click YES on the abort dialog.  This will pass control to
589   the debugger, and you will be able to debug the cause of the fatal
590   error.
592   Emacs functions implemented in C use a naming convention that reflects
593   their names in lisp.  The names of the C routines are the lisp names
594   prefixed with 'F', and with dashes converted to underscores.  For
595   example, the function call-process is implemented in C by
596   Fcall_process.  Similarly, lisp variables are prefixed with 'V', again
597   with dashes converted to underscores.  These conventions enable you to
598   easily set breakpoints or examine familiar lisp variables by name.
600   Since Emacs data is often in the form of a lisp object, and the
601   Lisp_Object type is difficult to examine manually in a debugger,
602   Emacs provides a helper routine called debug_print that prints out a
603   readable representation of a Lisp_Object.  If you are using GDB,
604   there is a .gdbinit file in the src directory which provides
605   definitions that are useful for examining lisp objects.  Therefore,
606   the following tips are mainly of interest when using MSVC.
608   The output from debug_print is sent to stderr, and to the debugger
609   via the OutputDebugString routine.  The output sent to stderr should
610   be displayed in the console window that was opened when the
611   emacs.exe executable was started.  The output sent to the debugger
612   should be displayed in its "Debug" output window.
614   When you are in the process of debugging Emacs and you would like to
615   examine the contents of a Lisp_Object variable, pop up the QuickWatch
616   window (QuickWatch has an eyeglass symbol on its button in the
617   toolbar).  In the text field at the top of the window, enter
618   debug_print(<variable>) and hit return.  For example, start and run
619   Emacs in the debugger until it is waiting for user input.  Then click
620   on the Break button in the debugger to halt execution.  Emacs should
621   halt in ZwUserGetMessage waiting for an input event.  Use the Call
622   Stack window to select the procedure w32_msp_pump up the call stack
623   (see below for why you have to do this).  Open the QuickWatch window
624   and enter debug_print(Vexec_path).  Evaluating this expression will
625   then print out the contents of the lisp variable exec-path.
627   If QuickWatch reports that the symbol is unknown, then check the call
628   stack in the Call Stack window.  If the selected frame in the call
629   stack is not an Emacs procedure, then the debugger won't recognize
630   Emacs symbols.  Instead, select a frame that is inside an Emacs
631   procedure and try using debug_print again.
633   If QuickWatch invokes debug_print but nothing happens, then check the
634   thread that is selected in the debugger.  If the selected thread is
635   not the last thread to run (the "current" thread), then it cannot be
636   used to execute debug_print.  Use the Debug menu to select the current
637   thread and try using debug_print again.  Note that the debugger halts
638   execution (e.g., due to a breakpoint) in the context of the current
639   thread, so this should only be a problem if you've explicitly switched
640   threads.
643 This file is part of GNU Emacs.
645 GNU Emacs is free software: you can redistribute it and/or modify
646 it under the terms of the GNU General Public License as published by
647 the Free Software Foundation, either version 3 of the License, or
648 (at your option) any later version.
650 GNU Emacs is distributed in the hope that it will be useful,
651 but WITHOUT ANY WARRANTY; without even the implied warranty of
652 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
653 GNU General Public License for more details.
655 You should have received a copy of the GNU General Public License
656 along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.