Documentation/smatch: add a reference to the mailing list
[smatch.git] / Documentation / smatch.txt
1 Smatch
3 0.  Introduction
4 1.  Building Smatch
5 2.  Using Smatch
6 3.  Smatch vs Sparse
8 Section 0: Introduction
10 The Smatch mailing list is <>.
12 Section 1:  Building Smatch
13 ---------------------------
15 Smatch requires sqlite3.  It requires the binaries and the C, Perl and
16 Python libraries for sqlite3.
18 apt-get install sqlite3 libsqlite3-dev libdbd-sqlite3-perl
20 Smatch is easy to build.  Just type `make`.  There isn't an install process
21 right now so just run it from the build directory.
24 Section 2:  Using Smatch
25 ------------------------
27 Smatch can be used with a cross function database. It's not mandatory to
28 build the database but it's a useful thing to do.  Building the database
29 for the kernel takes 2-3 hours on my computer.  For the kernel you build
30 the database with:
32         cd ~/path/to/kernel_dir
33         ~/path/to/smatch_dir/smatch_scripts/
35 For projects other than the kernel you run Smatch with the options
36 "--call-tree --info --param-mapper --spammy" and finish building the
37 database by running the script:
39         ~/progs/smatch/devel/smatch_data/db/
41 Each time you rebuild the cross function database it becomes more accurate. I
42 normally rebuild the database every morning.
44 If you are running Smatch over the whole kernel you can use the following
45 command:
47         ~/progs/smatch/devel/smatch_scripts/
49 The script will create a .c.smatch file for every file it tests
50 and a combined smatch_warns.txt file with all the warnings.
52 If you are running Smatch just over one kernel file:
54         ~/progs/smatch/devel/smatch_scripts/kchecker drivers/whatever/file.c
56 You can also build a directory like this:
58         ~/progs/smatch/devel/smatch_scripts/kchecker drivers/whatever/
60 The kchecker script prints its warnings to stdout.
62 The above scripts will ensure that any ARCH or CROSS_COMPILE environment
63 variables are passed to kernel build system - thus allowing for the use of
64 Smatch with kernels that are normally built with cross-compilers.
66 If you are building something else (which is not the Linux kernel) then use
67 something like:
69         make CHECK="~/progs/smatch/devel/smatch --full-path" \
70                 CC=~/progs/smatch/devel/smatch/cgcc | tee smatch_warns.txt
72 The makefile has to let people set the CC with an environment variable for that
73 to work, of course.
76 Section 3:  Smatch vs Sparse
77 ----------------------------
79 Smatch uses Sparse as a C parser.  I have made a few hacks to Sparse so I
80 have to distribute the two together.  Sparse is released under the MIT license
81 and Smatch is GPLv2+.  If you make changes to Sparse please send those to the
82 Sparse mailing list and I will pick them up from
83 there.  Partly I do that for licensing reasons because I don't want to pull GPL
84 changes into the Sparse code I re-distribute.