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

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

[Markus Elfring]

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

How do you think about a wording variant like the following
for the change description?

   Clarify the usage of the make variable “C” for coccicheck.


> +C flag is used. The C flag is a variable used by the makefile

Can such a wording approach trigger understanding difficulties?


> +                                    This flag can be used to
> +run scripts for …

I find this description improvable.


> +The value 1 is passed to the C flag to check for files that make considers
> +need to be recompiled.::

Would you like to distinguish consequences between “compilation” and “recompilation”?

The mentioned parameter is assigned to the macro “KBUILD_CHECKSRC”.
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Makefile?id=fc80c51fd4b23ec007e88d4c688f2cac1b8648e7#n198

The macro “KBUILD_CHECKSRC” is eventually checked for the setting of a few additional macros.
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/scripts/Makefile.build?id=fc80c51fd4b23ec007e88d4c688f2cac1b8648e7#n97

Would you like to determine where these macros are actually applied?

Do you find the commit 0c33f125732d0d33392ba6774d85469d565d3496 ("kbuild:
run the checker after the compiler") from 2020-07-07 interesting for
the discussed documentation adjustment?
https://lore.kernel.org/patchwork/patch/1260832/
https://lore.kernel.org/lkml/20200622154512.82758-1-luc.vanoostenryck@gmail.com/


> +    make C=1 CHECK="scripts/coccicheck" "drivers/bluetooth/bfusb.o"

* Can double quotes be omitted here?

* How do you think about to enclose any data by apostrophes?

Regards,
Markus
_______________________________________________
Cocci mailing list
Cocci@systeme.lip6.fr
https://systeme.lip6.fr/mailman/listinfo/cocci

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

[Julia Lawall]

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



On Mon, 10 Aug 2020, Jonathan Corbet wrote:

> On Mon, 10 Aug 2020 09:30:18 +0200
> Markus Elfring <Markus.Elfring@web.de> wrote:
>
> > > Modify coccinelle documentation to further clarify
> > > the usage of the makefile C variable flag by coccicheck.
> >
> > How do you think about a wording variant like the following
> > for the change description?
> >
> >    Clarify the usage of the make variable “C” for coccicheck.
> >
> >
> > > +C flag is used. The C flag is a variable used by the makefile
> >
> > Can such a wording approach trigger understanding difficulties?
> > [...]
>
> Markus, please don't harass our contributors.  This patch is an
> improvement and, unless Julia disagrees, I am happy to apply it.

There will be a V3.  Thanks.

julia

[-- Attachment #2: Type: text/plain, Size: 136 bytes --]

_______________________________________________
Cocci mailing list
Cocci@systeme.lip6.fr
https://systeme.lip6.fr/mailman/listinfo/cocci

[Cocci] [PATCH v2] 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 v2:
        - Change the message tone to imperative as suggested by Markus
Elfring
	- Add examples for using a specific file and explain in detail
the usage of the C variable, 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..bbcb4f7e8b5c 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 flag is used. The C flag is a variable used by the makefile
+to select which files to work with. This flag can be used to
+run scripts for the entire kernel, a specific directory,
+or for a single file. For example, to check drivers/bluetooth/bfusb.c,
 
-    make C=1 CHECK="scripts/coccicheck"
+The value 1 is passed to the C flag to check for files that make considers
+need to be recompiled.::
 
-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 flag to check for files regardless of
+whether they need to be recompiled 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