[PATCH v2] Add .clang-format

[Simon Marchi]

I suggest to ask the binutils folks if they would be fine with having it
at the top-level, it would simplify things.  Adding binutils@.

Binutils people, some of us GDB people would like to add a .clang-format
file in the tree.  This file represents the best approximation we have
of our style that we are able to do with clang-format.  The intent, for
now, is just to allow people to use git-clang-format, or formatting
portions of code in IDEs, to get reasonably close to the correct
formatting, keeping in mind that the output might need some manual
adjustments.

Are you ok with having this file at the top-level?  Just adding this
file shouldn't alter anybody's workflow.

Simon


On 9/2/25 10:22 PM, Tom Tromey wrote:
> This patch adds a .clang-format file to gdb.
> 
> The resulting reformatting is what I'd describe as "ok but not great".
> There are a few variances from our normal style, some discussed in
> comments in the file, and some in the bug.
> 
> I've somewhat come around to the idea that some ugliness is
> acceptable, particularly because I regularly see code that's already
> ugly anyway -- either in formatting or along some other dimension.
> 
> I don't know of a way to enforce a particular version.  I have only
> tried clang-format 18 with this particular file.  I've documented this
> in the file.
> 
> I used "AllowShortFunctionsOnASingleLine: InlineOnly" as previously
> discussed.  I feel that the spirit of the GNU style is that vertical
> space is free, and we should use "None" here.  (This goes against
> something we previously decided on the list, though.)
> 
> I put the file in gdb/ and then tried it on gdbsupport/gdbserver like:
> 
>      clang-format --style=file:../gdb/.clang-format
> 
> This is unwieldy but OTOH putting this in the root directory seems
> unfriendly, since that would affect binutils.
> 
> For the time being you should not bulk reformat files.  I think we
> should have a flag day for this, but at some later point.  See the
> earlier discussion for details.
> 
> Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=30098
> ---
>  .gitignore        |   1 -
>  gdb/.clang-format | 180 ++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 180 insertions(+), 1 deletion(-)
>  create mode 100644 gdb/.clang-format
> 
> diff --git a/.gitignore b/.gitignore
> index 7f1c81e00c4..eb44ff7f255 100644
> --- a/.gitignore
> +++ b/.gitignore
> @@ -37,7 +37,6 @@ TAGS.sub
>  .local.vimrc
>  .lvimrc
>  
> -.clang-format
>  .clang-tidy
>  .clangd
>  .cache
> diff --git a/gdb/.clang-format b/gdb/.clang-format
> new file mode 100644
> index 00000000000..53e4c2ee23c
> --- /dev/null
> +++ b/gdb/.clang-format
> @@ -0,0 +1,180 @@
> +# -*- yaml -*-
> +
> +# A clang format style for gdb.
> +
> +# ⚠️⚠️⚠️ DO NOT BULK REFORMAT FILES ⚠️⚠️⚠️
> +
> +# This style is still in flux and still considered "alpha".  Use "git
> +# clang-format" or the like to reformat just the parts your patch
> +# touches -- at most.  At some point in the future we will bulk
> +# reformat and at that point we'll send out new instructions.
> +
> +# This has only been tried with clang-format 18.
> +
> +# A few known bugs:
> +
> +# * Labels are not handled GNU-style.
> +#   https://github.com/llvm/llvm-project/issues/24492
> +#   https://github.com/llvm/llvm-project/issues/53717
> +
> +# * Function call bin-packing is weird.
> +#   https://github.com/llvm/llvm-project/issues/31255
> +#   https://github.com/llvm/llvm-project/issues/37051
> +#   In some spots this means an unavoidable line break just after a
> +#   "(".
> +
> +# * gettext calls like "_()" are reformatted to "_ ()"
> +#   I don't think there's an upstream bug for this yet
> +
> +# * '#if defined ()' removes the space before the paren:
> +#   https://github.com/llvm/llvm-project/issues/55292
> +#   (Supposedly fixed.)
> +
> +# * Open brace after a lambda should be on new line.
> +#   https://github.com/llvm/llvm-project/issues/133135
> +
> +# * Braced initializers don't put a newline before the "{".
> +#   Historically gdb was inconsistent about this.
> +
> +
> +# Options here are generally in alphabetical order.
> +
> +Language: Cpp
> +# BasedOnStyle: GNU
> +AccessModifierOffset: -2
> +AlignAfterOpenBracket: Align
> +AlignConsecutiveAssignments: false
> +AlignConsecutiveDeclarations: false
> +AlignConsecutiveMacros: false
> +AlignEscapedNewlines: Left
> +AlignOperands: true
> +AlignTrailingComments: true
> +AllowAllArgumentsOnNextLine: false
> +AllowAllParametersOfDeclarationOnNextLine: false
> +AllowShortBlocksOnASingleLine: false
> +AllowShortCaseLabelsOnASingleLine: false
> +AllowShortEnumsOnASingleLine: false
> +AllowShortFunctionsOnASingleLine: None
> +AllowShortIfStatementsOnASingleLine: Never
> +AllowShortLambdasOnASingleLine: All
> +AllowShortLoopsOnASingleLine: false
> +AlwaysBreakAfterReturnType: TopLevelDefinitions
> +AlwaysBreakBeforeMultilineStrings: false
> +AlwaysBreakTemplateDeclarations: Yes
> +#
> +# Run:
> +# git grep 'define ATTRIBUTE_' -- include gdb* | \
> +#   sed -e's/^.*\(ATTRIBUTE_[A-Z0-9_]*\).*$/\1/' | \
> +#   sort -u | \
> +#   sed -e "s/^\(.*\)$/  '\1',/"
> +AttributeMacros: [
> +  'ATTRIBUTE_ALIGNED_ALIGNOF',
> +  'ATTRIBUTE_COLD',
> +  'ATTRIBUTE_FORMAT_PRINTF_STANDARD',
> +  'ATTRIBUTE_FPTR_PRINTF',
> +  'ATTRIBUTE_GCC_STRUCT',
> +  'ATTRIBUTE_HOT',
> +  'ATTRIBUTE_MALLOC',
> +  'ATTRIBUTE_NOCLONE',
> +  'ATTRIBUTE_NONNULL',
> +  'ATTRIBUTE_NONSTRING',
> +  'ATTRIBUTE_NORETURN',
> +  'ATTRIBUTE_NO_SANITIZE_UNDEFINED',
> +  'ATTRIBUTE_NULL_PRINTF',
> +  'ATTRIBUTE_PACKED',
> +  'ATTRIBUTE_PRINTF',
> +  'ATTRIBUTE_PURE',
> +  'ATTRIBUTE_RESULT_SIZE_1',
> +  'ATTRIBUTE_RESULT_SIZE_1_2',
> +  'ATTRIBUTE_RESULT_SIZE_2',
> +  'ATTRIBUTE_RETURNS_NONNULL',
> +  'ATTRIBUTE_SENTINEL',
> +  'ATTRIBUTE_UNUSED',
> +  'ATTRIBUTE_UNUSED_LABEL',
> +  'ATTRIBUTE_UNUSED_RESULT',
> +  'ATTRIBUTE_USED',
> +  'ATTRIBUTE_VISIBILITY',
> +  'ATTRIBUTE_WARN_UNUSED_RESULT',
> +  ]
> +BinPackArguments: true
> +BinPackParameters: true
> +# Because BreakBeforeBraces = GNU, we don't need BraceWrapping.
> +BreakBeforeBinaryOperators: All
> +BreakBeforeBraces: GNU
> +BreakBeforeTernaryOperators: true
> +BreakConstructorInitializers: BeforeColon
> +BreakInheritanceList: BeforeColon
> +BreakStringLiterals: true
> +ColumnLimit: 79
> +CommentPragmas: 'ARI:'
> +CompactNamespaces: false
> +ConstructorInitializerIndentWidth: 2
> +ContinuationIndentWidth: 2
> +Cpp11BracedListStyle: false
> +DerivePointerAlignment: false
> +DisableFormat: false
> +# The docs say not to use this.
> +# ExperimentalAutoDetectBinPacking: false
> +FixNamespaceComments: true
> +# This one comes from libopcodes and is used in gdb.
> +ForEachMacros: [ 'FOR_EACH_DISASSEMBLER_OPTION' ]
> +IncludeBlocks: Preserve
> +IncludeCategories:
> +  - Regex: '^"(common-defs.h|defs.h|server.h)/'
> +    Priority: -1
> +# IncludeIsMainRegex: [ not needed ]
> +IndentCaseLabels: false
> +# See notes at the top of the file -- this is incorrect but that's a
> +# clang-format issue.
> +IndentGotoLabels: true
> +IndentPPDirectives: None
> +IndentWidth: 2
> +IndentWrappedFunctionNames: false
> +KeepEmptyLinesAtTheStartOfBlocks: false
> +LineEnding: LF
> +# MacroBlockBegin: ''
> +# MacroBlockEnd: ''
> +MaxEmptyLinesToKeep: 1
> +NamespaceIndentation: None
> +# NamespaceMacros
> +PackConstructorInitializers: Never
> +PenaltyBreakAssignment: 50
> +PenaltyBreakBeforeFirstCallParameter: 100
> +# clang 20 setting:
> +# PenaltyBreakBeforeMemberAccess: 50
> +# PenaltyBreakComment
> +# PenaltyBreakFirstLessLess
> +PenaltyBreakOpenParenthesis: 100
> +# PenaltyBreakString
> +# PenaltyBreakTemplateDeclaration
> +# PenaltyExcessCharacter
> +# PenaltyReturnTypeOnItsOwnLine
> +PointerAlignment: Right
> +# RawStringFormats: [ I don't think we need this ]
> +# Should be IndentOnly but that requires clang 20.
> +ReflowComments: false
> +# FIXME - enable
> +SortIncludes: Never
> +SortUsingDeclarations: true
> +SpaceAfterCStyleCast: true
> +SpaceAfterLogicalNot: false
> +SpaceAfterTemplateKeyword: false
> +SpaceBeforeAssignmentOperators: true
> +SpaceBeforeCpp11BracedList: true
> +SpaceBeforeCtorInitializerColon: true
> +SpaceBeforeInheritanceColon: true
> +SpaceBeforeParens: Always
> +SpaceBeforeRangeBasedForLoopColon: true
> +SpaceBeforeSquareBrackets: false
> +SpaceInEmptyBlock: false
> +SpacesBeforeTrailingComments: 1
> +SpacesInAngles: false
> +SpacesInContainerLiterals: true
> +SpacesInParens: Never
> +SpacesInSquareBrackets: false
> +Standard: c++17
> +# Oh Python...
> +StatementMacros: [ 'PyObject_HEAD' ]
> +TabWidth: 8
> +TypenameMacros: [ 'ENUM_BITFIELD' ]
> +UseTab: ForContinuationAndIndentation
> -- 
> 2.49.0
>