Documentation/smatch.rst

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