This is the Semantic User's Manual

Copyright © 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Eric M. Ludlam Copyright © 2001, 2002, 2003, 2004 David Ponce Copyright © 2002, 2003 Richard Y. Kim

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being list their titles, with the Front-Cover Texts being list, and with the Back-Cover Texts being list.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

This is the Semantic User's Guide Infrastructure for parser based text analysis in Emacs

Copyright © 1999, 2000, 2001, 2002, 2003, 2004 Eric M. Ludlam, David Ponce, and Richard Y. Kim

     [file semanticheader.texi not included]

Semantic User's Guide
*********************

This chapter describes how to use applications enabled by semantic. Many of these come with semantic, but others are distributed apart from semantic.

speedbar
********

Speedbar supports the display of tags through the Semantic parser.  To use this utility, add a line like this to your .emacs file:

     (add-hook 'speedbar-load-hook (lambda () (require 'semantic-sb)))

or you can simply add:

     (require 'semantic-sb)

Once installed, speedbar will use semantic to find tags, and will display them appropriately.  Tags from semantic will have additional details which can be seen, such as return type, or arguments to functions.

If you use semantic-load.el, you do not need to add the above lines in your .emacs file.

Two additional speedbar modes are described in Speedbar Analysis, and Class Browser.

ECB
***

From the ECB Website: http://ecb.sourceforge.net:

     ECB is a source code browser for Emacs. It is a global minor-mode
     which displays a couple of windows that can be used to browse
     directories, files and file-contents like methods and variables.

imenu
*****

There is special support for creating Imenu entries using semantic. This is a highly customizable tool which can create specialized menu systems for navigating your source file.

By default, each language that wants special imenu support will set itself up for it.  To setup imenu for your buffers, use this command in your .emacs file:

     (add-hook 'semantic-init-hooks (lambda ()
                                    	   (imenu-add-to-menubar "TAGS")))

Also supported is which-func-mode.  This usually uses imenu tags to show the current function.  The semantic support for this function uses overlays, which is much faster.

If you use semantic-load.el, you do not need to add the above lines in your .emacs file.

You can customize imenu with the following options:

 -- Option: semantic-imenu-summary-function
     Function to use when creating items in Imenu. Some useful functions are found in semantic-format-tag-functions.

 -- Option: semantic-imenu-bucketize-file
     Non-nil if tags in a file are to be grouped into buckets.

 -- Option: semantic-imenu-buckets-to-submenu
     Non-nil if buckets of tags are to be turned into submenus. This option is ignored if semantic-imenu-bucketize-file is nil.

 -- Option: semantic-imenu-expand-type-members
     Non-nil if types should have submenus with members in them.

 -- Option: semantic-imenu-bucketize-type-members
     Non-nil if members of a type should be grouped into buckets. nil means to keep them in the same order. Overriden to nil if semantic-imenu-bucketize-file is nil.

 -- Option: semantic-imenu-sort-bucket-function
     Function to use when sorting tags in the buckets of functions. See semantic-bucketize and the FILTER argument for more details on this function.

 -- Option: semantic-imenu-index-directory
     Non nil to index the entire directory for tags. Doesn't actually parse the entire directory, but displays tags for all files currently listed in the current Semantic database. This variable has no meaning if semanticdb is not active.

 -- Option: semantic-imenu-auto-rebuild-directory-indexes
     If non-nil automatically rebuild directory index imenus. That is when a directory index imenu is updated, automatically rebuild other buffer local ones based on the same semanticdb.

When adding support to a language, this variable may need to be set:

 -- Variable: semantic-imenu-expandable-tag-classes
     List of expandable tag classes. Tags of those classes will be given submenu with children. By default, a type has interesting children.  In Texinfo, however, a section has interesting children.

senator
*******

Senator stands for SEmantic NAvigaTOR and was written by David Ponce.

This library defines commands and a minor mode to navigate and manage semantic language tags in the current buffer.

Commands
========

The following user level commands are provided by Senator.

Navigation
----------

 -- Function: senator-next-tag
     Navigate to the next Semantic tag. Return the tag or nil if at end of buffer.

 -- Function: senator-previous-tag
     Navigate to the previous Semantic tag. Return the tag or nil if at beginning of buffer.

 -- Function: senator-jump
     Jump to the semantic symbol SYM.

     If optional IN-CONTEXT is non-nil jump in the local type's context (see function senator-current-type-context).  If optional NO-DEFAULT is non-nil do not provide a default value.

     When called interactively you can combine the IN-CONTEXT and NO-DEFAULT switches like this:

     - C-u       IN-CONTEXT.
     - C-u -     NO-DEFAULT.
     - C-u C-u   IN-CONTEXT + NO-DEFAULT.

Searching
---------

Searching using senator mode restricts the search only to the definition text, such as the name of the functions or variables in a given buffer.

 -- Command: senator-isearch-toggle-semantic-mode
     Toggle semantic searching on or off in isearch mode. C-c , i toggle semantic searching.

 -- Command: senator-search-forward what &optional bound noerror count
 -- Command: senator-search-backward what &optional bound noerror count
     Search semantic tags forward or backward from point for string WHAT. Set point to the end of the occurrence found, and return point.  See search-forward for details and the meaning of BOUND NOERROR and COUNT.  COUNT is just ignored in the current implementation.

 -- Command: re-search-forward regex
 -- Command: re-search-backward regex
     Search forward and backward for a token matching the regular expression REGEX.

 -- Command: word-search-forward word
 -- Command: word-search-backward word
     Search forward and backward for a token whose name matches WORD.

Completion
----------

Completion in senator scans all known definitions in the local file, and uses that information to provide the completion.

 -- Command: senator-complete-symbol &optional cycle-once
     Complete the current symbol under point. If optional argument CYCLE-ONCE is non-nil, only cycle through the list of completions once, doing nothing where there are no more matches.

 -- Command: senator-completion-menu-popup
     Popup a completion menu for the symbol at point. The popup menu displays all of the possible completions for the symbol it was invoked on.  To automatically split large menus this function use imenu--mouse-menu to handle the popup menu.

Copy/Paste
----------

Token Copy/Paste is a high level form of the typical copy yank used by Emacs.  Copying a tag saves the meta-information related to the function or item the cursor is currently in.  When that information is yanked into a new buffer, the form of the text created is based on the current status of the programming buffer.

For example, pasting a function into a different file results in a function call template to be inserted.  In a Texinfo file, a @deffn is created with documentation for that function or command.

 -- Command: senator-copy-tag
     Take the current tag, and place it in the tag ring.

 -- Command: senator-kill-tag
     Take the current tag, place it in the tag ring, and kill it. Killing the tag removes the text for that tag, and places it into the kill ring.  Retrieve that text with C-y.

 -- Command: senator-yank-tag
     Yank a tag from the tag ring. The form the tag takes is differnet depending on where it is being yanked to.

 -- Command: senator-copy-tag-to-register register &optional kill-flag
     Copy the current tag into REGISTER. Optional argument KILL-FLAG will delete the text of the tag to the kill ring.

For programmers, to provide specialized pasting, created an override function for insert-foreign-tag (see Writing Parsers (semantic-langdev).)

Minor Mode
----------

 -- Command: senator-minor-mode
     Toggle the SEmantic NAvigaTOR key bindings in the current buffer.

     The following default key bindings are provided when semantic minor mode is enabled:

     C-c , n
          senator-next-tag

     C-c , p
          senator-previous-tag

     C-c , i
          senator-isearch-toggle-semantic-mode

     C-c , j
          semantic-complete-jump-local

     C-c , J
          semantic-complete-jump

     C-c , TAB
          senator-complete-symbol

     C-c , SPC
          senator-completion-menu-popup

     C-c , C-y
          senator-yank-tag

     C-c , C-w
          senator-kill-tag

     C-c , M-w
          senator-copy-tag

     C-c , +
          senator-unfold-tag

     C-c , -
          senator-fold-tag

Customization
=============

To enable the Senator keymap in all modes that support semantic parsing, use this:

     (add-hook 'semantic-init-hooks 'senator-minor-mode)

If you use semantic-load.el, you do not need to add the above lines in your .emacs file.

To customize navigation around different types of tokens, use the following variables:

 -- Option: senator-step-at-tag-classes
     List of tag classes where to step. A tag class is a symbol like 'variable, 'function, 'type, or other. If nil navigation steps at any tag found.  This is a buffer local variable.  It can be set in a mode hook to get a specific langage navigation.

 -- Option: senator-step-at-start-end-tag-classes
     List of tag classes where to step at start and end. A tag class is a symbol like 'variable, 'function, 'type, or other. If nil, navigation only step at beginning of tags.  If t, step at start and end of any tag where it is allowed to step.  Also, stepping at start and end of a tag prevent stepping inside its components. This is a buffer local variable.  It can be set in a mode hook to get a specific langage navigation.

To have a mode specific customization, do something like this in a hook:

     (add-hook 'mode-hook
               (lambda ()
                 (setq senator-step-at-tag-classes '(function variable))
                 (setq senator-step-at-start-end-tag-classes '(function))
                 ))

This will cause navigation and search commands to stop only between functions and variables, and to step at start and end of functions only.

Analyzer
********

The semantic analyzer is a library tool that performs context analysis and can derive useful information.

 -- Command: semantic-analyze-current-context position
     Analyze the current context at POSITION. If called interactively, display interesting information about POSITION in a separate buffer. Returns an object based on symbol semantic-analyze-context.

While this can be used as a command, it is mostly useful while debugging the analyzer, or tools using the return value.  Use the Emacs command describe-class to learn more about using semantic-analyze-context.

Another command that uses the analyzer context can derive a completion list.

 -- Command: semantic-analyze-possible-completions context
     Return a list of semantic tags which are possible completions. CONTEXT is either a position (such as point), or a precalculated context.  Passing in a context is useful if the caller also needs to access parts of the analysis. Completions run through the following filters:

     Elements currently in scope

     Constants currently in scope

     Elements match the :prefix in the CONTEXT.

     Type of the completion matches the type of the context.
          Context type matching can identify the following:

     No specific type

     Assignment into a variable of some type.

     Argument to a function with type constraints.
          When called interactively, displays the list of possible completions in a buffer.

Smart Completion
================

The file semantic-ia.el contains two commands for performing smart completion using the analysis library.  Analysis to calculate these completions are done through the analyzer and completion mechanism.  These functions just provide commands that can be bound to key bindings.

 -- Command: semantic-ia-complete-symbol point
     Complete the current symbol at POINT. Completion options are calculated with semantic-analyze-possible-completions.

 -- Command: semantic-ia-complete-symbol-menu point
     Complete the current symbol via a menu based at POINT. Completion options are calculated with semantic-analyze-possible-completions.

 -- Command: semantic-ia-complete-tip point
     Pop up a tooltip for completion at POINT.

 -- Command: semantic-ia-show-summary point
     Display a summary for the symbol under POINT.

 -- Command: semantic-ia-show-doc point
     Display the code-level documentation for the symbol at POINT.

Smart Idle Completion
=====================

You can get smart completions or summary information to automatically popup without explicity pressing a key or running a function.

This is accomplished through the Idle Scheduler and related features. See Idle Scheduler for more on the Scheduler.

Summaries are provided with semantic-idle-summary-mode.  See Idle Summary Mode.

Completions are provided with semantic-idle-completions-mode. See Idle Completions Mode.

Speedbar Analysis
=================

The Analyzer output can be used through a speedbar interface. This interface lists details about the analysis, such as the current function, local arguments and variables, details on the prefix (the symbol the cursor is on), and a list of all possible completions. Completions are specified in semantic-analyze-possible-completions Analyzer.

Each entry can be jumped to by clicking on the name.  For strongly typed languages, this means you will jump to the definition of the variable, slot, or type definition.

In addition each entry has an <i> button.  Clicking on this will display a summary of everything that is known about the variable or type displayed on that line.

If you click on the name of a variable in the ``Completions'' menu, then the text that was recently analyzed will be replaced with the name of the token that was clicked on in speedbar.

 -- Command: semantic-speedbar-analysis
     Start Speedbar in semantic analysis mode. The analyzer displays information about the current context, plus a smart list of possible completions.

You can also enter speedbar analyzer mode by selecting ``Analyze'' from the ``Display'' menu item on speedbar's menu.

Class Browser
*************

The semantic class browser is a library that can covert a project file group into an object structure that contains links between structures so that the inheritance links between semantic tags can be easily navigated.

The core to this library is one function in semantic-cb.el.

 -- Function: semantic-cb-new-class-browser
     Create an object representing this project's organization. The object returned is of type semantic-cb-project, which contains the slot `:types', a list of all top-level types.  Each element is a class of type semantic-cb-token, or semantic-cb-type.

Use the Emacs function describe-class to learn more about these classes.

You can access the class inheritance structure through a speedbar interface.  You can choose the ``Class Browser'' option from Speedbar's ``Display'' menu item, or use the following command:

 -- Command: semantic-cb-speedbar-mode
     Bring speedbar up, and put it into Class Browser mode. This will use the Class Browser logic applied to the current Semantic project database to build the available relations.  The structure of the class hierarchy can then be navigated using traditional speedbar interactions.

Document
********

The document program uses semantic tag tables to aid in the creation of texinfo documentation. For example, the following is a code fragment from document.el that comes with semantic:

     (defun document (&optional resetfile)
       "Document the function or variable the cursor is in.
     Optional argument RESETFILE is provided w/ universal argument.
     When non-nil, query for a new documentation file."
       ...
       )

While visiting document.el, put the cursor somewhere within the function shown above. Then type M-x document. After asking for the texinfo file name, which in this case is semantic.texi, this will update the texinfo documentation of the document function in that file. The result is that the following texinfo text will be either created or updated in user-guide.texi file:

     @deffn Command document &optional resetfile
     Document the function or variable the cursor is in.
     Optional argument @var{RESETFILE} is provided w/ universal argument.
     When non-@code{nil}, query for a new documentation file.
     @end deffn

Note that the function name, arguments and documentation string is put in the right place. Within the doc-string, the function arguments are marked with the @var command and the nil code fragment is marked with @code command. This example provides just a glimpse of what is possible with the syntactic information provided by semantic.

The main entry point for the documentation generator are the following commands:

 -- Command: document &optional resetfile
     Document the function or variable the cursor is in. Optional argument RESETFILE is provided w/ universal argument. When non-nil, query for a new documentation file.

 -- Command: document-inline
     Document the current function with an inline comment.

 -- Command: document-insert-defun-comment tag buffer
     Insert mode-comment documentation about TAG from BUFFER.

 -- Command: document-insert-new-file-header header
     Insert a new header file into this buffer.  Add reference to HEADER. Used by prototype if this file doesn't have an introductory comment.

In addition to these base documentation commands, the texinfo semantic parser includes a two convenience functions when working directly with texinfo files.

 -- Command: semantic-texi-update-doc &optional tag
     Update the documentation for TAG. If the current buffer is a texinfo file, then find the source doc, and update it.  If the current buffer is a source file, then get the documentation for this item, find the existing doc in the associated manual, and update that.

 -- Command: semantic-texi-goto-source &optional tag
     Jump to the source for the definition in the texinfo file TAG. If TAG is nil, it is derived from the deffn under POINT.

Charts
******

Some commands to draw charts of statistics generated from parsing:

 -- Command: semantic-chart-tags-by-class &optional tagtable
     Create a bar chart representing the number of tags for a given tag class. Each bar represents how many toplevel tags in TAGTABLE exist with a given class.  See semantic-symbol->name-assoc-list for tokens which will be charted. TAGTABLE is passedto semantic-something-to-tag-table.

 -- Command: semantic-chart-database-size &optional tagtable
     Create a bar chart representing the size of each file in semanticdb. Each bar represents how many toplevel nonterminals in TAGTABLE exist in each database entry. TAGTABLE is passedto semantic-something-to-tag-table.

 -- Command: semantic-chart-tag-complexity &optional class tagtable
     Create a bar chart representing the complexity of some tokens. Complexity is calculated for tokens with a tag of CLASS.  Each bar represents the complexity of some nonterminal in TAGTABLE. Only the most complex items are charted. TAGTABLE is passedto semantic-something-to-tag-table.

Idle Scheduler
**************

The Idle Scheduler in Semantic 2.0 replaces what was once Auto-Parse mode.  The Idle Scheduler now performs multiple duties.

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, sheduled idle processes that use the semantic tag tables are run.

 -- Command: global-semantic-idle-scheduler-mode &optional arg
     Toggle global use of option semantic-idle-scheduler-mode. The idle scheduler with automatically reparse buffers in idle time, and then schedule other jobs setup with semantic-idle-scheduler-add. If ARG is positive, enable, if it is negative, disable. If ARG is nil, then toggle. global-semantic-auto-parse-mode,global-semantic-idle-scheduler-mode

semantic-auto-parse-mode, semantic-idle-scheduler-mode

 -- Option: 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.

 -- Option: semantic-idle-scheduler-mode-hook
     Hook run at the end of function semantic-idle-scheduler-mode.

You can add new functionality to the idle scheduler by reading the Application Developers Guide see Idle Scheduling (semantic-appdev.info).

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.

Reparse Configuration
---------------------

 -- Option: semantic-idle-scheduler-max-buffer-size
     Maximum size in bytes of buffers automatically reparsed. If this value is less than or equal to 0, buffers are automatically reparsed regardless of their size.

Reparse Messages
----------------

 -- Option: semantic-idle-scheduler-no-working-message
     If non-nil, disable display of working messages during parse.

 -- Option: semantic-idle-scheduler-working-in-modeline-flag
     Non-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.

Reprasing Hooks
---------------

 -- Variable: semantic-before-idle-scheduler-reparse-hooks
     Hooks run before option 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.

 -- Variable: semantic-after-idle-scheduler-reparse-hooks
     Hooks run after option semantic-idle-scheduler has parsed. If any hook throws an error, this variable is reset to nil. This hook is not protected from lexical errors.

Idle Summary Mode
=================

A summary describes a tag in a useful way.  These can be displayed for the lexical token under the cursor in idle time using this mode.

 -- semantic-idle-summary-mode: &optional arg
     Display a tag summary of the lexical token under the cursor. This means for getting the current tag to display information can be overriden with idle-summary-current-symbol-info. This is a minor mode which performs actions during idle time. With prefix argument ARG, turn on if positive, otherwise off.  The minor mode can be turned on only if semantic feature is available and the current buffer was set up for parsing.  Return non-nil if the minor mode is enabled

semantic-summary-mode, semantic-idle-summary-mode

 -- Option: semantic-idle-summary-function
     Function to use when displaying tag information during idle time. Some useful functions are found in semantic-format-tag-functions.

Idle Completions Mode
=====================

The definition of completion lists is described in the Analyzer section Analyzer.

The Idle Completions mode will calculate the list of possible completions in idle time, and display them in a popup list, and also highlight the symbol that needs completion.

 -- semantic-idle-completions-mode: &optional arg
     Display a tooltip with a list of possible completions near the cursor. There is no convenience for performing a completion replacement.  For that you should bind semantic-ia-complete-symbol. This is a minor mode which performs actions during idle time. With prefix argument ARG, turn on if positive, otherwise off.  The minor mode can be turned on only if semantic feature is available and the current buffer was set up for parsing.  Return non-nil if the minor mode is enabled

This mode operates by using the command semantic-complete-inline-analyzer.

Minor Modes
***********

     [file minor-modes.texi not included]

Semantic Database
*****************

Semanticdb is a utility which tracks your parsed files, and saves the parsed information to disk.  When you reload your source files, semanticdb automatically associates the file with the cached copy, saving time by not re-parsing your buffer.

Semanticdb also provides an API for programs to use to look up information about a tag.  These functions can return tag information without loading the source file into memory.

Lastly, the semanticdb interface allows programmers to create alternate back ends.  Such a back end could allow access to tag information in binary files, not normally accessable to semantic.  A back end could also be written to store tag information in an alternate form of persistent storage.

To use semanticdb, add the following to your .emacs file:

     (require 'semanticdb)
     (global-semanticdb-minor-mode 1)

If you use semantic-load.el, or the default CEDET install mechanism, you do not need to add the above lines in your .emacs file.

The Semantic Database has several user level configuration options that controls it's use.  From the user perspective, it appears to be one large application.  Internally it is divided into sections.

Core Tables
     These core tables for semanticdb are not associated with files, or backends.  They define the basic behavior of a database and table.

Persistent Tables
     These databases are what are generally used in semantic to store information to disk.

Custom Backends
     These databases and tables are interfaces to some other source of tagging information, such as the symbols loaded in Emacs Lisp, or perhaps symbols in a Java .class file.

You can execute hooks when semanticdb is activated using its mode hook.

 -- Option: semanticdb-mode-hooks
     Hooks run whenever global-semanticdb-minor-mode is run. Use semanticdb-minor-mode-p to determine if the mode has been turned on or off.

Semanticdb Tag Storage
======================

Once you have tables of tags parsed from your files, the default action is to save them when Emacs exits.  You can control the file name and directories where the caches are stored.

 -- Option: semanticdb-default-file-name
     File name of the semantic tag cache.

 -- Option: semanticdb-default-save-directory
     Directory name where semantic cache files are stored. If this value is nil, files are saved in the current directory.  If the value is a valid directory, then it overrides semanticdb-default-file-name and stores caches in a coded file name in this directory.

 -- Option: semanticdb-persistent-path
     List of valid paths that semanticdb will cache tags to. When global-semanticdb-minor-mode is active, tag lists will be saved to disk when Emacs exits.  Not all directories will have tags that should be saved. The value should be a list of valid paths.  A path can be a string, indicating a directory in which to save a variable.  An element in the list can also be a symbol.  Valid symbols are never, which will disable any saving anywhere, always, which enables saving everywhere, or project, which enables saving in any directory that passes a list of predicates in semanticdb-project-predicate-functions.

 -- Variable: semanticdb-project-predicate-functions
     List of predicates to try that indicate a directory belongs to a project. This list is used when semanticdb-persistent-path contains the value 'project.  If the predicate list is nil, then presume all paths are valid.

     Project Management software (such as EDE and JDE) should add their own predicates with add-hook to this variable, and semanticdb will save tag caches in directories controlled by them.

 -- Option: semanticdb-save-database-hooks
     Hooks run after a database is saved. Each function is called with one argument, the object representing the database recently written.

Semanticdb Search Configuration
===============================

When different tools such as smart completion or tag jumping needs to find a tag, those routines call semanticdb search routines.  Some time usually needs to be spent making sure semanticdb can find the files your tags are in.

The search path should include:

 1. The current file

 2. a table for each #include file

 3. if 'recursive is in the throttle, then all include files included in include files.

Include files or equivalent are found in:

 1. current directory

 2. directories specified by your project.  (such as EDE, or the semanticdb-project-roots variable.)

 3. system directories

In C code, semantic tries to distinguish between project and system headers based on "" or <> delimiters.  Each language can distinguish using it's own rules.

The system directory is set up via the variable semantic-dependency-system-include-path.  The path is also modified by some system database create routines, such as semanticdb-create-ebrowse-database. See Include paths.

You can use the command:

     M-x semantic-add-system-include RET /some/path

to add more paths interactively into the current mode's path.  This will allow semantic to find more files w/out using system databases.

SemanticDB project roots
------------------------

Project roots specify where different code projects start.  Searching for files usually stops within a single project, so specifying these roots is important if you want semantic to find tags in other related directories.

 -- Option: semanticdb-project-roots
     List of directories, where each directory is the root of some project. All subdirectories of a root project are considered a part of one project. Values in this string can be overriden by project management programs via the semanticdb-project-root-functions variable.

 -- Variable: semanticdb-project-root-functions
     List of functions used to determine a given directories project root. Functions in this variable can override semanticdb-project-roots. Functions set in the variable are given one argument (a directory) and must return a string, (the root directory) or a list of strings (multiple root directories in a more complex system).  This variable should be used by project management programs like EDE or JDE.

Include Paths
-------------

You can add and remove system include paths based on major mode using the following commands:

 -- Command: semantic-add-system-include dir &optional mode
     Add a system include DIR to path for MODE. Modifies a mode-local version of semantic-dependency-system-include-path.

 -- Command: semantic-remove-system-include dir &optional mode
     Add a system include DIR to path for MODE. Modifies a mode-local version of semantic-dependency-system-include-path.

SemanticDB Search Throttle
--------------------------

The semanticdb find throttle is a configuration variable that may often 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.

 -- Variable: semanticdb-find-default-throttle
     The default throttle for 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:

     file
          The file the search is being performed from.  This option is here for completeness only, and is assumed to always be on.

     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.

     project
          Tables from the same local project are included If project is specified, then local is assumed.

     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.

     system
          Tables from system databases.  These are specifically tables from system header files, or language equivalent.

     recursive
          For include based searches, includes tables referenced by included files.

     omniscience
          Included system databases which are omniscience, or somehow know everything.  Omniscience databases are found in semanticdb-project-system-databases.  The Emacs Lisp system DB is an omniscience database.

To set the throttle, use a command like this:

     (setq-mode-local c-mode
     		 semanticdb-find-default-throttle
     		 '(project unloaded system recursive))

Semanticdb search debugging commands
------------------------------------

You can use 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 M-x semanticdb-find-test-translate-path RET to then make sure specific tables from the path are discovered correctly.

 -- Command: semanticdb-dump-all-table-summary
     Dump a list of all databases in Emacs memory.

 -- Command: semanticdb-find-test-translate-path &optional arg
     Call and output results of semanticdb-find-translate-path With ARG non-nil, specify a BRUTISH translation.

Lastly, you can test an explicit search term using this command:

 -- Command: semantic-adebug-searchdb regex
     Search the semanticdb for REGEX for the current buffer. Display the results as a debug list.

Semanticdb System Backends
==========================

 -- Variable: semanticdb-project-system-databases
     List of databases containing system library information. Mode authors can create their own system databases which know detailed information about the system libraries for querying purposes. Put those into this variable as a buffer-local, or mode-local value.

These system databases are a part of the `omniscience' throttle value.

While these are enabled with semanticdb-find-default-throttle, a secondary flag is needed for internal controls that prevent recursive duplication.

 -- Variable: semanticdb-search-system-databases
     Non nil if search routines are to include a system database.

Changing Backends
=================

If you want to use some other form of backend, you can use this variable to choose which back end class to use for your general tag storage.

 -- Variable: 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.

Script Generated Cache Files
============================

You can create new semantic databases with the semanticdb.sh script file.  Give this script the directory you want parsed, and it will create a cache file for you.

     $ semanticdb.sh *.el

Create System Databases
=======================

If your supported langauge stores the system libraries in readilly available parsable source code, you can pre-generate database files for them once, which will be used over and over for tools such as summary-mode, or the analyzer.

Use the following command to create new system databases:

 -- Command: semanticdb-create-system-database path &optional class
     Create a system database starting at PATH. PATH should be a top level directory for a series of files containing declarations for SYSTEM files.  In C, this would be header filaes. CLASS is the class for the database to create.  Only child classes of symbol semanticdb-project-database-system are accepted.

 -- Command: semanticdb-create-ebrowse-database dir
     Create an EBROSE database for directory DIR. The database file is stored in ~/.semanticdb, or whichever directory is specified by semanticdb-default-system-save-directory.

The CLASS requested here is a bit of archana representing the class name for the language the entry is for.  Use completion SPC to see the ones available.  The name of the language should be part of the class name.

Debugging Speed Problems
************************

If aspects of semantic cause your Emacs to slow down or block editing, there are several things that may be happening.  The most time consuming aspect of semantic is usually the parsing of files for tag information, and this action can be triggered from many possible sources.

A simple way to determine where the problem lies is to use the command M-x debug-on-quit RET and then just hit C-g next time it gets 'stuck' somewhere.  It will give you a stack and one of the many semantic mode functions will likely show up in that stack trace.

From a simple standpoint, your next action might be to use the the Senator menu under Modes and just toggle suspected modes on and off.

Interruptibility
================

One of the goals with the semantic based minor modes and auto parse is that it should be interruptible.  Thus, a keyboard action should interrupt any active parsing or mode activity.  In practice, I've found this doesn't always work and I've been a bit stymied as to why.

You can test the interruptibility framework by running M-x semantic-test-throw-on-input RET and seeing that you can press any key to break out of the loop.

Incremental parsing
===================

The incremental parser used by semantic will reparse only small sections of a file you have edited, which eliminates the need to reparse entire files.  This speeds up minor modes that need the local buffer to be up to date, such as speedbar or ECB.

If the incremental parsing is not always working for you (meaning it will parse the whole file frequently while you edit) then perhaps you need to customize semantic-edits-verbose-flag to enable some friendly debug output.  Additionally using semantic-load-enable-semantic-debugging-helpers to help identify possible problem areas by enabling highlight edits mode and show parser state mode see Incremental Parser Debugging (semantic-langdev.info)

Symbol lookup
=============

There are many minor modes that have special behaviors tied into the current parser state, with the most complex modes being the summary and completion modes.  These modes can initiate parsing not only in the current buffer, but in other buffers that are referred to in the current source by some form of include statement.

If they turn out not to be useful in the language mode you are operating in, then it may be best to disable them.

Alternately, you can control how these major modes, and other modes like them parse alternate files by adjusting semanticdb-find-default-throttle. You can read more in see DB Search Paths (semantic-appdev.info).

Customizing
***********

Customizations can be divided into two categories. * M-x customize * Low level hooks.

GNU Free Documentation License
******************************

     [file fdl.texi not included]