You can begin using semantic by enabling Semantic mode, a global minor mode: type M-x semantic-mode, or click on the Source Code Parsers (Semantic) menu item in the Tools menu.

When Semantic mode is turned on, Emacs automatically parses each file you visit.  This allows you to use semantic user commands in those buffers.  It also enables a number of ``helper'' minor modes for saving tags, displaying tag information, and so forth.  See Semantic mode.

To enable Semantic mode each time you start Emacs, add the line (semantic-mode 1) to your initialization file.  See Init File (Emacs manual).

Semantic mode
=============

Semantic mode is a global minor mode for semantic as a whole.  When enabled, each file you visit is automatically parsed, provided its major mode is specified in the variable semantic-new-buffer-setup-functions (the default is to parse every buffer semantic knows how to parse).

In each parser-enabled buffer, a number of semantic commands are available for navigating, querying, and editing source code. See Semantic mode user commands.  Enabling Semantic mode also installs a Development menu on the menu-bar, with many of these commands.

In addition, enabling Semantic mode turns on certain auxiliary global minor modes, as specified by the variable semantic-default-submodes.  The default auxiliary modes are SemanticDB mode (see SemanticDB) and Global Semantic Idle Scheduler mode.  You can also toggle the auxiliary minor modes separately, using their mode functions (e.g. M-x semanticdb-minor-mode), or via the Development menu.  These auxiliary minor modes are described in the following sections.

 -- Variable: semantic-new-buffer-setup-functions
     The value of this variable is an alist of functions to call for setting up semantic parsing in the buffer.  Each element has the form (MODE . FN), where MODE is a value of major-mode for the buffer and FN is the corresponding function for setting up the parser.  FN is called, with no arguments, after the major mode is initialized (and after the mode hooks have been run).

     The default value enables semantic for all supported major modes (i.e., C, C++, Scheme, Javascript, Java, HTML, SRecode, and Make), but you can remove modes from this list if you don't want to use semantic with them.

 -- Variable: semantic-default-submodes
     The value of this variable is a list of symbols, specifying the auxiliary minor modes to enable when enabling Semantic mode.  The valid mode symbols are:

       * semantic-idle-scheduler-mode (see Idle Scheduler).

       * semanticdb-minor-mode (see SemanticDB).

       * semantic-idle-summary-mode (see Idle Summary Mode).

       * semantic-idle-completions-mode (see Idle Completions Mode).

       * semantic-highlight-func-mode

       * semantic-decoration-mode

       * semantic-stickyfunc-mode

       * semantic-mru-bookmark-mode

Semantic mode user commands
---------------------------

Semantic mode provides a number of commands for navigating, querying, and editing source code in a language-aware manner.  These commands generally act on tags, which are the source-code units deemed ``important'' by the present programming language (e.g. functions in the C programming language).

These commands may be used in any buffer that has been parsed by semantic.  Several of them prompt for a tag name using the minibuffer; here, the TAB key can be used to complete tag names. Others act on the current tag, meaning the tag at (or around) point.

\C-c , j
     Prompt for a tag defined in the current file, and move point to it (semantic-complete-jump-local).

\C-c , J
     Prompt for a tag defined in any file that Emacs has parsed, and move point to it (semantic-complete-jump).

\C-c , l
     Display a list of the possible completions of the current tag (semantic-analyze-possible-completions).

\C-c , g
     Prompt for a tag, and display a list of tags that call it (semantic-symref-symbol).

\C-c , G
     Display a list of tags that call the current tag (semantic-symref).

\C-c , p
     Move point to the previous tag (senator-previous-tag).

\C-c , n
     Move point to the next tag (senator-next-tag).

\C-c , u
     Move point ``up'' one reference (senator-go-to-up-reference). The meaning of ``up'' is language-dependent; in C++, for instance, this means moving to the parent of the current tag.

\C-c, SPC
     (semantic-complete-analyze-inline)

\C-c,\C-w
     Kill the current tag (senator-kill-tag).  This removes the text for that tag, placing it in the kill ring.  You can retrieve the text with C-y.  This also places the tag in the tag ring, so that you can yank it with \C-c,\C-y, below.

\C-c,\M-w
     Copy the current tag into the kill ring as well as the tag ring (senator-copy-tag).

\C-c,\C-y
     Yank a tag from the tag ring (senator-yank-tag).

\C-c,r
     Copy the current tag into a register (senator-copy-tag-to-register).  With an optional argument, kill it as well.  This allows you to insert or jump to that tag with the usual register commands.  See Registers (Emacs manual).

?\C-c , up
     Transpose the current tag with the previous one (senator-transpose-tags-up).

?\C-c ?, down
     Transpose the current tag with the next one (senator-transpose-tags-down).

Semantic Database
=================

The Semantic Database (SemanticDB) caches the results of parsing source code files.  This data can be saved to disk when you exit Emacs, and reloaded automatically when you subsequently revisit the same source code files.  This saves time by eliminating the need to re-parse unmodified files.

SemanticDB also provides an API that programs can use to acquire information about source code tags.  This information can be accessed without loading the original the source files into memory. It can also be used to create alternate ``back-ends'' for storing tag information in alternative on-disk formats.

By default, SemanticDB is enabled together with Semantic mode.  To disable it, remove it from semantic-default-submodes (see Semantic mode).  You can also enable or disable SemanticDB with M-x global-semanticdb-minor-mode.

 -- Command: global-semanticdb-minor-mode
     Toggle SemanticDB mode.  When enabled, any source code parsed by semantic is cached in a database.

SemanticDB offers a large number of customizable options, which are described in the following subsections.

Semanticdb Tag Storage
----------------------

Each time you exit Emacs, any data cached by SemanticDB is saved in the directory .emacs.d/semanticdb/, located in your home directory.  Within this directory, the cache data is written into a set of files according to a SemanticDB-specific filename convention. If the SemanticDB directory does not exist, Emacs first asks if you want to create it.

You can change the name of the SemanticDB directory by customizing the variable semanticdb-default-save-directory.

 -- Option: semanticdb-default-save-directory
     The name of the directory where SemanticDB cache files are saved.  If the value is nil, SemanticDB saves its data into a single file, in the current directory, whose filename is given by semanticdb-default-file-name.

 -- Option: semanticdb-default-file-name
     The name of a cache file in which to save SemanticDB, when semanticdb-default-save-directory is nil.

You can force SemanticDB to save the data from only certain files, or suppress saving altogether, by customizing semanticdb-persistent-path:

 -- Option: semanticdb-persistent-path
     List of valid paths for SemanticDB to cache.  Each element should be a directory name (a string); then the parse data from any file in that directory is saved.

     As a special exception, the value of this variable can be a list containing a single symbol: never, always, or project.  The symbol never disables saving anywhere; always enables saving everywhere; and project enables saving directory based on the variable semanticdb-project-predicate-functions.

     The default value is (always).

 -- Variable: semanticdb-project-predicate-functions
     The value of this variable is a list of predicates for indicating that a directory belongs to a project.  This list is used when the value of semanticdb-persistent-path is (project).  If the list is empty, all paths are considered valid.

     Project management packages, such as EDE (see EDE manual), may add their own predicates with add-hook to this variable.  This allows SemanticDB to save tag caches in directories controlled by them.

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

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:

 1. The entries defined by the current file.

 2. The entries defined by the include files of the current file.

 3. The entries defined by the include files included from the include files (and so on, recursively).

In C and C++, for instance, include files are defined with the #include preprocessor directive (SemanticDB tries to distinguish between project and system headers, based on the "" and <> filename delimiters).  Include directives are matched to filenames in the SemanticDB cache using the following criteria:

 1. Whether the file is in the same directory as the current file

 2. Whether the file is in the same project, as defined by EDE (see EDE manual) or the semanticdb-project-roots variable (see Semanticdb Roots).

 3. Whether the file is in the system include path (see Include paths).

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.

 -- 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 semanticdb-project-root-functions.

 -- Variable: semanticdb-project-root-functions
     The value of this variable is a list of functions to determine a given directory's project root.  These functions are called, one at a time, with one argument (the directory name), and must return either nil, a string (the project root), or a list of strings (multiple project roots, for complex systems).  The first non-nil return value, if any, is taken to be the project root, overriding semanticdb-project-roots.

If you use EDE for project management, it will set semanticdb-project-root-functions automatically. See EDE manual.

Include Paths
.............

System include paths are standard locations to find source code tags, such as the header files in /usr/include and its subdirectories on Unix-like operating systems.  You can add and remove system include paths using the following commands:

 -- Command: semantic-add-system-include dir &optional mode
     This command prompts for a directory, 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 MODE argument.

 -- Command: semantic-remove-system-include dir &optional mode
     This command prompt for a directory, DIR, and removes it from the system include path for the current major mode (or MODE).

 -- Command: semantic-customize-system-include-path &optional mode
     Customize the system include path for the current major mode (or MODE).

 -- Function: semanticdb-implied-include-tags
     Include tags implied for all files of a given mode.  You can set this variable with defvar-mode-local for a particular mode so that any symbols that exist for all files for that mode are included.

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.

 -- 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))

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 semantic-idle-summary-mode to remove 'unloaded, thus removing poor speed at unexpected times.

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.

Alternately, you can get a list of include files semantic encountered, but could not find on disk using 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 Semanticdb Search Configuration.  If the search config is ok, you may need to configure the search throttle.  See Search Throttle.

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

 -- Command: semanticdb-find-adebug-lost-includes
     Translate the current path, then display the lost includes. Examines the variable semanticdb-find-lost-includes.

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.

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.

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.

 -- 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

To use these generated tables, you would likely need to restart Emacs.

Create System Databases
-----------------------

If your supported language stores the system libraries in readily 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.

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

Idle Scheduler
==============

The Idle Scheduler in semantic 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, scheduled 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.

 -- Option: semantic-idle-scheduler-verbose-flag
     Non-nil means that the idle scheduler should provide debug messages. Use this setting to debug idle activities.

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.

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

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

 -- 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 Working Options
--------------------

Similiar to the reparsing that occurs at short intervals in idle time, there is extra work that can be controlled to occur in idle time also.

Idle work occurs after a longer delay, and can be very time consuming.  The work done includes:

Create Include Path Caches
     Create the optimized search caches needed for symbol lookup.

Create Type Cache
     Create the datatype caches needed for intellisense features.

Save Databases
     All file-based semantic databases are saved to disk.

Parse neighboring files
     All files in the same directory as the current buffer are speculatively parsed.

These features can be controlled with the following variables:

 -- Option: semantic-idle-scheduler-work-idle-time
     Time in seconds of idle before scheduling big work. This time should be long enough that once any big work is started, it is unlikely the user would be ready to type again right away.

 -- Option: semantic-idle-work-parse-neighboring-files-flag
     Non-nil means to parse files in the same dir as the current buffer. Disable to prevent lots of excessive parsing in idle time.

Debugging Idle Time Issues
--------------------------

If you see errors produced in idle time, it could be an indication of a more serious issue elsewhere.  It is not enough to enable debug-on-error, as the idle timer tries to keep errors under wraps.

Instead, there are two commands you can use whenever you see an idle error.

 -- Command: semantic-debug-idle-function
     Run the Semantic idle function with debugging turned on.

 -- Command: semantic-debug-idle-work-function
     Run the Semantic idle work function with debugging turned on.

Once you identify the general location of the idle error, you can send the stack trace to the mailing list, or perhaps find a more focused way to reproduce the issue.

Idle Summary Mode
-----------------

Similar to the Emacs Lisp facility eldoc, semantic-idle-summary-mode will display the prototype, or other helpful doc about the symbol currently under point.

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

 -- Variable: semantic-idle-summary-out-of-context-faces
     List of font-lock faces that indicate a useless summary context. Those are generally faces used to highlight comments or strings.

     It might be useful to override this variable to add comment faces specific to a major mode.  For example, in jde mode:

          (defvar-mode-local jde-mode semantic-idle-summary-out-of-context-faces
             (append (default-value 'semantic-idle-summary-out-of-context-faces)
          	   '(jde-java-font-lock-doc-tag-face
          	     jde-java-font-lock-link-face
          	     jde-java-font-lock-bold-face
          	     jde-java-font-lock-underline-face
          	     jde-java-font-lock-pre-face
          	     jde-java-font-lock-code-face)))

Idle Completions Mode
---------------------

The definition of smart completion 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, or other inline completion mechanism.

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

Idle completion uses the completion function semantic-complete-analyze-inline-idle.  Changing the behavior of the idle completion popups should be done through those utilities.

 -- Command: semantic-complete-analyze-inline-idle
     Perform prompt completion to do in buffer completion. semantic-analyze-possible-completions is used to determine the possible values. The function returns immediately, leaving the buffer in a mode that will perform the completion. Configure semantic-complete-inline-analyzer-idle-displayor-class to change how completion options are displayed.

 -- Option: semantic-complete-inline-analyzer-idle-displayor-class
     Class for displayor to use with inline completion at idle time.

     Customize this variable to get a list of options, such as popup tooltips, ghosting text, or traditional completion tools.