@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, 2010, 2011
+@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Building, Maintaining, Programs, Top
@chapter Compiling and Testing Programs
for use in the compilation buffer.
* Grep Searching:: Searching with grep.
* Flymake:: Finding syntax errors on the fly.
-* Debuggers:: Running symbolic debuggers for non-Lisp programs.
+* Debuggers:: Running symbolic debuggers for non-Lisp programs.
* Executing Lisp:: Various modes for editing Lisp programs,
with different facilities for running
the Lisp programs.
* Libraries: Lisp Libraries. Creating Lisp programs to run in 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.
+* External Lisp:: Communicating through Emacs with a separate Lisp.
@end menu
@node Compilation
@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
@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
You can also kill the compilation process with @kbd{M-x
kill-compilation}.
- If you want to run two compilations at once, you should start the
-first one, then rename the @samp{*compilation*} buffer (perhaps using
-@code{rename-uniquely}; @pxref{Misc Buffer}), and start the other
-compilation. That will create a new @samp{*compilation*} buffer.
+ To run two compilations at once, start the first one, then rename
+the @samp{*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.
Emacs does not expect a compiler process to launch asynchronous
subprocesses; if it does, and they keep running after the main
@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
@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
@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
@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}.
@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.
-* Debugger Operation:: Connection between the debugger and source buffers.
-* Commands of GUD:: Key bindings for common commands.
-* GUD Customization:: Defining your own commands for GUD.
+* Starting GUD:: How to start a debugger subprocess.
+* Debugger Operation:: Connection between the debugger and source buffers.
+* 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.
@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
@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
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
@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. 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.
+* GDB User Interface 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.
+* Threads Buffer:: Displays your threads.
* Stack Buffer:: Select a frame from the call stack.
-* Other GDB-UI Buffers:: Input/output, locals, registers,
+* Other GDB Buffers:: Input/output, locals, registers,
assembler, threads and memory buffers.
* Watch Expressions:: Monitor variable values in the speedbar.
+* Multithreaded Debugging:: Debugging programs with several threads.
@end menu
-@node GDB-UI Layout
+@node GDB User Interface Layout
@subsubsection GDB User Interface Layout
@cindex GDB User Interface layout
|--------------------------------+--------------------------------+
| Primary Source buffer | I/O buffer for debugged pgm |
|--------------------------------+--------------------------------+
-| Stack buffer | Breakpoints/thread buffer |
+| Stack buffer | Breakpoints/Threads buffer |
+--------------------------------+--------------------------------+
@end group
@end smallexample
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}
+want with the @samp{GUD->GDB-Windows} and @samp{GUD->GDB-Frames}
sub-menus. If the menu-bar is unavailable, type @code{M-x
gdb-display-@var{buffertype}-buffer} or @code{M-x
gdb-frame-@var{buffertype}-buffer} respectively, where
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.
+other click with @kbd{Mouse-1} on the relevant button in the header
+line. 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
selecting a stack frame updates it to display the local variables of the
new frame.
-@node Other GDB-UI Buffers
+@node Other GDB Buffers
@subsubsection Other Buffers
@table @asis
@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,
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}).
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.
+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
+@kbd{Mouse-1} on the relevant button in the header line.
@node Watch Expressions
@subsubsection Watch Expressions
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
non-@code{nil}. This can be useful if you are debugging with a full
screen Emacs frame.
+@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.
+
+@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
+
+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
because people often leave unfinished edits the source file, and don't
recompile it until they think it is ready to use.
- Because the argument to @code{load-library} is usually not in itself
-a valid file name, file name completion is not available. Indeed, when
-using this command, you usually do not know exactly what file name
-will be used.
-
@vindex load-path
- The sequence of directories searched by @kbd{M-x load-library} is
-specified by the variable @code{load-path}, a list of strings that are
-directory names. The default value of the list contains the directories where
+ The variable @code{load-path} specifies the sequence of directories
+searched by @kbd{M-x load-library}. Its value should be a list of
+strings that are directory names; in addition, @code{nil} in this list
+stands for the current default directory. (Generally, it is not a
+good idea to put @code{nil} in the list; if you find yourself wishing
+that @code{nil} were in the list, most likely what you really want is
+to do @kbd{M-x load-file} this once.)
+
+ The default value of @code{load-path} is a list of directories where
the Lisp code for Emacs itself is stored. If you have libraries of
-your own, put them in a single directory and add that directory
-to @code{load-path}. @code{nil} in this list stands for the current default
-directory, but it is probably not a good idea to put @code{nil} in the
-list. If you find yourself wishing that @code{nil} were in the list,
-most likely what you really want to do is use @kbd{M-x load-file}
-this once.
+your own, put them in a single directory and add that directory to
+@code{load-path}, by adding a line like this to your init file
+(@pxref{Init File}):
+
+@example
+(add-to-list 'load-path "/path/to/lisp/libraries")
+@end example
@cindex autoload
- Often you do not have to give any command to load a library, because
-the commands defined in the library are set up to @dfn{autoload} that
-library. Trying to run any of those commands calls @code{load} to load
-the library; this replaces the autoload definitions with the real ones
-from the library.
+ Some commands are @dfn{autoloaded}: when you run them, Emacs will
+automatically load the associated library first. For instance, the
+@code{compile} and @code{compilation-mode} commands
+(@pxref{Compilation}) are autoloaded; if you call either command,
+Emacs automatically loads the @code{compile} library. In contrast,
+the command @code{recompile} is not autoloaded, so it is unavailable
+until you load the @code{compile} library.
@vindex load-dangerous-libraries
@cindex Lisp files byte-compiled by XEmacs
@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.
-
- 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}.
+ 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.
+
+@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.
+
+@vindex initial-scratch-message
+ At startup, the @samp{*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}. If you set it to the
+empty string, or @code{nil}, the initial message is suppressed.
@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
HCoop / bpt / emacs.git / blobdiff