silentbob/README

   1
   2
   3
   4                 SILENT BOB
   5 "Silent Bob", actually, it can be drawn an analogy with three programs, which
   6 leaded to its creation, ctags, cscope, ctree( first I'll describe them, and
   7 their problems, and then - their differences from "Bob").
   8
   9 Description of some programs  ( on which motives SilentBob was written)
  10
  11 Let's take, for example, such well-known program as ctags, probably you've
  12 used it and you know it's main point of work. It simply creates special file,
  13 which stores information about some source files. Usually it's OS kernels and
  14 other big programs, like sendmail or apache. This file contains:
  15 1. "Addresses" of all functions, structures, macroses, etc. "Address" means
  16 file name + string number (or regular expression, using which an appropriate
  17 string can be found). That file, for example, in Vim, can be used to evaluate
  18 ":tag <name>" to make a quick switch. Also ctags allows to extract "goodies"
  19 from files - simply to find out its contents.
  20
  21 csope - very useful program, it doesn't create file, described above, but can
  22 do search and has some additional features:
  23 1. Interface for "comfortable" search.
  24 2. It can trace which functions called and what does they call (one layer
  25 "lower")
  26 3. It also can trace who calls certain functions  (one layer "upper")
  27 And some other feature, which I have never used...
  28
  29 And at last - ctree. Theoreticaly, it can show all above described information
  30 several layers "lower". Practically I couldn't turn it on.
  31
  32 Problems of existing software
  33
  34 ctags problems:
  35 For "tags" file creation regular expressions are used, which allows to add
  36 other languages, but places a substantial limits:
  37 1. Quality of received information is quite low.
  38 2. Information, which we receive, in "interactive" mode is not full enough.
  39 3. Support for C++ is present, but not quite good.
  40
  41 cscope problems:
  42 Actually, all ctags problems, plus:
  43 1. Base, which actually doesn't needed anybody, but "weights" 150 Mbytes (for
  44 Linux 2.6.14 for example)
  45 2. Quality of "interactivity" is not good enough
  46 3. Support for C++ is absent. This is not good, because problems, which this
  47 kind of software is called to solve, lies down to different libraries,
  48 including Qt3/GTK.
  49
  50 In SilentBob this problems are absent. Program uses preprocessor (written by
  51 me) either than regular expressions.
  52
  53 Main ideas of SilentBob
  54
  55 Preprocessor, which is described above, is called "THE_TT" and placed in
  56 appropriate file...
  57 Actually it's quite simple: it removes all "extras" from C/C++ source. It
  58 removes/minimizes all variants of C code notations, removes all extra space
  59 symbols and comments, adds additional spaces where it's necessary (for
  60 example, before brackets). THE_TT allows to take some part of code and
  61 exactly (about 99%) tell you what is it, using minimum of checks.
  62 All it works quite fast (for example, 1.6 GHz processor, 256 Mb of RAM - works
  63 excellent), which allows to do some interesting things. As far as I know,
  64 such kind of code usually is written only to compilers and isn't used for
  65 other things, what, as for my view, isn't good enough.
  66
  67 Next SilentBob's level - "t_op", "what_is_this" and alike functions. First of
  68 them simply allows to enumerate all "operators" of source code, second -
  69 checks, what kind of operator do we met. Actually, "what_is_this" isn't
  70 quite enough for all, so some additional functions exists... Now, THE_TT and
  71 t_op are two separate parts of program. In future I plan to unite them...
  72
  73 It took from me for about one month to develop current version (1.0-rc1) and
  74 two months for testing, finding out bugs, etc.
  75
  76 LYRICS
  77 ("life story", "blog" )
  78
  79 SilentBob was written one dark night, when one Siberian fellow tried to
  80 understand how sys_poll system call works. After some time of digging the
  81 sources and several tanks of drinked beer, this fellow understood, that
  82 abilities of Gvim only isn't quite enough. Some tricks was made - they helped
  83 a little, but this wasn't the solution.
  84 Then, some other popular programs was used. After several tries fellow
  85 understood, that he received the access to function he needs. But only one
  86 function. If you take into account, that such calls, let's say, not only one
  87 in program - you can imaging fellows indignation.
  88
  89
  90     Version 1.5
  91  - added -j N for --cgrep --grep --make-ctags --call-tags. Tags creation code (--make-ctags) is rewritten for new
  92 engine (sblib/TT.cxx). gclib library was minimized to size needed only for SilentBob. Of course, you are able to
  93 download gclib2 separately.
  94
  95     Version 1.4
  96  - Bug fixes. Bugs are caught, fryed and worn out
  97  - Removed support for ./tags file from exuberant-ctags. Now the project is autonomous and doesn't need it.
  98  - Added heapsort and [working] variant with paralleling.
  99  - All libs are in the one heap now
 100
 101
 102
 103
 104 To build project you may use Scons (go to ./Scons), AAP (./AAP directory) or with plain ./configure
 105
 106  -- Scripts:
 107   build_bob.bob  - used to create SConsturct, main.aap, build_bob.sh
 108              if you have bob and all plugins installed run as a
 109            ordinary script.
 110   build_bob.sh     - build all parts... with bash script. Very fast.
 111   install.sh     - alternative script for installing. It installs everything to /usr.
 112   make.sed     - SED script, which is used to automatize automake :-)
 113   package.sh     - alternative method for building SilentBob. It installs everything to ../package,
 114            removing all files in the current dir before.
 115
 116
 117 To install plugins you must execute
 118 $ make install_plugins
 119 Plugins are installed to invariable directory
 120 /usr/lib/silent_bob/
 121 BUT you may manually copy files libplugin_* to the ~/.silent_bob/plugins/ directory.
 122
 123   -- Building with alternative methods (non ./configure):
 124 install.sh,package.sh,install.sh scripts are executed from build directory.
 125 i.e. Executing from directories Scons or APP, you are to add "../scripts/".
 126 Also it may be a bug (?) of changing the order in Scons. If you have such problem you may build needed targets in series (see the commands below).
 127 <commands>
 128 scons ligclib.so
 129 scons libsblib.so
 130 scons silent_bob
 131 </commands>
 132 Bug of incorrect compilation something non -O2 in CFLAGS was found in AAP 1.088.
 133 Using scons, AAP or bash-script you must be in the first-level sub-directory, like:
 134 ./AAP ./SCons ./debug, or change top_srcdir= in build_bob.bob and recreate build files.
 135 Of course, the second variant will work only if you have installed working version of Bob.
 136
 137     HOW to USE:
 138 Files for SilentBob are given as parameters or as file with filelist (every file is in the new line)
 139 and option -L, i.e. -L <file with filelist>.
 140
 141  -- Creating filelist:
 142 $ bob --cfiles
 143 or
 144 $ bob -f
 145
 146  -- Creating file ./tags
 147 $ bob --make-ctags
 148 or
 149 $ bob -c
 150 You may specify -j N --make-ctags, where N is the num of CPUs
 151 *  templates are not indexed
 152 ** There is test option "--lang cpp" for C++. This option make Bob to use "C++" mode.
 153    In this mode global variables are not indexed. To search global vars in C++ code it's recommended
 154    to use --cgrep option.
 155
 156 If you have plugins installed (not from deb package), you may add for these options (--cfiles и --make-ctags) --perl or --python accordingly for Perl and Python, but this fitch is testing...
 157 $ bob [--perl | --python] --files
 158 $ bob [--perl | --python] --make-ctags
 159 Created tag file is supported only by Vim, but you may use directly SilentBob to work with it.
 160
 161  -- Creating ./call_tags file
 162 $ bob <filelist> --call-tags
 163 It creates tags file. But instead of start points of function it will be written where they are called.
 164 You may rename it to ./tags, run Vi and go throw _functions_call_points with a plain usual command
 165         :tag
 166
 167  -- Call-trees
 168 ./call_tags needed.
 169
 170   -- Simple
 171 $ bob <the name of function> [--depth N]
 172 Where N is the maximum level (for huge projects).
 173
 174   -- The reverse
 175 $ bob -u <the name of function> [--depth N]
 176 Сorrectness for C++ code functions is not guaranteed.
 177
 178   -- Search in operators :
 179 $ bob <filelist> --cgrep op1,op2...
 180 Where op1 and op2 are required parts of _one operator_. I.e. to search the place of checking T variable
 181 you may use, for example:
 182 $ bob -L ./cfiles --cgrep if,T
 183 Using -ts option (it may be used at once c>./tags) you may get tags-formatted output.
 184
 185  -- Access to tags
 186 $ bob --tags <function1> <function2> ... <functionN>
 187 Where function1..functionN are needed symbol from ./tags file
 188 The code if all listed functions will be reflected after this call
 189
 190 And also there are many another tasty things, not listed here.
 191
 192                 Other information
 193 We need responses about working with Bob on another platforms.
 194 Any thoughts on:
 195     Oleg Puchinin <graycardinalster@gmail.com>
 196
 197 Thanks for your attention.
 198 Oleg.
 199
 200 Translation to English: Evgeniy Ivanov <lolkaantimat Angry_DOG gmail BIGdot com>