From 0760ede8cf14fb2bc2d6d670c18af63b7fd7d7b6 Mon Sep 17 00:00:00 2001 From: Mikail <mikail.ya...@tu-dortmund.de> Date: Mon, 25 Feb 2019 11:26:06 +0100 Subject: [PATCH] ClangFormat in Coding Conventions and ClangFormat table in Appendix B
--- eng/appendix-a.rst | 2 +- eng/appendix-b.rst | 138 +++++++++++++++++++++++++++++++++++++ eng/coding-conventions.rst | 8 +++ eng/index.rst | 2 + 4 files changed, 149 insertions(+), 1 deletion(-) create mode 100644 eng/appendix-b.rst diff --git a/eng/appendix-a.rst b/eng/appendix-a.rst index 4897360..7d33d78 100644 --- a/eng/appendix-a.rst +++ b/eng/appendix-a.rst @@ -4,7 +4,7 @@ .. COMMENT: RTEMS Foundation, The RTEMS Documentation Project -Appendix: Core Qualification Artifacts/Documents +Appendix A: Core Qualification Artifacts/Documents ************************************************ An effort at NASA has been performed to suggest a core set of artifacts diff --git a/eng/appendix-b.rst b/eng/appendix-b.rst new file mode 100644 index 0000000..a5b4f3e --- /dev/null +++ b/eng/appendix-b.rst @@ -0,0 +1,138 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project +.. COMMENT: embedded brains GmbH + + +Appendix B: Formatting RTEMS with ClangFormat +************************************************ + +The RTEMS formatting style can only be described partially with +`ClangFormat <https://clang.llvm.org/docs/ClangFormat.html>`_. +The table below lists the formatting specifications of RTEMS and whether +these specifications are supported by the ClangFormat configuration options. +Many formatting options of the RTEMS style are not supported. +The idea of ClangFormat is to support only a limited set of common styles really well. +ClangFormat could be adapted to support the RTEMS style fully. +For example, one can load the CMakefile of LLVM with QTCreator, build the project, +and develop ClangFormat with the help of the debugger. +However, the changes to ClangFormat would need to be kept as private patches, +as the project would not accept them in the main branch. + +.. table:: Table 2. ClangFormat options to describe the RTEMS formatting style. + :class: rtems-table + + +--------------------------------+------------------------------+-----------------------------+ + | **RTEMS format specification** | **Option in ClangFormat** | **Comment** | + +--------------------------------+------------------------------+-----------------------------+ + | Spaces instead of tabs | UseTab: Never | Never uses tabs | + +--------------------------------+------------------------------+-----------------------------+ + | Two spaces for indentation | IndentWidth: 2 | Hanging indentations | + | | | not supported | + +--------------------------------+------------------------------+-----------------------------+ + | 80 characters per line | ColumnLimit: 80 | Limit can still be exceeded | + | | | although penalty high | + +--------------------------------+------------------------------+------------+----------------+ + | Don't use more than one blank | MaxEmptyLinesToKeep: 1 | / | + | line in a row | | | + +--------------------------------+------------------------------+-----------------------------+ + | Don't use trailing whitespace | Not supported | / | + | at the end of a line | | | + +--------------------------------+------------------------------+-----------------------------+ + | Never keep empty lines at the | KeepEmptyLinesAtTheStart | / | + | start of a block | OfBlocks: false | | + +--------------------------------+------------------------------+-----------------------------+ + | RTEMS Comment style | Not supported | With option ReflowComments | + | | | long comments are split, | + | | | but last */ is not on | + | | | new line | + +--------------------------------+------------------------------+-----------------------------+ + | PointerAlignmentStyle | RTEMS pointer alignment | / | + | | not supported | | + +--------------------------------+------------------------------+-----------------------------+ + | Indentation for case labels | IndentCaseLabels: true | / | + +--------------------------------+------------------------------+-----------------------------+ + | Braces | BreakBeforeBraces: WebKit | WebKit uses a similar style | + | | | to RTEMS for these breaks | + +--------------------------------+------------------------------+-----------------------------+ + | Braces for function on new | AfterControlStatement: false | AfterFunction: true | + | line, for control statements | | | + | in same line | | | + +--------------------------------+------------------------------+-----------------------------+ + | Function return types and | AllowAllParametersOf | Breaks after return type, | + | names on one line if they fit | DeclarationOnNextLine: false | penalty can be set | + +--------------------------------+------------------------------+-----------------------------+ + | Put function calls on one line | AllowAllParametersOf | If true, all function | + | if they fit | DeclarationOnNextLine: false | parameters would be on one | + | | | line | + +--------------------------------+------------------------------+-----------------------------+ + | Opening brace of function | AlignAfterOpenBracket: | Always break after open | + | definition one line after the | AlwaysBreak | bracket | + | closing parenthesis of its | | | + | prototype | | | + +--------------------------------+------------------------------+-----------------------------+ + | First argument of a function | Inconsistent in ClangFormat | When a break is inserted | + | prototype in a new line | | after function return type, | + | | | all parameters will be on | + | | | the same line | + +--------------------------------+------------------------------+-----------------------------+ + | For var. declarations at begin | PointerAlignment: Left, | RTEMS pointer alignment | + | of function, or for params in | AlignConsecutive | is not supported | + | function definition, align | Declarations: true | | + | identifiers | | | + | (see ratemonperiod.c, l. 28) | | | + +--------------------------------+------------------------------+-----------------------------+ + | Allow function parameters in | Not supported | / | + | a function call to be in | | | + | seperate lines although column | | | + | limit not exceeded. ");" then | | | + | needs to be in a seperate line | | | + +--------------------------------+------------------------------+-----------------------------+ + | Single space inside and | SpacesInParentheses: true, | Exception is to never put | + | outside of each parenthesis of | SpacesInSquareBrackets: true | a space before a closing | + | a conditional expression, | | semicolon, cannot be | + | put space around parameters | | described in ClangFormat | + | in (.) or [.] | | | + +--------------------------------+------------------------------+-----------------------------+ + | No space between a function | SpaceBeforeParens: | Uses f(.), never f (.) | + | name or function-like macro | ControlStatements | | + | and the opening parens | | | + +--------------------------------+------------------------------+-----------------------------+ + | Single space before and after | Not supported | / | + | ternary operators | | | + +--------------------------------+------------------------------+-----------------------------+ + | A single space before and | SpaceBeforeAssignment | Only assignments | + | after binary operators | Operators: true | | + +--------------------------------+------------------------------+-----------------------------+ + | Put no space between unary | Not supported | / | + | operators (*, &, !, ~, ++, --) | | | + | and their operands | | | + +--------------------------------+------------------------------+-----------------------------+ + | No spaces around dereferencing | Not supported | / | + | operators (-> and .) | | | + +--------------------------------+------------------------------+-----------------------------+ + | Space around assignement | SpaceBeforeAssignment | / | + | operator | Operators: true | | + +--------------------------------+------------------------------+-----------------------------+ + | Align operands on multiple | AlignOperands: true | / | + | lines if line too long | | | + +--------------------------------+------------------------------+-----------------------------+ + | Break line in long binary | BreakBeforeBinaryOperators: | Operator is in new line, | + | operator | All/NonAssignment | can also be set for | + | | | assignments | + +--------------------------------+------------------------------+-----------------------------+ + | Allow splitting of conditions | Not supported | / | + | (e.g., in for loops) into | | | + | multiple lines after ";", | | | + | when loop head too long | | | + +--------------------------------+------------------------------+-----------------------------+ + | Nested struct alignment | Not supported | / | + +--------------------------------+------------------------------+-----------------------------+ + | Nested array alignment | Not supported | / | + +--------------------------------+------------------------------+-----------------------------+ + | Nested struct alignment over | Not supported | / | + | multiple lines, break after | | | + | arguments and the "};" | | | + | in a new line | | | + +--------------------------------+------------------------------+-----------------------------+ diff --git a/eng/coding-conventions.rst b/eng/coding-conventions.rst index 488ee26..6b47151 100644 --- a/eng/coding-conventions.rst +++ b/eng/coding-conventions.rst @@ -250,3 +250,11 @@ more tools, configurations, etc here. * `Uncrustify <http://uncrustify.sourceforge.net/>`_. Configuration for RTEMS: `rtems.uncrustify <https://devel.rtems.org/attachment/wiki/Developer/Coding/Conventions/rtems.uncrustify>`_. + +* `ClangFormat <https://clang.llvm.org/docs/ClangFormat.html>`_. + ClangFormat is a code formatting tool with many configuration options. + The main idea of ClangFormat is to support a limited set of styles really well. + The RTEMS formatting style is not supported. + It can only be described partially with a custom formatting configuration. + See Appendix-B for the table which lists the formatting specifications of RTEMS and whether + these specifications are supported by the ClangFormat configuration options. diff --git a/eng/index.rst b/eng/index.rst index 5e7f934..aab7289 100644 --- a/eng/index.rst +++ b/eng/index.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2016, 2018 embedded brains GmbH .. Copyright (C) 2016, 2018 RTEMS Foundation, The RTEMS Documentation Project .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -28,5 +29,6 @@ RTEMS Software Engineering Handbook (|version|) users-manuals license-requirements appendix-a + appendix-b function_and_variable concept -- 2.17.1
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
