From: Chong Yidong Date: Fri, 20 Nov 2009 01:52:41 +0000 (+0000) Subject: * sem-user.texi (Semanticdb Search Configuration): Rearrange nodes. X-Git-Tag: emacs-pretest-23.1.90~314 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=bd6f6833522a44610e9075efb97322bdc44765bf;p=emacs.git * sem-user.texi (Semanticdb Search Configuration): Rearrange nodes. (Search Throttle, Semanticdb Roots, Include paths, Idle Scheduler): Numerous copyedits. --- diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index f95f251d08e..cffce1a6996 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,9 @@ +2009-11-20 Chong Yidong + + * sem-user.texi (Semanticdb Search Configuration): Rearrange nodes. + (Search Throttle, Semanticdb Roots, Include paths, Idle Scheduler): + Numerous copyedits. + 2009-11-17 Juanma Barranquero * semantic.texi (Semantic Internals, Glossary): diff --git a/doc/misc/sem-user.texi b/doc/misc/sem-user.texi index dd8f23c2e4f..38bb1d6982e 100644 --- a/doc/misc/sem-user.texi +++ b/doc/misc/sem-user.texi @@ -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