cppwinrt code base should have clang-format style formatting enforced automatically

.clang-format

@@ -0,0 +1,163 @@
+---
+Language: Cpp
+BasedOnStyle: Microsoft
+
+AccessModifierOffset: -4
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: false
+AlignEscapedNewlines: DontAlign
+AlignOperands: true
+AlignTrailingComments: true
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortBlocksOnASingleLine: false
+AllowShortLambdasOnASingleLine: Inline
+AlwaysBreakBeforeMultilineStrings: true
+AlwaysBreakTemplateDeclarations: MultiLine
+BinPackArguments: false
+BinPackParameters: false
+BraceWrapping:
+  AfterCaseLabel: true
+  AfterUnion: true
+  BeforeLambdaBody: true
+  SplitEmptyFunction: false
+  SplitEmptyRecord: false
+  SplitEmptyNamespace: false
+BreakBeforeBinaryOperators: None
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializers: AfterColon
+BreakStringLiterals: false
+CommentPragmas: '^ IWYU pragma:'
+CompactNamespaces: true
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+ConstructorInitializerIndentWidth: 4
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: false
+DerivePointerAlignment: false
+DisableFormat: false
+FixNamespaceComments: true
+ForEachMacros: [ foreach, Q_FOREACH, BOOST_FOREACH ]
+IncludeBlocks: Regroup
+IndentCaseLabels: false
+IncludeCategories:
+  - Regex: '^"(stdafx.h|pch.h|precomp.h)"$'
+    Priority: -1
+IndentWrappedFunctionNames: false
+KeepEmptyLinesAtTheStartOfBlocks: true
+MacroBlockBegin: '^BEGIN_COM_MAP$|^BEGIN_CONNECTION_POINT_MAP$|^BEGIN_HELPER_NODEMAP$|^BEGIN_MODULE$|^BEGIN_MSG_MAP$|^BEGIN_OBJECT_MAP$|^BEGIN_TEST_CLASS$|^BEGIN_TEST_METHOD$|^BEGIN_TEST_METHOD_PROPERTIES$'
+MacroBlockEnd: '^END_COM_MAP$|^END_CONNECTION_POINT_MAP$|^END_HELPER_NODEMAP$|^END_MODULE$|^END_MSG_MAP$|^END_OBJECT_MAP$|^END_TEST_CLASS$|^END_TEST_METHOD$|^END_TEST_METHOD_PROPERTIES$'
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: All
+ObjCBlockIndentWidth: 2
+ObjCSpaceAfterProperty: false
+ObjCSpaceBeforeProtocolList: true
+PackConstructorInitializers: NextLineOnly
+PenaltyBreakBeforeFirstCallParameter: 19
+PenaltyBreakComment: 300
+PenaltyBreakFirstLessLess: 120
+PenaltyBreakString: 2000
+PenaltyExcessCharacter: 2
+PointerAlignment: Left
+SortIncludes: false
+SpaceAfterCStyleCast: false
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: ControlStatements
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInAngles: Never
+SpacesInContainerLiterals: true
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard: Latest
+
+AttributeMacros: [
+  CALLBACK,
+]
+
+StatementMacros: [
+  _Acquires_exclusive_lock_,
+  _Acquires_lock_,
+  _Acquires_nonreentrant_lock_,
+  _Acquires_shared_lock_,
+  _Analysis_assume_smart_lock_acquired_,
+  _Analysis_assume_smart_lock_released_,
+  _Create_lock_level_,
+  _Detaches_lock_,
+  _Function_class_,
+  _Global_cancel_spin_lock_,
+  _Global_critical_region_,
+  _Global_interlock_,
+  _Global_priority_region_,
+  _Has_lock_kind_,
+  _Has_lock_level_,
+  _IRQL_always_function_max_,
+  _IRQL_always_function_min_,
+  _IRQL_raises_,
+  _IRQL_requires_,
+  _IRQL_requires_max_,
+  _IRQL_requires_min_,
+  _IRQL_requires_same_,
+  _IRQL_restores_,
+  _IRQL_restores_global_,
+  _IRQL_saves_,
+  _IRQL_saves_global_,
+  _Lock_level_order_,
+  _Moves_lock_,
+  _Must_inspect_result_,
+  _No_competing_thread_,
+  _Post_same_lock_,
+  _Post_writable_byte_size_,
+  _Pre_satisfies_,
+  _Releases_exclusive_lock_,
+  _Releases_lock_,
+  _Releases_nonreentrant_lock_,
+  _Releases_shared_lock_,
+  _Replaces_lock_,
+  _Requires_exclusive_lock_held_,
+  _Requires_lock_held_,
+  _Requires_lock_not_held_,
+  _Requires_no_locks_held_,
+  _Requires_shared_lock_held_,
+  _Ret_maybenull_,
+  _Ret_range_,
+  _Struct_size_bytes_,
+  _Success_,
+  _Swaps_locks_,
+  _Use_decl_annotations_,
+  _When_,
+
+  DECLARE_ORDINAL_MAP,
+  DECLARE_PROCNAME_MAP,
+  DEFINE_ORDINAL_ENTRIES,
+  DEFINE_ORDINAL_ENTRIES_ALTNAME,
+  DEFINE_ORDINAL_ENTRIES_APISET,
+  DEFINE_ORDINAL_MAP,
+  DEFINE_PROCNAME_ENTRIES,
+  DEFINE_PROCNAME_ENTRIES_ALTNAME,
+  DEFINE_PROCNAME_ENTRIES_APISET,
+  DEFINE_PROCNAME_MAP,
+  DLOENTRY,
+  DLOENTRY_APISET,
+  DLPENTRY,
+  DLPENTRY_APISET,
+
+  RpcEndExcept,
+
+  ActivatableClass,
+  ActivatableClassWithFactory,
+  ActivatableClassWithFactoryEx,
+  ActivatableStaticOnlyFactory,
+  ActivatableStaticOnlyFactoryEx,
+  CoCreatableClass,
+  CoCreatableClassWithFactory,
+  CoCreatableClassWithFactoryEx,
+
+  TEST_CASE,
+  SECTION,
+]
+
+TypenameMacros: [
+  IFACEMETHOD,
+  STDMETHOD,
+  STDAPI_,
+]

.clang-format-ignore

@@ -0,0 +1,5 @@
+_build/*
+
+**/CxClass.*
+test/old_tests/Component/Component_h.h
+test/old_tests/Composable/Composable_h.h

.editorconfig

@@ -0,0 +1,106 @@
+# editorconfig: http://editorconfig.org/
+# Help developers standardize spaces, tabs, encoding, end-line characters across editors
+
+# top-most .editorconfig file
+root = true
+
+# defaults for all files
+[*]
+charset = utf-8
+end_of_line = lf
+tab_width = 4
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# markdown, diff overrides
+# two trailing spaces are required for <br/> and hard line-breaks in markdown files
+# see: (https://daringfireball.net/projects/markdown/syntax#p) and (http://spec.commonmark.org/0.27/#hard-line-break)
+[*.{md,diff}]
+trim_trailing_whitespace = false
+
+[*.{md,xml,xsd,gprops,man,natvis}]
+indent_size = 2
+
+# XML-based MSBuild and Visual Studio files
+[*.{props,targets,settings,*proj,vcxitems,filters,ruleset,config,nuspec,resx,vsixmanifest,vsct}]
+indent_size = 2
+
+# Exceptions to the above *proj wildcard
+[*.vdproj]
+indent_size = 4
+
+# Visual Studio uses hard tabs for SLN files, so don't fight it
+[*.sln]
+indent_style = tab
+
+# Visual Studio removes the last empty line, so don't fight it
+[*.{vcxproj}]
+insert_final_newline = false
+
+# YAML overrides
+[*.{yml,yaml}]
+indent_size = 2
+
+[*.{cpp,h,idl}]
+trim_trailing_whitespace = true
+insert_final_newline = true
+cpp_indent_braces=false
+cpp_indent_multi_line_relative_to=innermost_parenthesis
+cpp_indent_within_parentheses=indent
+cpp_indent_preserve_within_parentheses=false
+cpp_indent_case_contents=true
+cpp_indent_case_labels=false
+cpp_indent_case_contents_when_block=false
+cpp_indent_lambda_braces_when_parameter=true
+cpp_indent_goto_labels=one_left
+cpp_indent_preprocessor=leftmost_column
+cpp_indent_access_specifiers=false
+cpp_indent_namespace_contents=true
+cpp_indent_preserve_comments=false
+cpp_new_line_before_open_brace_namespace=ignore
+cpp_new_line_before_open_brace_type=ignore
+cpp_new_line_before_open_brace_function=ignore
+cpp_new_line_before_open_brace_block=ignore
+cpp_new_line_before_open_brace_lambda=ignore
+cpp_new_line_scope_braces_on_separate_lines=false
+cpp_new_line_close_brace_same_line_empty_type=false
+cpp_new_line_close_brace_same_line_empty_function=false
+cpp_new_line_before_catch=true
+cpp_new_line_before_else=true
+cpp_new_line_before_while_in_do_while=false
+cpp_space_before_function_open_parenthesis=remove
+cpp_space_within_parameter_list_parentheses=false
+cpp_space_between_empty_parameter_list_parentheses=false
+cpp_space_after_keywords_in_control_flow_statements=true
+cpp_space_within_control_flow_statement_parentheses=false
+cpp_space_before_lambda_open_parenthesis=false
+cpp_space_within_cast_parentheses=false
+cpp_space_after_cast_close_parenthesis=false
+cpp_space_within_expression_parentheses=false
+cpp_space_before_block_open_brace=true
+cpp_space_between_empty_braces=false
+cpp_space_before_initializer_list_open_brace=false
+cpp_space_within_initializer_list_braces=true
+cpp_space_preserve_in_initializer_list=true
+cpp_space_before_open_square_bracket=false
+cpp_space_within_square_brackets=false
+cpp_space_before_empty_square_brackets=false
+cpp_space_between_empty_square_brackets=false
+cpp_space_group_square_brackets=true
+cpp_space_within_lambda_brackets=false
+cpp_space_between_empty_lambda_brackets=false
+cpp_space_before_comma=false
+cpp_space_after_comma=true
+cpp_space_remove_around_member_operators=true
+cpp_space_before_inheritance_colon=true
+cpp_space_before_constructor_colon=true
+cpp_space_remove_before_semicolon=true
+cpp_space_after_semicolon=false
+cpp_space_remove_around_unary_operator=true
+cpp_space_around_binary_operator=insert
+cpp_space_around_assignment_operator=insert
+cpp_space_pointer_reference_alignment=left
+cpp_space_around_ternary_operator=insert
+cpp_wrap_preserve_blocks=one_liners

.github/workflows/ci.yml

@@ -7,6 +7,53 @@ on:
       - master
 
 jobs:
+  check-formatting:
+    name: 'Check Formatting of Changes'
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Force a non-shallow checkout, so that clang-format can access source history to compare against
+          # See https://github.com/actions/checkout for more details.
+          fetch-depth: 0
+
+      - name: Find vcvars64.bat
+        run: |
+          $vcvars64 = & "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere" -latest -find VC\Auxiliary\Build\vcvars64.bat
+          if (!$vcvars64) { exit 1 }
+          Write-Host "Using vcvars64: ${vcvars64}"
+          Add-Content $env:GITHUB_ENV "vcvars64=$vcvars64"
+
+      - name: Check Formatting
+        shell: cmd
+        run: |
+          call "%vcvars64%"
+
+          call .\find_clang_format.cmd
+          if %ERRORLEVEL% neq 0 (
+            exit /b %ERRORLEVEL%
+          )
+
+          git clang-format origin/master --binary "%CLANG_FORMAT%" --style file -- cppwinrt/*.h cppwinrt/*.cpp fast_fwd/*.h fast_fwd/*.cpp natvis/*.h natvis/*.cpp prebuild/*.h prebuild/*.cpp scratch/*.h scratch/*.cpp strings/*.h strings/*.cpp test/*.h test/*.cpp vsix/*.h vsix/*.cpp
+
+          if %ERRORLEVEL% neq 0 (
+            echo ::error::This branch contains changes that have not been formatted with 'clang-format',
+            echo NOTE:  To resolve this issue, you can run 'clang-format' in the following ways:
+            echo        * Run build_test_all.cmd which will run 'git clang-format' on all source files that have been modified
+            echo          in your branch.  
+            echo        * Run 'format_all_files.cmd' which will format _all_ source files. This script is
+            echo          simple to run, however there's a chance it may touch additional files you never changed due to you having
+            echo          a mis-matched version of 'clang-format'. This may require you to manually revert changes made by
+            echo          'clang-format' to the locations where you made no code changes.
+            echo.
+            echo        For more information, please see https://github.com/microsoft/cppwinrt?tab=readme-ov-file#formatting
+            echo.
+            echo NOTE:  As an additional note, given that different versions of 'clang-format' may have different behaviors, this
+            echo        may be a false positive. If you believe that to be the case ^(e.g. none of the above resulted in modifications
+            echo        to the code you have changed^), please note this in your PR.
+            exit /b 1
+          )
+
   test-msvc-cppwinrt-build:
     name: '${{ matrix.compiler }}: Build (${{ matrix.arch }}, ${{ matrix.config }})'
     strategy:

README.md

@@ -34,3 +34,22 @@ a dev command prompt at the root of the repo _after_ following the above build i
 * Run `build_prior_projection.cmd` in the dev command prompt as well
 * Run `prepare_versionless_diffs.cmd` which removes version stamps on both current and prior projection
 * Use a directory-level differencing tool to compare `_build\$(arch)\$(flavor)\winrt` and `_reference\$(arch)\$(flavor)\winrt`
+
+## Formatting
+
+This project has adopted `clang-format` as the tool for formatting our code.
+Please note that the `.clang-format` at the root of the repo is a copy from the internal Windows repo with few additions.
+In general, please do not modify it.
+If you find that a macro is causing bad formatting of code, you can add that macro to one of the corresponding arrays in the `.clang-format` file (e.g. `AttributeMacros`, etc.), format the code, and submit a PR.
+
+> _NOTE: Different versions of `clang-format` may format the same code differently.
+In an attempt to maintain consistency between changes, we've standardized on using the version of `clang-format` that ships with the latest version of Visual Studio.
+If you have LLVM installed and added to your `PATH`, the version of `clang-format` that gets picked up by default may not be the one we expect.
+
+Before submitting a PR to the cppwinrt repo we ask that you first run `clang-format` on your changes.
+There is a CI check in place that will fail the build for your PR if you have not run `clang-format`.
+`clang-format` will run automatically as part of `build_test_all.cmd`, so if you use that script this
+should happen automatically.
+
+If for some reason you would like to force formatting of every file in the repo then you can run `format_all_files.cmd` to
+do so.  This will take longer than `git clang-format` that will only format files that you have modified.

build_test_all.cmd

@@ -9,13 +9,22 @@ if "%target_platform%"=="" set target_platform=x64
 if "%target_configuration%"=="" set target_configuration=Release
 if "%target_version%"=="" set target_version=1.2.3.4
 
+:: Automatically run clang-format on all .cpp and .h files under the specified directories before building.
+call "%~dp0/find_clang_format.cmd"
+if %ERRORLEVEL% neq 0 exit /b %ERRORLEVEL%
+
+echo Running clang-format on all modified files...
+git clang-format origin/master --binary "%CLANG_FORMAT%" --style file -- cppwinrt/*.h cppwinrt/*.cpp fast_fwd/*.h fast_fwd/*.cpp natvis/*.h natvis/*.cpp prebuild/*.h prebuild/*.cpp scratch/*.h scratch/*.cpp strings/*.h strings/*.cpp test/*.h test/*.cpp vsix/*.h vsix/*.cpp
+
+:: NuGet restore all solutions before building
 if not exist ".\.nuget" mkdir ".\.nuget"
 if not exist ".\.nuget\nuget.exe" powershell -Command "$ProgressPreference = 'SilentlyContinue' ; Invoke-WebRequest https://dist.nuget.org/win-x86-commandline/latest/nuget.exe -OutFile .\.nuget\nuget.exe"
 
 call .nuget\nuget.exe restore cppwinrt.sln"
 call .nuget\nuget.exe restore natvis\cppwinrtvisualizer.sln
 call .nuget\nuget.exe restore test\nuget\NugetTest.sln
 
+:: Build all solutions in order
 call msbuild /m /p:Configuration=%target_configuration%,Platform=%target_platform%,CppWinRTBuildVersion=%target_version% cppwinrt.sln /t:fast_fwd
 
 call msbuild /p:Configuration=%target_configuration%,Platform=%target_platform%,Deployment=Component;CppWinRTBuildVersion=%target_version% natvis\cppwinrtvisualizer.sln
@@ -37,4 +46,5 @@ call msbuild /m /p:Configuration=%target_configuration%,Platform=%target_platfor
 call msbuild /m /p:Configuration=%target_configuration%,Platform=%target_platform%,CppWinRTBuildVersion=%target_version% cppwinrt.sln /t:test\test_module_lock_none
 call msbuild /m /p:Configuration=%target_configuration%,Platform=%target_platform%,CppWinRTBuildVersion=%target_version% cppwinrt.sln /t:test\old_tests\test_old
 
+:: Run tests after building
 call run_tests.cmd %target_platform% %target_configuration%