Commit bd6f6833 authored by Chong Yidong's avatar Chong Yidong
Browse files

* sem-user.texi (Semanticdb Search Configuration): Rearrange nodes.

(Search Throttle, Semanticdb Roots, Include paths, Idle Scheduler):
Numerous copyedits.
parent 725bff06
2009-11-20 Chong Yidong <cyd@stupidchicken.com>
* sem-user.texi (Semanticdb Search Configuration): Rearrange nodes.
(Search Throttle, Semanticdb Roots, Include paths, Idle Scheduler):
Numerous copyedits.
2009-11-17 Juanma Barranquero <lekktu@gmail.com>
* semantic.texi (Semantic Internals, Glossary):
......
......@@ -202,7 +202,6 @@ described in the following subsections.
* Semanticdb Tag Storage::
* Semanticdb Search Configuration::
* Changing Backends::
* Script Generated Cache Files::
* Create System Databases::
@end menu
......@@ -277,59 +276,105 @@ written.
@subsection Semanticdb Search Configuration
When another part of @semantic{} (or another Emacs package using
@semantic{}) searches for a tag within SemanticDB, the SemanticDB
library may perform a search in the locations of the database:
@enumerate
@item
The entries defined by the current file.
@item
The entries defined by the @dfn{include files} of the current file.
@item
The entries defined by the include files included from the include
files (and so on, recursively).
@end enumerate
In C and C++, for instance, include files are defined with the
@samp{#include} preprocessor directive (SemanticDB tries to
distinguish between project and system headers, based on the @code{""}
and @code{<>} filename delimiters). Include directives are matched to
filenames in the SemanticDB cache using the following criteria:
@enumerate
@item
Whether the file is in the same directory as the current file
@item
Whether the file is in the same project, as defined by EDE
(@pxref{Top,,,ede,EDE manual}) or the @code{semanticdb-project-roots}
variable (@pxref{Semanticdb Roots}).
@item
Whether the file is in the @dfn{system include path} (@pxref{Include
paths}).
@end enumerate
@semantic{}) queries the SemanticDB library for a source code tag, the
search need not be limited to tags defined within the current file.
It can include tags defined elsewhere, such as @dfn{header files}
referenced by the current file (e.g., via the C/C++ @code{#include}
directive). While performing the search, the SemanticDB library may
even automatically visit other files and parse them, if necessary.
The variable @code{semanticdb-find-default-throttle} determines how
aggressively SemanticDB searches for source code tags. @xref{Search
Throttle}.
The details of SemanticDB searches can vary from language to
language. In C/C++ code, for example, SemanticDB distinguishes
between @dfn{project header files} and @dfn{system header files},
based on whether the @code{#include} directive uses the @code{""} or
@code{<>} filename delimiter. SemanticDB looks for system header in
the @dfn{system include path} (@pxref{Include paths}).
@menu
* Search Throttle:: Controlling how semanticdb searches occur
* Semanticdb Roots:: Specifying the root of different projects
* Include paths:: Add/Remove directories to include search paths
* Search Throttle:: Controlling how semanticdb searches occur
* Semanticdb search debugging commands::
@end menu
@node Search Throttle
@subsubsection SemanticDB Search Throttle
The SemanticDB @dfn{search throttle} determines how aggressive
SemanticDB searches are. It is controlled by the variable
@code{semanticdb-find-default-throttle}. The default value of this
variable aims for maximum accuracy, at the expense of search time.
Other parts of the @semantic{} package, particularly the different
language parsers, may change the value of
@code{semanticdb-find-default-throttle}. You can override its value,
for a given major mode, like this:
@example
(setq-mode-local c-mode
semanticdb-find-default-throttle
'(project unloaded system recursive))
@end example
@anchor{semanticdb-find-default-throttle}
@defvar semanticdb-find-default-throttle
The default throttle for @code{semanticdb-find} routines.
The throttle controls how detailed the list of database
tables is for a symbol lookup. The value is a list with
the following keys:
@table @code
@item file
The file the search is being performed from. This option is here for
completeness only, and is assumed to always be on.
@item local
Tables from the same local directory are included. This includes
files directly referenced by a file name which might be in a different
directory.
@item project
Tables from the same local project are included If @code{project} is
specified, then @code{local} is assumed.
@item unloaded
If a table is not in memory, load it. If it is not cached on disk
either, get the source, parse it, and create the table.
@item system
Tables from system databases. These are specifically tables
from system header files, or language equivalent.
@item recursive
For include based searches, includes tables referenced by included
files.
@item omniscience
Included system databases which are omniscience, or somehow know
everything. Omniscience databases are found in
@code{semanticdb-project-system-databases}. The Emacs Lisp system
@var{db} is an omniscience database.
@end table
@end defvar
@node Semanticdb Roots
@subsubsection SemanticDB project roots
Project roots are the ``top-level'' directories for a single code
project. With the exception of system directories, SemanticDB
searches are usually limited to the current single code project.
Therefore, it is helpful to specify the project root if you want
@semantic{} tag searches to work correctly.
The @code{project} setting in the SemanticDB search throttle
(@pxref{Search Throttle}) tells SemanticDB to search within the
current single code project. For @semantic{}'s point of view,
@dfn{projects} are determined by their top-level directories, or
@dfn{project roots}; every subdirectory of a project root is
considered part of the same project.
If you use EDE for project management, it will set the project roots
automatically. @xref{Top,,,ede,EDE manual}. You can also specify
them yourself.
@anchor{semanticdb-project-roots}
@deffn Option semanticdb-project-roots
The value of this variable is a list of directories (strings) that are
project root. All subdirectories of a project root are considered
part of the same project. This variable can be overriden by project
management programs via @code{semanticdb-project-root-functions}.
project roots. All subdirectories of a project root are considered
part of the same project. This variable can be overriden by
@code{semanticdb-project-root-functions}.
@end deffn
@anchor{semanticdb-project-root-functions}
......@@ -343,30 +388,27 @@ non-@code{nil} return value, if any, is taken to be the project root,
overriding @code{semanticdb-project-roots}.
@end defvar
If you use EDE for project management, it will set
@code{semanticdb-project-root-functions} automatically.
@xref{Top,,,ede,EDE manual}.
@node Include paths
@subsubsection Include Paths
System include paths are standard locations to find source code tags,
such as the @dfn{header files} in @file{/usr/include} and its
subdirectories on Unix-like operating systems. You can add and remove
system include paths using the following commands:
subdirectories on Unix-like operating systems.
You can add and remove system include paths using the following
commands:
@anchor{semantic-add-system-include}
@deffn Command semantic-add-system-include dir &optional mode
This command prompts for a directory, @var{dir}, and adds it as a
system include path for the current major mode. When called
non-interactively, the major mode can be specified with the @var{mode}
argument.
Prompts for a directory, @var{dir}, and add it as a system include
path for the current major mode. When called non-interactively, the
major mode can be specified with the @var{mode} argument.
@end deffn
@anchor{semantic-remove-system-include}
@deffn Command semantic-remove-system-include dir &optional mode
This command prompt for a directory, @var{dir}, and removes it from
the system include path for the current major mode (or @var{mode}).
Prompt for a directory, @var{dir}, and remove it from the system
include path for the current major mode (or @var{mode}).
@end deffn
@anchor{semantic-customize-system-include-path}
......@@ -384,80 +426,17 @@ any symbols that exist for all files for that mode are included.
@c @xref{Search Optimization}, for more information on include paths.
@node Search Throttle
@subsubsection SemanticDB Search Throttle
The SemanticDB search throttle is a variable that may be configured by
a language support author. If you need to customize this for
yourself, you may need to override the mode values in a mode support
hook.
@defvar semanticdb-find-default-throttle
@anchor{semanticdb-find-default-throttle}
The default throttle for @code{semanticdb-find} routines.
The throttle controls how detailed the list of database
tables is for a symbol lookup. The value is a list with
the following keys:
@table @code
@item file
The file the search is being performed from. This option is here for
completeness only, and is assumed to always be on.
@item local
Tables from the same local directory are included. This includes
files directly referenced by a file name which might be in a different
directory.
@item project
Tables from the same local project are included If @code{project} is
specified, then @code{local} is assumed.
@item unloaded
If a table is not in memory, load it. If it is not cached on disk
either, get the source, parse it, and create the table.
@item system
Tables from system databases. These are specifically tables
from system header files, or language equivalent.
@item recursive
For include based searches, includes tables referenced by included
files.
@item omniscience
Included system databases which are omniscience, or somehow know
everything. Omniscience databases are found in
@code{semanticdb-project-system-databases}. The Emacs Lisp system
@var{db} is an omniscience database.
@end table
@end defvar
To set the throttle, use a command like this:
@example
(setq-mode-local c-mode
semanticdb-find-default-throttle
'(project unloaded system recursive))
@end example
The default value of the throttle is for maximum accuracy at the
expense of time taken to perform a particular look-up. The throttle
is tweaked by @code{semantic-idle-summary-mode} to remove 'unloaded,
thus removing poor speed at unexpected times.
@node Semanticdb search debugging commands
@subsubsection Semanticdb search debugging commands
You can use @kbd{M-x semanticdb-dump-all-table-summary RET} to see the
list of databases that will be searched from a given buffer. It
should include DBs for the directories you expect. You can follow up
with @kbd{M-x semanticdb-find-test-translate-path RET} to then make
sure specific tables from the path are discovered correctly.
You can use @kbd{M-x semanticdb-dump-all-table-summary} to see the
list of databases that will be searched from a given buffer. You can
follow up with @kbd{M-x semanticdb-find-test-translate-path} to then
make sure specific tables from the path are discovered correctly.
Alternately, you can get a list of include files @semantic{}
encountered, but could not find on disk using
@kbd{M-x semanticdb-find-adebug-lost-includes RET}.
Once you have used the below functions to debug the problem, you may
need to reconfigure how @semantic{} finds include files.
See @ref{Semanticdb Search Configuration}. If the search config is
ok, you may need to configure the search throttle. See @ref{Search Throttle}.
encountered, but could not find on disk using @kbd{M-x
semanticdb-find-adebug-lost-includes}.
@deffn Command semanticdb-dump-all-table-summary
@anchor{semanticdb-dump-all-table-summary}
......@@ -495,27 +474,13 @@ The default is to save databases in flat files. Alternatively, you
could write a new database backend that stores tags into a database,
or other storage system.
@defvar semanticdb-new-database-class
@anchor{semanticdb-new-database-class}
The default type of database created for new files.
This can be changed on a per file basis, so that some directories
are saved using one mechanism, and some directories via a different
mechanism.
@defvar semanticdb-new-database-class
The default type of database created for new files. This can be
changed on a per file basis, so that some directories are saved using
one mechanism, and some directories via a different mechanism.
@end defvar
@node Script Generated Cache Files
@subsection Script Generated Cache Files
You can create new semantic databases with the @file{semanticdb.sh}
script file. Give this script the directory you want parsed, and it
will create a cache file for you.
@example
$ semanticdb.sh *.el
@end example
To use these generated tables, you would likely need to restart Emacs.
@node Create System Databases
@subsection Create System Databases
......@@ -531,99 +496,86 @@ The database file is stored in ~/.semanticdb, or whichever directory
is specified by @code{semanticdb-default-system-save-directory}.
@end deffn
@node Idle Scheduler
@section Idle Scheduler
@cindex Idle Scheduler
The Idle Scheduler in @semantic{} performs multiple duties.
The @dfn{Semantic idle scheduler} is a part of @semantic{} that
performs various operations while Emacs is waiting for user input
(idle time). Its primary job is to perform buffer parsing, but it is
also used for other purposes, such as displaying information about
tags.
The primary job is to schedule buffer parsing in idle time. The
first buffer whose cache is checked is the current buffer. After
this, all other buffers are checked.
Once that has been accomplished, scheduled idle processes that use the
semantic tag tables are run.
@deffn Command global-semantic-idle-scheduler-mode &optional arg
@anchor{global-semantic-idle-scheduler-mode}
Toggle global use of option @dfn{semantic-idle-scheduler-mode}.
The idle scheduler with automatically reparse buffers in idle time,
and then schedule other jobs setup with @dfn{semantic-idle-scheduler-add}.
If @var{ARG} is positive, enable, if it is negative, disable.
If @var{ARG} is @code{nil}, then toggle.
@obsolete{global-semantic-auto-parse-mode,global-semantic-idle-scheduler-mode}
@deffn Command global-semantic-idle-scheduler-mode &optional arg
This command toggles Semantic Idle Scheduler mode in every
@semantic{}-enabled buffer. This minor mode ensures that the buffer
is automatically reparsed whenever Emacs is idle. If there is
additional idle time, it runs jobs scheduled by other parts of
@semantic{}, such as Semantic Idle Summary mode (@pxref{Idle Summary
Mode}) and Semantic Idle Completions mode (@pxref{Idle Completions
Mode}).
@end deffn
@obsolete{semantic-auto-parse-mode, semantic-idle-scheduler-mode}
@deffn Option semantic-idle-scheduler-idle-time
@anchor{semantic-idle-scheduler-idle-time}
Time in seconds of idle before scheduling events.
This time should be short enough to ensure that idle-scheduler will be
run as soon as Emacs is idle.
@end deffn
@deffn Option semantic-idle-scheduler-mode-hook
@anchor{semantic-idle-scheduler-mode-hook}
Hook run at the end of function @dfn{semantic-idle-scheduler-mode}.
@deffn Option semantic-idle-scheduler-idle-time
The value of this variable is the amount of idle time, in seconds,
before the Semantic idle scheduler activates. The default is 1.
@end deffn
@deffn Option semantic-idle-scheduler-verbose-flag
@anchor{semantic-idle-scheduler-verbose-flag}
Non-@code{nil} means that the idle scheduler should provide debug messages.
Use this setting to debug idle activities.
@deffn Option semantic-idle-scheduler-verbose-flag
If this variable is non-@code{nil}, the idle scheduler prints verbose
messages while running, which are useful for debugging.
@end deffn
You can add new functionality to the idle scheduler by reading the
Application Developers Guide
@inforef{Idle Scheduling, , semantic-appdev.info}.
@menu
* Reparsing Options:: Reparsing the current buffer in idle time
* Idle Working Options:: Options for extra work done at idle time
* Debugging Idle Time Issues:: How to produce good bug reports
* Idle Summary Mode:: Display prototype of symbol under cursor
* Idle Completions Mode:: Smart completion pop-up help
* Reparsing Options:: Reparsing the current buffer in idle time
* Idle Working Options:: Options for extra work done at idle time
* Debugging Idle Time Issues:: How to produce good bug reports
* Idle Summary Mode:: Display prototype of symbol under cursor
* Idle Completions Mode:: Smart completion pop-up help
@end menu
@node Reparsing Options
@subsection Reparsing Options
The Idle Scheduler will automatically reparse all buffers that need
it. User input at any time will cancel the operations and return to
normal editing.
When activated during idle time, the Semantic idle scheduler
automatically reparses all buffers that need it. Any arriving user
input cancels this, returning Emacs to its normal editing behavior.
@deffn Option semantic-idle-scheduler-max-buffer-size
@anchor{semantic-idle-scheduler-max-buffer-size}
Maximum size in bytes of buffers automatically reparsed.
If this value is less than or equal to @var{0}, buffers are automatically
@deffn Option semantic-idle-scheduler-max-buffer-size
Maximum size in bytes of buffers automatically reparsed. If this
value is less than or equal to @var{0}, buffers are automatically
reparsed regardless of their size.
@end deffn
@deffn Option semantic-idle-scheduler-no-working-message
@anchor{semantic-idle-scheduler-no-working-message}
If non-@code{nil}, disable display of working messages during parse.
@deffn Option semantic-idle-scheduler-no-working-message
If non-@code{nil}, disable display of working messages whie reparsing.
@end deffn
@deffn Option semantic-idle-scheduler-working-in-modeline-flag
@anchor{semantic-idle-scheduler-working-in-modeline-flag}
Non-@code{nil} means show working messages in the mode line.
Typically, parsing will show messages in the minibuffer.
This will move the parse message into the modeline.
@deffn Option semantic-idle-scheduler-working-in-modeline-flag
If non-@code{nil}, show working messages in the mode line. Normally,
re-parsing shows messages in the minibuffer; this moves the parse
message to the modeline instead.
@end deffn
@defvar semantic-before-idle-scheduler-reparse-hooks
@anchor{semantic-before-idle-scheduler-reparse-hooks}
Hooks run before option @code{semantic-idle-scheduler} begins parsing.
If any hook throws an error, this variable is reset to nil.
This hook is not protected from lexical errors.
@anchor{semantic-before-idle-scheduler-reparse-hook}
@defvar semantic-before-idle-scheduler-reparse-hook
This normal hook is run just before the idle scheduler begins
reparsing. If any hook function throws an error, the value of this
variable is reset to @code{nil}. This hook is not protected from
lexical errors.
@end defvar
@defvar semantic-after-idle-scheduler-reparse-hooks
@anchor{semantic-after-idle-scheduler-reparse-hooks}
Hooks run after option @code{semantic-idle-scheduler} has parsed.
If any hook throws an error, this variable is reset to nil.
@anchor{semantic-after-idle-scheduler-reparse-hook}
@defvar semantic-after-idle-scheduler-reparse-hook
This normal hook is run after the idle scheduler finishes reparsing.
If any hook throws an error, this variable is reset to @code{nil}.
This hook is not protected from lexical errors.
@end defvar
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment