Add clang-format support (#913)

MathiasMagnus · web-flow · commit 110f049fde28 · 2024-07-09T18:48:27.000+09:00
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/).
diff --git a/.clang-format 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
@@ -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)
diff --git a/.github/workflows/formatting.yml 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'
diff --git 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
@@ -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
@@ -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
diff --git a/include/.clang-format 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
@@ -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
@@ -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 <stdint.h>
 #include <stdbool.h>
 
@@ -211,3 +212,4 @@ isValidFormat(VkFormat format)
     }
 }
 
+// clang-format on
diff --git 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
@@ -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 <stdint.h>
 #include <ctype.h>
@@ -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
@@ -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 <stdint.h>
 
@@ -582,3 +583,4 @@ vkFormatTypeSize(VkFormat format)
         return 0;
     }
 }
+// clang-format on
diff --git a/other_include/.clang-format 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
@@ -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
@@ -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
+...

Original file line number	Diff line number	Diff line change
`@@ -9,6 +9,7 @@`
`9`	`9`	`** SPDX-License-Identifier: Apache-2.0`
`10`	`10`	`*/`
`11`	`11`
	`12`	`+// clang-format off: CI is complicated if formatting checks on generated files are enforced.`
`12`	`13`	`#include <stdint.h>`
`13`	`14`	`#include <stdbool.h>`
`14`	`15`
`@@ -211,3 +212,4 @@ isValidFormat(VkFormat format)`
`211`	`212`	`}`
`212`	`213`	`}`
`213`	`214`
	`215`	`+// clang-format on`