[RFC 0/2] add clang-format infrastructure

[RFC 0/2] add clang-format infrastructure

[Stephen Hemminger]

This is first draft of how to use clang format when doing
DPDK drivers and libraries.

Stephen Hemminger (2):
  Add clang format file
  doc: add clang-format documentation

 .clang-format                            | 181 ++++++++++++++++++++++
 doc/guides/contributing/clang-format.rst | 184 +++++++++++++++++++++++
 doc/guides/contributing/index.rst        |   1 +
 3 files changed, 366 insertions(+)
 create mode 100644 .clang-format
 create mode 100644 doc/guides/contributing/clang-format.rst

-- 
2.39.2

[RFC 1/2] Add clang format file

[Stephen Hemminger]

Based off of Linux kernel style with some local modifications
and DPDK foreach macros.

A couple of open questions to be resolved befor merging.
Is GPL license ok for config file (inherited from Linux here)?
Do we want to have per-driver files for some drivers (like MLX5)?

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 .clang-format | 181 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 181 insertions(+)
 create mode 100644 .clang-format

diff --git a/.clang-format b/.clang-format
new file mode 100644
index 000000000000..ad4d30520253
--- /dev/null
+++ b/.clang-format
@@ -0,0 +1,181 @@
+# SPDX-License-Identifier: GPL-2.0
+#
+# clang-format configuration file. Intended for clang-format >= 11.
+#
+# For more information, see:
+#
+#   Documentation/process/clang-format.rst
+#   https://clang.llvm.org/docs/ClangFormat.html
+#   https://clang.llvm.org/docs/ClangFormatStyleOptions.html
+#
+---
+AccessModifierOffset: -4
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: false
+AlignConsecutiveDeclarations: false
+AlignEscapedNewlines: Left
+AlignOperands: true
+AlignTrailingComments: false
+AllowAllParametersOfDeclarationOnNextLine: false
+AllowShortBlocksOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: None
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterDefinitionReturnType: None
+AlwaysBreakAfterReturnType: All
+AlwaysBreakBeforeMultilineStrings: false
+BinPackArguments: true
+BinPackParameters: true
+BraceWrapping:
+  AfterClass: false
+  AfterControlStatement: false
+  AfterEnum: false
+  AfterFunction: true
+  AfterNamespace: true
+  AfterObjCDeclaration: false
+  AfterStruct: false
+  AfterUnion: false
+  AfterExternBlock: false
+  BeforeCatch: false
+  BeforeElse: false
+  IndentBraces: false
+  SplitEmptyFunction: true
+  SplitEmptyRecord: true
+  SplitEmptyNamespace: true
+BreakBeforeBinaryOperators: None
+BreakBeforeBraces: Custom
+BreakBeforeInheritanceComma: false
+BreakBeforeTernaryOperators: false
+BreakConstructorInitializersBeforeComma: false
+BreakConstructorInitializers: BeforeComma
+BreakAfterJavaFieldAnnotations: false
+BreakStringLiterals: false
+ColumnLimit: 100
+CompactNamespaces: false
+ConstructorInitializerAllOnOneLineOrOnePerLine: false
+ConstructorInitializerIndentWidth: 8
+ContinuationIndentWidth: 8
+Cpp11BracedListStyle: false
+DerivePointerAlignment: false
+DisableFormat: false
+ExperimentalAutoDetectBinPacking: false
+FixNamespaceComments: false
+
+# Taken from:
+#   git grep -h '^#define [^[:space:]]*[A-Z_]*FOREACH[A-Z_]*' lib/ drivers/ \
+#   | sed "s,^#define \([:space:]]*[A-Z_]*FOREACH[A-Z_]*\)(.*$,  - \1," \
+#   | LC_ALL=C sort -u
+ForEachMacros:
+  - CIRBUF_FOREACH
+  - FOREACH_ABS_FUNC_IN_PORT
+  - FOREACH_DEVICE_ON_AUXILARY_BUS
+  - FOREACH_DEVICE_ON_PCIBUS
+  - FOREACH_DEVICE_ON_PLATFORM_BUS
+  - FOREACH_DEVICE_ON_VMBUS
+  - FOREACH_DRIVER_ON_AUXILARY_BUS
+  - FOREACH_DRIVER_ON_PCIBUS
+  - FOREACH_DRIVER_ON_PLATFORM_BUS
+  - FOREACH_DRIVER_ON_VMBUS
+  - FOREACH_SUBDEV
+  - FOREACH_SUBDEV_STATE
+  - ILIST_FOREACH
+  - LIST_FOREACH
+  - LIST_FOREACH_FROM
+  - LIST_FOREACH_FROM_SAFE
+  - LIST_FOREACH_SAFE
+  - MLX5_ETH_FOREACH_DEV
+  - MLX5_IPOOL_FOREACH
+  - MLX5_L3T_FOREACH
+  - ML_AVG_FOREACH_QP
+  - ML_AVG_RESET_FOREACH_QP
+  - ML_MAX_FOREACH_QP
+  - ML_MAX_RESET_FOREACH_QP
+  - ML_MIN_FOREACH_QP
+  - ML_MIN_RESET_FOREACH_QP
+  - PLT_TAILQ_FOREACH_SAFE
+  - RTE_BBDEV_FORWEACH
+  - RTE_DEV_FOREACH
+  - RTE_EAL_DEVARGS_FOREACH
+  - RTE_ETH_FOREACH_DEV
+  - RTE_ETH_FOREACH_DEV_OWNED_BY
+  - RTE_ETH_FOREACH_DEV_SIBLING
+  - RTE_ETH_FOREACH_MATCHING_DEV
+  - RTE_ETH_FOREACH_VALID_DEV
+  - RTE_GPU_FOREACH
+  - RTE_GPU_FOREACH_CHILD
+  - RTE_GPU_FOREACH_PARENT
+  - RTE_LCORE_FOREACH
+  - RTE_LCORE_FOREACH_WORKER
+  - RTE_TAILQ_FOREACH
+  - RTE_TAILQ_FOREACH_SAFE
+  - SILIST_FOREACH
+  - SLIST_FOREACH
+  - SLIST_FOREACH_FROM
+  - SLIST_FOREACH_FROM_SAFE
+  - SLIST_FOREACH_SAFE
+  - STAILQ_FOREACH
+  - TAILQ_FOREACH
+  - TAILQ_FOREACH_ENTRY
+  - TAILQ_FOREACH_ENTRY_SAFE
+  - TAILQ_FOREACH_FROM_SAFE
+  - TAILQ_FOREACH_SAFE
+  - json_array_foreach
+  - json_object_foreach
+  - rte_graph_foreach
+  - rte_graph_foreach_node
+  - vdev_netvsc_foreach_iface
+
+IncludeBlocks: Preserve
+IncludeCategories:
+  - Regex: '.*'
+    Priority: 1
+IncludeIsMainRegex: '(Test)?$'
+IndentCaseLabels: false
+IndentGotoLabels: false
+IndentPPDirectives: None
+IndentWidth: 8
+IndentWrappedFunctionNames: false
+JavaScriptQuotes: Leave
+JavaScriptWrapImports: true
+KeepEmptyLinesAtTheStartOfBlocks: false
+MacroBlockBegin: ''
+MacroBlockEnd: ''
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: None
+ObjCBinPackProtocolList: Auto
+ObjCBlockIndentWidth: 8
+ObjCSpaceAfterProperty: true
+ObjCSpaceBeforeProtocolList: true
+
+# Taken from git's rules
+PenaltyBreakAssignment: 10
+PenaltyBreakBeforeFirstCallParameter: 30
+PenaltyBreakComment: 10
+PenaltyBreakFirstLessLess: 0
+PenaltyBreakString: 10
+PenaltyExcessCharacter: 100
+PenaltyReturnTypeOnItsOwnLine: 60
+
+PointerAlignment: Right
+ReflowComments: false
+SortIncludes: false
+SortUsingDeclarations: false
+SpaceAfterCStyleCast: false
+SpaceAfterTemplateKeyword: true
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeCtorInitializerColon: true
+SpaceBeforeInheritanceColon: true
+SpaceBeforeParens: ControlStatementsExceptForEachMacros
+SpaceBeforeRangeBasedForLoopColon: true
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInAngles: false
+SpacesInContainerLiterals: false
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard: Cpp03
+TabWidth: 8
+UseTab: Always
+...
-- 
2.39.2

Re: [RFC 1/2] Add clang format file

[Bruce Richardson]

On Wed, Mar 22, 2023 at 10:06:54AM -0700, Stephen Hemminger wrote:
> Based off of Linux kernel style with some local modifications
> and DPDK foreach macros.
> 
> A couple of open questions to be resolved befor merging.
> Is GPL license ok for config file (inherited from Linux here)?
> Do we want to have per-driver files for some drivers (like MLX5)?
> 
> Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
> ---
>  .clang-format | 181 ++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 181 insertions(+)
>  create mode 100644 .clang-format
> 
> diff --git a/.clang-format b/.clang-format
> new file mode 100644
> index 000000000000..ad4d30520253
> --- /dev/null
> +++ b/.clang-format
> @@ -0,0 +1,181 @@
> +# SPDX-License-Identifier: GPL-2.0
> +#
> +# clang-format configuration file. Intended for clang-format >= 11.
> +#
> +# For more information, see:
> +#
> +#   Documentation/process/clang-format.rst
> +#   https://clang.llvm.org/docs/ClangFormat.html
> +#   https://clang.llvm.org/docs/ClangFormatStyleOptions.html
> +#
> +---
> +AccessModifierOffset: -4
> +AlignAfterOpenBracket: Align

This may be partially a matter of personal preference, but I disagree with
using this setting. This sets up line continuations with varaible widths,
and leads to:
* continuation lines being very short if the function name in a wrapped
  call is long
* indentation using a mix of tabs and spaces as it tries to line up exactly
  on a column with brackets

I think a better option for this setting, which is also aligned with our
coding rules, is for this to be set to "DontAlign" and the
"ContinuationIndentWidth" set to 16, leading to double-tab continuations
(at least in my testing).

/Bruce

Re: [RFC 1/2] Add clang format file

[Tyler Retzlaff]

On Fri, Mar 24, 2023 at 03:53:25PM +0000, Bruce Richardson wrote:
> On Wed, Mar 22, 2023 at 10:06:54AM -0700, Stephen Hemminger wrote:
> > Based off of Linux kernel style with some local modifications
> > and DPDK foreach macros.
> > 
> > A couple of open questions to be resolved befor merging.
> > Is GPL license ok for config file (inherited from Linux here)?
> > Do we want to have per-driver files for some drivers (like MLX5)?
> > 
> > Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
> > ---
> >  .clang-format | 181 ++++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 181 insertions(+)
> >  create mode 100644 .clang-format
> > 
> > diff --git a/.clang-format b/.clang-format
> > new file mode 100644
> > index 000000000000..ad4d30520253
> > --- /dev/null
> > +++ b/.clang-format
> > @@ -0,0 +1,181 @@
> > +# SPDX-License-Identifier: GPL-2.0
> > +#
> > +# clang-format configuration file. Intended for clang-format >= 11.
> > +#
> > +# For more information, see:
> > +#
> > +#   Documentation/process/clang-format.rst
> > +#   https://clang.llvm.org/docs/ClangFormat.html
> > +#   https://clang.llvm.org/docs/ClangFormatStyleOptions.html
> > +#
> > +---
> > +AccessModifierOffset: -4
> > +AlignAfterOpenBracket: Align
> 
> This may be partially a matter of personal preference, but I disagree with
> using this setting. This sets up line continuations with varaible widths,
> and leads to:
> * continuation lines being very short if the function name in a wrapped
>   call is long
> * indentation using a mix of tabs and spaces as it tries to line up exactly
>   on a column with brackets

+1

i find alignment to open bracket terrible. it also blows out to
multiple line diffs if something like a function name is changed
and there are parameters on following lines.

> 
> I think a better option for this setting, which is also aligned with our
> coding rules, is for this to be set to "DontAlign" and the
> "ContinuationIndentWidth" set to 16, leading to double-tab continuations
> (at least in my testing).
> 
> /Bruce

[RFC 2/2] doc: add clang-format documentation

[Stephen Hemminger]

Modify existing Linux kernel documentation of clang-format
to match usage in DPDK.

Still waiting for right to reuse acknowledgment for original
Linux kernel author of this documentation.  If not ok, then
can just write a new version.

Probably need some wording about applicability to base
driver code.

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
 doc/guides/contributing/clang-format.rst | 184 +++++++++++++++++++++++
 doc/guides/contributing/index.rst        |   1 +
 2 files changed, 185 insertions(+)
 create mode 100644 doc/guides/contributing/clang-format.rst

diff --git a/doc/guides/contributing/clang-format.rst b/doc/guides/contributing/clang-format.rst
new file mode 100644
index 000000000000..4b3dda0d520c
--- /dev/null
+++ b/doc/guides/contributing/clang-format.rst
@@ -0,0 +1,184 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright 2023 The DPDK contributors
+    Original from Linux kernel docs
+
+.. _clangformat:
+
+clang-format
+============
+
+``clang-format`` is a tool to format C/C++/... code according to
+a set of rules and heuristics. Like most tools, it is not perfect
+nor covers every single case, but it is good enough to be helpful.
+
+``clang-format`` can be used for several purposes:
+
+  - Quickly reformat a block of code to the DPDK style. Specially useful
+    when moving code around and aligning/sorting. See clangformatreformat_.
+
+  - Spot style mistakes, typos and possible improvements in files
+    you maintain, patches you review, diffs, etc. See clangformatreview_.
+
+  - Help you follow the coding style rules, specially useful for those
+    new to DPDK development or working at the same time in several
+    projects with different coding styles.
+
+Its configuration file is ``.clang-format`` in the root of the DPDK tree.
+The rules contained there try to approximate the most common DPDK
+coding style. They also try to follow :ref:`coding_style`
+as much as possible. A driver may have a slightly different style,
+it is possible that you may want to tweak the defaults for a particular
+folder. To do so, you can override the defaults by writing
+another ``.clang-format`` file in a subfolder.
+
+The tool itself has already been included in the repositories of popular
+Linux distributions for a long time. Search for ``clang-format`` in
+your repositories. Otherwise, you can either download pre-built
+LLVM/clang binaries or build the source code from:
+
+    https://releases.llvm.org/download.html
+
+See more information about the tool at:
+
+    https://clang.llvm.org/docs/ClangFormat.html
+
+    https://clang.llvm.org/docs/ClangFormatStyleOptions.html
+
+
+.. _clangformatreview:
+
+Review files and patches for coding style
+-----------------------------------------
+
+By running the tool in its inline mode, you can review full subsystems,
+folders or individual files for code style mistakes, typos or improvements.
+
+To do so, you can run something like::
+
+    # Make sure your working directory is clean!
+    clang-format -i driver/*.[ch]
+
+And then take a look at the git diff.
+
+Counting the lines of such a diff is also useful for improving/tweaking
+the style options in the configuration file; as well as testing new
+``clang-format`` features/versions.
+
+``clang-format`` also supports reading unified diffs, so you can review
+patches and git diffs easily. See the documentation at:
+
+    https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting
+
+To avoid ``clang-format`` formatting some portion of a file, you can do::
+
+    int formatted_code;
+    // clang-format off
+        void    unformatted_code  ;
+    // clang-format on
+    void formatted_code_again;
+
+While it might be tempting to use this to keep a file always in sync with
+``clang-format``, specially if you are writing new files or if you are
+a maintainer, please note that people might be running different
+``clang-format`` versions or not have it available at all. Therefore,
+you should probably refrain yourself from using this for all sources.
+
+.. _clangformatreformat:
+
+Reformatting blocks of code
+---------------------------
+
+By using an integration with your text editor, you can reformat arbitrary
+blocks (selections) of code with a single keystroke. This is specially
+useful when moving code around, for complex code that is deeply intended,
+for multi-line macros (and aligning their backslashes), etc.
+
+Remember that you can always tweak the changes afterwards in those cases
+where the tool did not do an optimal job. But as a first approximation,
+it can be very useful.
+
+There are integrations for many popular text editors. For some of them,
+like vim, emacs, BBEdit and Visual Studio you can find support built-in.
+For instructions, read the appropriate section at:
+
+    https://clang.llvm.org/docs/ClangFormat.html
+
+For Atom, Eclipse, Sublime Text, Visual Studio Code, XCode and other
+editors and IDEs you should be able to find ready-to-use plugins.
+
+For this use case, consider using a secondary ``.clang-format``
+so that you can tweak a few options. See clangformatextra_.
+
+
+.. _clangformatmissing:
+
+Missing support
+---------------
+
+``clang-format`` is missing support for some things that are common
+in DPDK code. They are easy to remember, so if you use the tool
+regularly, you will quickly learn to avoid/ignore those.
+
+In particular, some very common ones you will notice are:
+
+  - Aligned blocks of one-line ``#defines``, e.g.::
+
+        #define TRACING_MAP_BITS_DEFAULT       11
+        #define TRACING_MAP_BITS_MAX           17
+        #define TRACING_MAP_BITS_MIN           7
+
+    vs.::
+
+        #define TRACING_MAP_BITS_DEFAULT 11
+        #define TRACING_MAP_BITS_MAX 17
+        #define TRACING_MAP_BITS_MIN 7
+
+  - Aligned designated initializers, e.g.::
+
+        static const struct eth_dev_ops ops = {
+                .dev_close     = eth_dev_close,
+	        .dev_start     = eth_dev_start,
+	        .dev_stop      = eth_dev_stop,
+	        .dev_configure = eth_dev_configure,
+                .dev_infos_get = eth_dev_info,
+        };
+
+    vs.::
+
+        static const struct eth_dev_ops ops = {
+                .dev_close = eth_dev_close,
+	        .dev_start = eth_dev_start,
+	        .dev_stop = eth_dev_stop,
+	        .dev_configure = eth_dev_configure,
+                .dev_infos_get = eth_dev_info,
+        };
+
+
+.. _clangformatextra:
+
+Extra features/options
+----------------------
+
+Some features/style options are not enabled by default in the configuration
+file in order to minimize the differences between the output and the current
+code. In other words, to make the difference as small as possible,
+which makes reviewing full-file style, as well diffs and patches as easy
+as possible.
+
+In other cases (e.g. particular subsystems/folders/files), the DPDK style
+might be different and enabling some of these options may approximate
+better the style there.
+
+For instance:
+
+  - Aligning assignments (``AlignConsecutiveAssignments``).
+
+  - Aligning declarations (``AlignConsecutiveDeclarations``).
+
+  - Reflowing text in comments (``ReflowComments``).
+
+  - Sorting ``#includes`` (``SortIncludes``).
+
+They are typically useful for block re-formatting, rather than full-file.
+You might want to create another ``.clang-format`` file and use that one
+from your editor/IDE instead.
diff --git a/doc/guides/contributing/index.rst b/doc/guides/contributing/index.rst
index 7a9e6b368e1c..68e70f2350a4 100644
--- a/doc/guides/contributing/index.rst
+++ b/doc/guides/contributing/index.rst
@@ -9,6 +9,7 @@ Contributor's Guidelines
     :numbered:
 
     coding_style
+    clang-format
     design
     abi_policy
     abi_versioning
-- 
2.39.2