trailblazing / cscope_auto Goto Github PK

```
:::text

cscope_auto

cscope_auto was derived from cscope_dynamic.
It introduced g:file_extensions to custmize your c/c++ file extensions in the
.vimrc/init.vim. Once got settings completed, forget it. No further
interactions is necessary.

A Vim plugin that enables very fast automatic cscope database updates for C/C++
codebases. It accomplishes this by using two cscope databases; a large one, and
a small one. When a file is written it is moved to the small database, which
can update in a matter of seconds - often sub-second. The file is then removed
from the large database to avoid duplicate cscope query results. Subsequent
writes to the same file only trigger a small database update. The initial move
from the large to small database is a one time cost. This works well because
you're often only modifying a subset of files at a time.

===============================================================================
===============================================================================

1. Installation
1.1 cscope key maps
1.2 Dependencies
2. Configurables
2.1 Variables
2.2 Hooks
3. Tricks
3.1 Status Line Indicator
4. Compatibility
5. Development
6. References




1. Installation
===============================================================================
vim-packager

    function! s:packager_init(plugin_dir, package_manager) abort
        call packager#add('trailblazing/cscope_auto', { 'type' : 'opt',
                \ 'requires' : 'trailblazing/boot' })
    endfunction
    call s:packager_init(g:plugin_dir['vim'], g:package_manager['vim'])

Or clone the repository[6] into your ~/.vim/pack/*/opt/ directory.

Alternatively you can grab a vimball release from the downloads
section[1][2][4][9] .  Then install it the standard vimball way.
    Generate wimball from source
    $ make
    Installation
    vim -b ./cscope_auto.vmb
    :so %
    :q

1.1 cscope key maps
=======================================
The plugin does not provide key maps for searching the database. You should
also install cscope_maps.vim[5] from the cscope project to get the "default"
cscope key maps.


1.2 Dependencies
References [7], [8] is the current dependency.

2. Configurables
===============================================================================

2.1 Variables
=======================================
There are some variables that can be set changes the behavior of cscope_auto.

You could custimze the file extensions and g:directory_for_scan in .vimrc.local
under the current work directory (your project root):

let g:directory_for_scan = ["vinit"]
let g:directory_for_scan += ["zinit"]
let g:directory_for_scan += ["tinit"]

let g:file_extensions = ["*.vim"]
" let g:file_extensions += ["*.h"]
" let g:file_extensions += ["*.c"]
" let g:file_extensions += ["*.H"]
" let g:file_extensions += ["*.C"]
" let g:file_extensions += ["*.hh"]
" let g:file_extensions += ["*.cc"]
" let g:file_extensions += ["*.h++"]
" let g:file_extensions += ["*.c++"]
" let g:file_extensions += ["*.hxx"]
" let g:file_extensions += ["*.cxx"]
" let g:file_extensions += ["*.hpp"]
" let g:file_extensions += ["*.cpp"]
" let g:file_extensions += ["*.inl"]
" let g:file_extensions += ["*.impl"]
let g:file_extensions += ["*.txt"]
let g:file_extensions += ["*.lua"]

g:cscopedb_file_complete     Sets the name and location of the "complete" cscope DB.

g:cscopedb_file_partial      Sets the name and location of the partial cscope DB.

g:cscopedb_auto_init         If true, auto init cscope_auto if the DB
                             g:cscopedb_file_complete already exists.

g:cscopedb_extra_files       A file with a list of files for cscope_auto to
                             pass to cscope. Can be used to index "out of tree"
                             source code. Or can be used with
                             g:cscopedb_auto_files = 0 if you don't want
                             cscope_auto to automatically find source code.
                             May also be useful if you want to pass absolute
                             path names to cscope.

g:cscopedb_src_dirs_file     This is a file with a list of directories - one per
                             line. The auto init searches source code files in
                             the directories listed. If this file does not
                             exist, the current directory will be used.

g:cscopedb_auto_files        If true, automatically find source code relative
                             to the current working directory.

g:cscopedb_resolve_links     Resolve symlinks for files passed to cscope.
                             Defaults is true. Set to 0 or false if you don't
                             want links resolved.

g:cscopedb_lock_file         Location of lock file. Lock file is used to wait
                             for cscope to finish its work before requesting
                             it to do more work.

g:cscopedb_big_min_interval  Minimal interval between big database updates.
                             Big DB updates can be expensive. This tames the
                             scenario where you may make changes to many files
                             in a short window.

Actually you are not recommended to define these variables by yourself.

2.2 Hooks
=======================================
Users may define functions to get feedback from cscope_auto.

cscope_auto#setup(function("s:cscope_state"))
                             User function s:cscope_state(updateing)
                             called by cscope_auto when a database
                             update begins or ends. Useful for feedback to user.
                             See "Status Line Indicator" example.
                             Argument to function will be true if the plugin
                             has started an update. False when it is done
                             updating.


3. Tricks
===============================================================================

3.1 Status Line Indicator
=======================================
It is useful to have a status line indicator for when the database is updating.
Below is an example.

    function! s:cscope_state(updating)
        if a:updating
            let g:statusline_cscope_flag = "C"
        else
            let g:statusline_cscope_flag = ""
        endif
        execute "redrawstatus!"
    endfunction

    function! s:session_state(updating)
        if a:updating
            packadd cscope_auto
            augroup cscope_auto | au!
                autocmd BufEnter * :call cscope_auto#setup(function("s:cscope_state"))
            augroup END
            let g:statusline_session_flag = "S"
        else
            augroup cscope_auto | au!
            augroup END
            let g:statusline_session_flag = ""
        endif
        execute "redrawstatus!"
    endfunction
    augroup session_auto
        au!
        autocmd VimEnter * :call session_auto#setup(function("s:session_state"))
    augroup END

4. Compatibility
===============================================================================
cscope_auto uses some shell-isms. Therefore it probably only works on *nix
machines that have a proper shell. It likely also functions under cygwin.


5. Development
===============================================================================
Pull requests are very welcome.


6. References
===============================================================================
[1] https://bitbucket.org/ericgarver/cscope_dynamic
[2] http://www.vim.org/scripts/script.php?script_id=5098
[3] http://vim.wikia.com/wiki/Timer_to_execute_commands_periodically
[4] https://github.com/erig0/cscope_dynamic
[5] http://cscope.sourceforge.net/cscope_maps.vim
[6] https://github.com/trailblazing/cscope_auto
[7] https://github.com/trailblazing/boot
[8] https://github.com/trailblazing/session_auto
[9] https://vim.fandom.com/wiki/Using_VimBall_with_make

```