Initial Commit

[packages] / xemacs-packages / semantic / doc / installation.texi

@ignore
@node Installation
@chapter Installation and Basic Configuration
@c This 'ignore' section fools texinfo-all-menus-update into creating
@c proper menus for this chapter.
@end ignore

Semantic should be installed as a part of the CEDET distribution.  See
the cedet/INSTALL file in the cedet distribution for basic
installation instructions.

@menu
* Canned Configuration::
* Search Optimization::
* Parsing Optimization::
@end menu

@node Canned Configuration
@section Canned Configuration

As described briefly in the cedet/INSTALL file, there are several
canned configurations you can use.  These configuration files just
turn different semantic modes on and off, but don't change intrinsic
semantic parsing behaviors.

@deffn Command semantic-load-enable-minimum-features
@anchor{semantic-load-enable-minimum-features}
Enable the minimum number of semantic features for basic usage.
This includes:
@table @asis
@item @dfn{semantic-idle-scheduler-mode}
Keeps a buffer's parse tree up to date.
(@pxref{(semantic-user)Idle Scheduler}.)
@item @code{semanticdb-minor-mode}
Stores tags when a buffer is not in memory.
(@pxref{(semantic-user)semanticdb}.)
@item @dfn{semanticdb-load-system-caches}
Loads any systemdbs created earlier.
(@pxref{(semantic-user)semanticdb}.)
@item @dfn{semanticdb-load-ebrowse-caches}
Loads any ebrowse dbs created earlier.
(@pxref{(semantic-user)Create System Databases}.)
@end table
@end deffn

@deffn Command semantic-load-enable-code-helpers
@anchor{semantic-load-enable-code-helpers}
Enable some semantic features that provide coding assistance.
This includes @dfn{semantic-load-enable-minimum-features} plus:
@table @dfn
@item imenu
Lists Semantic generated tags in the menubar.
@item semantic-idle-summary-mode
Show a summary for the tag indicated by
code under point.  (intellisense)
(@pxref{(semantic-user)Idle Summary Mode}.)
@item senator-minor-mode
Semantic Navigator, and global menu for all features semantic.
(@pxref{(semantic-user)senator}.)
@item semantic-mru-bookmark-mode
Provides a `switch-to-buffer' like keybinding for tag names.
(@pxref{(semantic-user)MRU Bookmarks Mode}.)
@end table
@end deffn

@deffn Command semantic-load-enable-gaudy-code-helpers
@anchor{semantic-load-enable-gaudy-code-helpers}
Enable semantic features that provide gaudy coding assistance.
This includes @dfn{semantic-load-enable-code-helpers}.
@table @dfn
@item semantic-stickyfunc-mode
Tracks current function in header-line (when available).
(@pxref{(semantic-user)Sticky Function Mode}.)
@item semantic-idle-completions-mode
Provide smart symbol completion automatically at idle time.
(@pxref{(semantic-user)Idle Completions Mode}.)
@item semantic-decoration-mode
Decorate tags based on various attributes.
(@pxref{(semantic-user)Tag Decoration Mode}.)
@end table

@obsolete{semantic-load-enable-guady-code-helpers,semantic-load-enable-gaudy-code-helpers}
@end deffn

@deffn Command semantic-load-enable-excessive-code-helpers
@anchor{semantic-load-enable-excessive-code-helpers}
Enable all semantic features that provide coding assistance.
This includes all features of @dfn{semantic-load-enable-code-helpers} plus:
@table @dfn
@item which-func-mode
Display the current function in the mode line.
@end table


@end deffn

@deffn Command semantic-load-enable-semantic-debugging-helpers
@anchor{semantic-load-enable-semantic-debugging-helpers}
Enable all semantic features that assist with debugging semantic.
These modes include:
@table @dfn
@item semantic-highlight-edits-mode
Highlight text that has been edited since the last parse step.
(@pxref{(semantic-user)Highlight Edits Mode}.)
@item semantic-show-unmatched-syntax-mode
Highlight lexical tokens which failed to be parsed.
(@pxref{(semantic-user)Unmatched Syntax Highlighting}.)
@item semantic-show-parser-state-mode
Show the current buffer state via small indicators in the mode line.
(@pxref{(semantic-user)Parser State}.)
@end table

@end deffn


@node Search Optimization
@section Search Optimization

A common use of semantic is for smart completion and tag browsing.
These operations involve searching through the tags of your files.
For complete documentation on configuring your searches,
@ref{(semantic-user)Semanticdb Search Configuration}.

The default configuration is for fast searches that may not find your
symbols all the time.

Searching is controlled with @code{semanticdb-find-default-throttle}.
To force the search to find and read and tag files not yet in memory,
you might add code like this for C mode.

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

Finding unloaded databases requires knowing the search path.  You can
find headers on a system or project level search path.
@xref{(semantic-user)Include paths}.

If using the above tactic doesn't work for your language (something
other than C/C++), it may be that your language isn't configured
properly for finding include files.  You would need to refer to the
@ref{(semantic-langdev)} for details.

If you were to be working on a linux kernel, you might opt to
configure your search path in your @file{.emacs} file with code like
this:

@example
(semantic-reset-system-include 'c-mode)
(semantic-add-system-include "/usr/src/linux-2.4/include" 'c-mode)
@end example

It is also useful to find and install extra search engine back-ends,
such @xref{(semantic-user)Create System Databases}.  Ebrowse is one such back-end for
C and C++ code.

You might create an ebrowse database for your C include files like
this:

@example
M-x semanticdb-create-ebrowse-database RET /usr/include/ RET
@end example

This will create the database, save it, and add it to the database
search list for your C and C++ based projects.  These databases will
be created in your @file{~/.semanticdb} directory to be reloaded in
future Emacs sessions.


@node Parsing Optimization
@section Parsing Optimization

The semantic parsers generate the tags that form the basis of all the
semantic based tools, such as browsers and completion.  Keeping those
tags up to date can have performance implications.

Here are some common tasks you may be interested in:

@subsection Don't parse certain buffers

You can inhibit parsing using the @code{semantic-inhibit-functions}
variable. 

@defvar semantic-inhibit-functions
@anchor{semantic-inhibit-functions}
List of functions to call with no arguments before to setup Semantic.
If any of these functions returns non-@code{nil}, the current buffer is not
setup to use Semantic.
@end defvar

You could have this inihibit parsing in very large files, or files
which case particular problems to semantic.


@subsection Parsing in idle time

Tags are usually kept up to date when Emacs is idle
@ref{(semantic-user)Idle Scheduler}.  The semantic's idle-scheduler
automatically updates the tags in various buffers before executing
specific idle modes, such as summary mode.

You might choose to tune the scheduler with some code like this in
your @file{.emacs} file:

@example
;; Increase the delay before activation
(setq semantic-idle-scheduler-idle-time 10)
;; Don't reparse really big buffers.
(setq semantic-idle-scheduler-max-buffer-size 100000)
@end example