*cecscope.txt*  Charles E Campblell's Cscope Plugin         Sep 18, 2013

Author:  Charles E. Campbell  <NcampObell@SdrPchip.AorgM-NOSPAM>
         (remove NOSPAM from Campbell's email first)
Copyright: (c) 2004-2013 by Charles E. Campbell         *cecscope-copyright*
           The VIM LICENSE applies to cecscope.vim and cecscope.txt
           (see |copyright|) except use "cecscope" instead of "Vim".
           No warranty, express or implied.  Use At-Your-Own-Risk.
Note:    Required:
         * your :version of vim must have +cscope
         * vim 7.0aa snapshot#188 or later for the "quickfix" display

1. Contents                                     *cecscope-contents*

  1. Contents............................: |cecscope-contents|
  2. Installing cecscope.................: |cecscope-install|
  3. Cescope Manual......................: |cecscope-manual|
  3. Cescope Tutorial....................: |cecscope-tutorial|
  5. Cescope History.....................: |cecscope-history|

2. Installing cecscope                        *cecscope-install*

    1. vim cecscope.vba.gz
    2. :so %
    3. :q

    Cecscope now requires vim 7.2 or later; it uses the fnameescape() function
    to avoid certain security problems.  It is possible to use "carefully
    crafted filenames" to cause vim to execute arbitrary commands otherwise.
    Admittedly, most such filenames are obviously bad apples.

    Using vim 7.2 also means that your vimball plugin is reasonably
    up-to-date, which is used by the install process.

3. Cescope Manual                           *cecscope-manual*
                                           *:CS* *:CSL* *:CSS* *:CSH*
    :CS     [cdefgist]   : cscope command handler
    :CSL[!] [cdefgist]   : locallist/quickfix style (! restores efm)
    :CSS[!] [cdefgist]   : split window and use cscope
    :CSH                 : give quick help on how to use cecscope
    :CSR                 : cscope reset

    !            split vertically
    c (calls)    find functions calling function under cursor
    d (called)   find functions called by function under cursor
    e (egrep)    egrep search for the word under cursor
    f (file)     open the file named under cursor
    g (global)   find global definition(s) of word under cursor
    i (includes) find files that #include file named under cursor
    s (symbol)   find all references to the word under cursor
    t (text)     find all instances of the word under cursor

    A simple >
<   will initialize cscope, building its database if necessary.  What
    :CS will do: >

        if <cscope.out> exists in the current directory:
           "cs add" it.
        else if $CSCOPE_DB (an environment variable) exists and the
           file it references exists:
           "cs add" it.
        else if <cscope.out> exists in any directory from the current
           directory or in any parent directory up to but not
           including the $HOME directory:
           "cs add" it.
           Also: search upwards from current file's directory if
           it happens to differ from the getcwd();
           "cs add" any <cscope.out> files found.
        else if &csprg is executable, apply &csprg -b to the current file.
    Thus :CS will search for and attempt to use a cscope database,
    building one if necessary.

    In addition, when using gvim, there is a menu interface under the
    "DrChip" label with all of the above options mentioned.  The first
    four items are taken from:

        Use Messages Display
        Use Horiz Split Display
        Use Vert Split Display
        Use Quickfix Display

    The "Use" method that's currently active will not be present (initially,
    that's the "Use Messages Display").

    For special options to be passed to cscope for database building, set
    g:cecscope_dboptions to the desired string.  For example, to use all
    source files in a so-called namefile: >
        let g:cecscope_dboptions= "-inamefile"
<   One must explicitly list *.cpp, *.c++, and *.C files, for example, in
    such a file.

    By default, the |location-list| for cecscope, used for displaying results,
    is given by: >
        let g:cecscope_height= 5
<   You may change this in your .vimrc (Windows: _vimfiles) file.

    By default, the :CSR command ("cscope reset") resets the connection and
    rebuilds the database.  If this option is set (to a non-zero value), only
    the connection will be reset.

4. Cescope Tutorial                              *cecscope-tutorial*

    To use this plugin you'll need to have vim 7.0aa, snapshot#188 or later,
    and your version should have +cscope.  To check that latter condition,
    either look for +cscope through the output of >
<   or type >
        :echo has("cscope")
<   You'll need to recompile your vim if you don't have +cscope.

    Once you have your cscope-enabled vim, then change directory to wherever
    you have some C code.  Type >
        cscope -b *.[ch]
<   and the cscope database will be generated (<cscope.out>).  If you don't
    have a cscope database, the file specified by the environment variable
    named >
<   will be used.  Sadly, otherwise cecscope.vim will issue a warning message.


    Assuming you're using gvim: Select >
        DrChip:Cscope:Use Quickfix Display
<   This will make the information from cscope show up in a local quickfix
    window (see |:lopen|).  The other modes allow one to see cscope messages
    as regular messages (which will shortly disappear) or in another window.

    Place your cursor atop some function that you've written: >
        DrChip:Cscope:Find function which calls word under cursor
<   and you'll see a locallist window open up which tells you something like >
        xgrep.c|410 info| <<sprt>> Edbg(("xgrep(%s)",sprt(filename)));
<   To jump to that entry, type >
<   To jump to the next entry, type >
<   To jump to the previous entry, type >
<   You can also switch windows (ex. <ctrl-w>j, see |window-move-cursor|)
    to the locallist window, move the cursor about normally, then hit the
    <cr> to jump to the selection.

    You could've done the above using the command line!  Again, just
    place your cursor atop some function that you've written, then type: >
        :CSL c
<   You may use the :ll, :lne, and :lp commands as before.

    Just type >
<   for a quick help display.  Of course, you can always type : >
        :help CS
<   too.

5. Cescope History                                *cecscope-history*

    v5  Nov 25, 2008    * csqfkeep wasn't always defined when used; fixed
        Jun 23, 2009    * |'csprg'| option used to specify cscope program
        Oct 11, 2010    * included search from current file's directory upwards
        Feb 22, 2011    * for menus, &go =~# used to insure correct case
        Apr 27, 2012    * (Saurabh Sarpal) provided a patch for
        Sep 18, 2013    * (Saurabh Sarpal) provided a patch instituting
                          the |g:cecscope_no_rebuild| option
    v4  Nov 12, 2008    * csqf kept if has("quickfix") is true
                        * vim 7.2 required, and warning message is issued if
                          vim isn't 7.2 (or later)
                        * fnameescape() used for security purposes (thus vim 7.2)
                        * help menu fixed
    v3  Oct 12, 2006    * removed "silent" from cscope calls; it prevented the
                          selector from appearing.
    v1  Jan 30, 2006    * initial release