From patchwork Wed Dec 12 11:09:36 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 39 Return-Path: Received: from relay10.mail.gandi.net (relay10.mail.gandi.net [217.70.178.230]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 4FD9260B13 for ; Wed, 12 Dec 2018 12:09:55 +0100 (CET) Received: from w540.lan (2-224-242-101.ip172.fastwebnet.it [2.224.242.101]) (Authenticated sender: jacopo@jmondi.org) by relay10.mail.gandi.net (Postfix) with ESMTPSA id DB09124001D; Wed, 12 Dec 2018 11:09:54 +0000 (UTC) From: Jacopo Mondi To: libcamera-devel@lists.libcamera.org Date: Wed, 12 Dec 2018 12:09:36 +0100 Message-Id: <1544612976-27101-3-git-send-email-jacopo@jmondi.org> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1544612976-27101-1-git-send-email-jacopo@jmondi.org> References: <1544612976-27101-1-git-send-email-jacopo@jmondi.org> Subject: [libcamera-devel] [PATCH v4 2/2] Documentation: Add style checker tool X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 12 Dec 2018 11:09:55 -0000 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 --- 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 +# +# 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