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