linux-kernel - [PATCH 2/3] Documentation/smatch: convert to RST

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <20240401204512.538453-3-javier.carrasco.cruz@gmail.com>
Date: Mon,  1 Apr 2024 22:45:11 +0200
From: Javier Carrasco <javier.carrasco.cruz@...il.com>
To: dan.carpenter@...aro.org,
	javier.carrasco.cruz@...il.com
Cc: smatch@...r.kernel.org,
	linux-kernel@...r.kernel.org
Subject: [PATCH 2/3] Documentation/smatch: convert to RST

Convert existing smatch documentation to RST, and add it to the index
accordingly.

Signed-off-by: Javier Carrasco <javier.carrasco.cruz@...il.com>
---
 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@...r.kernel.org>.

-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