[libcamera-devel] [PATCH v4 2/2] Documentation: Add style checker tool

[Jacopo Mondi]

Add the style checker tool 'checkstyle.sh' and add tool documentation section
to 'coding-style.rst'.

The script is in a very early development stage, and it has been tested
locally only. Use this a starting point, as we might later consider
re-implementing it in something that is not shell scripting (as Python, in
example).

Signed-off-by: Jacopo Mondi <jacopo at jmondi.org>
---
 Documentation/coding-style.rst |  45 +++++++++++++
 utils/checkstyle.sh            | 141 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 186 insertions(+)
 create mode 100755 utils/checkstyle.sh

diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst
index 4747927..c2f95c7 100644
--- a/Documentation/coding-style.rst
+++ b/Documentation/coding-style.rst
@@ -78,3 +78,48 @@ C++-11-specific features:
   * General-purpose smart pointers (std::unique_ptr), deprecating std::auto_ptr
     Smart pointers, as well as shared pointers and weak pointers, shall not be
     overused.
+
+
+Tools
+-----
+
+Libcamera provides a style checker scripts that uses 'astyle', to ease
+identification of style errors before patches gets submitted for review.
+
+Right now, these are the basic astyle options used by the project's code base:
+
+| --style=linux
+| --indent=force-tab=8
+| --attach-namespaces
+| --attach-extern-c
+| --pad-oper
+| --align-pointer=name
+| --align-reference=name
+| --max-code-length=120
+
+Astyle works on full files, and modifies files in place unless instructed to
+do differently. It can't serve directly as a style validator by operating
+directly on patches. The libcamera project thus provides a 'checkstyle.sh'
+script that wraps around git and astyle to get the changes recorded in the
+top-most commit in the working tree and detect style errors.
+
+Here is a simple usage example:
+
+  * Do your file editing, then "git add" and "git commit" as usual.
+  * Run 'checkstyle.sh' on your latest commit: be aware that 'checkstyle.sh'
+    works on commits, so make sure your index is clean.
+
+To use the script simply run:
+
+.. code-block:: bash
+
+        $ ./utils/checkstyle.sh
+
+The tool outputs the differences between the code added by the last commit
+and its astyled version, for all source files modified by the commit.
+
+Once the script doesn't report any difference, or when the reported
+differences are false positives according to your best judgment, the patches
+are ready to be submitted for review.
+
+Happy hacking, libcamera awaits your patches!
diff --git a/utils/checkstyle.sh b/utils/checkstyle.sh
new file mode 100755
index 0000000..7f52975
--- /dev/null
+++ b/utils/checkstyle.sh
@@ -0,0 +1,141 @@
+#!/bin/bash
+# SPDX-License-Identifier: GPL-2.0-or-later
+# Copyright (C) 2018, Google Inc.
+#
+# Author: Jacopo Mondi <jacopo at jmondi.org>
+#
+# checkstyle.sh - A style checker script using astyle for the libcamera project
+#
+# The scripts makes use of the following tools, which are expected to be
+# found in $PATH:
+# - astyle
+# - git
+# - diff
+# - colordiff
+
+ASTYLE=astyle
+ASTYLE_OPT='-n --style=linux --indent=force-tab=8 --attach-namespaces
+--attach-extern-c --pad-oper --align-pointer=name --align-reference=name
+--max-code-length=120'
+EXTDIFF=colordiff
+INTDIFF=diff
+GIT=git
+TMP=/tmp/
+
+# Check for tools to be installed and available in $PATH
+TOOL_LIST="$ASTYLE $EXTDIFF $INTDIFF $GIT"
+for T in $TOOL_LIST; do
+	if [ _$(which $T) = '_' ]; then
+		echo $T "missing or not in \$PATH; please install it"
+		exit 1
+	fi
+done
+
+COMMIT_MSG=$($GIT log --format=%s -n1)
+FLIST=$($GIT diff-index --name-only HEAD^)
+
+echo "Running $0 on commit: \"$COMMIT_MSG\""
+echo
+echo "The commit modifies the following files:"
+for F in $FLIST; do echo $F; done
+echo
+
+# Loop on every file modified by the last commit
+for F in $FLIST; do
+	rm $TMP/chstyle.* &> /dev/null
+	BASENAME=$(basename $F)
+	DIRNAME=$(dirname $F)
+
+	echo
+	# Skip style check on meson files
+	if [[ $BASENAME == "meson.build" ]]; then
+		echo "================================================================="
+		echo "skip checks on:" $F
+		echo "it's a meson build file"
+		echo "================================================================="
+		continue;
+	fi
+
+	# Skip style check on hidden files
+	if [[ $BASENAME == '.'* ]]; then
+		echo "================================================================="
+		echo "skip checks on:" $F
+		echo "it's an hidden file"
+		echo "================================================================="
+		continue;
+	fi
+
+	# Skip Documentation patches
+	if [[ $DIRNAME == 'Documentation' ]]; then
+		echo "================================================================="
+		echo "skip checks on:" $F
+		echo "it's a Documentation file"
+		echo "================================================================="
+		continue;
+	fi
+
+	# Skip patches on utils/
+	if [[ $DIRNAME == 'utils' ]]; then
+		echo "================================================================="
+		echo "skip checks on:" $F
+		echo "it's a utils/ script"
+		echo "================================================================="
+		continue;
+	fi
+
+	echo "================================================================="
+	echo "Checking style on file: " $F
+
+	$GIT show $F > $TMP/chstyle.patch
+	patch -p1 -R < $TMP/chstyle.patch > /dev/null
+	if [[ ! -f "$F" ]]; then
+		# If the file has been added by the last commit, run astyle
+		# on it and report the differences
+		echo
+		echo "Is $BASENAME introduced by this commit? It seems so..."
+		echo "Now running astyle on the whole file: $BASENAME"
+		echo
+		patch -p1 < $TMP/chstyle.patch > /dev/null
+		$ASTYLE $ASTYLE_OPT < $F > $TMP/chstyle.astylepre
+		echo "-----------------------------------------------------------------"
+		$EXTDIFF $F $TMP/chstyle.astylepre
+		echo "-----------------------------------------------------------------"
+		echo
+		echo "If you see nothing here, it means the patch on this file is good!"
+		echo "Otherwise, you may want to check what's wrong with this change"
+		echo "================================================================="
+		continue
+	fi
+
+	# Run astyle on the file -before- this commit, and then -after-
+	# Record the differences between the two to have the astyled version
+	# of the latest changes
+	$ASTYLE $ASTYLE_OPT < $F > $TMP/chstyle.astylepre
+	patch -p1 < $TMP/chstyle.patch > /dev/null
+	$ASTYLE $ASTYLE_OPT < $F > $TMP/chstyle.astylepost
+	$INTDIFF $TMP/chstyle.astylepre $TMP/chstyle.astylepost \
+		| grep -e '^[\>\<]' \
+		| sed s/^[\>\<]\ // > $TMP/chstyle.astylediff
+
+	# Sanitize the content of the patch as recorded in the commit
+	grep ^[+-] $TMP/chstyle.patch \
+		| sed s/^[+-]// | sed /^[+-]\.*/d > $TMP/chstyle.patchpost
+
+	# Now compare the two: raw commit and its astyled version
+	echo "-----------------------------------------------------------------"
+	$EXTDIFF -u $TMP/chstyle.patchpost /tmp/chstyle.astylediff
+	echo "-----------------------------------------------------------------"
+	echo
+	echo "If you see nothing here, it means the patch on this file is good!"
+	echo "Otherwise, you may want to check what's wrong with this change"
+	echo "================================================================="
+done
+
+cat << _END_MSG
+
+-----------------------------------------------------------------
+If checkstyle reports any difference you may want to check what's
+wrong in your patch before submitting it, otherwise the patch
+is ready to be sent out!
+-----------------------------------------------------------------
+_END_MSG
-- 
2.7.4