Documentation/smatch.txt

   1 Smatch
   2
   3 0.  Introduction
   4 1.  Building Smatch
   5 2.  Using Smatch
   6 3.  Smatch vs Sparse
   7
   8 Section 0: Introduction
   9
  10 The Smatch mailing list is <smatch@vger.kernel.org>.
  11
  12 Section 1:  Building Smatch
  13 ---------------------------
  14
  15 Smatch needs some dependencies to build:
  16
  17 In Debian run:
  18 apt-get install gcc make sqlite3 libsqlite3-dev libdbd-sqlite3-perl libssl-dev libtry-tiny-perl
  19
  20 Or in Fedora run:
  21 yum install gcc make sqlite3 sqlite-devel sqlite perl-DBD-SQLite openssl-devel perl-Try-Tiny
  22
  23 Smatch is easy to build.  Just type `make`.  There isn't an install process
  24 right now so just run it from the build directory.
  25
  26
  27 Section 2:  Using Smatch
  28 ------------------------
  29
  30 Smatch can be used with a cross function database. It's not mandatory to
  31 build the database but it's a useful thing to do.  Building the database
  32 for the kernel takes 2-3 hours on my computer.  For the kernel you build
  33 the database with:
  34
  35         cd ~/path/to/kernel_dir
  36         ~/path/to/smatch_dir/smatch_scripts/build_kernel_data.sh
  37
  38 For projects other than the kernel you run Smatch with the options
  39 "--call-tree --info --param-mapper --spammy" and finish building the
  40 database by running the script:
  41
  42         ~/progs/smatch/devel/smatch_data/db/create_db.sh
  43
  44 Each time you rebuild the cross function database it becomes more accurate. I
  45 normally rebuild the database every morning.
  46
  47 If you are running Smatch over the whole kernel you can use the following
  48 command:
  49
  50         ~/progs/smatch/devel/smatch_scripts/test_kernel.sh
  51
  52 The test_kernel.sh script will create a .c.smatch file for every file it tests
  53 and a combined smatch_warns.txt file with all the warnings.
  54
  55 If you are running Smatch just over one kernel file:
  56
  57         ~/progs/smatch/devel/smatch_scripts/kchecker drivers/whatever/file.c
  58
  59 You can also build a directory like this:
  60
  61         ~/progs/smatch/devel/smatch_scripts/kchecker drivers/whatever/
  62
  63 The kchecker script prints its warnings to stdout.
  64
  65 The above scripts will ensure that any ARCH or CROSS_COMPILE environment
  66 variables are passed to kernel build system - thus allowing for the use of
  67 Smatch with kernels that are normally built with cross-compilers.
  68
  69 If you are building something else (which is not the Linux kernel) then use
  70 something like:
  71
  72         make CHECK="~/progs/smatch/devel/smatch --full-path" \
  73                 CC=~/progs/smatch/devel/smatch/cgcc | tee smatch_warns.txt
  74
  75 The makefile has to let people set the CC with an environment variable for that
  76 to work, of course.
  77
  78
  79 Section 3:  Smatch vs Sparse
  80 ----------------------------
  81
  82 Smatch uses Sparse as a C parser.  I have made a few hacks to Sparse so I
  83 have to distribute the two together.  Sparse is released under the MIT license
  84 and Smatch is GPLv2+.  If you make changes to Sparse please send those to the
  85 Sparse mailing list linux-sparse@vger.kernel.org and I will pick them up from
  86 there.  Partly I do that for licensing reasons because I don't want to pull GPL
  87 changes into the Sparse code I re-distribute.
  88