CSPOT
Old Page

What is cspot.
Why should I use cspot?
Download
Instalation
Plugins and improvements
Commands
File list format and options
Kernel example

What is cspot.
Tool for searching in source code. It use sparse for parsing job. It supports only C language. Unlike other tools it runs preprocessor before  parsing file, which means, you may find an identifier which is created by macro expansion. On the other side, you may search just in compiled parts of source code only - which is bad because you won't find all of the occurances, but you may also know which declaration of global variables/functions are/aren't used. If you need all occurances use cscope, gnu global, ctags, grep or some other tool.
You may build a database to fasten the frequent search.


Why should I use cspot?
Well, if you need preprocessing, it is a great tool.
If you use sparse, then cspot may help you a lot (you don't need to set neither directories where the includes are searched, nor check what macros are pre-defined in compilation of selected file.
cspot (with cspot_cc) can do it for you and all you have to do is to catch sparse output with -so

Download

Version	Release date	MD5SUM
cspot-latest.tgz	?	?
cspot-0.0.1.tgz	?	?
cspot-0.0.2.tgz	?	?
cspot-0.0.3.tgz	?	?
cspot-0.0.4.tgz	?	?
cspot-0.0.5.tgz	3.9.2006	a781870e0586f11ccc560cef99b4c4fb

Instalation
First you must compile source code supplied in file 'cspot-x.x.x.tgz'.
It contains a version of sparse it was developed with, and if you want to use more recent version of sparse, you may apply the patch 'sparse-patch'.

tar -xzf cspot-x.x.x.tgz will unpack the archive.
make install run in created folder as root will compile and install the cspot to /usr/local/bin.


Plugins and improvements
You may use cspot with make.
All you need to do is to set compiler from gcc to cspot_cc {you may configure it to use your favourite version of gcc}.
cspot_cc is designed to manage file list {set right action to file and add files if needed}

Then after every run of make you will have file list with proper action set.
Running cspot -db database -fl filelist -p or equivalent, will update the database.

You may also use the plugin for Emacs. Just look at supplied .emacs file and set your favourite shortcuts in .emacs file in your home directory.


Commands
You may you a command line of cspot, which is visible when running cspot with no parameters (or with no search command), or you may invoke cspot with search parametr and seek in file.

fl (filelist) parameters: filename
def (define) parameters: filename
ip (include path) parameters: filename
db-ro, db-rw, db (database mode read only, read write) parameters: filename
bf, uf, rf (build, update, remove file) parameters: filename
ba, ua, bm, sm (build, update all, build in memory, save memory) parameters: none
p (process filelist) parameters: none
ls (list identifiers) parameters: none
regexp (regular expression) parameters: identifier
so (sparse output) parameters: filename

search in database
ff, fc, fu (function definition, declaration, usage)    parameters: identifier
mf, mu (macro definition, usage) parameters: identifier
vc, vu (variable declaration, usage) parameters: identifier
sf, sc, si, su (struct definition, declaration, usage, info) parameters: identifier
td, tc (typedef, typedef usage) parameters: identifier
sym (symbol) parameters: identifier
in (included) parameters: identifier
uv, uff (unused variables, functions definitions) parameters: none

search without database
lvd, lvu (local variable declaration, local variable usage)    parameters: file line pos
parameters specify the place where identifier is placed in source file
prints only refering to this declaration/ only the correct declaration

va, vla (visible (local-file) at)   parameters: file line pos
vfa, vlfa (visible (local-file) function at)    parameters: file line pos
vma, vlma (visible (local-file) macro at)    parameters: file line pos
vva, vlva (visible (local-file) variable at)    parameters: file line pos
cfa, ufa (called (functions) /used (global variables) in function at)    parameters: file line pos





File list format and options
Two different formats are allowed.

First is just sequence
source_file:include_path:macro_file
where include_path and macro_file is optional
{ thus it can be generated by find ;) }

Second is sequence
c:source_file:include_path:macro_file

if include_path or macro_file omitted default is used
:*:include_path:macro_file   to set default from now on (defaults can be also set by -def, -ip)

c is one of commands...
% no action. File will not be precessed when processing file list. cspot_cc may change the action
+ add file to database.
u update file in database, action will be set to %
U update file (including includes), action will be set to %
* update file in database, action will not be set to %
# no action, cspot_cc may not change action
- remove file from database, action will be set to %
_ remove file including includes, action will be set to %

Known bugs
cspot_cc doesn't support gcc's option -I properly ... it suppose all included header files are 'user' include not system, which can make troubles when building database for kernel.
       if you use 'sys-in' option then all header files will be considered to be system and during preprocessing would be found earlier than standard gcc includes...

Kernel example
      
english example
czech example
if you want to generate database for kernel the best (fastest) choise would be to 'compile' the kernel with cspot_cc (which would invoke gcc) instead of gcc
       cspot_cc use a file cspot_config to define where the gcc compiler should be found

       why:
             we need to set right include headers (preprocessing of kernel files during parsing) and macros
             it is doubtlessly the easiest way, because each kernel 'module?' has -D paramert of gcc set differently (macros are set for module only and could possibly collide)
       how:
             well you may change your kernel Makefile and change gcc compiler to cspot_cc
             or make symlink gcc pointing to cspot_cc and change the PATH variable (then no configuration would be available for cspot_cc and defaults (see source code) will be used)
             or use string expansion of make... so expand gcc to 'cspot_cc -compiler gcc -directory cspot.directory -filelist cspot.file_list'
       how does it work:
             make will find our cspot_cc and will use it as a compiler
             cspot_cc will catch -D and -I optinos and write the '.i' and '.m' files
             cspot_cc wil invoke gcc (compiler) with unchanged params  according to defaults or cspot.config file  
       you may find script in examples/ directory





Better documentation will come soon...
If you don't mind czech

Go Home