Skip to content

Help

Jump to bottom Edit New page
hari-rangarajan edited this page Sep 14, 2017 · 1 revision

Help

*CCTree.txt* Plugin for C Call-Tree Explorer *CCTree*

Author: Hari Rangarajan (First.Last AT gmail DOT com)
Last Change: 20 March. 2011

CCTree version 1.20

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

CCTree generates call-trees for any function or macro in real-time inside Vim.
Requires Cscope and operation is limited to C code for now.

==============================================================================
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 WIN32 versions are available at the following locations:
http://www.geocities.com/shankara_c/cscope.html
http://www.bell-labs.com/project/wwexptools/packages.html
http://iamphet.nm.ru/cscope/index.html

==============================================================================
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
CCTreeAppendDB
CCTreeUnLoadDB
CCTreeShowLoadedDBs
Refer to |CCTree-usage|

Native Xref Database~
CCTreeLoadXRefDB
CCTreeSaveXRefDB 

                            Refer to <font color="#ffffff">|</font><font color="#008b8b">CCTree-fast-loading</font><font color="#ffffff">|</font>

Symbol tracing
CCTreeTraceForward
CCTreeTraceReverse
CCTreeRecurseDepthPlus
CCTreeRecurseDepthMinus
Refer to |CCTree-explore-source|
Trace Management
CCTreeWindowSaveCopy
CCTreeWindowHiCallTree
Refer to |CCTree-preview-window|

Dynamic configuration
CCTreeOptsEnable ( for auto-complete)
CCTreeOptsDisable ( for auto-complete)
CCTreeOptsToggle ( for auto-complete)
Options
DynamicTreeHiLights: Control dynamic tree highlighting
UseUnicodeSymbols: Use of UTF-8 special characters for tree

**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       <font color="#6a5acd"><CR></font>  
  Preview symbol in other window    <font color="#6a5acd"><Ctrl-P></font>  

  Save copy of preview window       <font color="#6a5acd"><C-\></font>y  
  Highlight current call-tree flow  <font color="#6a5acd"><C-l></font>  
  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 = '' " 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.

5.2. Exploring source-code~
CCTree-explore-source

Get reverse call tree for symbol <C-><
>
:CCTreeTraceReverse
<

Get forward call tree for symbol <C->>
>
:CCTreeTraceForward
<
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
Preview symbol in other window

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 <font color="#ffffff">|</font><font color="#008b8b">perl-using</font><font color="#ffffff">|</font> or :help <font color="#ffffff">|</font><font color="#008b8b">perl-dynamic</font><font color="#ffffff">|</font>

5.6. Miscellaneous CCTree-Miscellaneous

    UTF-8 usage                             <font color="#ffffff">*</font><font color="#ff00ff">CCTree-UTF8-Symbols</font><font color="#ffffff">*</font>  
        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:

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

  • Functions inside macro definitions will be incorrectly attributed to the top
    level calling function

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

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 :)
Add a custom footer
Add a custom sidebar
Clone this wiki locally