vimrc/bundle/cctree/doc/cctree.txt

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

Author: Hari Rangarajan (First.Last AT gmail DOT com)
Last Change: 17 June 2011

CCTree version 1.53

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>
      CCTreeLoadXRefDBFromDisk	 <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.
                     Feature is DISABLED by default for this reason)
 
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*
5.7.   Session serialization                    *CCTree-Database-Serialization*

        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.

        Notes: No merging database support for CCTree native DB's [at present].

        Trace native XRef Db from disk~
                                        *CCTree-Database-Load-Instantaneously*

        Load and trace CCTree native XRefDb directly from disk, use command
        ":CCTreeLoadXRefDBFromDisk "

>
           :CCTreeLoadXRefDBFromDisk cctree.out
<
        
        The command traces symbols on-demand from disk; occupies no memory and 
        is pretty quick under reasonable usage.

       Load database from memory or disk~
                                        *CCTree-Database-Memory-Speed-Trade-off*

       |CCTreeLoadXRefDB| loads the symbols on disk into memory, this will
       result in faster construction of call-trees, whereas the
       |CCTreeLoadXRefDBFromDisk| command traces the call-trees from disk,
       saving memory while sacrificing speed. Users can choose between the 
       two depending on requirements.

       Writing large Xref Databases~
                                                 *CCTree-Large-Xref-Databases*

       CCTree can use external utilities to write extremely large files beyond
       VimScripts capabilities. It requires the use of an external tool that can
       join text files (i.e., 'cat' in unix). This utility is triggered if the size
       of the file being written exceeds g:CCTreeDbFileMaxSize (40 Mb or as 
       configured)

       The join utility command is configured by default as follows:
       let CCTreeJoinProgCmd = 'PROG_JOIN JOIN_OPT IN_FILES > OUT_FILE'

       let  g:CCTreeJoinProg = 'cat'           " PROG_JOIN
       let  g:CCTreeJoinProgOpts = ""          " JOIN_OPT

ccglue~
                                                       *CCTree-ccglue*

Check out the ccglue project at http://ccglue.sourceforge.net for an external
tool that can build cctree-compatible xref databases, which can be loaded
and updated very quickly.


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.53: June 17, 2011
      1. Bug fix related to appending cscope databases
      2. Bug fix related to loading xref databases

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*


   Ben Fritz                      (ver 1.53 -- Bug reports on database append/load)
   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: