[PATCH 0/3] Documentation/smatch: RST conversion and fixes

[PATCH 0/3] Documentation/smatch: RST conversion and fixes

[Javier Carrasco]

This series converts the existing smatch.txt to RST and adds it to the
index, so it can be built together with the sparse documentation.

When at it, a couple of small fixes has been included.

Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>

Javier Carrasco (3):
  Documentation/smatch: fix paths in the examples
  Documentation/smatch: convert to RST
  Documentation/smatch: fix typo in submitting-patches.md

 Documentation/index.rst                  |  1 +
 Documentation/{smatch.txt => smatch.rst} | 68 +++++++++++++-----------
 Documentation/submitting-patches.md      |  2 +-
 3 files changed, 38 insertions(+), 33 deletions(-)
 rename Documentation/{smatch.txt => smatch.rst} (60%)

--
2.40.1

[PATCH 1/3] Documentation/smatch: fix paths in the examples

[Javier Carrasco]

A few examples use the '~/progs/smatch/devel/smatch_scripts/' path,
which seems to be a local reference that does not reflect the real
paths in the project (one would not expect 'devel' inside 'smatch').

Use the generic '~/path/to/smatch_dir/' path, which is already used
in some examples.

Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>
---
 Documentation/smatch.txt | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/smatch.txt b/Documentation/smatch.txt
index 59106d49..b2c3ac4e 100644
--- a/Documentation/smatch.txt
+++ b/Documentation/smatch.txt
@@ -39,7 +39,7 @@ 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:

-	~/progs/smatch/devel/smatch_data/db/create_db.sh
+	~/path/to/smatch_dir/smatch_data/db/create_db.sh

 Each time you rebuild the cross function database it becomes more accurate. I
 normally rebuild the database every morning.
@@ -47,18 +47,18 @@ normally rebuild the database every morning.
 If you are running Smatch over the whole kernel you can use the following
 command:

-	~/progs/smatch/devel/smatch_scripts/test_kernel.sh
+	~/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:

-	~/progs/smatch/devel/smatch_scripts/kchecker drivers/whatever/file.c
+	~/path/to/smatch_dir/smatch_scripts/kchecker drivers/whatever/file.c

 You can also build a directory like this:

-	~/progs/smatch/devel/smatch_scripts/kchecker drivers/whatever/
+	~/path/to/smatch_dir/smatch_scripts/kchecker drivers/whatever/

 The kchecker script prints its warnings to stdout.

@@ -69,8 +69,8 @@ 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:

-	make CHECK="~/progs/smatch/devel/smatch --full-path" \
-		CC=~/progs/smatch/devel/smatch/cgcc | tee smatch_warns.txt
+	make CHECK="~/path/to/smatch_dir/smatch --full-path" \
+		CC=~/path/to/smatch_dir/smatch/cgcc | tee smatch_warns.txt

 The makefile has to let people set the CC with an environment variable for that
 to work, of course.
--
2.40.1

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

[Javier Carrasco]

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

Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.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@vger.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

[PATCH 3/3] Documentation/smatch: fix typo in submitting-patches.md

[Javier Carrasco]

Fix a small typo in the smatch documentation about the patch submission
process.

Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>
---
 Documentation/submitting-patches.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/submitting-patches.md b/Documentation/submitting-patches.md
index 5c4191bd..3f4c548f 100644
--- a/Documentation/submitting-patches.md
+++ b/Documentation/submitting-patches.md
@@ -20,7 +20,7 @@ Kernel submitting process.
    Notice that sparse uses the MIT License.

 4. Smatch is built on top of Sparse but it is licensed under the GPLv2+ the
-   git repostories are:
+   git repositories are:

 	https://github.com/error27/smatch
 	https://repo.or.cz/w/smatch.git
--
2.40.1

Re: [PATCH 0/3] Documentation/smatch: RST conversion and fixes

[Dan Carpenter]

On Mon, Apr 01, 2024 at 10:45:09PM +0200, Javier Carrasco wrote:
> This series converts the existing smatch.txt to RST and adds it to the
> index, so it can be built together with the sparse documentation.
> 
> When at it, a couple of small fixes has been included.
> 
> Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>

Thanks!  Applied.  (Will push probably later this week).

regards,
dan carpenter