# HG changeset patch # User Chong Yidong # Date 1262109976 18000 # Node ID d937917bda79016c0b64af1c4808e2ad84cf19e0 # Parent 63c5fb6b67fcafafd46ff6f4e8de19b426e978f1 * doc/emacs/misc.texi (Shell): Document async-shell-command. * doc/emacs/building.texi (Grep Searching): Document zrgrep. * doc/emacs/mini.texi (Completion Options): * doc/lispref/minibuf.texi (Completion Styles): Document `initials' style. diff -r 63c5fb6b67fc -r d937917bda79 doc/emacs/ChangeLog --- a/doc/emacs/ChangeLog Tue Dec 29 18:44:27 2009 +0100 +++ b/doc/emacs/ChangeLog Tue Dec 29 13:06:16 2009 -0500 @@ -1,3 +1,11 @@ +2009-12-29 Chong Yidong + + * misc.texi (Shell): Document async-shell-command. + + * building.texi (Grep Searching): Document zrgrep. + + * mini.texi (Completion Options): Mention `initals' completion style. + 2009-12-24 Chong Yidong * emacs.texi (Top): Update node listing. diff -r 63c5fb6b67fc -r d937917bda79 doc/emacs/building.texi --- a/doc/emacs/building.texi Tue Dec 29 18:44:27 2009 +0100 +++ b/doc/emacs/building.texi Tue Dec 29 13:06:16 2009 -0500 @@ -356,8 +356,10 @@ @item M-x grep-find @itemx M-x find-grep @itemx M-x rgrep -Run @code{grep} via @code{find}, with user-specified arguments, and -collect output in the buffer named @samp{*grep*}. +Run @code{grep} via @code{find}, and collect output in the buffer +named @samp{*grep*}. +@item M-x zrgrep +Run @code{zgrep} and collect output in the buffer named @samp{*grep*}. @item M-x kill-grep Kill the running @code{grep} subprocess. @end table @@ -400,21 +402,22 @@ @findex lgrep @findex rgrep +@findex zrgrep 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. -Case sensitivity of the search is controlled by the -current value of @code{case-fold-search}. +Case sensitivity of the search is controlled by the current value of +@code{case-fold-search}. The command @kbd{M-x zrgrep} is similar to +@code{rgrep}, but it calls @code{zgrep} instead of @code{grep} to +search the contents of gzipped files. -These commands build the shell commands based on the variables + These commands build the shell commands based on the variables @code{grep-template} (for @code{lgrep}) and @code{grep-find-template} -(for @code{rgrep}). +(for @code{rgrep}). The files to search can use aliases defined in +the variable @code{grep-files-aliases}. -The files to search can use aliases defined in the variable -@code{grep-files-aliases}. - -Subdirectories listed in the variable + Subdirectories listed in the variable @code{grep-find-ignored-directories} such as those typically used by various version control systems, like CVS and arch, are automatically skipped by @code{rgrep}. @@ -854,11 +857,12 @@ * Source Buffers:: Use the mouse in the fringe/margin to control your program. * Breakpoints Buffer:: A breakpoint control panel. +* Threads Buffer:: Displays your threads. * Stack Buffer:: Select a frame from the call stack. * Other GDB-UI Buffers:: Input/output, locals, registers, assembler, threads and memory buffers. * Watch Expressions:: Monitor variable values in the speedbar. -* Reverse Debugging:: Execute and reverse debug your program. +* Multithreaded Debugging:: Debugging programs with several threads. @end menu @node GDB-UI Layout @@ -883,7 +887,7 @@ |--------------------------------+--------------------------------+ | Primary Source buffer | I/O buffer for debugged pgm | |--------------------------------+--------------------------------+ -| Stack buffer | Breakpoints/Threads buffer | +| Stack buffer | Breakpoints/Thread buffer | +--------------------------------+--------------------------------+ @end group @end smallexample @@ -1011,10 +1015,92 @@ Visit the source line for the breakpoint you click on. @end table +@vindex gdb-show-threads-by-default When @code{gdb-many-windows} is non-@code{nil}, the breakpoints buffer shares its window with the threads buffer. To switch from one to the other click with @kbd{Mouse-1} on the relevant button in the header -line. +line, or press @kbd{TAB} inside that buffer. If +@code{gdb-show-threads-by-default} is non-@code{nil}, the threads +buffer, rather than the breakpoints buffer, is shown at start up. + +@node Threads Buffer +@subsubsection Threads Buffer + +@findex gdb-select-thread +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-select-thread}) and +display the associated source in the primary source buffer. +Alternatively, click @kbd{Mouse-2} on a thread to select it. Contents +of all GDB buffers are updated whenever you select a thread. + + You can customize variables under @code{gdb-buffers} group to select +fields included in threads buffer. + +@table @code +@item gdb-thread-buffer-verbose-names +@vindex gdb-thread-buffer-verbose-names +Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)} in +threads buffer. + +@item gdb-thread-buffer-arguments +@vindex gdb-thread-buffer-arguments +Show arguments of thread top frames in threads buffer. + +@item gdb-thread-buffer-locations +@vindex gdb-thread-buffer-locations +Show file information or library names in threads buffer. + +@item gdb-thread-buffer-addresses +@vindex gdb-thread-buffer-addresses +Show addresses for thread frames in threads buffer. +@end table + + It’s possible to observe information for several threads +simultaneously (in addition to buffers which show information for +currently selected thread) using the following keys from the threads +buffer. + +@table @kbd +@item d +@kindex d @r{(GDB threads buffer)} +@findex gdb-display-disassembly-for-thread +Display disassembly buffer for the thread at current line. +(@code{gdb-display-disassembly-for-thread}) + +@item f +@kindex f @r{(GDB threads buffer)} +@findex gdb-display-stack-for-thread +Display stack buffer for the thread at current line. +(@code{gdb-display-stack-for-thread}). + +@item l +@kindex l @r{(GDB threads buffer)} +@findex gdb-display-locals-for-thread +Display locals buffer for the thread at current line. +(@code{gdb-display-locals-for-thread}). + +@item r +@kindex r @r{(GDB threads buffer)} +@findex gdb-display-registers-for-thread +Display registers buffer for the thread at current line. +(@code{gdb-display-registers-for-thread}). +@end table + +Pressing their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and +@kbd{R} displays the corresponding buffer in a new frame. + + When you create a buffer showing information about some specific +thread, it becomes bound to that thread and keeps showing actual +information while you debug your program. Every GDB buffer contains a +number of thread it shows information for in its mode name. Thread +number is also included in the buffer name of bound buffers to prevent +buffer names clashing. + +Further commands are available in the threads buffer which depend on the +mode of GDB that is used for controlling execution of your program. +(@pxref{Multithreaded Debugging, Stopping and Starting Multi-threaded Programs}). @node Stack Buffer @subsubsection Stack Buffer @@ -1051,7 +1137,7 @@ @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}). Press @key{RET} or +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, @@ -1070,27 +1156,12 @@ press @key{SPC} to toggle the display of floating point registers (@code{toggle-gdb-all-registers}). -@item Assembler Buffer -The assembler buffer displays the current frame as machine code. An +@item Disassembly Buffer +The disassembly buffer displays the current frame as machine code. An arrow points to the current instruction, and you can set and remove breakpoints as in a source buffer. Breakpoint icons also appear in the fringe or margin. -@item Threads Buffer -@findex gdb-threads-select -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 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. - -When there is more than one main thread and the threads buffer is -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}). @@ -1103,8 +1174,9 @@ 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. +with the registers buffer. To switch from one to the other click with +@kbd{Mouse-1} on the relevant button in the header line or press +@kbd{TAB} inside the buffer. @node Watch Expressions @subsubsection Watch Expressions @@ -1172,26 +1244,96 @@ non-@code{nil}. This can be useful if you are debugging with a full screen Emacs frame. -@node Reverse Debugging -@subsubsection Reverse Debugging +@node Multithreaded Debugging +@subsubsection Stopping and Starting Multi-threaded Programs +@cindex Multithreaded debugging in GDB + +@subsubheading All-stop Debugging + +In all-stop mode, whenever your program stops, @emph{all} threads of +execution stop. Likewise, whenever you restart the program, all +threads start executing. @xref{All-Stop Mode, , All-Stop Mode, gdb, +The GNU debugger}. You can enable this behaviour in Emacs by setting +@code{gdb-non-stop-setting} to @code{nil} before starting a debugging +session. + +@subsubheading Non-stop Debugging +@cindex Non-stop debugging in GDB + +For some multi-threaded targets, GDB supports a further mode of +operation in which you can examine stopped program threads in the +debugger while other threads continue to execute freely. +@xref{Non-Stop Mode, , Non-Stop Mode, gdb, The GNU debugger}. +This is referred to as @dfn{non-stop} mode. + +Versions of GDB prior to 7.0 do not support non-stop mode and it does +not work on all targets. In such cases, Emacs uses all-stop mode +regardless of the value of @code{gdb-non-stop-setting}. + +@vindex gdb-non-stop-setting +If the variable @code{gdb-non-stop-setting} is non-@code{nil} (the +default value), Emacs tries to start GDB in non-stop mode. Note that +GDB debugging session needs to be restarted for change of this setting +to take effect. + +@vindex gdb-switch-when-another-stopped +When a thread stops in non-stop mode, Emacs automatically switches to +that thread. It may be undesirable to allow switching of current +thread when some other stopped thread is already selected. Set +@code{gdb-switch-when-another-stopped} to @code{nil} to prevent this. + +@vindex gdb-switch-reasons +Emacs can decide whether or not to switch to the stopped thread +depending on the reason which caused the stop. Customize +@code{gdb-switch-reasons} to select stop reasons which make Emacs +switch thread. - The GDB tool bar shares many buttons with the other GUD debuggers -for tasks like stepping and printing expressions. It also has a -further set of buttons that allow reverse debugging (@pxref{Process -Record and Replay, , ,gdb, The GNU debugger}). This is useful when it -takes a long time to reproduce the conditions where your program fails -or for transient problems, like race conditions in multi-threaded -programs, where a failure might otherwise be hard to reproduce. +@vindex gdb-stopped-hooks +The variable @code{gdb-stopped-hooks} allows you to execute your +functions whenever some thread stops. + + In non-stop mode, you can switch between different modes for GUD +execution control commands. + +@vindex gdb-gud-control-all-threads +@table @dfn +@item Non-stop/A + +When @code{gdb-gud-control-all-threads} is @code{t} (the default +value), interruption and continuation commands apply to all threads, +so you can halt or continue all your threads with one command using +@code{gud-stop-subjob} and @code{gud-cont}, respectively. The +@samp{Go} button is shown on the toolbar when at least one thread is +stopped, whereas @samp{Stop} button is shown when at least one thread +is running. + +@item Non-stop/T -To use reverse debugging, set a breakpoint slightly before the -location of interest and run your program to that point. Enable -process recording by clicking on the record button. At this point, a -new set of buttons appear. These buttons allow program execution in -the reverse direction. Run your program over the code where the -problem occurs, and then use the new set of buttons to retrace your -steps, examine values, and analyze the problem. When analysis is -complete, turn off process recording by clicking on the record button -again. +When @code{gdb-gud-control-all-threads} is @code{nil}, only the +current thread is stopped/continued. @samp{Go} and @samp{Stop} +buttons on the GUD toolbar are shown depending on the state of current +thread. +@end table + +You can change the current value of @code{gdb-gud-control-all-threads} +from the tool bar or from @samp{GUD->GDB-MI} menu. + + Stepping commands always apply to the current thread. + +@subsubheading Fine Thread Control + + In non-stop mode, you can interrupt/continue your threads without +selecting them. Hitting @kbd{i} in threads buffer interrupts thread +under point, @kbd{c} continues it, @kbd{s} steps through. More such +commands may be added in the future. + +Combined with creating bound buffers for any thread, this allows you +to change and track state of many threads in the same time. + + Note that when you interrupt a thread, it stops with @samp{signal +received} reason. If that reason is included in your +@code{gdb-switch-reasons} (it is by default), Emacs will switch to +that thread. @node Executing Lisp @section Executing Lisp Expressions diff -r 63c5fb6b67fc -r d937917bda79 doc/emacs/mini.texi --- a/doc/emacs/mini.texi Tue Dec 29 18:44:27 2009 +0100 +++ b/doc/emacs/mini.texi Tue Dec 29 13:06:16 2009 -0500 @@ -456,12 +456,13 @@ using the variable @code{completion-styles}. Its value should be a list of symbols, each representing a @dfn{completion style}; valid style symbols are @code{basic}, @code{partial-completion}, -@code{emacs22}, and @code{emacs21}. When completing, Emacs attempts -to use the first completion style in the list; if this does not return -any completion alternatives, it tries the next completion style in the -list, and so on. The completion rules described in @ref{Completion -Commands} correspond to the default value of @code{completion-styles}, -which is @code{(basic partial-completion emacs22)}. +@code{emacs22}, @code{emacs21}, and @code{initials}. When completing, +Emacs attempts to use the first completion style in the list; if this +does not return any completion alternatives, it tries the next +completion style in the list, and so on. The completion rules +described in @ref{Completion Commands} correspond to the default value +of @code{completion-styles}, which is @code{(basic partial-completion +emacs22)}. @cindex Icomplete mode @findex icomplete-mode diff -r 63c5fb6b67fc -r d937917bda79 doc/emacs/misc.texi --- a/doc/emacs/misc.texi Tue Dec 29 18:44:27 2009 +0100 +++ b/doc/emacs/misc.texi Tue Dec 29 13:06:16 2009 -0500 @@ -485,6 +485,9 @@ Run the shell command line @var{cmd} with region contents as input; optionally replace the region with the output (@code{shell-command-on-region}). +@item M-& @var{cmd} @key{RET} +Run the shell command line @var{cmd} asynchronously, and display the +output (@code{async-shell-command}). @item M-x shell Run a subshell with input and output through an Emacs buffer. You can then give commands interactively. @@ -542,6 +545,11 @@ program. You do not get any status information for an asynchronous command, since it hasn't finished yet when @code{shell-command} returns. + You can also type @kbd{M-&} (@code{async-shell-command}) to execute +a shell command asynchronously. This behaves exactly like calling +@code{shell-command} with @samp{&}, except that you do not need to add +the @samp{&} to the shell command line. + @kindex M-| @findex shell-command-on-region @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but diff -r 63c5fb6b67fc -r d937917bda79 doc/lispref/ChangeLog --- a/doc/lispref/ChangeLog Tue Dec 29 18:44:27 2009 +0100 +++ b/doc/lispref/ChangeLog Tue Dec 29 13:06:16 2009 -0500 @@ -1,3 +1,7 @@ +2009-12-29 Chong Yidong + + * minibuf.texi (Completion Styles): Document `initials' style. + 2009-12-25 Chong Yidong * frames.texi (Resources): Describe inhibit-x-resources. diff -r 63c5fb6b67fc -r d937917bda79 doc/lispref/minibuf.texi --- a/doc/lispref/minibuf.texi Tue Dec 29 18:44:27 2009 +0100 +++ b/doc/lispref/minibuf.texi Tue Dec 29 13:06:16 2009 -0500 @@ -1589,13 +1589,13 @@ @var{all-completions} functions. @end defvar - By default, @code{completion-styles-alist} contains four pre-defined + By default, @code{completion-styles-alist} contains five pre-defined completion styles: @code{basic}, a basic completion style; @code{partial-completion}, which does partial completion (completing each word in the input separately); @code{emacs22}, which performs -completion according to the rules used in Emacs 22; and -@code{emacs21}, which performs completion according to the rules used -in Emacs 21. +completion according to the rules used in Emacs 22; @code{emacs21}, +which performs completion according to the rules used in Emacs 21; and +@code{initials}, which completes acronyms and initialisms. @node Programmed Completion @subsection Programmed Completion diff -r 63c5fb6b67fc -r d937917bda79 etc/NEWS --- a/etc/NEWS Tue Dec 29 18:44:27 2009 +0100 +++ b/etc/NEWS Tue Dec 29 13:06:16 2009 -0500 @@ -26,27 +26,27 @@ ** New configure options for Emacs developers These are not new features; only the configure flags are new. - +--- *** --enable-profiling builds Emacs with profiling enabled. This might not work on all platforms. - +--- *** --enable-checking[=OPTIONS] builds emacs with extra runtime checks. --- ** `make install' now consistently ignores umask, creating a world-readable install. -** Emacs compiles with Gconf support by default, if it is detected. +** Emacs compiles with Gconf support, if it is detected. Use the configure option --without-gconf to disable this. * Startup Changes in Emacs 23.2 - ++++ ** The command-line option -Q (--quick) also inhibits loading X resources. However, if Emacs is compiled with the Lucid or Motif toolkit, X resource settings for the graphical widgets are still applied. On Windows, the -Q option causes Emacs to ignore Registry settings, but environment variables set on the Registry are still honored. - ++++ *** The new variable `inhibit-x-resources' shows whether X resources were loaded. @@ -55,9 +55,11 @@ * Changes in Emacs 23.2 ++++ ** The maximum size of buffers (and the largest fixnum) is doubled. On typical 32bit systems, buffers can now be up to 512MB. +--- ** The default value of `trash-directory' is now nil. This means that `move-file-to-trash' trashes files according to freedesktop.org specifications, the same method used by the Gnome, @@ -80,13 +82,14 @@ via the XSETTINGS mechanism. This includes antialias, hinting, hintstyle, RGBA, DPI and lcdfilter changes. ++++ ** Killing a buffer with a running process now asks for confirmation. To remove this query, remove `process-kill-buffer-query-function' from `kill-buffer-query-functions', or set the appropriate process flag with `set-process-query-on-exit-flag'. ** File-local variable changes - ++++ *** Specifying a minor mode as a local variables enables that mode, unconditionally. The previous behavior, toggling the mode, was neither reliable nor generally desirable. @@ -104,17 +107,18 @@ `copy-file-locals-to-dir-locals'. ** Internationalization changes - ++++ *** Unibyte sessions are now considered obsolete. This refers to the EMACS_UNIBYTE environment variable as well as the --unibyte, --multibyte, --no-multibyte, and --no-unibyte command line arguments. Customizing enable-multibyte-characters and setting default-enable-multibyte-characters are also deprecated. - +--- *** New coding system `utf-8-hfs'. This is suitable for default-file-name-coding-system on Mac OS X; see international/ucs-normalize.el. +--- ** Function arguments in *Help* buffers are now shown in upper-case. Customize `help-downcase-arguments' to t to show them in lower-case. @@ -127,11 +131,11 @@ becomes the primary selection (for interaction with other window applications). If you enable this, you might want to bind `mouse-yank-primary' to Mouse-2. - ++++ *** When `save-interprogram-paste-before-kill' is non-nil, the kill commands save the interprogram-paste selection into the kill ring before doing anything else. This avoids losing the selection. - ++++ *** When `kill-do-not-save-duplicates' is non-nil, identical subsequent kills are not duplicated in the `kill-ring'. @@ -140,7 +144,7 @@ *** The new command `completion-at-point' provides mode-sensitive completion. *** tab-always-indent set to `complete' lets TAB do completion as well. - ++++ *** The new completion-style `initials' is available. For instance, this can complete M-x lch to list-command-history. @@ -151,6 +155,7 @@ +++ ** The default value of `blink-matching-paren-distance' is increased. +--- ** M-n provides more default values in the minibuffer for commands that read file names. These include the file name at point (when ffap is loaded without ffap-bindings), the file name on the current line @@ -158,14 +163,20 @@ (for Dired commands that operate on several directories, such as copy, rename, or diff). ++++ ** M-r is bound to the new `move-to-window-line-top-bottom'. This moves point to the window center, top and bottom on successive invocations, in the same spirit as the C-l (recenter-top-bottom) command. ++++ ** The new variable `recenter-positions' determines the default cycling order of C-l (`recenter-top-bottom'). ++++ +** The abbrevs file is now a file named abbrev_defs in +user-emacs-directory; but the old location, ~/.abbrev_defs, is used if +that file exists. * Changes in Specialized Modes and Packages in Emacs 23.2 @@ -180,11 +191,15 @@ ** pcomplete provides a new command `pcomplete-std-completion' which is similar to `pcomplete' but using the standard completion UI code. -** .calc.el and .abbrev_defs obey user-emacs-directory. - -** Calc graphing commands (`g f' etc.) now work on MS-Windows, -if you have the native Windows port of Gnuplot version 3.8 or later -installed. +** Calc ++++ +*** The Calc settings file is now a file named calc.el in +user-emacs-directory; but the old location, ~/.calc.el, is used if +that file exists. + +--- +*** Graphing commands (`g f' etc.) now work on MS-Windows, if you have +the native Windows port of Gnuplot version 3.8 or later installed. ** Calendar and diary @@ -224,8 +239,8 @@ watch expressions. These features require GDB 7.0 or later. ** Grep - -A new command `zrgrep' searches recursively in gzipped files. ++++ +*** A new command `zrgrep' searches recursively in gzipped files. ** Info @@ -366,6 +381,7 @@ `default-directory' is already remote. Calling the external commands is possible by `*su' or `*sudo', repectively. +--- *** When running in a new enough xterm (newer than version 242), emacs asks xterm what the background color is and it sets up faces accordingly for a dark background if needed (the current default is to @@ -442,8 +458,10 @@ ** New function `completion-in-region' to use the standard completion facilities on a particular region of text. ++++ ** The 4th arg to all-completions (aka hide-spaces) is declared obsolete. +--- ** read-file-name-predicate is obsolete. It was used to pass the predicate to read-file-name-internal because read-file-name-internal abused its `pred' argument to pass the current directory, but this hack is not needed @@ -451,6 +469,7 @@ ** Frame parameter changes ++++ *** You can give the `fullscreen' frame parameter the value `maximized'. This maximizes the frame. @@ -458,6 +477,7 @@ *** The new frame parameter `sticky' makes Emacs frames sticky in virtual desktops. +--- ** completion-base-size is obsoleted by completion-base-position. This change causes a few backward incompatibilities, mostly with choose-completion-string-functions where the `mini-p' argument has @@ -491,11 +511,12 @@ a `process-file' call does not change a remote file. By this, file name handlers like Tramp can apply optimizations. ++++ ** Hash tables have a new printed representation that is readable. The feature `hashtable-print-readable' identifies this new functionality. -** Functions performing Unicode normalization are added. They are: +** New functions performing Unicode normalization are added: ucs-normalize-NFD-region, ucs-normalize-NFD-string, ucs-normalize-NFC-region, ucs-normalize-NFC-string, ucs-normalize-NFKD-region, ucs-normalize-NFKD-string,