537 lines
18 KiB
Text
537 lines
18 KiB
Text
*CCTree.txt* Plugin for C Call-Tree Explorer *CCTree*
|
|
|
|
Author: Hari Rangarajan (First.Last AT gmail DOT com)
|
|
Last Change: 20 May 2011
|
|
|
|
CCTree version 1.51
|
|
|
|
For Vim version 7.0 and above
|
|
|
|
==============================================================================
|
|
|
|
1. Overview |CCTree-overview|
|
|
2. Downloads |CCTree-download|
|
|
3. Installation |CCTree-installation|
|
|
4. Configuration |CCTree-configuration|
|
|
5. Features |CCTree-features|
|
|
6. Limitations |CCTree-limitations|
|
|
7. FAQ & TIPS |CCTree-faq|
|
|
8. History |CCTree-history|
|
|
9. Thanks |CCTree-thanks|
|
|
|
|
==============================================================================
|
|
1. Overview~
|
|
*CCTree-overview*
|
|
|
|
Plugin generates dependency-trees for symbols using a cscope database in Vim.
|
|
Basic cross-referencing includes functions and macros. Enhanced symbol
|
|
processing covers macros, typedefs, enums, and global variables.
|
|
|
|
Requires Cscope and works best with C code.
|
|
|
|
==============================================================================
|
|
2. Downloads~
|
|
*CCTree-download*
|
|
|
|
You can download the latest release of the script from this url :
|
|
http://www.vim.org/scripts/script.php?script_id=2368
|
|
|
|
|
|
Cscope packages can be found here:
|
|
http://cscope.sourceforge.net/
|
|
http://code.google.com/p/cscope-win32/
|
|
|
|
|
|
==============================================================================
|
|
3. Installation~
|
|
*CCTree-installation*
|
|
|
|
Copy this file to ~/.vim/plugins/ or to /vimfiles/plugins/ (on Win32
|
|
platforms)
|
|
|
|
It should also be possible to load it as a filetype plugin ~/.vim/ftplugin/c/
|
|
Need to set :filetype plugin on
|
|
|
|
|
|
==============================================================================
|
|
CONFIGURATION *CCTree-configuration*
|
|
4. Options~
|
|
|
|
You can customize behavior by changing the following variable settings
|
|
|
|
4.1.1 Cscope Symbol Database~
|
|
*CCTreeCscopeDb*
|
|
|
|
Cscope database file, g:CCTreeCscopeDb = "cscope.out"
|
|
|
|
4.1.2 Call-tree Depth~
|
|
*CCTreeRecursiveDepth*
|
|
Maximum call levels, g:CCTreeRecursiveDepth = 3
|
|
|
|
4.1.3 Call-tree Minimum Visible Depth~
|
|
*CCTreeMinVisibleDepth*
|
|
Maximum visible(unfolded) level, g:CCTreeMinVisibleDepth = 3
|
|
|
|
4.1.4 Call-tree window display~
|
|
|
|
4.4.1 Orientation~
|
|
*CCTreeOrientation*
|
|
Orientation of window, g:CCTreeOrientation = "leftabove"
|
|
(standard vim options for split: [right|left][above|below])
|
|
|
|
4.5 Direction~
|
|
*CCTreeWindowVertical*
|
|
Use Vertical window, g:CCTreeWindowVertical = 1
|
|
|
|
4.5.1 Dimensions~
|
|
|
|
These settings determine the layout of the CCTree preview window.
|
|
|
|
4.5.2 Horizontal Window Settings~
|
|
*CCTreeWindowHeight*
|
|
Horizontal window, g:CCTreeWindowHeight, default is -1.
|
|
|
|
4.5.2 Vertical Window Settings~
|
|
*CCTreeWindowMinWidth*
|
|
*CCTreeWindowWidth*
|
|
Minimum width for window, g:CCTreeWindowMinWidth = 40.
|
|
g:CCTreeWindowWidth = -1, auto-select best width to fit.
|
|
|
|
|
|
4.6 Call-tree display format~
|
|
*CCTreeDisplayMode*
|
|
Display format, g:CCTreeDisplayMode, default: 1
|
|
|
|
Values: 1 -- Ultra-compact (takes minimum screen width)
|
|
2 -- Compact (Takes little more space)
|
|
3 -- Wide (Takes copious amounts of space)
|
|
|
|
For vertical splits, 1 and 2 are good, while 3 is good for horizontal
|
|
displays.
|
|
|
|
4.7. Dynamic Call-tree highlighting~
|
|
*CCTreeHilightCallTree*
|
|
|
|
Enable/disable dynamic call-tree highlighting, default: 1
|
|
|
|
|
|
4.7.1 Syntax items~
|
|
*CCTreeSymbol* *CCTreeHiSymbol*
|
|
CCTreeSymbol is the symbol name.
|
|
CCTreeHiSymbol is the highlighted call tree functions.
|
|
|
|
*CCTreeMarkers* *CCTreeHiMarkers*
|
|
CCTreeMarkers include "|","+--->".
|
|
CCTreeHiMarkers is the same as CCTreeMarkers except these denote the
|
|
highlighted call-tree.
|
|
|
|
|
|
|
|
==============================================================================
|
|
COMMAND LIST *CCTree-commands-list*
|
|
|
|
Database Management~
|
|
CCTreeLoadDB <dbname>
|
|
CCTreeAppendDB <dbname>
|
|
CCTreeUnLoadDB
|
|
CCTreeShowLoadedDBs
|
|
Refer to |CCTree-usage|
|
|
|
|
Native Xref Database~
|
|
CCTreeLoadXRefDB <dbname>
|
|
CCTreeSaveXRefDB <dbname>
|
|
|
|
Refer to |CCTree-fast-loading|
|
|
|
|
Symbol tracing~
|
|
CCTreeTraceForward <symbolname>
|
|
CCTreeTraceReverse <symbolname>
|
|
CCTreeRecurseDepthPlus
|
|
CCTreeRecurseDepthMinus
|
|
Refer to |CCTree-explore-source|
|
|
Trace Management~
|
|
CCTreeWindowSaveCopy
|
|
CCTreeWindowHiCallTree
|
|
Refer to |CCTree-preview-window|
|
|
|
|
Dynamic configuration~
|
|
CCTreeOptsEnable <option> (<tab> for auto-complete)
|
|
CCTreeOptsDisable <option> (<tab> for auto-complete)
|
|
CCTreeOptsToggle <option> (<tab> for auto-complete)
|
|
Options~
|
|
DynamicTreeHiLights: Control dynamic tree highlighting
|
|
UseUnicodeSymbols: Use of UTF-8 special characters for tree
|
|
UseConceal: Use (+Conceal) feature instead of 'ignore'
|
|
syntax highlighting. Allows CCTree window
|
|
to be exported in HTML without syntax markup
|
|
characters. (Vim 7.3+ only)
|
|
*CCTree-Enhanced-Symbol-Processing*
|
|
EnhancedSymbolProcessing: Cross-reference enums, macros,
|
|
global variables, typedefs (WARNING: Database
|
|
processing speeds will be slow).
|
|
|
|
SHORTCUT KEYS *CCTree-Key-Map*
|
|
Default Mappings~
|
|
*CCTree-Default-Key-Map*
|
|
Get reverse call tree for symbol <C-\><
|
|
Get forward call tree for symbol <C-\>>
|
|
Increase depth of tree and update <C-\>=
|
|
Decrease depth of tree and update <C-\>-
|
|
|
|
Open symbol in other window <CR>
|
|
Preview symbol in other window <Ctrl-P>
|
|
|
|
Save copy of preview window <C-\>y
|
|
Highlight current call-tree flow <C-l>
|
|
Compress(Fold) call tree view zs
|
|
(This is useful for viewing long
|
|
call trees which span across
|
|
multiple pages)
|
|
|
|
Custom user-mappings
|
|
*CCTree-Custom-Key-Map*
|
|
Users can custom-map the short-cut keys by
|
|
overriding the following variables in their
|
|
Vim start-up configuration
|
|
>
|
|
let g:CCTreeKeyTraceForwardTree = '<C-\>>'
|
|
let g:CCTreeKeyTraceReverseTree = '<C-\><'
|
|
let g:CCTreeKeyHilightTree = '<C-l>' " Static highlighting
|
|
let g:CCTreeKeySaveWindow = '<C-\>y'
|
|
let g:CCTreeKeyToggleWindow = '<C-\>w'
|
|
let g:CCTreeKeyCompressTree = 'zs' " Compress call-tree
|
|
let g:CCTreeKeyDepthPlus = '<C-\>='
|
|
let g:CCTreeKeyDepthMinus = '<C-\>-'
|
|
<
|
|
|
|
==============================================================================
|
|
FEATURES *CCTree-features*
|
|
|
|
5.1. Symbol database~
|
|
*CCTree-usage*
|
|
Build cscope database, for example:
|
|
> cscope -b -i cscope.files
|
|
[Tip: add -c option to build uncompressed databases for faster
|
|
load speeds]
|
|
|
|
Load database~
|
|
>
|
|
:CCTreeLoadDB
|
|
<
|
|
(Please note that it might take a while depending on the
|
|
database size)
|
|
|
|
A database name, i.e., my_cscope.out, can be specified with the command. If
|
|
not provided, a prompt will ask for the filename; default is cscope.out.
|
|
|
|
Unload database ~
|
|
>
|
|
:CCTreeUnLoadDB
|
|
<
|
|
Append database~
|
|
>
|
|
:CCTreeAppendDB
|
|
<
|
|
Allows multiple cscope files to be loaded and cross-referenced
|
|
Illustration: >
|
|
:CCTreeAppendDB ./cscope.out
|
|
:CCTreeAppendDB ./dir1/cscope.out
|
|
:CCTreeAppendDB ./dir2/cscope.out
|
|
<
|
|
A database name, i.e., my_cscope.out, can be specified with
|
|
the command. If not provided, a prompt will ask for the
|
|
filename; default is cscope.out.
|
|
|
|
FASTER DATABASE LOADING *CCTree-fast-loading*
|
|
|
|
Save native Xref Db~
|
|
>
|
|
:CCTreeSaveXRefDb cctree.out
|
|
<
|
|
This command will save the cross-referenced symbols currently loaded into
|
|
memory into a serialized format for faster loading.
|
|
|
|
Load native XRef Db~
|
|
>
|
|
:CCTreeLoadXRefDb cctree.out
|
|
<
|
|
This command will load cross-referenced symbols from the previously saved
|
|
native format database.
|
|
|
|
ccglue~
|
|
*CCTree-ccglue*
|
|
|
|
Check out the ccglue project at http://ccglue.sourceforge.net for an external
|
|
tool that can build cctree-compatible xref databases.
|
|
|
|
|
|
5.2. Exploring source-code~
|
|
*CCTree-explore-source*
|
|
|
|
Get reverse call tree for symbol <C-\><
|
|
>
|
|
:CCTreeTraceReverse <symbolname>
|
|
<
|
|
|
|
Get forward call tree for symbol <C-\>>
|
|
>
|
|
:CCTreeTraceForward <symbolname>
|
|
<
|
|
Increase depth of tree and update <C-\>=
|
|
>
|
|
:CCTreeRecurseDepthPlus
|
|
<
|
|
Decrease depth of tree and update <C-\>-
|
|
>
|
|
:CCTreeRecurseDepthMinus
|
|
<
|
|
5.3. Preview Window~
|
|
*CCTree-preview-window*
|
|
Open symbol in other window <CR>
|
|
Preview symbol in other window <Ctrl-P>
|
|
|
|
5.4. Syntax Coloring~
|
|
*CCTree-Syntax*
|
|
CCTreeHiXXXX allows dynamic highlighting of the call-tree. To observe the
|
|
effect, move the cursor to the function to highlight the current call-tree.
|
|
This option can be turned off using the setting, *CCTreeHilightCallTree* .
|
|
|
|
For faster highlighting, the value of 'updatetime' can be changed.
|
|
|
|
5.5 Support for large database files~
|
|
*CCTree-LargeDatabase* *CCTree-LargeFile*
|
|
Vimscript does not have an API for reading files line-by-line. This
|
|
becomes a problem when parsing large databases. CCTree can overcome
|
|
the limitation using an external utility (i.e., GNU coreutils: split)
|
|
or VimScript's perl interpreter interface (:version must indicate +perl)
|
|
|
|
5.5.1 Using GNU Coreutils (split/cat)~
|
|
*CCTree-Tools-split* *CCTree-Tools-cat*
|
|
The following settings are tailored to suit GNU coreutils split; the
|
|
default settings should work with no changes on typical linux/unix distros.
|
|
Monopoly OSes will require installation of unixutils or equivalent.
|
|
|
|
External command is setup with the following parameters~
|
|
>
|
|
let g:CCTreeSplitProgCmd =
|
|
'PROG_SPLIT SPLIT_OPT SPLIT_SIZE IN_FILE OUT_FILE_PREFIX'
|
|
<
|
|
|
|
Break-down of individual parameters~
|
|
The split utility is assumed to be on the path; otherwise, specify full path
|
|
g:CCTreeSplitProg = 'split'
|
|
|
|
Option for splitting files (-C or -l)~
|
|
>
|
|
let g:CCTreeSplitProgOption = '-C'
|
|
<
|
|
If split program does not support -C, then this parameter must be set to
|
|
the number of lines in the split files
|
|
>
|
|
let g:CCTreeDbFileSplitLines = -1
|
|
<
|
|
Largest filesize Vimscript can handle; file sizes greater than this will
|
|
be temporarily split
|
|
>
|
|
let g:CCTreeDbFileMaxSize = 40000000 (40 Mbytes)
|
|
<
|
|
Sample system command~
|
|
Typical:
|
|
>
|
|
split -C 40000000 inputFile outputFilePrefix
|
|
<
|
|
When g:CCTreeDbFileSplitLines is set to 10000 (-C options will be ignored)
|
|
>
|
|
split -l 10000 inputFile outputFilePrefix
|
|
<
|
|
*CCTree-Tools-Perl*
|
|
*CCTree-Tools-Perl-LargeFile*
|
|
Enabling perl interface~
|
|
|
|
By default, perl usage is disabled. Set
|
|
>
|
|
let g:CCTreeUsePerl = 1
|
|
< to enable the perl interface.
|
|
|
|
Perl interface is typically faster than native Vimscript.
|
|
This option can be used independent of the file size
|
|
|
|
For more info on setting up perl interface
|
|
:help |perl-using| or :help |perl-dynamic|
|
|
|
|
5.6. Miscellaneous *CCTree-Miscellaneous*
|
|
|
|
UTF-8 usage *CCTree-UTF8-Symbols*
|
|
UTF-8 symbols should work fine on the majority of
|
|
X11 systems; however, some terminals might cause problems.
|
|
|
|
To use symbols for drawing the tree, this option can be enabled.
|
|
>
|
|
let g:CCTreeUseUTF8Symbols = 1
|
|
<
|
|
The options interface (CCTreeOptsxxx) can be used to
|
|
modify options on-the-fly.
|
|
|
|
==============================================================================
|
|
6. Limitations~
|
|
*CCTree-limitations*
|
|
|
|
The following are known limitations:
|
|
|
|
Basic Symbol Processing:
|
|
(1) The accuracy of the call-tree will only be as good as the cscope database
|
|
generation. (NOTE: Different flavors of Cscope have some known limitations
|
|
due to the lexical analysis engine. This results in incorrectly identified
|
|
function blocks, etc.)
|
|
|
|
Enhanced Symbol Processing:
|
|
(1) Cscope does not mark-up nameless enums correctly; hence,
|
|
CCTree cannot recognize nameless enum symbols.
|
|
|
|
|
|
==============================================================================
|
|
7. FAQ~
|
|
*CCTree-faq*
|
|
|
|
+ I see strange characters "!#@" on my screen when dynamic highlighting is
|
|
enabled. Why do I see them?
|
|
|
|
Check :hi ignore. You will see something like
|
|
hi ignore ctermfg=white guifg=bg
|
|
|
|
For console, white must be your background color; for GUI, guifg must be set
|
|
to bg.
|
|
|
|
==============================================================================
|
|
8. History~
|
|
*CCTree-history*
|
|
Version 1.51: May 18, 2011
|
|
1. Robust error reporting when external (split/cat) utils fail
|
|
|
|
Version 1.50: May 6, 2011
|
|
1. Support cross-referencing of global variables, macros,
|
|
enums, and typedefs.
|
|
|
|
Version 1.40: April 22, 2011
|
|
1. Maintain order of functions called during forward tracing
|
|
|
|
Version 1.39: April 18, 2011
|
|
1. Use +Conceal feature for highlighting (only Vim 7.3)
|
|
|
|
Version 1.33: April 5, 2011
|
|
1. Load and trace CCTree native XRefDb directly from disk
|
|
2. Fix AppendDB command when 'ignorecase' is set
|
|
|
|
Version 1.26: March 28, 2011
|
|
1. Fix macro cross-referencing limitation
|
|
2. Correct native xref file format
|
|
|
|
Version 1.21: March 21, 2011
|
|
1. Support serialization of loaded
|
|
cscope databases (for faster loading)
|
|
|
|
Version 1.07: March 09, 2011
|
|
1. Fix new keymaps incorrectly applied to buffer
|
|
2. CCTreeOptsToggle command for toggling options
|
|
|
|
Version 1.04: March 06, 2011
|
|
1. Customization for key mappings
|
|
2. Dynamic configuration of UI variables
|
|
3. Folding long call-trees to show current path dynamically
|
|
|
|
Version 1.01: March 04, 2011
|
|
1. Make UTF-8 symbols for tree optional
|
|
|
|
Version 1.00: March 02, 2011
|
|
1. Staging release for upcoming features
|
|
- Complete refactoring of code to take
|
|
advantage of VimScript's OO features
|
|
2. Faster decompression of symbols
|
|
3. Display related changes
|
|
- Use of unicode symbols for tree
|
|
4. Bugfixes related to multi-database loading
|
|
|
|
Version 0.90: February 18, 2011
|
|
1. Support for large databases using external split utility or perl
|
|
interface
|
|
|
|
Version 0.85: February 9, 2011
|
|
1. Significant increase in database loading and decompression speeds
|
|
|
|
Version 0.80: February 4, 2011
|
|
1. Reduce memory usage by removing unused xref symbols
|
|
|
|
Version 0.75: June 23, 2010
|
|
1. Support for saving CCTree preview window; multiple
|
|
CCTree windows can now be open
|
|
|
|
ersion 0.71: May 11, 2010
|
|
1. Fix script bug
|
|
|
|
Version 0.70: May 8, 2010
|
|
1. Functionality to load multiple cscope databases
|
|
|
|
Version 0.65: July 12, 2009
|
|
1. Toggle preview window
|
|
|
|
Version 0.61: December 24, 2008
|
|
1. Fixed bug when processing include files
|
|
2. Remove 'set ruler' option
|
|
|
|
Version 0.60: November 26, 2008
|
|
1. Added support for source-file dependency tree
|
|
|
|
Version 0.50: October 17, 2008
|
|
1. Optimizations for compact memory foot-print and
|
|
improved compressed-database load speeds
|
|
|
|
Version 0.41: October 6, 2008
|
|
1. Minor fix: Compressed cscope databases will load
|
|
incorrectly if encoding is not 8-bit
|
|
|
|
Version 0.4: September 28, 2008
|
|
1. Rewrite of display-related code
|
|
2. New syntax hightlighting
|
|
3. Dynamic highlighting for call-trees
|
|
4. Support for new window modes (vertical, horizontal)
|
|
5. New display format option for compact or wide call-trees
|
|
6. Preview window fix
|
|
|
|
Version 0.3: September 21, 2008
|
|
1. Support compressed cscope databases
|
|
2. Display window related bugs fixed
|
|
3. More intuitive display and folding capabilities
|
|
|
|
Version 0.2: September 12, 2008
|
|
(Patches from Yegappan Lakshmanan, thanks!)
|
|
1. Support for using the plugin in Vi-compatible mode
|
|
2. Filtering out unwanted lines before processing the db
|
|
3. Command-line completion for the commands
|
|
4. Using the cscope db from any directory
|
|
|
|
Version 0.1: August 31,2008
|
|
1. Cross-referencing support for only functions and macros
|
|
(Note: Functions inside macro definitions will be incorrectly
|
|
attributed to the top level calling function)
|
|
|
|
|
|
==============================================================================
|
|
9. Thanks~
|
|
*CCTree-thanks*
|
|
|
|
|
|
Qaiser Durrani (ver 1.51 -- Reporting issues with SunOS)
|
|
Ben Fritz (ver 1.39 -- Suggestion/Testing for
|
|
conceal feature)
|
|
Ben Fritz (ver 1.26 -- Bug report)
|
|
Frank Chang (ver 1.0x -- testing/UI enhancement
|
|
ideas/bug fixes)
|
|
Arun Chaganty/Timo Tiefel (Ver 0.60 -- bug report)
|
|
Michael Wookey (Ver 0.40 -- Testing/bug report/patches)
|
|
Yegappan Lakshmanan (Ver 0.20 -- Patches)
|
|
|
|
The Vim Community, ofcourse :)
|
|
|
|
|
|
vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl:
|
|
|