X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/fc275000aac4d9ef89705b400007bb7b7cbd697f..135e3b47ec43ea6c2d83c460f43fbacb8b8257e2:/man/building.texi diff --git a/man/building.texi b/man/building.texi index b55fc1e47c..d9ee90187e 100644 --- a/man/building.texi +++ b/man/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 Free Software Foundation, Inc. +@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Building, Maintaining, Programs, Top @chapter Compiling and Testing Programs @@ -111,7 +111,7 @@ line of the @samp{*compilation*} buffer changes to say @samp{exit} @samp{run}. @findex kill-compilation - Starting a new compilation also kills any compilation + Starting a new compilation also kills any compilation already running in @samp{*compilation*}, as the buffer can only handle one compilation at any time. However, @kbd{M-x compile} asks for confirmation before actually killing a compilation that is running. @@ -210,9 +210,9 @@ click @kbd{Mouse-2} on the error message; you need not switch to the backquote or ``grave accent,'' not the single-quote. This command is available in all buffers, not just in @samp{*compilation*}; it displays the next error message at the top of one window and source -location of the error in another window. It also momentarily -highlights the relevant source line. You can change the behavior of -this highlighting with the variable @code{next-error-highlight}. +location of the error in another window. It also temporarily +highlights the relevant source line, for a period controlled by the +variable @code{next-error-highlight}. The first time @w{@kbd{C-x `}} is used after the start of a compilation, it moves to the first error's location. Subsequent uses of @kbd{C-x @@ -335,9 +335,11 @@ Emacs. @section Searching with Grep under Emacs Just as you can run a compiler from Emacs and then visit the lines -with compilation errors, you can also run @code{grep} and -then visit the lines on which matches were found. This works by -treating the matches reported by @code{grep} as if they were ``errors.'' +with compilation errors, you can also run @code{grep} and then visit +the lines on which matches were found. This works by treating the +matches reported by @code{grep} as if they were ``errors.'' The +buffer of matches uses Grep mode, which is a variant of Compilation +mode (@pxref{Compilation Mode}). @table @kbd @item M-x grep @@ -359,9 +361,17 @@ that specifies how to run @code{grep}. Use the same arguments you would give @code{grep} when running it normally: a @code{grep}-style regexp (usually in single-quotes to quote the shell's special characters) followed by file names, which may use wildcards. If you -specify a prefix argument for @kbd{M-x grep}, it detects the tag -(@pxref{Tags}) around point, and puts that into the default -@code{grep} command. +specify a prefix argument for @kbd{M-x grep}, it finds the tag +(@pxref{Tags}) in the buffer around point, and puts that into the +default @code{grep} command. + + Your command need not simply run @code{grep}; you can use any shell +command that produces output in the same format. For instance, you +can chain @code{grep} commands, like this: + +@example +grep -nH -e foo *.el | grep bar | grep toto +@end example The output from @code{grep} goes in the @samp{*grep*} buffer. You can find the corresponding lines in the original files using @w{@kbd{C-x @@ -386,8 +396,8 @@ the @code{find-grep-dired} command, in @ref{Dired and Find}. The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep} (recursive grep) are more user-friendly versions of @code{grep} and @code{grep-find}, which prompt separately for the regular expression -to match, the files to search, and the base directory for the search -(rgrep only). Case sensitivity of the search is controlled by the +to match, the files to search, and the base directory for the search. +Case sensitivity of the search is controlled by the current value of @code{case-fold-search}. These commands build the shell commands based on the variables @@ -526,10 +536,11 @@ allowed. GUD assumes that the first argument not starting with a @subsection Debugger Operation @cindex fringes, and current execution line in GUD - When you run a debugger with GUD using the textual interface, the -debugger uses an Emacs buffer for its ordinary input and output. This -is called the GUD buffer. Input and output from the program you are -debugging also use this buffer. + Generally when you run a debugger with GUD, the debugger uses an Emacs +buffer for its ordinary input and output. This is called the GUD +buffer. Input and output from the program you are debugging also use +this buffer. We call this @dfn{text command mode}. The GDB Graphical +Interface can use further buffers (@pxref{GDB Graphical Interface}). The debugger displays the source files of the program by visiting them in Emacs buffers. An arrow in the left fringe indicates the @@ -553,13 +564,13 @@ to be reflected in the debugger's tables. The Tooltip facility (@pxref{Tooltips}) provides support for GUD@. You activate this feature by turning on the minor mode @code{gud-tooltip-mode}. Then you can display a variable's value in a -tooltip simply by pointing at it with the mouse. In graphical mode, -with a C program, you can also display the @code{#define} directive -associated with an identifier when the program is not executing. This -operates in the GUD buffer and in source buffers with major modes in -the list @code{gud-tooltip-modes}. If the variable -@code{gud-tooltip-echo-area} is non-@code{nil} then the variable's -value is displayed in the echo area. +tooltip simply by pointing at it with the mouse. This operates in the +GUD buffer and in source buffers with major modes in the list +@code{gud-tooltip-modes}. If the variable @code{gud-tooltip-echo-area} +is non-@code{nil} then the variable's value is displayed in the echo +area. When debugging a C program using the GDB Graphical Interface, you +can also display macro definitions associated with an identifier when +the program is not executing. GUD tooltips are disabled when you use GDB in text command mode (@pxref{GDB Graphical Interface}), because displaying an expression's @@ -818,24 +829,26 @@ operation you must not change these values during the GDB session. @vindex gud-gdb-command-name @findex gdba You can also run GDB in text command mode, like other debuggers. To -do this, set @code{gud-gdb-command-name} to @code{"gdb --fullname"} or -edit the startup command in the minibuffer to say that. You need to -do use text command mode to run multiple debugging sessions within one -Emacs session. If you have customized @code{gud-gdb-command-name} in -that way, you can use @kbd{M-x gdba} to invoke GDB in graphical mode. +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. If you have customized +@code{gud-gdb-command-name} in this way, you can use @kbd{M-x gdba} to +invoke GDB in graphical mode. @menu -* GDB User Interface Layout:: Control the number of displayed buffers. +* GDB-UI Layout:: Control the number of displayed buffers. +* Source Buffers:: Use the mouse in the fringe/margin to + control your program. * Breakpoints Buffer:: A breakpoint control panel. * Stack Buffer:: Select a frame from the call stack. -* Other GDB User Interface Buffers:: Input/output, locals, registers, +* Other GDB-UI Buffers:: Input/output, locals, registers, assembler, threads and memory buffers. -* GDB commands in the Fringe:: Use the mouse in the fringe/margin to - control your program. * Watch Expressions:: Monitor variable values in the speedbar. @end menu -@node GDB User Interface Layout +@node GDB-UI Layout @subsubsection GDB User Interface Layout @cindex GDB User Interface layout @@ -850,25 +863,21 @@ you are debugging. If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb} displays the following frame layout: -@example +@smallexample +@group +--------------------------------+--------------------------------+ -| | | | GUD buffer (I/O of GDB) | Locals buffer | -| | | |--------------------------------+--------------------------------+ -| | | -| Source buffer | I/O buffer for debugged pgm | -| | | +| Primary Source buffer | I/O buffer for debugged pgm | |--------------------------------+--------------------------------+ -| | | | Stack buffer | Breakpoints buffer | -| | | +--------------------------------+--------------------------------+ -@end example +@end group +@end smallexample However, if @code{gdb-use-separate-io-buffer} is @code{nil}, the I/O -buffer does not appear and the source buffer occupies the full width -of the frame. +buffer does not appear and the primary source buffer occupies the full +width of the frame. @findex gdb-restore-windows If you change the window layout, for example, while editing and @@ -880,7 +889,7 @@ layout with the command @code{gdb-restore-windows}. containing just the GUD buffer and a source file, type @kbd{M-x gdb-many-windows}. - You may also specify additional GUD-related buffers to display, + You may also specify additional GDB-related buffers to display, either in the same frame or a different one. Select the buffers you want with the @samp{GUD->GDB-windows} and @samp{GUD->GDB-Frames} sub-menus. If the menu-bar is unavailable, type @code{M-x @@ -900,11 +909,66 @@ as well as GDB's breakpoints. You do need to check that the breakpoints in recently edited source files are still in the right places. +@node Source Buffers +@subsubsection Source Buffers +@cindex GDB commands in Fringe + +@c @findex gdb-mouse-set-clear-breakpoint +@c @findex gdb-mouse-toggle-breakpoint +Many GDB commands can be entered using keybindings or the tool bar but +sometimes it is quicker to use the fringe. These commands either +manipulate breakpoints or control program execution. When there is no +fringe, you can use the margin but this is only present when the +source file already has a breakpoint. + +You can click @kbd{Mouse-1} in the fringe or display margin of a +source buffer to set a breakpoint there and, on a graphical display, a +red bullet will appear on that line. If a breakpoint already exists +on that line, the same click will remove it. You can also enable or +disable a breakpoint by clicking @kbd{C-Mouse-1} on the bullet. + +A solid arrow in the left fringe of a source buffer indicates the line +of the innermost frame where the debugged program has stopped. A +hollow arrow indicates the current execution line of higher level +frames. + +If you drag the arrow in the fringe with @kbd{Mouse-1} +(@code{gdb-mouse-until}), execution will continue to the line where +you release the button, provided it is still in the same frame. +Alternatively, you can click @kbd{Mouse-3} at some point in the fringe +of this buffer and execution will advance to there. A similar command +(@code{gdb-mouse-jump}) allows you to jump to a source line without +executing the intermediate lines by clicking @kbd{C-Mouse-3}. This +command allows you to go backwards which can be useful for running +through code that has already executed, in order to examine its +execution in more detail. + +@table @kbd +@item Mouse-1 +Set or clear a breakpoint. + +@item C-Mouse-1 +Enable or disable a breakpoint. + +@item Mouse-3 +Continue execution to here. + +@item C-Mouse-3 +Jump to here. +@end table + +If the variable @code{gdb-find-source-frame} is non-@code{nil} and +execution stops in a frame for which there is no source code e.g after +an interrupt, then Emacs finds and displays the first frame further up +stack for which there is source. If it is @code{nil} then the source +buffer continues to display the last frame which maybe more useful, +for example, when re-setting a breakpoint. + @node Breakpoints Buffer @subsubsection Breakpoints Buffer - The breakpoints buffer shows the existing breakpoints and -watchpoints (@pxref{Breakpoints,,, gdb, The GNU debugger}). It has + The breakpoints buffer shows the existing breakpoints, watchpoints and +catchpoints (@pxref{Breakpoints,,, gdb, The GNU debugger}). It has these special commands, which mostly apply to the @dfn{current breakpoint}, the breakpoint which point is on. @@ -914,7 +978,7 @@ breakpoint}, the breakpoint which point is on. @findex gdb-toggle-breakpoint Enable/disable the current breakpoint (@code{gdb-toggle-breakpoint}). On a graphical display, this changes the color of a bullet in the -margin of the source buffer at the relevant line. This is red when +margin of a source buffer at the relevant line. This is red when the breakpoint is enabled and grey when it is disabled. Text-only terminals correspondingly display a @samp{B} or @samp{b}. @@ -942,34 +1006,35 @@ of the nested subroutine calls (@dfn{stack frames}) now active in the program. @xref{Backtrace,, Backtraces, gdb, The GNU debugger}. @findex gdb-frames-select - The selected frame number is displayed in reverse contrast. To -select a frame in GDB, move point in the stack buffer to that stack -frame and type @key{RET} (@code{gdb-frames-select}), or click +An arrow in the fringe points to the selected frame or, if the fringe is +not present, the number of the selected frame is displayed in reverse +contrast. To select a frame in GDB, move point in the stack buffer to +that stack frame and type @key{RET} (@code{gdb-frames-select}), or click @kbd{Mouse-2} on a stack frame. If the locals buffer is visible, -selecting a stack frame updates it to display the local variables of -the new frame. +selecting a stack frame updates it to display the local variables of the +new frame. -@node Other GDB User Interface Buffers +@node Other GDB-UI Buffers @subsubsection Other Buffers @table @asis @item Input/Output Buffer @vindex gdb-use-separate-io-buffer If the variable @code{gdb-use-separate-io-buffer} is non-@code{nil}, -the executable program that is being debugged takes its input and -displays its output here. Otherwise it uses the GUD buffer for that. -To toggle whether GUD mode uses this buffer, do @kbd{M-x -gdb-use-separate-io-buffer}. That takes effect when you next -restart the program you are debugging. +the program being debugged takes its input and displays its output +here. Otherwise it uses the GUD buffer for that. To toggle whether +GUD mode uses this buffer, do @kbd{M-x gdb-use-separate-io-buffer}. +This takes effect when you next restart the program you are debugging. The history and replay commands from Shell mode are available here, -as are the commands to send signals to the program you are debugging. +as are the commands to send signals to the debugged program. @xref{Shell Mode}. @item Locals Buffer The locals buffer displays the values of local variables of the current frame for simple data types (@pxref{Frame Info, Frame Info, -Information on a frame, gdb, The GNU debugger}). +Information on a frame, gdb, The GNU debugger}). Press @key{RET} or +click @kbd{Mouse-2} on the value if you want to edit it. Arrays and structures display their type only. With GDB 6.4 or later, move point to their name and press @key{RET}, or alternatively click @@ -981,7 +1046,7 @@ of GDB, use @kbd{Mouse-2} or @key{RET} on the type description @findex toggle-gdb-all-registers The registers buffer displays the values held by the registers (@pxref{Registers,,, gdb, The GNU debugger}). Press @key{RET} or -click @kbd{Mouse-2} on a register if you want to change its value. +click @kbd{Mouse-2} on a register if you want to edit its value. With GDB 6.4 or later, recently changed register values display with @code{font-lock-warning-face}. With earlier versions of GDB, you can press @key{SPC} to toggle the display of floating point registers @@ -999,10 +1064,10 @@ The threads buffer displays a summary of all threads currently in your program (@pxref{Threads, Threads, Debugging programs with multiple threads, gdb, The GNU debugger}). Move point to any thread in the list and press @key{RET} to select it (@code{gdb-threads-select}) and -display the associated source in the source buffer. 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. +display the associated source in the primary source buffer. +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. @item Memory Buffer The memory buffer lets you examine sections of program memory @@ -1013,49 +1078,6 @@ displays. Click @kbd{Mouse-3} on the header line to select the display format or unit size for these data items. @end table -@node GDB commands in the Fringe -@subsubsection GDB commands in the Fringe -@cindex GDB commands in the Fringe - -@c @findex gdb-mouse-set-clear-breakpoint -@c @findex gdb-mouse-toggle-breakpoint -Many GDB commands can be entered using keybindings or the tool bar but -sometimes it is quicker to use the fringe. These commands either -manipulate breakpoints or control program execution. When there is no -fringe, you can use the margin but this is only present when the -source file already has a breakpoint. - -You can click @kbd{Mouse-1} in the fringe or display margin of a -source buffer to set a breakpoint there and, on a graphical display, a -red bullet will appear on that line. If a breakpoint already exists -on that line, the same click will remove it. You can also enable or -disable a breakpoint by clicking @kbd{C-Mouse-1} on the bullet. - -If you drag the debugger arrow in the fringe with @kbd{Mouse-1} -(@code{gdb-mouse-until}), execution will continue to the line where -you release the button, provided it is still in the same frame. -Alternatively, you can click @kbd{Mouse-3} at some point in the fringe -of this buffer and execution will advance to there. A similar command -(@code{gdb-mouse-jump}) allows you to jump to a source line without -executing the intermediate lines by clicking @kbd{C-Mouse-3}. This -command allows you to go backwards which can be useful for running -through code that has already executed, in order to examine its -execution in more detail. - -@table @kbd -@item Mouse-1 -Set or clear a breakpoint. - -@item C-Mouse-1 -Enable or disable a breakpoint. - -@item Mouse-3 -Continue execution to here. - -@item C-Mouse-3 -Jump to here. -@end table - @node Watch Expressions @subsubsection Watch Expressions @cindex Watching expressions in GDB @@ -1077,8 +1099,11 @@ value for pointers and just the name and type otherwise. Root expressions also display the frame address as a tooltip to help identify the frame in which they were defined. - To expand or contract a complex data type, click @kbd{Mouse-2} -on the tag to the left of the expression. + To expand or contract a complex data type, click @kbd{Mouse-2} or +press @key{SPC} on the tag to the left of the expression. Emacs asks +for confirmation before expanding the expression if its number of +immediate children exceeds the value of the variable +@code{gdb-max-children}. @kindex D @r{(GDB speedbar)} @findex gdb-var-delete @@ -1254,7 +1279,7 @@ Evaluate the defun containing or after point, and print the value in the echo area (@code{eval-defun}). @item M-x eval-region Evaluate all the Lisp expressions in the region. -@item M-x eval-current-buffer +@item M-x eval-buffer Evaluate all the Lisp expressions in the buffer. @end table @@ -1309,11 +1334,11 @@ displaying it in the echo area. The argument's value does not matter. definition for Edebug (@pxref{Instrumenting, Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}). @findex eval-region -@findex eval-current-buffer +@findex eval-buffer The most general command for evaluating Lisp expressions from a buffer is @code{eval-region}. @kbd{M-x eval-region} parses the text of the region as one or more Lisp expressions, evaluating them one by one. -@kbd{M-x eval-current-buffer} is similar but evaluates the entire +@kbd{M-x eval-buffer} is similar but evaluates the entire buffer. This is a reasonable way to install the contents of a file of Lisp code that you are ready to test. Later, as you find bugs and change individual functions, use @kbd{C-M-x} on each function that you @@ -1322,7 +1347,7 @@ change. This keeps the Lisp world in step with the source file. @vindex eval-expression-print-level @vindex eval-expression-print-length @vindex eval-expression-debug-on-error -The customizable variables @code{eval-expression-print-level} and + The two customizable variables @code{eval-expression-print-level} and @code{eval-expression-print-length} control the maximum depth and length of lists to print in the result of the evaluation commands before abbreviating them. @code{eval-expression-debug-on-error} controls