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
        :CS
   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:

        Help
        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").

    g:cecscope_dboptions
    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.

    g:cecscope_height
    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.

    g:cecscope_no_rebuild
    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

   GETTING STARTED
    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
        :version
   or type
        :echo has("cscope")
   You'll need to recompile your vim if you don't have +cscope.

    BUILDING CSCOPE DATABASE
    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
        $CSCOPE_DB
   will be used.  Sadly, otherwise cecscope.vim will issue a warning message.

    SELECTING A DISPLAY MODE

    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.

    USING THE QUICKFIX DISPLAY
    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
        :ll
   To jump to the next entry, type
        :lne
   To jump to the previous entry, type
        :lp
   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.

    USING THE COMMAND LINE
    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.

    HELP
    Just type
        :CSH
   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
                          g:cecscope_height
        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

=====================================================================
vim:tw=78:ts=8:ft=help:sts=4:et:ai