X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/95dbaaea805198e1e69cd55ae958e960226fb10b..a4bead12924447ab979dc70c922aaa2f4e44f90c:/doc/emacs/building.texi diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index 986b0c2e42..4c79c04717 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -1,6 +1,6 @@ @c This is part of the Emacs manual. @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. +@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Building, Maintaining, Programs, Top @chapter Compiling and Testing Programs @@ -65,7 +65,7 @@ directory. @vindex compile-command The default for the compilation command is normally @samp{make -k}, which is correct most of the time for nontrivial programs. -(@xref{Top,, Make, make, GNU Make Manual}.) If you have done @kbd{M-x +@xref{Top,, Make, make, GNU Make Manual}. If you have done @kbd{M-x compile} before, the default each time is the command you used the previous time. @code{compile} stores this command in the variable @code{compile-command}, so setting that variable specifies the default @@ -92,9 +92,12 @@ the end of the buffer. @cindex compilation buffer, keeping point at end @vindex compilation-scroll-output - If you set the variable @code{compilation-scroll-output} to a -non-@code{nil} value, then the compilation buffer always scrolls to -follow output as it comes in. + If you change the variable @code{compilation-scroll-output} to a +non-@code{nil} value, the compilation buffer will scroll automatically +to follow the output as it comes in. If the value is +@code{first-error}, the scrolling stops at the first error that +appears, leaving point at that error. For any other non-@code{nil} +value, the buffer continues scrolling until there is no more output. @findex recompile To rerun the last compilation with the same command, type @kbd{M-x @@ -194,11 +197,15 @@ compilation buffer produce automatic source display. @end table @findex compile-goto-error +@vindex compilation-auto-jump-to-first-error You can visit the source for any particular error message by moving point in the @samp{*compilation*} buffer to that error message and typing @key{RET} (@code{compile-goto-error}). Alternatively, you can click @kbd{Mouse-2} on the error message; you need not switch to the -@samp{*compilation*} buffer first. +@samp{*compilation*} buffer first. If you set the variable +@code{compilation-auto-jump-to-first-error} to a non-@code{nil} value, +Emacs automatically jumps to the first error, if any, as soon as it +appears in the @samp{*compilation*} buffer. @kindex M-g M-n @kindex M-g n @@ -343,7 +350,7 @@ mode (@pxref{Compilation Mode}). @table @kbd @item M-x grep -@item M-x lgrep +@itemx M-x lgrep Run @code{grep} asynchronously under Emacs, with matching lines listed in the buffer named @samp{*grep*}. @item M-x grep-find @@ -450,13 +457,15 @@ Flymake, flymake, The Flymake Manual}. @cindex PDB @c Do you believe in GUD? -The GUD (Grand Unified Debugger) library provides an interface to -various symbolic debuggers from within Emacs. We recommend the -debugger GDB, which is free software, but GUD can also run DBX, SDB or -XDB. GUD can also serve as an interface to Perl's debugging mode, the -Python debugger PDB, and to JDB, the Java Debugger. -@xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference -Manual}, for information on debugging Emacs Lisp programs. +The GUD (Grand Unified Debugger) library provides an Emacs interface +to a wide variety of symbolic debuggers. Unlike the GDB graphical +interface, which only runs GDB (@pxref{GDB Graphical Interface}), GUD +can also run DBX, SDB, XDB, Perl's debugging mode, the Python debugger +PDB, or the Java Debugger JDB. + + In addition, Emacs contains a built-in system for debugging Emacs +Lisp programs. @xref{Debugging,, The Lisp Debugger, elisp, the Emacs +Lisp Reference Manual}, for information on the Emacs Lisp debugger. @menu * Starting GUD:: How to start a debugger subprocess. @@ -471,15 +480,21 @@ Manual}, for information on debugging Emacs Lisp programs. @node Starting GUD @subsection Starting GUD - There are several commands for starting a debugger, each corresponding -to a particular debugger program. + There are several commands for starting a debugger under GUD, each +corresponding to a particular debugger program. @table @kbd @item M-x gdb @key{RET} @var{file} @key{RET} @findex gdb -Run GDB as a subprocess of Emacs. By default, this uses an IDE-like -graphical interface; see @ref{GDB Graphical Interface}. Only GDB -works with the graphical interface. +Run GDB as a subprocess of Emacs. This uses an IDE-like graphical +interface; see @ref{GDB Graphical Interface}. Only GDB works with the +graphical interface. + +@item M-x gud-gdb @key{RET} @var{file} @key{RET} +@findex gud-gdb +Run GDB as a subprocess of Emacs. This command creates a buffer for +input and output to GDB, and switches to it. If a GDB buffer already +exists, it just switches to that buffer. @item M-x dbx @key{RET} @var{file} @key{RET} @findex dbx @@ -491,21 +506,21 @@ the other supported debuggers. @item M-x xdb @key{RET} @var{file} @key{RET} @findex xdb @vindex gud-xdb-directories -Similar, but run XDB. Use the variable +Run XDB as a subprocess of Emacs. Use the variable @code{gud-xdb-directories} to specify directories to search for source files. @item M-x sdb @key{RET} @var{file} @key{RET} @findex sdb -Similar, but run SDB. +Run SDB as a subprocess of Emacs. - Some versions of SDB do not mention source file names in their +Some versions of SDB do not mention source file names in their messages. When you use them, you need to have a valid tags table (@pxref{Tags}) in order for GUD to find functions in the source code. -If you have not visited a tags table or the tags table doesn't list one -of the functions, you get a message saying @samp{The sdb support -requires a valid tags table to work}. If this happens, generate a valid -tags table in the working directory and try again. +If you have not visited a tags table or the tags table doesn't list +one of the functions, you get a message saying @samp{The sdb support +requires a valid tags table to work}. If this happens, generate a +valid tags table in the working directory and try again. @item M-x perldb @key{RET} @var{file} @key{RET} @findex perldb @@ -527,9 +542,15 @@ debugger supports. However, shell wildcards and variables are not allowed. GUD assumes that the first argument not starting with a @samp{-} is the executable file name. -Tramp provides a facility to debug programs on remote hosts. -@xref{Running a debugger on a remote host, Running a debugger on a remote host,, tramp, The Tramp Manual}. -@c Running a debugger on a remote host +@cindex remote host, debugging on +Tramp provides a facility to debug programs on remote hosts +(@pxref{Running a debugger on a remote host, Running a debugger on a +remote host,, tramp, The Tramp Manual}), whereby both the debugger and +the program being debugged are on the same remote host. This should +not be confused with debugging programs remotely, where the program +and the debugger run on different machines, as can be done using the +GDB remote debugging feature, for example (@pxref{Remote Debugging,, +Debugging Remote Programs, gdb, The GNU debugger}). @node Debugger Operation @subsection Debugger Operation @@ -811,27 +832,22 @@ Fully qualified class name derived from the expression surrounding point @node GDB Graphical Interface @subsection GDB Graphical Interface - By default, the command @code{gdb} starts GDB using a graphical -interface, using Emacs windows for display program state information. -In effect, this makes Emacs into an IDE (interactive development -environment). With it, you do not need to use textual GDB commands; -you can control the debugging session with the mouse. For example, -you can click in the fringe of a source buffer to set a breakpoint -there, or on a stack frame in the stack buffer to select that frame. + The command @code{gdb} starts GDB in a graphical interface, using +Emacs windows for display program state information. In effect, this +makes Emacs into an IDE (interactive development environment). With +it, you do not need to use textual GDB commands; you can control the +debugging session with the mouse. For example, you can click in the +fringe of a source buffer to set a breakpoint there, or on a stack +frame in the stack buffer to select that frame. This mode requires telling GDB that its ``screen size'' is unlimited, so it sets the height and width accordingly. For correct operation you must not change these values during the GDB session. @vindex gud-gdb-command-name - You can also run GDB in text command mode, like the other debuggers -in Emacs. To do this, replace the GDB @code{"--annotate=3"} option -with @code{"--fullname"} either in the minibuffer for the current -Emacs session, or the custom variable @code{gud-gdb-command-name} for -all future sessions. You need to use text command mode to debug -multiple programs within one Emacs session. You can also use -@kbd{M-x gud-gdb} to invoke GDB in text command mode if you have -problems before execution has started. + To run GDB in text command mode, like the other debuggers in Emacs, +use @kbd{M-x gud-gdb}. You need to use text command mode to debug +multiple programs within one Emacs session. @menu * GDB-UI Layout:: Control the number of displayed buffers. @@ -862,7 +878,7 @@ displays the following frame layout: @smallexample @group +--------------------------------+--------------------------------+ -| GUD buffer (I/O of GDB) | Locals buffer | +| GUD buffer (I/O of GDB) | Locals/Registers buffer | |--------------------------------+--------------------------------+ | Primary Source buffer | I/O buffer for debugged pgm | |--------------------------------+--------------------------------+ @@ -1070,24 +1086,25 @@ Alternatively, click @kbd{Mouse-2} on a thread to select it. If the locals buffer is visible, its contents update to display the variables that are local in the new thread. -When @code{gdb-many-windows} is non-@code{nil}, the threads buffer -shares its window with the breakpoints buffer. To switch from one to -the other click with @kbd{mouse-1} on the relevant button in the -header line. - When there is more than one main thread and the threads buffer is -present, Emacs displays the selected thread number in many of the -GDB-UI Buffers. +present, Emacs displays the selected thread number in the mode line of +many of the GDB-UI Buffers. @item Memory Buffer The memory buffer lets you examine sections of program memory (@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}). Click @kbd{Mouse-1} on the appropriate part of the header line to change the starting address or number of data items that the buffer -displays. Click @kbd{Mouse-3} on the header line to select the -display format or unit size for these data items. +displays. Alternatively, use @kbd{S} or @kbd{N} respectively. Click +@kbd{Mouse-3} on the header line to select the display format or unit +size for these data items. @end table +When @code{gdb-many-windows} is non-@code{nil}, the threads buffer +shares its window with the breakpoints buffer, and the locals buffer +with the registers buffer. To switch from one to the other click with +@kbd{mouse-1} on the relevant button in the header line. + @node Watch Expressions @subsubsection Watch Expressions @cindex Watching expressions in GDB @@ -1139,8 +1156,8 @@ edit its value. If the variable @code{gdb-delete-out-of-scope} is non-@code{nil} (the default value), Emacs automatically deletes watch expressions which go out of scope. Sometimes, when re-entering the same function, -it may be useful to set this value to nil so that you don't need to -recreate the watch expression. +it may be useful to set this value to @code{nil} so that you don't +need to recreate the watch expression. @vindex gdb-use-colon-colon-notation If the variable @code{gdb-use-colon-colon-notation} is @@ -1374,25 +1391,23 @@ used; its default is @code{t}. @node Lisp Interaction @section Lisp Interaction Buffers - The buffer @samp{*scratch*} which is selected when Emacs starts up is -provided for evaluating Lisp expressions interactively inside Emacs. - - The simplest way to use the @samp{*scratch*} buffer is to insert Lisp -expressions and type @kbd{C-j} after each expression. This command -reads the Lisp expression before point, evaluates it, and inserts the -value in printed representation before point. The result is a complete -typescript of the expressions you have evaluated and their values. + When Emacs starts up, it contains a buffer named @samp{*scratch*}, +which is provided for evaluating Lisp expressions interactively inside +Emacs. Its major mode is Lisp Interaction mode. - The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, which -is the same as Emacs-Lisp mode except for the binding of @kbd{C-j}. +@findex eval-print-last-sexp +@kindex C-j @r{(Lisp Interaction mode)} + The simplest way to use the @samp{*scratch*} buffer is to insert +Lisp expressions and type @kbd{C-j} (@code{eval-print-last-sexp}) +after each expression. This command reads the Lisp expression before +point, evaluates it, and inserts the value in printed representation +before point. The result is a complete typescript of the expressions +you have evaluated and their values. @findex lisp-interaction-mode - The rationale for this feature is that Emacs must have a buffer when -it starts up, but that buffer is not useful for editing files since a -new buffer is made for every file that you visit. The Lisp interpreter -typescript is the most useful thing I can think of for the initial -buffer to do. Type @kbd{M-x lisp-interaction-mode} to put the current -buffer in Lisp Interaction mode. + All other commands in Lisp Interaction mode are the same as in Emacs +Lisp mode. You can enable Lisp Interaction mode by typing @kbd{M-x +lisp-interaction-mode}. @findex ielm An alternative way of evaluating Emacs Lisp expressions interactively