[libcamera-devel] [PATCH] Documentation: Adjust guidelines regarding math.h header

[Laurent Pinchart]

While libcamera prefers usage of the C standard library headers (xxx.h)
over the C++ version (cxxx), we make an exception for cmath as the
overloaded versions of the math functions are convenient. Document this,
and adjust checkstyle.py accordingly.

Signed-off-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
---
 Documentation/coding-style.rst | 14 +++++++++++---
 utils/checkstyle.py            |  6 +++---
 2 files changed, 14 insertions(+), 6 deletions(-)

Jacopo, this originates from a discussion in the review of "[PATCH]
libcamera: ipu3: Fix compilation issues with gcc5". I haven't assigned
the authorship to you as you didn't provide a formal patch with an SoB
line. Please let me know if I should (and give me your SoB in that
case). Otherwise, a review is always appreciated :-)

diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst
index 7c56a1b70014..d467a5a1b1ad 100644
--- a/Documentation/coding-style.rst
+++ b/Documentation/coding-style.rst
@@ -195,9 +195,17 @@ them, defines C compatibility headers. The former have a name of the form
 <cxxx> while the later are named <xxx.h>. The C++ headers declare names in the
 std namespace, and may declare the same names in the global namespace. The C
 compatibility headers declare names in the global namespace, and may declare
-the same names in the std namespace. Usage of the C compatibility headers is
-strongly preferred. Code shall not rely on the optional declaration of names in
-the global or std namespace.
+the same names in the std namespace. Code shall not rely on the optional
+declaration of names in the global or std namespace.
+
+Usage of the C compatibility headers is preferred, except for the math.h header.
+Where math.h defines separate functions for different argument types (e.g.
+abs(int), labs(long int), fabs(double) and fabsf(float)) and requires the
+developer to pick the right function, cmath defines overloaded functions
+(std::abs(int), std::abs(long int), std::abs(double) and std::abs(float) and let
+the compiler select the right function. This avoids potential errors such as
+calling abs(int) with a float argument, performing an unwanted implicit integer
+conversion. For this reason, cmath is preferred over math.h.
 
 
 Documentation
diff --git a/utils/checkstyle.py b/utils/checkstyle.py
index b594a19aed5b..d5dc26c0f666 100755
--- a/utils/checkstyle.py
+++ b/utils/checkstyle.py
@@ -244,9 +244,9 @@ class IncludeChecker(StyleChecker):
     patterns = ('*.cpp', '*.h')
 
     headers = ('assert', 'ctype', 'errno', 'fenv', 'float', 'inttypes',
-               'limits', 'locale', 'math', 'setjmp', 'signal', 'stdarg',
-               'stddef', 'stdint', 'stdio', 'stdlib', 'string', 'time', 'uchar',
-               'wchar', 'wctype')
+               'limits', 'locale', 'setjmp', 'signal', 'stdarg', 'stddef',
+               'stdint', 'stdio', 'stdlib', 'string', 'time', 'uchar', 'wchar',
+               'wctype')
     include_regex = re.compile('^#include <c([a-z]*)>')
 
     def __init__(self, content):
-- 
Regards,

Laurent Pinchart