Establish clang-format and some scripts for it

Author: dmachaj

.clang-format

@@ -0,0 +1,236 @@
+---
+Language: Cpp
+# BasedOnStyle: LLVM
+
+AccessModifierOffset: -4
+AlignAfterOpenBracket: AlwaysBreak
+AlignConsecutiveAssignments: false
+AlignEscapedNewlines: DontAlign
+AlignOperands: true
+AlignTrailingComments: true
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortBlocksOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: None
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLambdasOnASingleLine: Empty
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterDefinitionReturnType: None
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: true
+AlwaysBreakTemplateDeclarations: MultiLine
+BinPackArguments: false
+BinPackParameters: false
+BraceWrapping:
+  AfterCaseLabel: true
+  AfterClass: true
+  AfterControlStatement: true
+  AfterEnum: true
+  AfterFunction: true
+  AfterNamespace: true
+  AfterStruct: true
+  AfterUnion: true
+  AfterExternBlock: true
+  BeforeCatch: true
+  BeforeElse: true
+  BeforeLambdaBody: true
+  SplitEmptyFunction: false
+  SplitEmptyRecord: false
+  SplitEmptyNamespace: false
+BreakBeforeBinaryOperators: None
+BreakBeforeBraces: Custom
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializers: AfterColon
+BreakStringLiterals: false
+ColumnLimit: 170
+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
+IndentWidth: 4
+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
+PenaltyReturnTypeOnItsOwnLine: 1000
+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
+TabWidth: 4
+UseTab: Never
+
+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,
+
+  # Additional definitions for the WIL repo
+  _Translates_NTSTATUS_to_HRESULT_,
+  _Translates_Win32_to_HRESULT_,
+  _Translates_last_error_to_HRESULT_,
+
+  TEST_CASE,
+  SECTION,
+]
+
+TypenameMacros: [
+  IFACEMETHOD,
+  STDMETHOD,
+  STDAPI_,
+]
+
+# Additional definitions for the WIL repo
+WhitespaceSensitiveMacros: [
+  __WI_CLANG_DISABLE_WARNING,
+]
+
+# TODO: Only supported by clang-format version 17+
+# Macros:
+# - WI_NOEXCEPT=noexcept
+# - __R_FN_PARAMS_FULL=int x
+# - RESULT_NORETURN=[[noreturn]]
+---
+Language: CSharp
+AlignAfterOpenBracket: AlwaysBreak
+AllowShortBlocksOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: None
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+BraceWrapping:
+  AfterCaseLabel: true
+  AfterClass: true
+  AfterControlStatement: true
+  AfterEnum: true
+  AfterFunction: true
+  AfterNamespace: true
+  AfterStruct: true
+  BeforeCatch: true
+  BeforeElse: true
+  SplitEmptyFunction: true
+  SplitEmptyRecord: true
+  SplitEmptyNamespace: true
+BreakBeforeBraces: Custom
+ColumnLimit: 130
+DerivePointerAlignment: false
+IndentWidth: 4
+PenaltyBreakBeforeFirstCallParameter: 19
+PenaltyBreakComment: 300
+PenaltyBreakFirstLessLess: 120
+PenaltyBreakString: 2000
+PenaltyExcessCharacter: 2
+PenaltyReturnTypeOnItsOwnLine: 1000
+PointerAlignment: Left
+TabWidth: 4
+UseTab: Never
+...
+

.github/workflows/ci.yml

@@ -7,6 +7,40 @@ on:
       - master
 
 jobs:
+- job: CheckFormatting
+
+  pool:
+    vmImage: 'windows-2022'
+
+  steps:
+  - script: |
+      if NOT EXIST "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars64.bat" (
+        echo ERROR: Could not locate 'vcvars' batch file. This script is intended to be run from a build machine & exit /B 1
+      )
+      call "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars64.bat"
+
+      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 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 ##vso[task.logissue type=error]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 'clang-format' on _all_ source files. This script is
+        echo          simpler 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
+      )
+    displayName: 'Check Formatting of Changes'
+
   test-msvc-cppwinrt-build:
     name: '${{ matrix.compiler }}: Build (${{ matrix.arch }}, ${{ matrix.config }})'
     strategy:

README.md

@@ -34,3 +34,19 @@ 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.

build_test_all.cmd

@@ -1,4 +1,6 @@
 @echo off
+setlocal
+setlocal EnableDelayedExpansion
 
 set target_platform=%1
 set target_configuration=%2
@@ -9,13 +11,36 @@ 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%
+
+set DIRS=cppwinrt fast_fwd prebuild scratch strings test vsix
+set EXTS=.cpp .h
+for %%d in (%DIRS%) do call :format_files %~dp0%%d
+goto :post_format
+
+:format_files
+    for %%e in (%EXTS%) do (
+        for /R %1 %%f in (*%%e) do call :run_clang_format "%%f"
+    )
+    goto :eof
+
+:run_clang_format
+    "%CLANG_FORMAT%" -style=file -i %1
+    goto :eof
+
+:post_format
+
+:: 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 +62,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%

find_clang_format.cmd

@@ -0,0 +1,14 @@
+@echo off
+:: NOTE: No 'setlocal' since we're "returning" the definition of "CLANG_FORMAT" to the caller
+
+:: Clang format's behavior has changed over time, meaning that different machines with different versions of LLVM
+:: installed may get different formatting behavior. In an attempt to ensure consistency, we use the clang-format.exe
+:: that ships with Visual Studio. There may still be issues if two different machines have different versions of Visual
+:: Studio installed, however this will hopefully improve things
+set CLANG_FORMAT=%VCINSTALLDIR%\Tools\Llvm\bin\clang-format.exe
+if not exist "%CLANG_FORMAT%" (
+    set CLANG_FORMAT=
+    echo ERROR: clang-format.exe not found at %%VCINSTALLDIR%%\Tools\Llvm\bin\clang-format.exe
+    echo ERROR: Ensure that this script is being run from a Visual Studio command prompt
+    exit /B 1
+)