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

@@ -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
+...

.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)

.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/[email protected]
+      with:
+        clang-format-version: '17'

.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 ]

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:}

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
+...

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
+...

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
+...

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

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

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

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

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
+...

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) {

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
+...