From 17fab5dfc8721d133c71adbd135410012898b409 Mon Sep 17 00:00:00 2001 From: Jacopo Mondi Date: Wed, 12 Dec 2018 12:09:36 +0100 Subject: Documentation: Document the style check script Add a section to the coding style documentation to explain usage of the checkstyle.py script. Signed-off-by: Jacopo Mondi Signed-off-by: Laurent Pinchart --- Documentation/coding-style.rst | 113 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) (limited to 'Documentation/coding-style.rst') diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst index 1b67abed..55e195cf 100644 --- a/Documentation/coding-style.rst +++ b/Documentation/coding-style.rst @@ -79,3 +79,116 @@ 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 +----- + +The 'astyle' code formatting tool can be used to reformat source files with the +libcamera coding style, defined by the following arguments. + +:: + + --style=linux + --indent=force-tab=8 + --attach-namespaces + --attach-extern-c + --pad-oper + --align-pointer=name + --align-reference=name + --max-code-length=120 + +As astyle is a code formatter, it operates on full files outputs reformatted +source code. While it can be used to reformat code before sending patches, it +may generate unrelated changes. To avoid this, libcamera provides a +'checkstyle.py' script wrapping astyle to only retain related changes. This +should be used to validate modifications before submitting them for review. + +The script operates on one or multiple git commits specified on the command +line. It does not modify the git tree, the index or the working directory and +is thus safe to run at any point. + +Commits are specified using the same revision range syntax as 'git log'. The +most usual use cases are to specify a single commit by sha1, branch name or tag +name, or a commit range with the .. syntax. When no arguments are +given, the topmost commit of the current branch is selected. + +:: + + $ ./utils/checkstyle.py cc7d204b2c51 + ---------------------------------------------------------------------------------- + cc7d204b2c51853f7d963d144f5944e209e7ea29 libcamera: Use the logger instead of cout + ---------------------------------------------------------------------------------- + No style issue detected + +When operating on a range of commits, style checks are performed on each commit +from oldest to newest. + +:: + + $ ../utils/checkstyle.py 3b56ddaa96fb~3..3b56ddaa96fb + ---------------------------------------------------------------------------------- + b4351e1a6b83a9cfbfc331af3753602a02dbe062 libcamera: log: Fix Doxygen documentation + ---------------------------------------------------------------------------------- + No style issue detected + + -------------------------------------------------------------------------------------- + 6ab3ff4501fcfa24db40fcccbce35bdded7cd4bc libcamera: log: Document the LogMessage class + -------------------------------------------------------------------------------------- + No style issue detected + + --------------------------------------------------------------------------------- + 3b56ddaa96fbccf4eada05d378ddaa1cb6209b57 build: Add 'std=c++11' cpp compiler flag + --------------------------------------------------------------------------------- + Commit doesn't touch source files, skipping + +Commits that do not touch any .c, .cpp or .h files are skipped. + +:: + + $ ./utils/checkstyle.py edbd2059d8a4 + ---------------------------------------------------------------------- + edbd2059d8a4bd759302ada4368fa4055638fd7f libcamera: Add initial logger + ---------------------------------------------------------------------- + --- src/libcamera/include/log.h + +++ src/libcamera/include/log.h + @@ -21,11 +21,14 @@ + { + public: + LogMessage(const char *fileName, unsigned int line, + - LogSeverity severity); + - LogMessage(const LogMessage&) = delete; + + LogSeverity severity); + + LogMessage(const LogMessage &) = delete; + ~LogMessage(); + + - std::ostream& stream() { return msgStream; } + + std::ostream &stream() + + { + + return msgStream; + + } + + private: + std::ostringstream msgStream; + + --- src/libcamera/log.cpp + +++ src/libcamera/log.cpp + @@ -42,7 +42,7 @@ + + static const char *log_severity_name(LogSeverity severity) + { + - static const char * const names[] = { + + static const char *const names[] = { + "INFO", + "WARN", + " ERR", + + --- + 2 potential style issues detected, please review + +When potential style issues are detected, they are displayed in the form of a +diff that fixes the issues, on top of the corresponding commit. As the script is +in early development false positive are expected. The flagged issues should be +reviewed, but the diff doesn't need to be applied blindly. + +Happy hacking, libcamera awaits your patches! -- cgit v1.2.1