Commit | Line | Data |
---|---|---|
3149927d CY |
1 | @c This file is included by semantic.texi |
2 | ||
3 | @c Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2007 | |
4 | @c Free Software Foundation, Inc. | |
5 | ||
6 | @c Permission is granted to copy, distribute and/or modify this | |
7 | @c document under the terms of the GNU Free Documentation License, | |
8 | @c Version 1.3 or any later version published by the Free Software | |
9 | @c Foundation; with no Invariant Sections, no Front-Cover Texts, and | |
10 | @c no Back-Cover Texts. A copy of the license is included in the | |
11 | @c section entitled ``GNU Free Documentation License''. | |
12 | ||
13 | You can begin using @semantic{} by enabling Semantic mode, a global | |
14 | minor mode: type @kbd{M-x semantic-mode}, or click on the @samp{Source | |
15 | Code Parsers (Semantic)} menu item in the @samp{Tools} menu. | |
16 | ||
17 | When Semantic mode is turned on, Emacs automatically parses each file | |
18 | you visit. This allows you to use @semantic{} user commands in those | |
19 | buffers. It also enables a number of ``helper'' minor modes for | |
20 | saving tags, displaying tag information, and so forth. @xref{Semantic | |
21 | mode}. | |
22 | ||
23 | To enable Semantic mode each time you start Emacs, add the line | |
24 | @code{(semantic-mode 1)} to your initialization file. @xref{Init | |
25 | File,,,emacs,Emacs manual}. | |
26 | ||
27 | @menu | |
28 | * Semantic mode:: Global minor mode for @semantic{}. | |
29 | * SemanticDB:: Caching parsed buffers between sessions. | |
30 | * Idle Scheduler:: Performing @semantic{} operations when idle. | |
31 | @end menu | |
32 | ||
33 | @node Semantic mode | |
34 | @section Semantic mode | |
35 | @cindex Semantic mode | |
36 | ||
37 | Semantic mode is a global minor mode for @semantic{} as a whole. When | |
38 | enabled, each file you visit is automatically parsed, provided its | |
39 | major mode is specified in the variable | |
40 | @code{semantic-new-buffer-setup-functions} (the default is to parse | |
41 | every buffer @semantic{} knows how to parse). | |
42 | ||
43 | In each parser-enabled buffer, a number of @semantic{} commands are | |
44 | available for navigating, querying, and editing source code. | |
45 | @xref{Semantic mode user commands}. Enabling Semantic mode also | |
46 | installs a @samp{Development} menu on the menu-bar, with many of these | |
47 | commands. | |
48 | ||
49 | In addition, enabling Semantic mode turns on certain auxilliary global | |
50 | minor modes, as specified by the variable | |
51 | @code{semantic-default-submodes}. The default auxilliary modes are | |
52 | SemanticDB mode (@pxref{SemanticDB}) and Global Semantic Idle | |
53 | Scheduler mode. You can also toggle the auxilliary minor modes | |
54 | separately, using their mode functions (e.g. @kbd{M-x | |
55 | semanticdb-minor-mode}), or via the @samp{Development} menu. These | |
56 | auxilliary minor modes are described in the following sections. | |
57 | ||
58 | @defvar semantic-new-buffer-setup-functions | |
59 | The value of this variable is an alist of functions to call for | |
60 | setting up @semantic{} parsing in the buffer. Each element has the | |
61 | form @code{(@var{mode} . @var{fn})}, where @var{mode} is a value of | |
62 | @code{major-mode} for the buffer and @var{fn} is the corresponding | |
63 | function for setting up the parser. @var{fn} is called, with no | |
64 | arguments, after the major mode is initialized (and after the mode | |
65 | hooks have been run). | |
66 | ||
67 | The default value enables @semantic{} for all supported major modes | |
68 | (i.e., C, C++, Scheme, Javascript, Java, HTML, SRecode, and Make), but | |
69 | you can remove modes from this list if you don't want to use | |
70 | @semantic{} with them. | |
71 | @end defvar | |
72 | ||
73 | @defvar semantic-default-submodes | |
74 | The value of this variable is a list of symbols, specifying the | |
75 | auxilliary minor modes to enable when enabling Semantic mode. The | |
76 | valid mode symbols are: | |
77 | ||
78 | @itemize | |
79 | @item @code{semantic-idle-scheduler-mode} (@pxref{Idle Scheduler}). | |
80 | @item @code{semanticdb-minor-mode} (@pxref{SemanticDB}). | |
81 | @item @code{semantic-idle-summary-mode} (@pxref{Idle Summary Mode}). | |
82 | @item @code{semantic-idle-completions-mode} (@pxref{Idle Completions Mode}). | |
83 | @item @code{semantic-highlight-func-mode} | |
84 | @item @code{semantic-decoration-mode} | |
85 | @item @code{semantic-stickyfunc-mode} | |
86 | @item @code{semantic-mru-bookmark-mode} | |
87 | @end itemize | |
88 | @end defvar | |
89 | ||
90 | @menu | |
91 | * Semantic mode user commands:: | |
92 | @end menu | |
93 | ||
94 | @node Semantic mode user commands | |
95 | @subsection Semantic mode user commands | |
96 | ||
97 | Semantic mode provides a number of commands for navigating, querying, | |
98 | and editing source code in a language-aware manner. These commands | |
99 | generally act on @dfn{tags}, which are the source-code units deemed | |
100 | ``important'' by the present programming language (e.g. functions in | |
101 | the C programming language). | |
102 | ||
103 | These commands may be used in any buffer that has been parsed by | |
104 | @semantic{}. Several of them prompt for a tag name using the | |
105 | minibuffer; here, the @kbd{TAB} key can be used to complete tag names. | |
106 | Others act on the @dfn{current tag}, meaning the tag at (or around) | |
107 | point. | |
108 | ||
109 | @table @kbd | |
110 | @item \C-c , j | |
111 | Prompt for a tag defined in the current file, and move point to it | |
112 | (@code{semantic-complete-jump-local}). | |
113 | ||
114 | @item \C-c , J | |
115 | Prompt for a tag defined in any file that Emacs has parsed, and move | |
116 | point to it (@code{semantic-complete-jump}). | |
117 | ||
118 | @item \C-c , l | |
119 | Display a list of the possible completions of the current tag | |
120 | (@code{semantic-analyze-possible-completions}). | |
121 | ||
122 | @item \C-c , g | |
123 | Prompt for a tag, and display a list of tags that call it | |
124 | (@code{semantic-symref-symbol}). | |
125 | ||
126 | @item \C-c , G | |
127 | Display a list of tags that call the current tag | |
128 | (@code{semantic-symref}). | |
129 | ||
130 | @item \C-c , p | |
131 | Move point to the previous tag (@code{senator-previous-tag}). | |
132 | ||
133 | @item \C-c , n | |
134 | Move point to the next tag (@code{senator-next-tag}). | |
135 | ||
136 | @item \C-c , u | |
137 | Move point ``up'' one reference (@code{senator-go-to-up-reference}). | |
138 | The meaning of ``up'' is language-dependent; in C++, for instance, | |
139 | this means moving to the parent of the current tag. | |
140 | ||
141 | @item \C-c, @key{SPC} | |
142 | (@code{semantic-complete-analyze-inline}) | |
143 | ||
144 | @item \C-c,\C-w | |
145 | Kill the current tag (@code{senator-kill-tag}). This removes the text | |
146 | for that tag, placing it in the kill ring. You can retrieve the text | |
147 | with @kbd{C-y}. This also places the tag in the @dfn{tag ring}, so | |
148 | that you can yank it with @kbd{\C-c,\C-y}, below. | |
149 | ||
150 | @item \C-c,\M-w | |
151 | Copy the current tag into the kill ring as well as the tag ring | |
152 | (@code{senator-copy-tag}). | |
153 | ||
154 | @item \C-c,\C-y | |
155 | Yank a tag from the tag ring (@code{senator-yank-tag}). | |
156 | ||
157 | @item \C-c,r | |
158 | Copy the current tag into a register | |
159 | (@code{senator-copy-tag-to-register}). With an optional argument, | |
160 | kill it as well. This allows you to insert or jump to that tag with | |
161 | the usual register commands. @xref{Registers,,,emacs,Emacs manual}. | |
162 | ||
163 | @item ?\C-c , @kbd{up} | |
164 | Transpose the current tag with the previous one | |
165 | (@code{senator-transpose-tags-up}). | |
166 | ||
167 | @item ?\C-c ?, @kbd{down} | |
168 | Transpose the current tag with the next one | |
169 | (@code{senator-transpose-tags-down}). | |
170 | @end table | |
171 | ||
172 | @node SemanticDB | |
173 | @section Semantic Database | |
174 | @cindex SemanticDB | |
175 | ||
176 | The Semantic Database (SemanticDB) caches the results of parsing | |
177 | source code files. This data can be saved to disk when you exit | |
178 | Emacs, and reloaded automatically when you subsequently revisit the | |
179 | same source code files. This saves time by eliminating the need to | |
180 | re-parse unmodified files. | |
181 | ||
182 | SemanticDB also provides an @acronym{API} that programs can use to | |
183 | acquire information about source code tags. This information can be | |
184 | accessed without loading the original the source files into memory. | |
185 | It can also be used to create alternate ``back-ends'' for storing tag | |
186 | information in alternative on-disk formats. | |
187 | ||
188 | By default, SemanticDB is enabled together with Semantic mode. To | |
189 | disable it, remove it from @code{semantic-default-submodes} | |
190 | (@pxref{Semantic mode}). You can also enable or disable SemanticDB | |
191 | with @kbd{M-x global-semanticdb-minor-mode}. | |
192 | ||
193 | @deffn Command global-semanticdb-minor-mode | |
194 | Toggle SemanticDB mode. When enabled, any source code parsed by | |
195 | @semantic{} is cached in a database. | |
196 | @end deffn | |
197 | ||
198 | SemanticDB offers a large number of customizable options, which are | |
199 | described in the following subsections. | |
200 | ||
201 | @menu | |
202 | * Semanticdb Tag Storage:: | |
203 | * Semanticdb Search Configuration:: | |
204 | * Changing Backends:: | |
205 | * Script Generated Cache Files:: | |
206 | * Create System Databases:: | |
207 | @end menu | |
208 | ||
209 | @node Semanticdb Tag Storage | |
210 | @subsection Semanticdb Tag Storage | |
211 | ||
212 | Each time you exit Emacs, any data cached by SemanticDB is saved in | |
213 | the directory @file{.emacs.d/semanticdb/}, located in your home | |
214 | directory. Within this directory, the cache data is written into a | |
215 | set of files according to a SemanticDB-specific filename convention. | |
216 | If the SemanticDB directory does not exist, Emacs first asks if you | |
217 | want to create it. | |
218 | ||
219 | You can change the name of the SemanticDB directory by customizing the | |
220 | variable @code{semanticdb-default-save-directory}. | |
221 | ||
222 | @anchor{semanticdb-default-save-directory} | |
223 | @deffn Option semanticdb-default-save-directory | |
224 | The name of the directory where SemanticDB cache files are saved. If | |
225 | the value is @code{nil}, SemanticDB saves its data into a single file, | |
226 | in the current directory, whose filename is given by | |
227 | @code{semanticdb-default-file-name}. | |
228 | @end deffn | |
229 | ||
230 | @anchor{semanticdb-default-file-name} | |
231 | @deffn Option semanticdb-default-file-name | |
232 | The name of a cache file in which to save SemanticDB, when | |
233 | @code{semanticdb-default-save-directory} is @code{nil}. | |
234 | @end deffn | |
235 | ||
236 | You can force SemanticDB to save the data from only certain files, or | |
237 | suppress saving altogether, by customizing | |
238 | @code{semanticdb-persistent-path}: | |
239 | ||
240 | @anchor{semanticdb-persistent-path} | |
241 | @deffn Option semanticdb-persistent-path | |
242 | List of valid paths for SemanticDB to cache. Each element should be a | |
243 | directory name (a string); then the parse data from any file in that | |
244 | directory is saved. | |
245 | ||
246 | As a special exception, the value of this variable can be a list | |
247 | containing a single symbol: @code{never}, @code{always}, or | |
248 | @code{project}. The symbol @code{never} disables saving anywhere; | |
249 | @code{always} enables saving everywhere; and @code{project} enables | |
250 | saving directory based on the variable | |
251 | @code{semanticdb-project-predicate-functions}. | |
252 | ||
253 | The default value is @code{(always)}. | |
254 | @end deffn | |
255 | ||
256 | @anchor{semanticdb-project-predicate-functions} | |
257 | @defvar semanticdb-project-predicate-functions | |
258 | The value of this variable is a list of predicates for indicating that | |
259 | a directory belongs to a project. This list is used when the value of | |
260 | @code{semanticdb-persistent-path} is @code{(project)}. If the list is | |
261 | empty, all paths are considered valid. | |
262 | ||
263 | Project management packages, such as EDE (@pxref{Top,,,ede,EDE | |
264 | manual}), may add their own predicates with @dfn{add-hook} to this | |
265 | variable. This allows SemanticDB to save tag caches in directories | |
266 | controlled by them. | |
267 | @end defvar | |
268 | ||
269 | @anchor{semanticdb-save-database-hooks} | |
270 | @deffn Option semanticdb-save-database-hooks | |
271 | Abnormal hook run after a database is saved. Each function is called | |
272 | with one argument, the object representing the database recently | |
273 | written. | |
274 | @end deffn | |
275 | ||
276 | @node Semanticdb Search Configuration | |
277 | @subsection Semanticdb Search Configuration | |
278 | ||
279 | When another part of @semantic{} (or another Emacs package using | |
280 | @semantic{}) searches for a tag within SemanticDB, the SemanticDB | |
281 | library may perform a search in the locations of the database: | |
282 | ||
283 | @enumerate | |
284 | @item | |
285 | The entries defined by the current file. | |
286 | @item | |
287 | The entries defined by the @dfn{include files} of the current file. | |
288 | @item | |
289 | The entries defined by the include files included from the include | |
290 | files (and so on, recursively). | |
291 | @end enumerate | |
292 | ||
293 | In C and C++, for instance, include files are defined with the | |
294 | @samp{#include} preprocessor directive (SemanticDB tries to | |
295 | distinguish between project and system headers, based on the @code{""} | |
296 | and @code{<>} filename delimiters). Include directives are matched to | |
297 | filenames in the SemanticDB cache using the following criteria: | |
298 | ||
299 | @enumerate | |
300 | @item | |
301 | Whether the file is in the same directory as the current file | |
302 | @item | |
303 | Whether the file is in the same project, as defined by EDE | |
304 | (@pxref{Top,,,ede,EDE manual}) or the @code{semanticdb-project-roots} | |
305 | variable (@pxref{Semanticdb Roots}). | |
306 | @item | |
307 | Whether the file is in the @dfn{system include path} (@pxref{Include | |
308 | paths}). | |
309 | @end enumerate | |
310 | ||
311 | @menu | |
312 | * Semanticdb Roots:: Specifying the root of different projects | |
313 | * Include paths:: Add/Remove directories to include search paths | |
314 | * Search Throttle:: Controlling how semanticdb searches occur | |
315 | * Semanticdb search debugging commands:: | |
316 | @end menu | |
317 | ||
318 | @node Semanticdb Roots | |
319 | @subsubsection SemanticDB project roots | |
320 | ||
321 | Project roots are the ``top-level'' directories for a single code | |
322 | project. With the exception of system directories, SemanticDB | |
323 | searches are usually limited to the current single code project. | |
324 | Therefore, it is helpful to specify the project root if you want | |
325 | @semantic{} tag searches to work correctly. | |
326 | ||
327 | @anchor{semanticdb-project-roots} | |
328 | @deffn Option semanticdb-project-roots | |
329 | The value of this variable is a list of directories (strings) that are | |
330 | project root. All subdirectories of a project root are considered | |
331 | part of the same project. This variable can be overriden by project | |
332 | management programs via @code{semanticdb-project-root-functions}. | |
333 | @end deffn | |
334 | ||
335 | @anchor{semanticdb-project-root-functions} | |
336 | @defvar semanticdb-project-root-functions | |
337 | The value of this variable is a list of functions to determine a given | |
338 | directory's project root. These functions are called, one at a time, | |
339 | with one argument (the directory name), and must return either | |
340 | @code{nil}, a string (the project root), or a list of strings | |
341 | (multiple project roots, for complex systems). The first | |
342 | non-@code{nil} return value, if any, is taken to be the project root, | |
343 | overriding @code{semanticdb-project-roots}. | |
344 | @end defvar | |
345 | ||
346 | If you use EDE for project management, it will set | |
347 | @code{semanticdb-project-root-functions} automatically. | |
348 | @xref{Top,,,ede,EDE manual}. | |
349 | ||
350 | @node Include paths | |
351 | @subsubsection Include Paths | |
352 | ||
353 | System include paths are standard locations to find source code tags, | |
354 | such as the @dfn{header files} in @file{/usr/include} and its | |
355 | subdirectories on Unix-like operating systems. You can add and remove | |
356 | system include paths using the following commands: | |
357 | ||
358 | @anchor{semantic-add-system-include} | |
359 | @deffn Command semantic-add-system-include dir &optional mode | |
360 | This command prompts for a directory, @var{dir}, and adds it as a | |
361 | system include path for the current major mode. When called | |
362 | non-interactively, the major mode can be specified with the @var{mode} | |
363 | argument. | |
364 | @end deffn | |
365 | ||
366 | @anchor{semantic-remove-system-include} | |
367 | @deffn Command semantic-remove-system-include dir &optional mode | |
368 | This command prompt for a directory, @var{dir}, and removes it from | |
369 | the system include path for the current major mode (or @var{mode}). | |
370 | @end deffn | |
371 | ||
372 | @anchor{semantic-customize-system-include-path} | |
373 | @deffn Command semantic-customize-system-include-path &optional mode | |
374 | Customize the system include path for the current major mode (or | |
375 | @code{mode}). | |
376 | @end deffn | |
377 | ||
378 | @anchor{semanticdb-implied-include-tags} | |
379 | @defun semanticdb-implied-include-tags | |
380 | Include tags implied for all files of a given mode. You can set this | |
381 | variable with @code{defvar-mode-local} for a particular mode so that | |
382 | any symbols that exist for all files for that mode are included. | |
383 | @end defun | |
384 | ||
385 | @c @xref{Search Optimization}, for more information on include paths. | |
386 | ||
387 | @node Search Throttle | |
388 | @subsubsection SemanticDB Search Throttle | |
389 | ||
390 | The SemanticDB search throttle is a variable that may be configured by | |
391 | a language support author. If you need to customize this for | |
392 | yourself, you may need to override the mode values in a mode support | |
393 | hook. | |
394 | ||
395 | @defvar semanticdb-find-default-throttle | |
396 | @anchor{semanticdb-find-default-throttle} | |
397 | The default throttle for @code{semanticdb-find} routines. | |
398 | The throttle controls how detailed the list of database | |
399 | tables is for a symbol lookup. The value is a list with | |
400 | the following keys: | |
401 | ||
402 | @table @code | |
403 | @item file | |
404 | The file the search is being performed from. This option is here for | |
405 | completeness only, and is assumed to always be on. | |
406 | @item local | |
407 | Tables from the same local directory are included. This includes | |
408 | files directly referenced by a file name which might be in a different | |
409 | directory. | |
410 | @item project | |
411 | Tables from the same local project are included If @code{project} is | |
412 | specified, then @code{local} is assumed. | |
413 | @item unloaded | |
414 | If a table is not in memory, load it. If it is not cached on disk | |
415 | either, get the source, parse it, and create the table. | |
416 | @item system | |
417 | Tables from system databases. These are specifically tables | |
418 | from system header files, or language equivalent. | |
419 | @item recursive | |
420 | For include based searches, includes tables referenced by included | |
421 | files. | |
422 | @item omniscience | |
423 | Included system databases which are omniscience, or somehow know | |
424 | everything. Omniscience databases are found in | |
425 | @code{semanticdb-project-system-databases}. The Emacs Lisp system | |
426 | @var{db} is an omniscience database. | |
427 | @end table | |
428 | ||
429 | @end defvar | |
430 | ||
431 | To set the throttle, use a command like this: | |
432 | ||
433 | @example | |
434 | (setq-mode-local c-mode | |
435 | semanticdb-find-default-throttle | |
436 | '(project unloaded system recursive)) | |
437 | @end example | |
438 | ||
439 | The default value of the throttle is for maximum accuracy at the | |
440 | expense of time taken to perform a particular look-up. The throttle | |
441 | is tweaked by @code{semantic-idle-summary-mode} to remove 'unloaded, | |
442 | thus removing poor speed at unexpected times. | |
443 | ||
444 | @node Semanticdb search debugging commands | |
445 | @subsubsection Semanticdb search debugging commands | |
446 | ||
447 | You can use @kbd{M-x semanticdb-dump-all-table-summary RET} to see the | |
448 | list of databases that will be searched from a given buffer. It | |
449 | should include DBs for the directories you expect. You can follow up | |
450 | with @kbd{M-x semanticdb-find-test-translate-path RET} to then make | |
451 | sure specific tables from the path are discovered correctly. | |
452 | ||
453 | Alternately, you can get a list of include files @semantic{} | |
454 | encountered, but could not find on disk using | |
455 | @kbd{M-x semanticdb-find-adebug-lost-includes RET}. | |
456 | ||
457 | Once you have used the below functions to debug the problem, you may | |
458 | need to reconfigure how @semantic{} finds include files. | |
459 | See @ref{Semanticdb Search Configuration}. If the search config is | |
460 | ok, you may need to configure the search throttle. See @ref{Search Throttle}. | |
461 | ||
462 | @deffn Command semanticdb-dump-all-table-summary | |
463 | @anchor{semanticdb-dump-all-table-summary} | |
464 | Dump a list of all databases in Emacs memory. | |
465 | @end deffn | |
466 | ||
467 | @deffn Command semanticdb-find-test-translate-path &optional arg | |
468 | @anchor{semanticdb-find-test-translate-path} | |
469 | Call and output results of @dfn{semanticdb-find-translate-path} | |
470 | With @var{arg} non-@code{nil}, specify a @var{brutish} translation. | |
471 | @end deffn | |
472 | ||
473 | @deffn Command semanticdb-find-adebug-lost-includes | |
474 | @anchor{semanticdb-find-adebug-lost-includes} | |
475 | Translate the current path, then display the lost includes. | |
476 | Examines the variable @code{semanticdb-find-lost-includes}. | |
477 | @end deffn | |
478 | ||
479 | Lastly, you can test an explicit search term using this command: | |
480 | ||
481 | @deffn Command semantic-adebug-searchdb regex | |
482 | @anchor{semantic-adebug-searchdb} | |
483 | Search the semanticdb for @var{regex} for the current buffer. | |
484 | Display the results as a debug list. | |
485 | @end deffn | |
486 | ||
487 | @node Changing Backends | |
488 | @subsection Changing Backends | |
489 | ||
490 | If you want to use some other form of backend, you can use this | |
491 | variable to choose which back end class to use for your general tag | |
492 | storage. | |
493 | ||
494 | The default is to save databases in flat files. Alternatively, you | |
495 | could write a new database backend that stores tags into a database, | |
496 | or other storage system. | |
497 | ||
498 | @defvar semanticdb-new-database-class | |
499 | @anchor{semanticdb-new-database-class} | |
500 | The default type of database created for new files. | |
501 | This can be changed on a per file basis, so that some directories | |
502 | are saved using one mechanism, and some directories via a different | |
503 | mechanism. | |
504 | @end defvar | |
505 | ||
506 | @node Script Generated Cache Files | |
507 | @subsection Script Generated Cache Files | |
508 | ||
509 | You can create new semantic databases with the @file{semanticdb.sh} | |
510 | script file. Give this script the directory you want parsed, and it | |
511 | will create a cache file for you. | |
512 | ||
513 | @example | |
514 | $ semanticdb.sh *.el | |
515 | @end example | |
516 | ||
517 | To use these generated tables, you would likely need to restart Emacs. | |
518 | ||
519 | @node Create System Databases | |
520 | @subsection Create System Databases | |
521 | ||
522 | If your supported language stores the system libraries in readily | |
523 | available parsable source code, you can pre-generate database files | |
524 | for them once, which will be used over and over for tools such as | |
525 | summary-mode, or the analyzer. | |
526 | ||
527 | @deffn Command semanticdb-create-ebrowse-database dir | |
528 | @anchor{semanticdb-create-ebrowse-database} | |
529 | Create an @var{ebrowse} database for directory @var{dir}. | |
530 | The database file is stored in ~/.semanticdb, or whichever directory | |
531 | is specified by @code{semanticdb-default-system-save-directory}. | |
532 | @end deffn | |
533 | ||
534 | ||
535 | @node Idle Scheduler | |
536 | @section Idle Scheduler | |
537 | @cindex Idle Scheduler | |
538 | ||
539 | The Idle Scheduler in @semantic{} performs multiple duties. | |
540 | ||
541 | The primary job is to schedule buffer parsing in idle time. The | |
542 | first buffer whose cache is checked is the current buffer. After | |
543 | this, all other buffers are checked. | |
544 | ||
545 | Once that has been accomplished, scheduled idle processes that use the | |
546 | semantic tag tables are run. | |
547 | ||
548 | @deffn Command global-semantic-idle-scheduler-mode &optional arg | |
549 | @anchor{global-semantic-idle-scheduler-mode} | |
550 | Toggle global use of option @dfn{semantic-idle-scheduler-mode}. | |
551 | The idle scheduler with automatically reparse buffers in idle time, | |
552 | and then schedule other jobs setup with @dfn{semantic-idle-scheduler-add}. | |
553 | If @var{ARG} is positive, enable, if it is negative, disable. | |
554 | If @var{ARG} is @code{nil}, then toggle. | |
555 | @obsolete{global-semantic-auto-parse-mode,global-semantic-idle-scheduler-mode} | |
556 | @end deffn | |
557 | ||
558 | @obsolete{semantic-auto-parse-mode, semantic-idle-scheduler-mode} | |
559 | ||
560 | @deffn Option semantic-idle-scheduler-idle-time | |
561 | @anchor{semantic-idle-scheduler-idle-time} | |
562 | Time in seconds of idle before scheduling events. | |
563 | This time should be short enough to ensure that idle-scheduler will be | |
564 | run as soon as Emacs is idle. | |
565 | @end deffn | |
566 | ||
567 | @deffn Option semantic-idle-scheduler-mode-hook | |
568 | @anchor{semantic-idle-scheduler-mode-hook} | |
569 | Hook run at the end of function @dfn{semantic-idle-scheduler-mode}. | |
570 | @end deffn | |
571 | ||
572 | @deffn Option semantic-idle-scheduler-verbose-flag | |
573 | @anchor{semantic-idle-scheduler-verbose-flag} | |
574 | Non-@code{nil} means that the idle scheduler should provide debug messages. | |
575 | Use this setting to debug idle activities. | |
576 | @end deffn | |
577 | ||
578 | You can add new functionality to the idle scheduler by reading the | |
579 | Application Developers Guide | |
580 | @inforef{Idle Scheduling, , semantic-appdev.info}. | |
581 | ||
582 | @menu | |
583 | * Reparsing Options:: Reparsing the current buffer in idle time | |
584 | * Idle Working Options:: Options for extra work done at idle time | |
585 | * Debugging Idle Time Issues:: How to produce good bug reports. | |
586 | * Idle Summary Mode:: Display prototype of symbol under cursor | |
587 | * Idle Completions Mode:: Smart completion pop-up help. | |
588 | @end menu | |
589 | ||
590 | @node Reparsing Options | |
591 | @subsection Reparsing Options | |
592 | ||
593 | The Idle Scheduler will automatically reparse all buffers that need | |
594 | it. User input at any time will cancel the operations and return to | |
595 | normal editing. | |
596 | ||
597 | @deffn Option semantic-idle-scheduler-max-buffer-size | |
598 | @anchor{semantic-idle-scheduler-max-buffer-size} | |
599 | Maximum size in bytes of buffers automatically reparsed. | |
600 | If this value is less than or equal to @var{0}, buffers are automatically | |
601 | reparsed regardless of their size. | |
602 | @end deffn | |
603 | ||
604 | @deffn Option semantic-idle-scheduler-no-working-message | |
605 | @anchor{semantic-idle-scheduler-no-working-message} | |
606 | If non-@code{nil}, disable display of working messages during parse. | |
607 | @end deffn | |
608 | ||
609 | @deffn Option semantic-idle-scheduler-working-in-modeline-flag | |
610 | @anchor{semantic-idle-scheduler-working-in-modeline-flag} | |
611 | Non-@code{nil} means show working messages in the mode line. | |
612 | Typically, parsing will show messages in the minibuffer. | |
613 | This will move the parse message into the modeline. | |
614 | @end deffn | |
615 | ||
616 | @defvar semantic-before-idle-scheduler-reparse-hooks | |
617 | @anchor{semantic-before-idle-scheduler-reparse-hooks} | |
618 | Hooks run before option @code{semantic-idle-scheduler} begins parsing. | |
619 | If any hook throws an error, this variable is reset to nil. | |
620 | This hook is not protected from lexical errors. | |
621 | @end defvar | |
622 | ||
623 | @defvar semantic-after-idle-scheduler-reparse-hooks | |
624 | @anchor{semantic-after-idle-scheduler-reparse-hooks} | |
625 | Hooks run after option @code{semantic-idle-scheduler} has parsed. | |
626 | If any hook throws an error, this variable is reset to nil. | |
627 | This hook is not protected from lexical errors. | |
628 | @end defvar | |
629 | ||
630 | @node Idle Working Options | |
631 | @subsection Idle Working Options | |
632 | ||
633 | Similiar to the reparsing that occurs at short intervals in idle | |
634 | time, there is extra work that can be controlled to occur in idle time | |
635 | also. | |
636 | ||
637 | Idle work occurs after a longer delay, and can be very time | |
638 | consuming. The work done includes: | |
639 | ||
640 | @table @asis | |
641 | @item Create Include Path Caches | |
642 | Create the optimized search caches needed for symbol lookup. | |
643 | @item Create Type Cache | |
644 | Create the datatype caches needed for intellisense features. | |
645 | @item Save Databases | |
646 | All file-based @semantic{} databases are saved to disk. | |
647 | @item Parse neighboring files | |
648 | All files in the same directory as the current buffer are | |
649 | speculatively parsed. | |
650 | @end table | |
651 | ||
652 | These features can be controlled with the following variables: | |
653 | ||
654 | @deffn Option semantic-idle-scheduler-work-idle-time | |
655 | @anchor{semantic-idle-scheduler-work-idle-time} | |
656 | Time in seconds of idle before scheduling big work. | |
657 | This time should be long enough that once any big work is started, it is | |
658 | unlikely the user would be ready to type again right away. | |
659 | @end deffn | |
660 | ||
661 | @deffn Option semantic-idle-work-parse-neighboring-files-flag | |
662 | @anchor{semantic-idle-work-parse-neighboring-files-flag} | |
663 | Non-@code{nil} means to parse files in the same dir as the current buffer. | |
664 | Disable to prevent lots of excessive parsing in idle time. | |
665 | @end deffn | |
666 | ||
667 | @node Debugging Idle Time Issues | |
668 | @subsection Debugging Idle Time Issues | |
669 | ||
670 | If you see errors produced in idle time, it could be an indication of a | |
671 | more serious issue elsewhere. It is not enough to enable | |
672 | @code{debug-on-error}, as the idle timer tries to keep errors under | |
673 | wraps. | |
674 | ||
675 | Instead, there are two commands you can use whenever you see an idle | |
676 | error. | |
677 | ||
678 | @deffn Command semantic-debug-idle-function | |
679 | @anchor{semantic-debug-idle-function} | |
680 | Run the Semantic idle function with debugging turned on. | |
681 | @end deffn | |
682 | ||
683 | @deffn Command semantic-debug-idle-work-function | |
684 | @anchor{semantic-debug-idle-work-function} | |
685 | Run the Semantic idle work function with debugging turned on. | |
686 | @end deffn | |
687 | ||
688 | Once you identify the general location of the idle error, you can send | |
689 | the stack trace to the mailing list, or perhaps find a more focused | |
690 | way to reproduce the issue. | |
691 | ||
692 | @node Idle Summary Mode | |
693 | @subsection Idle Summary Mode | |
694 | ||
695 | Similar to the Emacs Lisp facility eldoc, | |
696 | @code{semantic-idle-summary-mode} will display the prototype, or other | |
697 | helpful doc about the symbol currently under point. | |
698 | ||
699 | ||
700 | @deffn semantic-idle-summary-mode &optional arg | |
701 | @anchor{semantic-idle-summary-mode} | |
702 | Display a tag summary of the lexical token under the cursor. | |
703 | This means for getting the current tag to display information can | |
704 | be overriden with @code{idle-summary-current-symbol-info}. | |
705 | This is a minor mode which performs actions during idle time. | |
706 | With prefix argument ARG, turn on if positive, otherwise off. The | |
707 | minor mode can be turned on only if semantic feature is available and | |
708 | the current buffer was set up for parsing. Return non-nil if the | |
709 | minor mode is enabled | |
710 | @end deffn | |
711 | ||
712 | @obsolete{semantic-summary-mode, semantic-idle-summary-mode} | |
713 | ||
714 | @deffn Option semantic-idle-summary-function | |
715 | @anchor{semantic-idle-summary-function} | |
716 | Function to use when displaying tag information during idle time. | |
717 | Some useful functions are found in @code{semantic-format-tag-functions}. | |
718 | @end deffn | |
719 | ||
720 | @defvar semantic-idle-summary-out-of-context-faces | |
721 | @anchor{semantic-idle-summary-out-of-context-faces} | |
722 | List of font-lock faces that indicate a useless summary context. | |
723 | Those are generally faces used to highlight comments or strings. | |
724 | ||
725 | It might be useful to override this variable to add comment faces | |
726 | specific to a major mode. For example, in jde mode: | |
727 | ||
728 | @example | |
729 | (defvar-mode-local jde-mode semantic-idle-summary-out-of-context-faces | |
730 | (append (default-value 'semantic-idle-summary-out-of-context-faces) | |
731 | '(jde-java-font-lock-doc-tag-face | |
732 | jde-java-font-lock-link-face | |
733 | jde-java-font-lock-bold-face | |
734 | jde-java-font-lock-underline-face | |
735 | jde-java-font-lock-pre-face | |
736 | jde-java-font-lock-code-face))) | |
737 | @end example | |
738 | ||
739 | @end defvar | |
740 | ||
741 | @node Idle Completions Mode | |
742 | @subsection Idle Completions Mode | |
743 | ||
744 | The definition of smart completion is described in the Analyzer | |
745 | section @ref{Analyzer}. | |
746 | ||
747 | The Idle Completions mode will calculate the list of possible | |
748 | completions in idle time, and display them in a popup list, or other | |
749 | inline completion mechanism. | |
750 | ||
751 | @deffn semantic-idle-completions-mode &optional arg | |
752 | @anchor{semantic-idle-completions-mode} | |
753 | Display a tooltip with a list of possible completions near the cursor. | |
754 | There is no convenience for performing a completion replacement. For | |
755 | that you should bind @code{semantic-ia-complete-symbol}. | |
756 | This is a minor mode which performs actions during idle time. | |
757 | With prefix argument ARG, turn on if positive, otherwise off. The | |
758 | minor mode can be turned on only if semantic feature is available and | |
759 | the current buffer was set up for parsing. Return non-nil if the | |
760 | minor mode is enabled | |
761 | @end deffn | |
762 | ||
763 | This mode operates by using the command | |
764 | @code{semantic-complete-inline-analyzer}. | |
765 | ||
766 | Idle completion uses the completion function | |
767 | @code{semantic-complete-analyze-inline-idle}. Changing the behavior of | |
768 | the idle completion popups should be done through those utilities. | |
769 | ||
770 | @deffn Command semantic-complete-analyze-inline-idle | |
771 | @anchor{semantic-complete-analyze-inline-idle} | |
772 | Perform prompt completion to do in buffer completion. | |
773 | @dfn{semantic-analyze-possible-completions} is used to determine the | |
774 | possible values. | |
775 | The function returns immediately, leaving the buffer in a mode that | |
776 | will perform the completion. | |
777 | Configure @code{semantic-complete-inline-analyzer-idle-displayor-class} | |
778 | to change how completion options are displayed. | |
779 | @end deffn | |
780 | ||
781 | @deffn Option semantic-complete-inline-analyzer-idle-displayor-class | |
782 | @anchor{semantic-complete-inline-analyzer-idle-displayor-class} | |
783 | Class for displayor to use with inline completion at idle time. | |
784 | ||
785 | Customize this variable to get a list of options, such as popup | |
786 | tooltips, ghosting text, or traditional completion tools. | |
787 | @end deffn |