Convert existing smatch documentation to RST, and add it to the index
accordingly.
Signed-off-by: Javier Carrasco <javier.carrasco.cruz@xxxxxxxxx>
---
Documentation/index.rst | 1 +
Documentation/{smatch.txt => smatch.rst} | 56 +++++++++++++-----------
2 files changed, 31 insertions(+), 26 deletions(-)
rename Documentation/{smatch.txt => smatch.rst} (72%)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index e29a5643..761acbae 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -86,6 +86,7 @@ Some interesting external documentation:
test-suite
doc-guide
TODO
+ smatch
.. toctree::
:caption: Release Notes
diff --git a/Documentation/smatch.txt b/Documentation/smatch.rst
similarity index 72%
rename from Documentation/smatch.txt
rename to Documentation/smatch.rst
index b2c3ac4e..f209c8fb 100644
--- a/Documentation/smatch.txt
+++ b/Documentation/smatch.rst
@@ -1,43 +1,46 @@
+======
Smatch
+======
-0. Introduction
-1. Building Smatch
-2. Using Smatch
-3. Smatch vs Sparse
+.. Table of Contents:
-Section 0: Introduction
+.. contents:: :local:
+
+
+0. Introduction
+===============
The Smatch mailing list is <smatch@xxxxxxxxxxxxxxx>.
-Section 1: Building Smatch
----------------------------
+1. Building Smatch
+==================
Smatch needs some dependencies to build:
-In Debian run:
-apt-get install gcc make sqlite3 libsqlite3-dev libdbd-sqlite3-perl libssl-dev libtry-tiny-perl
+In Debian run::
-Or in Fedora run:
-yum install gcc make sqlite3 sqlite-devel sqlite perl-DBD-SQLite openssl-devel perl-Try-Tiny
+ apt-get install gcc make sqlite3 libsqlite3-dev libdbd-sqlite3-perl libssl-dev libtry-tiny-perl
-Smatch is easy to build. Just type `make`. There isn't an install process
-right now so just run it from the build directory.
+Or in Fedora run::
+
+ yum install gcc make sqlite3 sqlite-devel sqlite perl-DBD-SQLite openssl-devel perl-Try-Tiny
+Smatch is easy to build. Just type ``make``. There isn't an install process
+right now so just run it from the build directory.
-Section 2: Using Smatch
-------------------------
+2. Using Smatch
+===============
Smatch can be used with a cross function database. It's not mandatory to
build the database but it's a useful thing to do. Building the database
for the kernel takes 2-3 hours on my computer. For the kernel you build
-the database with:
+the database with::
- cd ~/path/to/kernel_dir
- ~/path/to/smatch_dir/smatch_scripts/build_kernel_data.sh
+ cd ~/path/to/kernel_dir ~/path/to/smatch_dir/smatch_scripts/build_kernel_data.sh
For projects other than the kernel you run Smatch with the options
"--call-tree --info --param-mapper --spammy" and finish building the
-database by running the script:
+database by running the script::
~/path/to/smatch_dir/smatch_data/db/create_db.sh
@@ -45,21 +48,23 @@ Each time you rebuild the cross function database it becomes more accurate. I
normally rebuild the database every morning.
If you are running Smatch over the whole kernel you can use the following
-command:
+command::
~/path/to/smatch_dir/smatch_scripts/test_kernel.sh
The test_kernel.sh script will create a .c.smatch file for every file it tests
and a combined smatch_warns.txt file with all the warnings.
-If you are running Smatch just over one kernel file:
+If you are running Smatch just over one kernel file::
~/path/to/smatch_dir/smatch_scripts/kchecker drivers/whatever/file.c
-You can also build a directory like this:
+You can also build a directory like this::
+
~/path/to/smatch_dir/smatch_scripts/kchecker drivers/whatever/
+
The kchecker script prints its warnings to stdout.
The above scripts will ensure that any ARCH or CROSS_COMPILE environment
@@ -67,7 +72,7 @@ variables are passed to kernel build system - thus allowing for the use of
Smatch with kernels that are normally built with cross-compilers.
If you are building something else (which is not the Linux kernel) then use
-something like:
+something like::
make CHECK="~/path/to/smatch_dir/smatch --full-path" \
CC=~/path/to/smatch_dir/smatch/cgcc | tee smatch_warns.txt
@@ -75,9 +80,8 @@ something like:
The makefile has to let people set the CC with an environment variable for that
to work, of course.
-
-Section 3: Smatch vs Sparse
-----------------------------
+3. Smatch vs Sparse
+===================
Smatch uses Sparse as a C parser. I have made a few hacks to Sparse so I
have to distribute the two together. Sparse is released under the MIT license
--
2.40.1
