From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S965405AbdKPRDQ (ORCPT ); Thu, 16 Nov 2017 12:03:16 -0500 Received: from aserp1040.oracle.com ([141.146.126.69]:50997 "EHLO aserp1040.oracle.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S936189AbdKPRCn (ORCPT ); Thu, 16 Nov 2017 12:02:43 -0500 From: Knut Omang To: linux-kernel@vger.kernel.org Cc: Knut Omang , Jonathan Corbet , =?UTF-8?q?H=C3=A5kon=20Bugge?= , =?UTF-8?q?=C3=85smund=20=C3=98stvold?= , John Haxby , linux-doc@vger.kernel.org Subject: [PATCH 7/7] Documentation: Update checkpatch --ignore-cfg description Date: Thu, 16 Nov 2017 18:01:47 +0100 Message-Id: <92089503875f8aaa3911425dea2d9690bc541e85.1510840787.git-series.knut.omang@oracle.com> X-Mailer: git-send-email 2.13.6 In-Reply-To: References: X-Source-IP: userv0022.oracle.com [156.151.31.74] Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org When running checkpatch with --ignore-cfg it will now traverse the directories above the source file until a match is found. Reflect this enhanced behaviour in the documentation. Signed-off-by: Knut Omang --- Documentation/dev-tools/run-checkpatch.rst | 48 ++++++++++++----------- 1 file changed, 26 insertions(+), 22 deletions(-) diff --git a/Documentation/dev-tools/run-checkpatch.rst b/Documentation/dev-tools/run-checkpatch.rst index c72f818..566d8c6 100644 --- a/Documentation/dev-tools/run-checkpatch.rst +++ b/Documentation/dev-tools/run-checkpatch.rst @@ -26,17 +26,20 @@ number of challenges: This is the purpose of supplying the option ``--ignore-cfg checkpatch.cfg`` to ``scripts/checkpatch.pl``. It will then look for a file named ``checkpatch.cfg`` in the current directory or alternatively in the directory of the source -file. If that file exists, checkpatch parses a set of rules from it, and use -them to determine how to invoke checkpatch for a particular file. The kernel -Makefile system supports using this feature as an integrated part of compiling -the code. +file. If neither is found, and the file is within the kernel tree, checkpatch +will recursively look for a file with the same name in the directories above +until a file is found or the top of the tree is reached. + +If a match is found, checkpatch parses a set of rules from it, and use them to +determine how to invoke checkpatch for a particular file. The kernel Makefile +system supports using this feature as an integrated part of compiling the code. The ignore configuration file ----------------------------- The ignore configuration file can be used to set policies and "rein in" -checkpatch errors piece by piece for a particular subsystem or driver. -The the following syntax is supported:: +checkpatch errors piece by piece for a particular subsystem or driver. The the +following syntax is supported:: # comments line_len @@ -55,9 +58,9 @@ exceptions. Running checkpatch from make ---------------------------- -You can run checkpatch subject to rules defined in ``checkpatch.cfg`` in the -directory of the source file by using "make P=1" to run checkpatch on all files -that gets recompiled, or "make P=2" to run checkpatch on all source files. +You can run checkpatch subject to rules defined in the closest matching +``checkpatch.cfg`` file in the tree by using "make P=1" to run checkpatch on all +files that gets recompiled, or "make P=2" to run checkpatch on all source files. A make variable ``PF`` allows passing additional parameters to checkpatch.pl. You can for instance use:: @@ -70,15 +73,15 @@ selectively enabling of types of errors via changes to the local ``checkpatch.cfg``, and you can focus on fixing up errors subsystem or driver by driver on a type by type basis. -By default checkpatch will skip all files in directories without a -checkpatch.cfg file when invoked with the --ignore-cfg parameter. This is to -allow builds with P=2 to pass even for subsystems that has not yet done anything -to rein in checkpatch errors. At some point when all subsystems and drivers -either have fixed all checkpatch errors or added proper checkpatch.cfg files, -this can be changed. +When invoked with the --ignore-cfg parameter, by default checkpatch will skip +all files in directories without a matching checkpatch.cfg according to the +algorithm described above. This is to allow builds with P=2 to pass even for +subsystems that has not yet done anything to rein in checkpatch errors. At some +point when all subsystems and drivers either have fixed all checkpatch errors or +added proper checkpatch.cfg files, this can be changed. -To force checkpatch to run a full run in directories without a checkpatch.cfg -file as well, use:: +To force checkpatch to run a full run in directories without a +checkpatch.cfg file as well, use:: make P=2 PF="--req-ignore-cfg" @@ -96,10 +99,11 @@ with the -k option to ``make`` to let it continue upon errors. Ever tightening checkpatch rules -------------------------------- -Commit the changes to checkpatch.cfg together with the code changes that fixes a -particular type of issue, this will allow automatic checkpatch testing. This way -we can ensure that new errors of that particular type do not inadvertently sneak -in again! This can be done at any subsystem or module maintainer's discretion -and at the right time without having to do it all at the same time. +Commit the changes to the relevant checkpatch.cfg together with the code changes +that fixes a particular type of issue, this will allow automatic checkpatch +testing. This way we can ensure that new errors of that particular type do not +inadvertently sneak in again! This can be done at any subsystem or module +maintainer's discretion and at the right time without having to do it all at the +same time. Before submitting your changes, verify that "make P=2" passes with no errors. -- git-series 0.9.1