* [RFC 0/2] add clang-format infrastructure @ 2023-03-22 17:06 Stephen Hemminger 2023-03-22 17:06 ` [RFC 1/2] Add clang format file Stephen Hemminger 2023-03-22 17:06 ` [RFC 2/2] doc: add clang-format documentation Stephen Hemminger 0 siblings, 2 replies; 5+ messages in thread From: Stephen Hemminger @ 2023-03-22 17:06 UTC (permalink / raw) To: dev; +Cc: 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* [RFC 1/2] Add clang format file 2023-03-22 17:06 [RFC 0/2] add clang-format infrastructure Stephen Hemminger @ 2023-03-22 17:06 ` Stephen Hemminger 2023-03-24 15:53 ` Bruce Richardson 2023-03-22 17:06 ` [RFC 2/2] doc: add clang-format documentation Stephen Hemminger 1 sibling, 1 reply; 5+ messages in thread From: Stephen Hemminger @ 2023-03-22 17:06 UTC (permalink / raw) To: dev; +Cc: 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 ^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [RFC 1/2] Add clang format file 2023-03-22 17:06 ` [RFC 1/2] Add clang format file Stephen Hemminger @ 2023-03-24 15:53 ` Bruce Richardson 2023-03-24 19:24 ` Tyler Retzlaff 0 siblings, 1 reply; 5+ messages in thread From: Bruce Richardson @ 2023-03-24 15:53 UTC (permalink / raw) To: Stephen Hemminger; +Cc: dev 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [RFC 1/2] Add clang format file 2023-03-24 15:53 ` Bruce Richardson @ 2023-03-24 19:24 ` Tyler Retzlaff 0 siblings, 0 replies; 5+ messages in thread From: Tyler Retzlaff @ 2023-03-24 19:24 UTC (permalink / raw) To: Bruce Richardson; +Cc: Stephen Hemminger, dev 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* [RFC 2/2] doc: add clang-format documentation 2023-03-22 17:06 [RFC 0/2] add clang-format infrastructure Stephen Hemminger 2023-03-22 17:06 ` [RFC 1/2] Add clang format file Stephen Hemminger @ 2023-03-22 17:06 ` Stephen Hemminger 1 sibling, 0 replies; 5+ messages in thread From: Stephen Hemminger @ 2023-03-22 17:06 UTC (permalink / raw) To: dev; +Cc: 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 ^ permalink raw reply related [flat|nested] 5+ messages in thread
end of thread, other threads:[~2023-03-24 19:24 UTC | newest] Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2023-03-22 17:06 [RFC 0/2] add clang-format infrastructure Stephen Hemminger 2023-03-22 17:06 ` [RFC 1/2] Add clang format file Stephen Hemminger 2023-03-24 15:53 ` Bruce Richardson 2023-03-24 19:24 ` Tyler Retzlaff 2023-03-22 17:06 ` [RFC 2/2] doc: add clang-format documentation Stephen Hemminger
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.