[PATCH v3] documentation: coccinelle: Improve command example for make C={1,2}

[PATCH v3] documentation: coccinelle: Improve command example for make C={1,2}

[Sumera Priyadarsini]

Modify coccinelle documentation to further clarify
the usage of the makefile C variable flag by coccicheck.

Signed-off-by: Sumera Priyadarsini <sylphrenadin@gmail.com>

---
Changes in v3:
        - Remove quotes as suggested by Markus Elfring
	- Change in wording, and punctuation, as suggested by Julia Lawall
---
 Documentation/dev-tools/coccinelle.rst | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/Documentation/dev-tools/coccinelle.rst b/Documentation/dev-tools/coccinelle.rst
index 6c791af1c859..74c5e6aeeff5 100644
--- a/Documentation/dev-tools/coccinelle.rst
+++ b/Documentation/dev-tools/coccinelle.rst
@@ -175,13 +175,20 @@ For example, to check drivers/net/wireless/ one may write::
     make coccicheck M=drivers/net/wireless/
 
 To apply Coccinelle on a file basis, instead of a directory basis, the
-following command may be used::
+C variable is used by the makefile to select which files to work with.
+This variable can be used to run scripts for the entire kernel, a
+specific directory, or for a single file.
 
-    make C=1 CHECK="scripts/coccicheck"
+For example, to check drivers/bluetooth/bfusb.c, the value 1 is
+passed to the C variable to check files that make considers
+need to be compiled.::
 
-To check only newly edited code, use the value 2 for the C flag, i.e.::
+    make C=1 CHECK=scripts/coccicheck drivers/bluetooth/bfusb.o
 
-    make C=2 CHECK="scripts/coccicheck"
+The value 2 is passed to the C variable to check files regardless of
+whether they need to be compiled or not.::
+
+    make C=2 CHECK=scripts/coccicheck drivers/bluetooth/bfusb.o
 
 In these modes, which work on a file basis, there is no information
 about semantic patches displayed, and no commit message proposed.
-- 
2.17.1

Re: [Cocci] [PATCH v3] documentation: coccinelle: Improve command example for make C={1, 2}

[Julia Lawall]

On Mon, 10 Aug 2020, Sumera Priyadarsini wrote:

> Modify coccinelle documentation to further clarify
> the usage of the makefile C variable flag by coccicheck.
>
> Signed-off-by: Sumera Priyadarsini <sylphrenadin@gmail.com>

Thanks.

Acked-by: Julia Lawall <julia.lawall@inria.fr>



>
> ---
> Changes in v3:
>         - Remove quotes as suggested by Markus Elfring
> 	- Change in wording, and punctuation, as suggested by Julia Lawall
> ---
>  Documentation/dev-tools/coccinelle.rst | 15 +++++++++++----
>  1 file changed, 11 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/dev-tools/coccinelle.rst b/Documentation/dev-tools/coccinelle.rst
> index 6c791af1c859..74c5e6aeeff5 100644
> --- a/Documentation/dev-tools/coccinelle.rst
> +++ b/Documentation/dev-tools/coccinelle.rst
> @@ -175,13 +175,20 @@ For example, to check drivers/net/wireless/ one may write::
>      make coccicheck M=drivers/net/wireless/
>
>  To apply Coccinelle on a file basis, instead of a directory basis, the
> -following command may be used::
> +C variable is used by the makefile to select which files to work with.
> +This variable can be used to run scripts for the entire kernel, a
> +specific directory, or for a single file.
>
> -    make C=1 CHECK="scripts/coccicheck"
> +For example, to check drivers/bluetooth/bfusb.c, the value 1 is
> +passed to the C variable to check files that make considers
> +need to be compiled.::
>
> -To check only newly edited code, use the value 2 for the C flag, i.e.::
> +    make C=1 CHECK=scripts/coccicheck drivers/bluetooth/bfusb.o
>
> -    make C=2 CHECK="scripts/coccicheck"
> +The value 2 is passed to the C variable to check files regardless of
> +whether they need to be compiled or not.::
> +
> +    make C=2 CHECK=scripts/coccicheck drivers/bluetooth/bfusb.o
>
>  In these modes, which work on a file basis, there is no information
>  about semantic patches displayed, and no commit message proposed.
> --
> 2.17.1
>
> _______________________________________________
> Cocci mailing list
> Cocci@systeme.lip6.fr
> https://systeme.lip6.fr/mailman/listinfo/cocci
>

Re: [Cocci] [PATCH v3] documentation: coccinelle: Improve command example for make C={1, 2}

[Julia Lawall]

[-- Attachment #1: Type: text/plain, Size: 1054 bytes --]



On Mon, 10 Aug 2020, Markus Elfring wrote:

> > the usage of the makefile C variable flag by coccicheck.
>
> * Can it be confusing to denote an item as a variable and a flag?
>
> * Would you really like to stress here that a flag can be variable?

This is not part of the documentation, so it doesn't really matter.

Nevertheless, Sumera, there is stail an occurrence of flag in the proposed
change to the documentation, so you could indeed change that one to
variable.

>
>
> > +This variable can be used to run scripts for …
>
> Can the scope for a make command be selected also without such a variable?

If you know something that is different than what is in the documentation,
then please say what it is.  Don't just ask questions.

> Will clarification requests for previously mentioned background information
> influence the proposed descriptions any further?

The point is to document the use of make coccicheck, not the C variables.
So the point about KBUILD_CHECK, while interesting, does not seem
appropriate for this documentation.

julia