From 110f049fde285893bb2cc971c697dfc3abba8436 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nagy-Egri=20M=C3=A1t=C3=A9=20Ferenc?= Date: Tue, 9 Jul 2024 11:48:27 +0200 Subject: [PATCH] Add clang-format support (#913) Adds the mechanics for using clang-format but does not reformat the sources or enable checking in CI. - A git-blame ignore file has been committed to the repo which instructs GitHub's blame functionality on the web interface to keep attribution of lines affected by formatting. Local clones may be [configured told similarly](https://www.stefanjudis.com/today-i-learned/how-to-exclude-commits-from-git-blame/). --- .clang-format | 13 +++++++++++++ .git-blame-ignore-revs | 4 ++++ .github/workflows/formatting.yml | 20 ++++++++++++++++++++ .github/workflows/windows.yml | 4 ++++ BUILDING.md | 12 ++++++++++++ external/.clang-format | 7 +++++++ external/fmt/.clang-format | 8 -------- include/.clang-format | 7 +++++++ lib/.clang-format | 14 ++++++++++++++ lib/vkformat_check.c | 2 ++ lib/vkformat_enum.h | 2 ++ lib/vkformat_str.c | 2 ++ lib/vkformat_typesize.c | 2 ++ other_include/.clang-format | 7 +++++++ scripts/mkvkformatfiles | 9 +++++++++ tests/gtest/.clang-format | 7 +++++++ 16 files changed, 112 insertions(+), 8 deletions(-) create mode 100644 .clang-format create mode 100644 .git-blame-ignore-revs create mode 100644 .github/workflows/formatting.yml create mode 100644 external/.clang-format delete mode 100644 external/fmt/.clang-format create mode 100644 include/.clang-format create mode 100644 lib/.clang-format create mode 100644 other_include/.clang-format create mode 100644 tests/gtest/.clang-format diff --git a/.clang-format b/.clang-format new file mode 100644 index 0000000000..03d8c95831 --- /dev/null +++ b/.clang-format @@ -0,0 +1,13 @@ +# Copyright 2024 The Khronos Group Inc. +# SPDX-License-Identifier: Apache-2.0 +--- +# Use defaults from the Google style with the following exceptions: +Language: Cpp +BasedOnStyle: Google +IndentWidth: 4 +IndentCaseLabels: false +AccessModifierOffset: -2 +ColumnLimit: 100 +SortIncludes: false +IndentPPDirectives: BeforeHash +... diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs new file mode 100644 index 0000000000..6e57846f13 --- /dev/null +++ b/.git-blame-ignore-revs @@ -0,0 +1,4 @@ +# Copyright 2024 The Khronos Group Inc. +# SPDX-License-Identifier: Apache-2.0 + +# Some note about why this hash is ignored (placeholder for initial formatting) \ No newline at end of file diff --git a/.github/workflows/formatting.yml b/.github/workflows/formatting.yml new file mode 100644 index 0000000000..971f148ba7 --- /dev/null +++ b/.github/workflows/formatting.yml @@ -0,0 +1,20 @@ +# Copyright 2024 The Khronos Group Inc. +# Copyright 2024 RasterGrid Kft. +# SPDX-License-Identifier: Apache-2.0 +name: Formatting + +on: + workflow_call: + +permissions: + contents: read + +jobs: + clang-format: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Run clang-format + uses: jidicula/clang-format-action@v4.13.0 + with: + clang-format-version: '17' \ No newline at end of file diff --git a/.github/workflows/windows.yml b/.github/workflows/windows.yml index b6816700b0..1812709255 100644 --- a/.github/workflows/windows.yml +++ b/.github/workflows/windows.yml @@ -25,7 +25,11 @@ on: workflow_dispatch: jobs: + #formatting: + # uses: ./.github/workflows/formatting.yml windows: + # Shortcircuit and don't burn CI time when formatting will reject + #needs: formatting strategy: matrix: os: [ windows-latest ] diff --git a/BUILDING.md b/BUILDING.md index 4371227baa..3de3f8b8e4 100755 --- a/BUILDING.md +++ b/BUILDING.md @@ -638,5 +638,17 @@ directory of your KTX-Software workarea or set the value of the `KTX_SPECIFICATION` CMake cache variable to the location of your specification clone. +Formatting +------------ + +The KTX repository is transitioning to enforcing a set of formatting guides, checked during CI. +The tool used for this is [ClangFormat](https://clang.llvm.org/docs/ClangFormat.html). +To minimize friction, it is advised that one configure their environment to run ClangFormat in an automated fashion, +minimally before committing to source control, ideally on every save. + +### Visual Studio Code + +Set the [`editor.formatOnSave`](https://code.visualstudio.com/docs/editor/codebasics#_formatting) option and use one of the C/C++ formatting extensions available, most notably [ms-vscode.cpptools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) or [llvm-vs-code-extensions.vscode-clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd). + {# vim: set ai ts=4 sts=4 sw=2 expandtab textwidth=75:} diff --git a/external/.clang-format b/external/.clang-format new file mode 100644 index 0000000000..ca48a56571 --- /dev/null +++ b/external/.clang-format @@ -0,0 +1,7 @@ +# Copyright 2024 The Khronos Group Inc. +# SPDX-License-Identifier: Apache-2.0 +--- +# Disable clang-format in this directory +DisableFormat: true +SortIncludes: false +... diff --git a/external/fmt/.clang-format b/external/fmt/.clang-format deleted file mode 100644 index df55d340f0..0000000000 --- a/external/fmt/.clang-format +++ /dev/null @@ -1,8 +0,0 @@ -# Run manually to reformat a file: -# clang-format -i --style=file -Language: Cpp -BasedOnStyle: Google -IndentPPDirectives: AfterHash -IndentCaseLabels: false -AlwaysBreakTemplateDeclarations: false -DerivePointerAlignment: false diff --git a/include/.clang-format b/include/.clang-format new file mode 100644 index 0000000000..ca48a56571 --- /dev/null +++ b/include/.clang-format @@ -0,0 +1,7 @@ +# Copyright 2024 The Khronos Group Inc. +# SPDX-License-Identifier: Apache-2.0 +--- +# Disable clang-format in this directory +DisableFormat: true +SortIncludes: false +... diff --git a/lib/.clang-format b/lib/.clang-format new file mode 100644 index 0000000000..992e5bd82f --- /dev/null +++ b/lib/.clang-format @@ -0,0 +1,14 @@ +# Copyright 2024 The Khronos Group Inc. +# SPDX-License-Identifier: Apache-2.0 +--- +# Use defaults from the Google style with the following exceptions: +Language: Cpp +BasedOnStyle: Google +IndentWidth: 4 +IndentCaseLabels: false +AccessModifierOffset: -2 +ColumnLimit: 100 +SortIncludes: false +AlwaysBreakAfterDefinitionReturnType: TopLevel +IndentPPDirectives: BeforeHash +... diff --git a/lib/vkformat_check.c b/lib/vkformat_check.c index 9e3037f4c8..a1ec463eef 100644 --- a/lib/vkformat_check.c +++ b/lib/vkformat_check.c @@ -9,6 +9,7 @@ ** SPDX-License-Identifier: Apache-2.0 */ +// clang-format off: CI is complicated if formatting checks on generated files are enforced. #include #include @@ -211,3 +212,4 @@ isValidFormat(VkFormat format) } } +// clang-format on diff --git a/lib/vkformat_enum.h b/lib/vkformat_enum.h index a8eb9da85e..693a72f3a5 100644 --- a/lib/vkformat_enum.h +++ b/lib/vkformat_enum.h @@ -1,3 +1,4 @@ +// clang-format off: CI is complicated if formatting checks on generated files are enforced. #if !defined(_VKFORMAT_ENUM_H_) && !defined(VULKAN_CORE_H_) #define _VKFORMAT_ENUM_H_ @@ -312,3 +313,4 @@ typedef uint64_t VkFlags64; #define VK_FORMAT_MAX_STANDARD_ENUM 184 #endif /* _VKFORMAT_ENUM_H_ */ +// clang-format on diff --git a/lib/vkformat_str.c b/lib/vkformat_str.c index 75a47fe02c..9f3bde9ce3 100644 --- a/lib/vkformat_str.c +++ b/lib/vkformat_str.c @@ -9,6 +9,7 @@ ** SPDX-License-Identifier: Apache-2.0 */ +// clang-format off: CI is complicated if formatting checks on generated files are enforced. #include #include @@ -1292,3 +1293,4 @@ stringToVkFormat(const char* str) return VK_FORMAT_R16G16_SFIXED5_NV; return VK_FORMAT_UNDEFINED; } +// clang-format on diff --git a/lib/vkformat_typesize.c b/lib/vkformat_typesize.c index 7914825a22..a07f9bde1f 100644 --- a/lib/vkformat_typesize.c +++ b/lib/vkformat_typesize.c @@ -9,6 +9,7 @@ ** SPDX-License-Identifier: Apache-2.0 */ +// clang-format off: CI is complicated if formatting checks on generated files are enforced. #include @@ -582,3 +583,4 @@ vkFormatTypeSize(VkFormat format) return 0; } } +// clang-format on diff --git a/other_include/.clang-format b/other_include/.clang-format new file mode 100644 index 0000000000..ca48a56571 --- /dev/null +++ b/other_include/.clang-format @@ -0,0 +1,7 @@ +# Copyright 2024 The Khronos Group Inc. +# SPDX-License-Identifier: Apache-2.0 +--- +# Disable clang-format in this directory +DisableFormat: true +SortIncludes: false +... diff --git a/scripts/mkvkformatfiles b/scripts/mkvkformatfiles index 2a5226591f..0281162728 100755 --- a/scripts/mkvkformatfiles +++ b/scripts/mkvkformatfiles @@ -218,6 +218,7 @@ function genTypeSize(format) { } function write_header_file(guard1, guard2, body, filename) { + print "// clang-format off: CI is complicated if formatting checks on generated files are enforced." > filename if (guard2) { print "#if !defined("guard1") && !defined("guard2")" > filename } else { @@ -228,12 +229,20 @@ function write_header_file(guard1, guard2, body, filename) { print copyright > filename print body > filename print "#endif /* "guard1" */" > filename + print "// clang-format on" > filename } function write_source_file(body, filename) { print banner > filename print copyright > filename + # write_source_file used for both java and c sources + if (filename ~ /\.(h|c)$/) { + print "// clang-format off: CI is complicated if formatting checks on generated files are enforced." > filename + } print body > filename + if (filename ~ /\.(h|c)$/) { + print "// clang-format on" > filename + } } function write_python_source_file(body, filename) { diff --git a/tests/gtest/.clang-format b/tests/gtest/.clang-format new file mode 100644 index 0000000000..ca48a56571 --- /dev/null +++ b/tests/gtest/.clang-format @@ -0,0 +1,7 @@ +# Copyright 2024 The Khronos Group Inc. +# SPDX-License-Identifier: Apache-2.0 +--- +# Disable clang-format in this directory +DisableFormat: true +SortIncludes: false +...