@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software
+@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Building, Maintaining, Programs, Top
+@node Building
@chapter Compiling and Testing Programs
@cindex building programs
@cindex program building
was started.
@findex kill-compilation
+@vindex compilation-always-kill
Starting a new compilation also kills any compilation already
running in @file{*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.
-You can also kill the compilation process with @kbd{M-x
+confirmation before actually killing a compilation that is running; to
+always automatically kill the compilation without asking, change the
+variable @code{compilation-always-kill} to @code{t}. You can also
+kill a compilation process with the command @kbd{M-x
kill-compilation}.
To run two compilations at once, start the first one, then rename
If the @file{*compilation*} buffer is shown in a window with a left
fringe (@pxref{Fringes}), the locus-visiting commands put an arrow in
the fringe, pointing to the current error message. If the window has
-no left fringe, such as on a text-only terminal, these commands scroll
-the window so that the current message is at the top of the window.
-If you change the variable @code{compilation-context-lines} to an
-integer value @var{n}, these commands scroll the window so that the
-current error message is @var{n} lines from the top, whether or not
-there is a fringe; the default value, @code{nil}, gives the behavior
-described above.
+no left fringe, such as on a text terminal, these commands scroll the
+window so that the current message is at the top of the window. If
+you change the variable @code{compilation-context-lines} to an integer
+value @var{n}, these commands scroll the window so that the current
+error message is @var{n} lines from the top, whether or not there is a
+fringe; the default value, @code{nil}, gives the behavior described
+above.
@vindex compilation-error-regexp-alist
@vindex grep-regexp-alist
@findex next-error-follow-minor-mode
You can type @kbd{C-c C-f} to toggle Next Error Follow mode. In
this minor mode, ordinary cursor motion in the compilation buffer
-automatically updates the source buffer, i.e.@: moving the cursor over
+automatically updates the source buffer, i.e., moving the cursor over
an error message causes the locus of that error to be displayed.
The features of Compilation mode are also available in a minor mode
@end example
@ifnottex
- On the MS-DOS ``operating system'', asynchronous subprocesses are
+ On MS-DOS, asynchronous subprocesses are
not supported, so @kbd{M-x compile} runs the compilation command
-synchronously (i.e.@: you must wait until the command finishes before
+synchronously (i.e., you must wait until the command finishes before
you can do anything else in Emacs). @xref{MS-DOS}.
@end ifnottex
Just as you can run a compiler from Emacs and then visit the lines
with compilation errors, you can also run @command{grep} and then
visit the lines on which matches were found. This works by treating
-the matches reported by @command{grep} as if they were ``errors.''
+the matches reported by @command{grep} as if they were errors.
The output buffer uses Grep mode, which is a variant of Compilation
mode (@pxref{Compilation Mode}).
Flymake mode is a minor mode that performs on-the-fly syntax
checking for many programming and markup languages, including C, C++,
-Perl, HTML, and @TeX{}/La@TeX{}. It is somewhat analogous to Flyspell
+Perl, HTML, and @TeX{}/@LaTeX{}. It is somewhat analogous to Flyspell
mode, which performs spell checking for ordinary human languages in a
similar fashion (@pxref{Spelling}). As you edit a file, Flymake mode
runs an appropriate syntax checking tool in the background, using a
C/C++ files this is usually the C compiler. Flymake can also use
build tools such as @code{make} for checking complicated projects.
- To enable Flymake mode, type @kbd{M-x flymake-mode}. You can go to
-the errors found by Flymake mode with @kbd{M-x
-flymake-goto-next-error} and @kbd{M-x flymake-goto-prev-error}. To
-display any error messages associated with the current line, use
-@kbd{M-x flymake-display-err-menu-for-current-line}.
+ To enable Flymake mode, type @kbd{M-x flymake-mode}. You can jump
+to the errors that it finds by using @kbd{M-x flymake-goto-next-error}
+and @kbd{M-x flymake-goto-prev-error}. To display any error messages
+associated with the current line, type @kbd{M-x
+flymake-display-err-menu-for-current-line}.
For more details about using Flymake,
@ifnottex
As you debug a program, Emacs displays the relevant source files by
visiting them in Emacs buffers, with an arrow in the left fringe
-indicating the current execution line. (On a text-only terminal, the
-arrow appears as @samp{=>}, overlaid on the first two text columns.)
-Moving point in such a buffer does not move the arrow. You are free
-to edit these source files, but note that inserting or deleting lines
-will throw off the arrow's positioning, as Emacs has no way to figure
-out which edited source line corresponds to the line reported by the
+indicating the current execution line. (On a text terminal, the arrow
+appears as @samp{=>}, overlaid on the first two text columns.) Moving
+point in such a buffer does not move the arrow. You are free to edit
+these source files, but note that inserting or deleting lines will
+throw off the arrow's positioning, as Emacs has no way to figure out
+which edited source line corresponds to the line reported by the
debugger subprocess. To update this information, you typically have
to recompile and restart the program.
@findex gud-tooltip-mode
@vindex gud-tooltip-echo-area
GUD Tooltip mode is a global minor mode that adds tooltip support to
-GUD. To toggle this mode, type @kbd{M-x gud-tooltip-mode}. It is
+GUD@. To toggle this mode, type @kbd{M-x gud-tooltip-mode}. It is
disabled by default. If enabled, you can move the mouse cursor over a
-variable to show its value in a tooltip (@pxref{Tooltips}); this takes
-effect in the GUD interaction buffer, and in all source buffers with
-major modes listed in the variable @code{gud-tooltip-modes}. If the
-variable @code{gud-tooltip-echo-area} is non-@code{nil}, values are
-shown in the echo area instead of a tooltip.
-
- When using GUD Tooltip mode with @kbd{M-x gud-gdb}, you should note
-that displaying an expression's value in GDB can sometimes expand a
-macro, potentially causing side effects in the debugged program. If
-you use the @kbd{M-x gdb} interface, this problem does not occur, as
-there is special code to avoid side-effects; furthermore, you can
-display macro definitions associated with an identifier when the
-program is not executing.
+variable, a function, or a macro (collectively called
+@dfn{identifiers}) to show their values in tooltips
+(@pxref{Tooltips}). Alternatively, mark an identifier or an
+expression by dragging the mouse over it, then leave the mouse in the
+marked area to have the value of the expression displayed in a
+tooltip. The GUD Tooltip mode takes effect in the GUD interaction
+buffer, and in all source buffers with major modes listed in the
+variable @code{gud-tooltip-modes}. If the variable
+@code{gud-tooltip-echo-area} is non-@code{nil}, or if you turned off
+the tooltip mode, values are shown in the echo area instead of a
+tooltip.
+
+ When using GUD Tooltip mode with @kbd{M-x gud-gdb}, displaying an
+expression's value in GDB can sometimes expand a macro, potentially
+causing side effects in the debugged program. For that reason, using
+tooltips in @code{gud-gdb} is disabled. If you use the @kbd{M-x gdb}
+interface, this problem does not occur, as there is special code to
+avoid side-effects; furthermore, you can display macro definitions
+associated with an identifier when the program is not executing.
@node Commands of GUD
@subsection Commands of GUD
selecting stack frames, and stepping through the program.
@table @kbd
-@item C-x @key{SPC}
-@kindex C-x SPC
+@item C-x C-a C-b
+@kindex C-x C-a C-b
Set a breakpoint on the source line that point is on.
@end table
- @kbd{C-x @key{SPC}} (@code{gud-break}), when called in a source
+ @kbd{C-x C-a C-b} (@code{gud-break}), when called in a source
buffer, sets a debugger breakpoint on the current source line. This
-command is available only after starting GUD. If you call it in a
+command is available only after starting GUD@. If you call it in a
buffer that is not associated with any debugger subprocess, it signals
a error.
that makes sense.
Because @key{TAB} serves as a completion command, you can't use it to
-enter a tab as input to the program you are debugging with GDB.
+enter a tab as input to the program you are debugging with GDB@.
Instead, type @kbd{C-q @key{TAB}} to enter a tab.
@node GUD Customization
you are using DBX; @code{sdb-mode-hook}, if you are using SDB;
@code{xdb-mode-hook}, if you are using XDB; @code{perldb-mode-hook},
for Perl debugging mode; @code{pdb-mode-hook}, for PDB;
-@code{jdb-mode-hook}, for JDB. @xref{Hooks}.
+@code{jdb-mode-hook}, for JDB@. @xref{Hooks}.
The @code{gud-def} Lisp macro (@pxref{Defining Macros,,, elisp, the
Emacs Lisp Reference Manual}) provides a convenient way to define an
@table @samp
@item %f
The name of the current source file. If the current buffer is the GUD
-buffer, then the ``current source file'' is the file that the program
+buffer, then the current source file is the file that the program
stopped in.
@item %l
The number of the current source line. If the current buffer is the GUD
-buffer, then the ``current source line'' is the line that the program
+buffer, then the current source line is the line that the program
stopped in.
@item %e
within one Emacs session, as that is currently unsupported by @kbd{M-x
gdb}.
- Internally, @kbd{M-x gdb} informs GDB that its ``screen size'' is
+ Internally, @kbd{M-x gdb} informs GDB that its screen size is
unlimited; for correct operation, you must not change GDB's screen
height and width values during the debugging session.
@end group
@end smallexample
- However, if @code{gdb-use-separate-io-buffer} is @code{nil}, the I/O
-buffer does not appear and the primary source buffer occupies the full
-width of the frame.
-
@findex gdb-restore-windows
@findex gdb-many-windows
- If you ever change the window layout, you can restore the ``many
-windows'' layout by typing @kbd{M-x gdb-restore-windows}. To toggle
+ If you ever change the window layout, you can restore the many-windows
+layout by typing @kbd{M-x gdb-restore-windows}. To toggle
between the many windows layout and a simple layout with just the GUD
interaction buffer and a source file, type @kbd{M-x gdb-many-windows}.
enables or disables an existing breakpoint; a breakpoint that is
disabled, but not unset, is indicated by a gray dot.
- On a text-only terminal, or when fringes are disabled, enabled
+ On a text terminal, or when fringes are disabled, enabled
breakpoints are indicated with a @samp{B} character in the left margin
of the window. Disabled breakpoints are indicated with @samp{b}.
(The margin is only displayed if a breakpoint is present.)
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
+line of the innermost frame where the debugged program has stopped. A
hollow arrow indicates the current execution line of a higher-level
frame. If you drag the arrow in the fringe with @kbd{Mouse-1}, that
causes execution to advance to the line where you release the button.
The GDB Threads buffer displays a summary of the threads in the
debugged program. @xref{Threads, Threads, Debugging programs with
multiple threads, gdb, The GNU debugger}. To select a thread, move
-point there and type @key{RET} (@code{gdb-select-thread}), or click on
+point there and press @key{RET} (@code{gdb-select-thread}), or click on
it with @kbd{Mouse-2}. This also displays the associated source
buffer, and updates the contents of the other GDB buffers.
@findex gdb-frames-select
On graphical displays, the selected stack frame is indicated by an
-arrow in the fringe. On text-only terminals, or when fringes are
-disabled, the selected stack frame is displayed in reverse contrast.
-To select a stack frame, move point in its line and type @key{RET}
+arrow in the fringe. On text terminals, or when fringes are disabled,
+the selected stack frame is displayed in reverse contrast. To select
+a stack frame, move point in its line and type @key{RET}
(@code{gdb-frames-select}), or click @kbd{Mouse-2} on it. Doing so
also updates the Locals buffer
@ifnottex
When @code{gdb-many-windows} is non-@code{nil}, the locals buffer
shares its window with the registers buffer, just like breakpoints and
-threads buffers. To switch from one to the other, click with
+threads buffers. To switch from one to the other, click with
@kbd{Mouse-1} on the relevant button in the header line.
@node Watch Expressions
@code{gdb-switch-reasons} to select the stop reasons which will cause
a thread switch.
-@vindex gdb-stopped-hooks
- The variable @code{gdb-stopped-hooks} allows you to execute your
+@vindex gdb-stopped-functions
+ The variable @code{gdb-stopped-functions} allows you to execute your
functions whenever some thread stops.
In non-stop mode, you can switch between different modes for GUD
@findex load
@findex load-library
+@vindex load-prefer-newer
@cindex load path for Emacs Lisp
If an Emacs Lisp file is installed in the Emacs Lisp @dfn{load path}
(defined below), you can load it by typing @kbd{M-x load-library},
searches through each directory in the Emacs Lisp load path, trying to
find a file matching that library name. If the library name is
@samp{@var{foo}}, it tries looking for files named
-@file{@var{foo}.elc}, @file{@var{foo}.el}, and lastly just
-@file{@var{foo}}; the first one found is loaded. This command prefers
-@file{.elc} files over @file{.el} files because compiled files load
-and run faster. If it finds that @file{@var{lib}.el} is newer than
-@file{@var{lib}.elc}, it issues a warning, in case someone made
+@file{@var{foo}.elc}, @file{@var{foo}.el}, and @file{@var{foo}}. The
+default behavior is to load the first file found. This command
+prefers @file{.elc} files over @file{.el} files because compiled files
+load and run faster. If it finds that @file{@var{lib}.el} is newer
+than @file{@var{lib}.elc}, it issues a warning, in case someone made
changes to the @file{.el} file and forgot to recompile it, but loads
the @file{.elc} file anyway. (Due to this behavior, you can save
unfinished edits to Emacs Lisp source files, and not recompile until
-your changes are ready for use.)
+your changes are ready for use.) If you set the option
+@code{load-prefer-newer} to a non-@code{nil} value, however, then
+rather than the procedure described above, Emacs loads whichever
+version of the file is newest.
Emacs Lisp programs usually load Emacs Lisp files using the
@code{load} function. This is similar to @code{load-library}, but is
@end example
@cindex autoload
- Some commands are @dfn{autoloaded}: when you run them, Emacs
+ Some commands are @dfn{autoloaded}; when you run them, Emacs
automatically loads the associated library first. For instance, the
@kbd{M-x compile} command (@pxref{Compilation}) is autoloaded; if you
call it, Emacs automatically loads the @code{compile} library first.
In contrast, the command @kbd{M-x recompile} is not autoloaded, so it
is unavailable until you load the @code{compile} library.
+@vindex help-enable-auto-load
+ Automatic loading can also occur when you look up the documentation
+of an autoloaded command (@pxref{Name Help}), if the documentation
+refers to other functions and variables in its library (loading the
+library lets Emacs properly set up the hyperlinks in the @file{*Help*}
+buffer). To disable this feature, change the variable
+@code{help-enable-auto-load} to @code{nil}.
+
@vindex load-dangerous-libraries
@cindex Lisp files byte-compiled by XEmacs
By default, Emacs refuses to load compiled Lisp files which were
@section Evaluating Emacs Lisp Expressions
@cindex Emacs Lisp mode
@cindex mode, Emacs Lisp
+@cindex evaluation, Emacs Lisp
@findex emacs-lisp-mode
Emacs Lisp mode is the major mode for editing Emacs Lisp. Its mode
@end table
@ifinfo
-@c This uses ``colon'' instead of a literal `:' because Info cannot
-@c cope with a `:' in a menu
+@c This uses 'colon' instead of a literal ':' because Info cannot
+@c cope with a ':' in a menu.
@kindex M-@key{colon}
@end ifinfo
@ifnotinfo
The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the
Emacs Lisp expression preceding point in the buffer, and displays the
value in the echo area. When the result of an evaluation is an
-integer, you can type @kbd{C-x C-e} a second time to display the value
-of the integer result in additional formats (octal, hexadecimal, and
-character).
+integer, it is displayed together with the value in other formats
+(octal, hexadecimal, and character).
If @kbd{M-:} or @kbd{C-x C-e} is given a prefix argument, it inserts
the value into the current buffer at point, rather than displaying it
-in the echo area. The argument's value does not matter.
+in the echo area. If the prefix argument is zero, any integer output
+is inserted together with its value in other formats (octal,
+hexadecimal, and character). Such a prefix argument also prevents
+abbreviation of the output according to the variables
+@code{eval-expression-print-level} and @code{eval-expression-print-length}
+(see below).
@kindex C-M-x @r{(Emacs Lisp mode)}
@findex eval-defun
@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 options @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 whether evaluation errors invoke the debugger when these
-commands are used; its default is @code{t}.
+before abbreviating them. Supplying a zero prefix argument to
+@code{eval-expression} or @code{eval-last-sexp} causes lists to be
+printed in full. @code{eval-expression-debug-on-error} controls
+whether evaluation errors invoke the debugger when these commands are
+used; its default is @code{t}.
@node Lisp Interaction
@section Lisp Interaction Buffers
At startup, the @file{*scratch*} buffer contains a short message, in
the form of a Lisp comment, that explains what it is for. This
message is controlled by the variable @code{initial-scratch-message},
-which should be either a string, or @code{nil} (which means to
+which should be either a documentation string, or @code{nil} (which means to
suppress the message).
@findex ielm