* [Cocci] [PATCH v2] Documentation: Coccinelle: fix typos and command example
@ 2020-06-29 21:16 Randy Dunlap
[not found] ` <c2c1dec0-2bd1-b0e2-1aa4-38d0e954d5ba@web.de>
2020-07-01 15:29 ` [Cocci] [PATCH v2] " Julia Lawall
0 siblings, 2 replies; 10+ messages in thread
From: Randy Dunlap @ 2020-06-29 21:16 UTC (permalink / raw)
To: LKML, linux-doc, Jonathan Corbet, Julia Lawall
Cc: Markus Elfring, Michal Marek, Nicolas Palix, cocci, Gilles Muller
From: Randy Dunlap <rdunlap@infradead.org>
Fix various typos etc. in dev-tools/coccinelle.rst:
- punctuation, grammar, wording
- add "path/to/file.c" when using Coccinelle to check a single file
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Julia Lawall <Julia.Lawall@lip6.fr>
Cc: Gilles Muller <Gilles.Muller@lip6.fr>
Cc: Nicolas Palix <nicolas.palix@imag.fr>
Cc: Michal Marek <michal.lkml@markovi.net>
Cc: cocci@systeme.lip6.fr
Cc: Markus Elfring <Markus.Elfring@web.de>
---
v2: s/at minimum/a minimum/ (Julia and Markus)
Documentation/dev-tools/coccinelle.rst | 44 +++++++++++------------
1 file changed, 22 insertions(+), 22 deletions(-)
--- linux-next-20200629.orig/Documentation/dev-tools/coccinelle.rst
+++ linux-next-20200629/Documentation/dev-tools/coccinelle.rst
@@ -85,7 +85,7 @@ Four basic modes are defined: ``patch``,
file:line:column-column: message
- ``context`` highlights lines of interest and their context in a
- diff-like style.Lines of interest are indicated with ``-``.
+ diff-like style. Lines of interest are indicated with ``-``.
- ``org`` generates a report in the Org mode format of Emacs.
@@ -119,7 +119,7 @@ For each semantic patch, a commit messag
description of the problem being checked by the semantic patch, and
includes a reference to Coccinelle.
-As any static code analyzer, Coccinelle produces false
+As with any static code analyzer, Coccinelle produces false
positives. Thus, reports must be carefully checked, and patches
reviewed.
@@ -135,18 +135,18 @@ the parallelism, set the J= variable. Fo
make coccicheck MODE=report J=4
-As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization,
+As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization;
if support for this is detected you will benefit from parmap parallelization.
When parmap is enabled coccicheck will enable dynamic load balancing by using
-``--chunksize 1`` argument, this ensures we keep feeding threads with work
+``--chunksize 1`` argument. This ensures we keep feeding threads with work
one by one, so that we avoid the situation where most work gets done by only
a few threads. With dynamic load balancing, if a thread finishes early we keep
feeding it more work.
When parmap is enabled, if an error occurs in Coccinelle, this error
-value is propagated back, the return value of the ``make coccicheck``
-captures this return value.
+value is propagated back, and the return value of the ``make coccicheck``
+command captures this return value.
Using Coccinelle with a single semantic patch
---------------------------------------------
@@ -177,13 +177,13 @@ For example, to check drivers/net/wirele
To apply Coccinelle on a file basis, instead of a directory basis, the
following command may be used::
- make C=1 CHECK="scripts/coccicheck"
+ make C=1 CHECK="scripts/coccicheck" path/to/file.c
To check only newly edited code, use the value 2 for the C flag, i.e.::
- make C=2 CHECK="scripts/coccicheck"
+ make C=2 CHECK="scripts/coccicheck" path/to/file.c
-In these modes, which works on a file basis, there is no information
+In these modes, which work on a file basis, there is no information
about semantic patches displayed, and no commit message proposed.
This runs every semantic patch in scripts/coccinelle by default. The
@@ -198,12 +198,12 @@ Debugging Coccinelle SmPL patches
Using coccicheck is best as it provides in the spatch command line
include options matching the options used when we compile the kernel.
-You can learn what these options are by using V=1, you could then
+You can learn what these options are by using V=1; you could then
manually run Coccinelle with debug options added.
Alternatively you can debug running Coccinelle against SmPL patches
-by asking for stderr to be redirected to stderr, by default stderr
-is redirected to /dev/null, if you'd like to capture stderr you
+by asking for stderr to be redirected to stderr. By default stderr
+is redirected to /dev/null; if you'd like to capture stderr you
can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For
instance::
@@ -211,8 +211,8 @@ instance::
make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err
cat cocci.err
-You can use SPFLAGS to add debugging flags, for instance you may want to
-add both --profile --show-trying to SPFLAGS when debugging. For instance
+You can use SPFLAGS to add debugging flags; for instance you may want to
+add both --profile --show-trying to SPFLAGS when debugging. For example
you may want to use::
rm -f err.log
@@ -229,7 +229,7 @@ DEBUG_FILE support is only supported whe
--------------------
Coccinelle supports reading .cocciconfig for default Coccinelle options that
-should be used every time spatch is spawned, the order of precedence for
+should be used every time spatch is spawned. The order of precedence for
variables for .cocciconfig is as follows:
- Your current user's home directory is processed first
@@ -237,7 +237,7 @@ variables for .cocciconfig is as follows
- The directory provided with the --dir option is processed last, if used
Since coccicheck runs through make, it naturally runs from the kernel
-proper dir, as such the second rule above would be implied for picking up a
+proper dir; as such the second rule above would be implied for picking up a
.cocciconfig when using ``make coccicheck``.
``make coccicheck`` also supports using M= targets. If you do not supply
@@ -260,13 +260,13 @@ If not using the kernel's coccicheck tar
order logic of .cocciconfig reading. If using the kernel's coccicheck target,
override any of the kernel's .coccicheck's settings using SPFLAGS.
-We help Coccinelle when used against Linux with a set of sensible defaults
+We help Coccinelle when used against Linux with a set of sensible default
options for Linux with our own Linux .cocciconfig. This hints to coccinelle
-git can be used for ``git grep`` queries over coccigrep. A timeout of 200
+that git can be used for ``git grep`` queries over coccigrep. A timeout of 200
seconds should suffice for now.
The options picked up by coccinelle when reading a .cocciconfig do not appear
-as arguments to spatch processes running on your system, to confirm what
+as arguments to spatch processes running on your system. To confirm what
options will be used by Coccinelle run::
spatch --print-options-only
@@ -290,7 +290,7 @@ given to it when options are in conflict
Coccinelle supports idutils as well but requires coccinelle >= 1.0.6.
When no ID file is specified coccinelle assumes your ID database file
-is in the file .id-utils.index on the top level of the kernel, coccinelle
+is in the file .id-utils.index on the top level of the kernel. Coccinelle
carries a script scripts/idutils_index.sh which creates the database with::
mkid -i C --output .id-utils.index
@@ -317,7 +317,7 @@ SmPL patch specific options
---------------------------
SmPL patches can have their own requirements for options passed
-to Coccinelle. SmPL patch specific options can be provided by
+to Coccinelle. SmPL patch-specific options can be provided by
providing them at the top of the SmPL patch, for instance::
// Options: --no-includes --include-headers
@@ -327,7 +327,7 @@ SmPL patch Coccinelle requirements
As Coccinelle features get added some more advanced SmPL patches
may require newer versions of Coccinelle. If an SmPL patch requires
-at least a version of Coccinelle, this can be specified as follows,
+a minimum version of Coccinelle, this can be specified as follows,
as an example if requiring at least Coccinelle >= 1.0.5::
// Requires: 1.0.5
_______________________________________________
Cocci mailing list
Cocci@systeme.lip6.fr
https://systeme.lip6.fr/mailman/listinfo/cocci
^ permalink raw reply [flat|nested] 10+ messages in thread
[parent not found: <c2c1dec0-2bd1-b0e2-1aa4-38d0e954d5ba@web.de>]
* Re: [Cocci] [PATCH v2] Documentation: Coccinelle: fix typos and command example
[not found] ` <c2c1dec0-2bd1-b0e2-1aa4-38d0e954d5ba@web.de>
@ 2020-06-30 15:11 ` Randy Dunlap
[not found] ` <2a3940de-6a81-1aff-8109-53c1c5a6aa1b@web.de>
0 siblings, 1 reply; 10+ messages in thread
From: Randy Dunlap @ 2020-06-30 15:11 UTC (permalink / raw)
To: Markus Elfring, linux-doc, Coccinelle
Cc: Michal Marek, Gilles Muller, kernel-janitors, Jonathan Corbet,
Nicolas Palix, LKML, Julia Lawall
On 6/30/20 5:23 AM, Markus Elfring wrote:
> …
>> +++ linux-next-20200629/Documentation/dev-tools/coccinelle.rst
> …> @@ -177,13 +177,13 @@ For example, to check drivers/net/wirele
>> To apply Coccinelle on a file basis, instead of a directory basis, the
>> following command may be used::
>>
>> - make C=1 CHECK="scripts/coccicheck"
>> + make C=1 CHECK="scripts/coccicheck" path/to/file.c
>
> I would like to clarify further software design aspects around such make functionality.
>
> We might stumble on different interpretations according to the wording “file basis”.
> Do you find a message like “make: Nothing to be done for 'path/to/file.c'.” interesting then?
>
> * Would you like to add any links for information around the support for
> source code checkers?
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Makefile?id=7c30b859a947535f2213277e827d7ac7dcff9c84#n198
>
> * How do you think about to enclose the path for the shown parameter
> by single quotes instead of double quotes?
>
> * Can such path specifications become more interesting occasionally
> if also an other file extension would be chosen than “.c”?
> Would you like to achieve any software extensions around suffix rules?
>
> Regards,
> Markus
Markus:
Feel free to submit patches.
--
~Randy
_______________________________________________
Cocci mailing list
Cocci@systeme.lip6.fr
https://systeme.lip6.fr/mailman/listinfo/cocci
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [Cocci] [PATCH v2] Documentation: Coccinelle: fix typos and command example
2020-06-29 21:16 [Cocci] [PATCH v2] Documentation: Coccinelle: fix typos and command example Randy Dunlap
[not found] ` <c2c1dec0-2bd1-b0e2-1aa4-38d0e954d5ba@web.de>
@ 2020-07-01 15:29 ` Julia Lawall
1 sibling, 0 replies; 10+ messages in thread
From: Julia Lawall @ 2020-07-01 15:29 UTC (permalink / raw)
To: Randy Dunlap
Cc: Michal Marek, Jonathan Corbet, linux-doc, Nicolas Palix, LKML,
Julia Lawall, Markus Elfring, Gilles Muller, cocci
On Mon, 29 Jun 2020, Randy Dunlap wrote:
> From: Randy Dunlap <rdunlap@infradead.org>
>
> Fix various typos etc. in dev-tools/coccinelle.rst:
>
> - punctuation, grammar, wording
> - add "path/to/file.c" when using Coccinelle to check a single file
>
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Julia Lawall <julia.lawall@inria.fr>
Thanks very much for your help!
julia
> Cc: Julia Lawall <Julia.Lawall@lip6.fr>
> Cc: Gilles Muller <Gilles.Muller@lip6.fr>
> Cc: Nicolas Palix <nicolas.palix@imag.fr>
> Cc: Michal Marek <michal.lkml@markovi.net>
> Cc: cocci@systeme.lip6.fr
> Cc: Markus Elfring <Markus.Elfring@web.de>
> ---
> v2: s/at minimum/a minimum/ (Julia and Markus)
> Documentation/dev-tools/coccinelle.rst | 44 +++++++++++------------
> 1 file changed, 22 insertions(+), 22 deletions(-)
>
> --- linux-next-20200629.orig/Documentation/dev-tools/coccinelle.rst
> +++ linux-next-20200629/Documentation/dev-tools/coccinelle.rst
> @@ -85,7 +85,7 @@ Four basic modes are defined: ``patch``,
> file:line:column-column: message
>
> - ``context`` highlights lines of interest and their context in a
> - diff-like style.Lines of interest are indicated with ``-``.
> + diff-like style. Lines of interest are indicated with ``-``.
>
> - ``org`` generates a report in the Org mode format of Emacs.
>
> @@ -119,7 +119,7 @@ For each semantic patch, a commit messag
> description of the problem being checked by the semantic patch, and
> includes a reference to Coccinelle.
>
> -As any static code analyzer, Coccinelle produces false
> +As with any static code analyzer, Coccinelle produces false
> positives. Thus, reports must be carefully checked, and patches
> reviewed.
>
> @@ -135,18 +135,18 @@ the parallelism, set the J= variable. Fo
>
> make coccicheck MODE=report J=4
>
> -As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization,
> +As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization;
> if support for this is detected you will benefit from parmap parallelization.
>
> When parmap is enabled coccicheck will enable dynamic load balancing by using
> -``--chunksize 1`` argument, this ensures we keep feeding threads with work
> +``--chunksize 1`` argument. This ensures we keep feeding threads with work
> one by one, so that we avoid the situation where most work gets done by only
> a few threads. With dynamic load balancing, if a thread finishes early we keep
> feeding it more work.
>
> When parmap is enabled, if an error occurs in Coccinelle, this error
> -value is propagated back, the return value of the ``make coccicheck``
> -captures this return value.
> +value is propagated back, and the return value of the ``make coccicheck``
> +command captures this return value.
>
> Using Coccinelle with a single semantic patch
> ---------------------------------------------
> @@ -177,13 +177,13 @@ For example, to check drivers/net/wirele
> To apply Coccinelle on a file basis, instead of a directory basis, the
> following command may be used::
>
> - make C=1 CHECK="scripts/coccicheck"
> + make C=1 CHECK="scripts/coccicheck" path/to/file.c
>
> To check only newly edited code, use the value 2 for the C flag, i.e.::
>
> - make C=2 CHECK="scripts/coccicheck"
> + make C=2 CHECK="scripts/coccicheck" path/to/file.c
>
> -In these modes, which works on a file basis, there is no information
> +In these modes, which work on a file basis, there is no information
> about semantic patches displayed, and no commit message proposed.
>
> This runs every semantic patch in scripts/coccinelle by default. The
> @@ -198,12 +198,12 @@ Debugging Coccinelle SmPL patches
>
> Using coccicheck is best as it provides in the spatch command line
> include options matching the options used when we compile the kernel.
> -You can learn what these options are by using V=1, you could then
> +You can learn what these options are by using V=1; you could then
> manually run Coccinelle with debug options added.
>
> Alternatively you can debug running Coccinelle against SmPL patches
> -by asking for stderr to be redirected to stderr, by default stderr
> -is redirected to /dev/null, if you'd like to capture stderr you
> +by asking for stderr to be redirected to stderr. By default stderr
> +is redirected to /dev/null; if you'd like to capture stderr you
> can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For
> instance::
>
> @@ -211,8 +211,8 @@ instance::
> make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err
> cat cocci.err
>
> -You can use SPFLAGS to add debugging flags, for instance you may want to
> -add both --profile --show-trying to SPFLAGS when debugging. For instance
> +You can use SPFLAGS to add debugging flags; for instance you may want to
> +add both --profile --show-trying to SPFLAGS when debugging. For example
> you may want to use::
>
> rm -f err.log
> @@ -229,7 +229,7 @@ DEBUG_FILE support is only supported whe
> --------------------
>
> Coccinelle supports reading .cocciconfig for default Coccinelle options that
> -should be used every time spatch is spawned, the order of precedence for
> +should be used every time spatch is spawned. The order of precedence for
> variables for .cocciconfig is as follows:
>
> - Your current user's home directory is processed first
> @@ -237,7 +237,7 @@ variables for .cocciconfig is as follows
> - The directory provided with the --dir option is processed last, if used
>
> Since coccicheck runs through make, it naturally runs from the kernel
> -proper dir, as such the second rule above would be implied for picking up a
> +proper dir; as such the second rule above would be implied for picking up a
> .cocciconfig when using ``make coccicheck``.
>
> ``make coccicheck`` also supports using M= targets. If you do not supply
> @@ -260,13 +260,13 @@ If not using the kernel's coccicheck tar
> order logic of .cocciconfig reading. If using the kernel's coccicheck target,
> override any of the kernel's .coccicheck's settings using SPFLAGS.
>
> -We help Coccinelle when used against Linux with a set of sensible defaults
> +We help Coccinelle when used against Linux with a set of sensible default
> options for Linux with our own Linux .cocciconfig. This hints to coccinelle
> -git can be used for ``git grep`` queries over coccigrep. A timeout of 200
> +that git can be used for ``git grep`` queries over coccigrep. A timeout of 200
> seconds should suffice for now.
>
> The options picked up by coccinelle when reading a .cocciconfig do not appear
> -as arguments to spatch processes running on your system, to confirm what
> +as arguments to spatch processes running on your system. To confirm what
> options will be used by Coccinelle run::
>
> spatch --print-options-only
> @@ -290,7 +290,7 @@ given to it when options are in conflict
>
> Coccinelle supports idutils as well but requires coccinelle >= 1.0.6.
> When no ID file is specified coccinelle assumes your ID database file
> -is in the file .id-utils.index on the top level of the kernel, coccinelle
> +is in the file .id-utils.index on the top level of the kernel. Coccinelle
> carries a script scripts/idutils_index.sh which creates the database with::
>
> mkid -i C --output .id-utils.index
> @@ -317,7 +317,7 @@ SmPL patch specific options
> ---------------------------
>
> SmPL patches can have their own requirements for options passed
> -to Coccinelle. SmPL patch specific options can be provided by
> +to Coccinelle. SmPL patch-specific options can be provided by
> providing them at the top of the SmPL patch, for instance::
>
> // Options: --no-includes --include-headers
> @@ -327,7 +327,7 @@ SmPL patch Coccinelle requirements
>
> As Coccinelle features get added some more advanced SmPL patches
> may require newer versions of Coccinelle. If an SmPL patch requires
> -at least a version of Coccinelle, this can be specified as follows,
> +a minimum version of Coccinelle, this can be specified as follows,
> as an example if requiring at least Coccinelle >= 1.0.5::
>
> // Requires: 1.0.5
>
> _______________________________________________
> Cocci mailing list
> Cocci@systeme.lip6.fr
> https://systeme.lip6.fr/mailman/listinfo/cocci
>
_______________________________________________
Cocci mailing list
Cocci@systeme.lip6.fr
https://systeme.lip6.fr/mailman/listinfo/cocci
^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2020-07-02 5:40 UTC | newest]
Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-06-29 21:16 [Cocci] [PATCH v2] Documentation: Coccinelle: fix typos and command example Randy Dunlap
[not found] ` <c2c1dec0-2bd1-b0e2-1aa4-38d0e954d5ba@web.de>
2020-06-30 15:11 ` Randy Dunlap
[not found] ` <2a3940de-6a81-1aff-8109-53c1c5a6aa1b@web.de>
2020-07-01 13:20 ` Randy Dunlap
[not found] ` <2f80fb10-dc7f-29be-dc3e-2715f8bafc6d@web.de>
2020-07-01 14:52 ` [Cocci] [v2] " Randy Dunlap
[not found] ` <648d287e-3636-1858-1439-103d317f8571@web.de>
2020-07-01 15:07 ` Randy Dunlap
[not found] ` <65db3f88-1ac8-374d-e3fe-2ea0970ffd67@web.de>
2020-07-01 15:19 ` Randy Dunlap
[not found] ` <bd4033cd-f564-0414-4dbf-4ff58f841648@web.de>
2020-07-01 19:15 ` Randy Dunlap
2020-07-02 0:08 ` Matthew Wilcox
2020-07-02 5:40 ` Julia Lawall
2020-07-01 15:29 ` [Cocci] [PATCH v2] " Julia Lawall
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).