@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
@c Free Software 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
* Executing Lisp:: Various modes for editing Lisp programs,
with different facilities for running
the Lisp programs.
-* Lisp Libraries:: How Lisp programs are loaded into Emacs.
-* Lisp Eval:: Executing a single Lisp expression in Emacs.
-* Lisp Interaction:: Executing Lisp in an Emacs buffer.
+* Libraries: Lisp Libraries. How Lisp programs are loaded into Emacs.
+* Eval: Lisp Eval. Executing a single Lisp expression in Emacs.
+* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
* External Lisp:: Communicating through Emacs with a separate Lisp.
@end menu
@table @kbd
@item M-x compile
Run a compiler asynchronously under Emacs, with error messages going to
-the @samp{*compilation*} buffer.
+the @file{*compilation*} buffer.
@item M-x recompile
Invoke a compiler with the same command as in the last invocation of
@kbd{M-x compile}.
compile}. This reads a shell command line using the minibuffer, and
then executes the command by running a shell as a subprocess (or
@dfn{inferior process}) of Emacs. The output is inserted in a buffer
-named @samp{*compilation*}. The current buffer's default directory is
+named @file{*compilation*}. The current buffer's default directory is
used as the working directory for the execution of the command;
normally, therefore, compilation takes place in this directory.
type @kbd{M-x compile}. A file can also specify a file-local value
for @code{compile-command} (@pxref{File Variables}).
- Starting a compilation displays the @samp{*compilation*} buffer in
+ Starting a compilation displays the @file{*compilation*} buffer in
another window but does not select it. While the compilation is
running, the word @samp{run} is shown in the major mode indicator for
-the @samp{*compilation*} buffer, and the word @samp{Compiling} appears
-in all mode lines. You do not have to keep the @samp{*compilation*}
+the @file{*compilation*} buffer, and the word @samp{Compiling} appears
+in all mode lines. You do not have to keep the @file{*compilation*}
buffer visible while compilation is running; it continues in any case.
When the compilation ends, for whatever reason, the mode line of the
-@samp{*compilation*} buffer changes to say @samp{exit} (followed by
+@file{*compilation*} buffer changes to say @samp{exit} (followed by
the exit code: @samp{[0]} for a normal exit), or @samp{signal} (if a
signal terminated the process).
If you want to watch the compilation transcript as it appears,
-switch to the @samp{*compilation*} buffer and move point to the end of
+switch to the @file{*compilation*} buffer and move point to the end of
the buffer. When point is at the end, new compilation output is
inserted above point, which remains at the end. Otherwise, point
remains fixed while compilation output is added at the end of the
@cindex compilation buffer, keeping point at end
@vindex compilation-scroll-output
If you change the variable @code{compilation-scroll-output} to a
-non-@code{nil} value, the @samp{*compilation*} buffer scrolls
+non-@code{nil} value, the @file{*compilation*} buffer scrolls
automatically to follow the output. If the value is
@code{first-error}, scrolling stops when the first error appears,
leaving point at that error. For any other non-@code{nil} value,
To rerun the last compilation with the same command, type @kbd{M-x
recompile}. This reuses the compilation command from the last
invocation of @kbd{M-x compile}. It also reuses the
-@samp{*compilation*} buffer and starts the compilation in its default
+@file{*compilation*} buffer and starts the compilation in its default
directory, which is the directory in which the previous compilation
was started.
@findex kill-compilation
Starting a new compilation also kills any compilation already
-running in @samp{*compilation*}, as the buffer can only handle one
+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
kill-compilation}.
To run two compilations at once, start the first one, then rename
-the @samp{*compilation*} buffer (perhaps using @code{rename-uniquely};
+the @file{*compilation*} buffer (perhaps using @code{rename-uniquely};
@pxref{Misc Buffer}), then switch buffers and start the other
-compilation. This will create a new @samp{*compilation*} buffer.
+compilation. This will create a new @file{*compilation*} buffer.
@vindex compilation-environment
You can control the environment passed to the compilation command
@cindex Compilation mode
@cindex mode, Compilation
@cindex locus
- The @samp{*compilation*} buffer uses a major mode called Compilation
+ The @file{*compilation*} buffer uses a major mode called Compilation
mode. Compilation mode turns each error message in the buffer into a
hyperlink; you can move point to it and type @key{RET}, or click on it
with the mouse (@pxref{Mouse References}), to visit the @dfn{locus} of
If you change the variable
@code{compilation-auto-jump-to-first-error} to a non-@code{nil} value,
Emacs automatically visits the locus of the first error message that
-appears in the @samp{*compilation*} buffer.
+appears in the @file{*compilation*} buffer.
Compilation mode provides the following additional commands. These
-commands can also be used in @samp{*grep*} buffers, where the
+commands can also be used in @file{*grep*} buffers, where the
hyperlinks are search matches rather than error messages (@pxref{Grep
Searching}).
visits the locus of the first error message. Each subsequent
@w{@kbd{C-x `}} visits the next error, in a similar fashion. If you
visit a specific error with @key{RET} or a mouse click in the
-@samp{*compilation*} buffer, subsequent @w{@kbd{C-x `}} commands
+@file{*compilation*} buffer, subsequent @w{@kbd{C-x `}} commands
advance from there. When @w{@kbd{C-x `}} finds no more error messages
to visit, it signals an error. @w{@kbd{C-u C-x `}} starts again from
the beginning of the compilation buffer, and visits the first locus.
through errors in the opposite direction.
The @code{next-error} and @code{previous-error} commands don't just
-act on the errors or matches listed in @samp{*compilation*} and
-@samp{*grep*} buffers; they also know how to iterate through error or
+act on the errors or matches listed in @file{*compilation*} and
+@file{*grep*} buffers; they also know how to iterate through error or
match lists produced by other commands, such as @kbd{M-x occur}
(@pxref{Other Repeating Search}). If you are already in a buffer
containing error messages or matches, those are the ones that are
is determined by the variable @code{next-error-highlight}.
@vindex compilation-context-lines
- If the @samp{*compilation*} buffer is shown in a window with a left
+ 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
command, but specifies the option for a noninteractive shell. This
means, in particular, that the shell should start with no prompt. If
you find your usual shell prompt making an unsightly appearance in the
-@samp{*compilation*} buffer, it means you have made a mistake in your
+@file{*compilation*} buffer, it means you have made a mistake in your
shell's init file by setting the prompt unconditionally. (This init
file may be named @file{.bashrc}, @file{.profile}, @file{.cshrc},
@file{.shrc}, etc., depending on what shell you use.) The shell init
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}).
@item M-x grep
@itemx M-x lgrep
Run @command{grep} asynchronously under Emacs, listing matching lines in
-the buffer named @samp{*grep*}.
+the buffer named @file{*grep*}.
@item M-x grep-find
@itemx M-x find-grep
@itemx M-x rgrep
Run @command{grep} via @code{find}, and collect output in the
-@samp{*grep*} buffer.
+@file{*grep*} buffer.
@item M-x zrgrep
-Run @code{zgrep} and collect output in the @samp{*grep*} buffer.
+Run @code{zgrep} and collect output in the @file{*grep*} buffer.
@item M-x kill-grep
Kill the running @command{grep} subprocess.
@end table
grep -nH -e foo *.el | grep bar | grep toto
@end example
- The output from @command{grep} goes in the @samp{*grep*} buffer. You
+ The output from @command{grep} goes in the @file{*grep*} buffer. You
can find the corresponding lines in the original files using @w{@kbd{C-x
`}}, @key{RET}, and so forth, just like compilation errors.
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}.
+Use the command @kbd{M-x flymake-display-err-menu-for-current-line}
+to display any error messages associated with the current line.
For more details about using Flymake,
@ifnottex
* Commands of GUD:: Key bindings for common commands.
* GUD Customization:: Defining your own commands for GUD.
* GDB Graphical Interface:: An enhanced mode that uses GDB features to
- implement a graphical debugging environment through
- Emacs.
+ implement a graphical debugging environment.
@end menu
@node Starting GUD
@kbd{M-x gud-gdb} and other commands listed in
@iftex
the preceding section.
-@end iftext
+@end iftex
@ifnottex
@ref{Starting GUD}.
@end ifnottex
commands to repeat them.
@iftex
See the next section
-@end iftext
+@end iftex
@ifnottex
@xref{Commands of GUD},
@end 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.
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.)
@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
@section Lisp Interaction Buffers
@findex lisp-interaction-mode
- When Emacs starts up, it contains a buffer named @samp{*scratch*},
+ When Emacs starts up, it contains a buffer named @file{*scratch*},
which is provided for evaluating Emacs Lisp expressions interactively.
Its major mode is Lisp Interaction mode. You can also enable Lisp
Interaction mode by typing @kbd{M-x lisp-interaction-mode}.
@findex eval-print-last-sexp
@kindex C-j @r{(Lisp Interaction mode)}
- In the @samp{*scratch*} buffer, and other Lisp Interaction mode
+ In the @file{*scratch*} buffer, and other Lisp Interaction mode
buffers, @kbd{C-j} (@code{eval-print-last-sexp}) evaluates the Lisp
expression before point, and inserts the value at point. Thus, as you
type expressions into the buffer followed by @kbd{C-j} after each
mode are the same as in Emacs Lisp mode.
@vindex initial-scratch-message
- At startup, the @samp{*scratch*} buffer contains a short message, in
+ 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
interactively is to use Inferior Emacs Lisp mode, which provides an
interface rather like Shell mode (@pxref{Shell Mode}) for evaluating
Emacs Lisp expressions. Type @kbd{M-x ielm} to create an
-@samp{*ielm*} buffer which uses this mode. For more information, see
+@file{*ielm*} buffer which uses this mode. For more information, see
that command's documentation.
@node External Lisp
evaluated. To begin an external Lisp session, type @kbd{M-x
run-lisp}. This runs the program named @command{lisp}, and sets it up
so that both input and output go through an Emacs buffer named
-@samp{*inferior-lisp*}. To change the name of the Lisp program run by
+@file{*inferior-lisp*}. To change the name of the Lisp program run by
@kbd{M-x run-lisp}, change the variable @code{inferior-lisp-program}.
- The major mode for the @samp{*lisp*} buffer is Inferior Lisp mode,
+ The major mode for the @file{*lisp*} buffer is Inferior Lisp mode,
which combines the characteristics of Lisp mode and Shell mode
(@pxref{Shell Mode}). To send input to the Lisp session, go to the
-end of the @samp{*lisp*} buffer and type the input, followed by
+end of the @file{*lisp*} buffer and type the input, followed by
@key{RET}. Terminal output from the Lisp session is automatically
inserted in the buffer.
buffer to a Lisp session that you had started with @kbd{M-x run-lisp}.
The expression sent is the top-level Lisp expression at or following
point. The resulting value goes as usual into the
-@samp{*inferior-lisp*} buffer. Note that the effect of @kbd{C-M-x} in
+@file{*inferior-lisp*} buffer. Note that the effect of @kbd{C-M-x} in
Lisp mode is thus very similar to its effect in Emacs Lisp mode
(@pxref{Lisp Eval}), except that the expression is sent to a different
Lisp environment instead of being evaluated in Emacs.
edited in Scheme mode, which can be explicitly enabled with @kbd{M-x
scheme-mode}. You can initiate a Scheme session by typing @kbd{M-x
run-scheme} (the buffer for interacting with Scheme is named
-@samp{*scheme*}), and send expressions to it by typing @kbd{C-M-x}.
+@file{*scheme*}), and send expressions to it by typing @kbd{C-M-x}.
HCoop / bpt / emacs.git / blobdiff