clang/docs/MSVCCompatibility.rst

   1 .. raw:: html
   2
   3   <style type="text/css">
   4     .none { background-color: #FFCCCC }
   5     .partial { background-color: #FFFF99 }
   6     .good { background-color: #CCFF99 }
   7   </style>
   8
   9 .. role:: none
  10 .. role:: partial
  11 .. role:: good
  12
  13 ==================
  14 MSVC compatibility
  15 ==================
  16
  17 When Clang compiles C++ code for Windows, it attempts to be compatible with
  18 MSVC.  There are multiple dimensions to compatibility.
  19
  20 First, Clang attempts to be ABI-compatible, meaning that Clang-compiled code
  21 should be able to link against MSVC-compiled code successfully.  However, C++
  22 ABIs are particularly large and complicated, and Clang's support for MSVC's C++
  23 ABI is a work in progress.  If you don't require MSVC ABI compatibility or don't
  24 want to use Microsoft's C and C++ runtimes, the mingw32 toolchain might be a
  25 better fit for your project.
  26
  27 Second, Clang implements many MSVC language extensions, such as
  28 ``__declspec(dllexport)`` and a handful of pragmas.  These are typically
  29 controlled by ``-fms-extensions``.
  30
  31 Third, MSVC accepts some C++ code that Clang will typically diagnose as
  32 invalid.  When these constructs are present in widely included system headers,
  33 Clang attempts to recover and continue compiling the user's program.  Most
  34 parsing and semantic compatibility tweaks are controlled by
  35 ``-fms-compatibility`` and ``-fdelayed-template-parsing``, and they are a work
  36 in progress.
  37
  38 Finally, there is :ref:`clang-cl`, a driver program for clang that attempts to
  39 be compatible with MSVC's cl.exe.
  40
  41 ABI features
  42 ============
  43
  44 The status of major ABI-impacting C++ features:
  45
  46 * Record layout: :good:`Complete`.  We've tested this with a fuzzer and have
  47   fixed all known bugs.
  48
  49 * Class inheritance: :good:`Mostly complete`.  This covers all of the standard
  50   OO features you would expect: virtual method inheritance, multiple
  51   inheritance, and virtual inheritance.  Every so often we uncover a bug where
  52   our tables are incompatible, but this is pretty well in hand.  This feature
  53   has also been fuzz tested.
  54
  55 * Name mangling: :good:`Ongoing`.  Every new C++ feature generally needs its own
  56   mangling.  For example, member pointer template arguments have an interesting
  57   and distinct mangling.  Fortunately, incorrect manglings usually do not result
  58   in runtime errors.  Non-inline functions with incorrect manglings usually
  59   result in link errors, which are relatively easy to diagnose.  Incorrect
  60   manglings for inline functions and templates result in multiple copies in the
  61   final image.  The C++ standard requires that those addresses be equal, but few
  62   programs rely on this.
  63
  64 * Member pointers: :good:`Mostly complete`.  Standard C++ member pointers are
  65   fully implemented and should be ABI compatible.  Both `#pragma
  66   pointers_to_members`_ and the `/vm`_ flags are supported. However, MSVC
  67   supports an extension to allow creating a `pointer to a member of a virtual
  68   base class`_.  Clang does not yet support this.
  69
  70 .. _#pragma pointers_to_members:
  71   https://msdn.microsoft.com/en-us/library/83cch5a6.aspx
  72 .. _/vm: https://msdn.microsoft.com/en-us/library/yad46a6z.aspx
  73 .. _pointer to a member of a virtual base class: https://llvm.org/PR15713
  74
  75 * Debug info: :good:`Mostly complete`.  Clang emits relatively complete CodeView
  76   debug information if ``/Z7`` or ``/Zi`` is passed. Microsoft's link.exe will
  77   transform the CodeView debug information into a PDB that works in Windows
  78   debuggers and other tools that consume PDB files like ETW. Work to teach lld
  79   about CodeView and PDBs is ongoing.
  80
  81 * RTTI: :good:`Complete`.  Generation of RTTI data structures has been
  82   finished, along with support for the ``/GR`` flag.
  83
  84 * C++ Exceptions: :good:`Mostly complete`.  Support for
  85   C++ exceptions (``try`` / ``catch`` / ``throw``) have been implemented for
  86   x86 and x64.  Our implementation has been well tested but we still get the
  87   odd bug report now and again.
  88   C++ exception specifications are ignored, but this is `consistent with Visual
  89   C++`_.
  90
  91 .. _consistent with Visual C++:
  92   https://msdn.microsoft.com/en-us/library/wfa0edys.aspx
  93
  94 * Asynchronous Exceptions (SEH): :partial:`Partial`.
  95   Structured exceptions (``__try`` / ``__except`` / ``__finally``) mostly
  96   work on x86 and x64.
  97   LLVM does not model asynchronous exceptions, so it is currently impossible to
  98   catch an asynchronous exception generated in the same frame as the catching
  99   ``__try``.
 100
 101 * Thread-safe initialization of local statics: :good:`Complete`.  MSVC 2015
 102   added support for thread-safe initialization of such variables by taking an
 103   ABI break.
 104   We are ABI compatible with both the MSVC 2013 and 2015 ABI for static local
 105   variables.
 106
 107 * Lambdas: :good:`Mostly complete`.  Clang is compatible with Microsoft's
 108   implementation of lambdas except for providing overloads for conversion to
 109   function pointer for different calling conventions.  However, Microsoft's
 110   extension is non-conforming.
 111
 112 Template instantiation and name lookup
 113 ======================================
 114
 115 MSVC allows many invalid constructs in class templates that Clang has
 116 historically rejected.  In order to parse widely distributed headers for
 117 libraries such as the Active Template Library (ATL) and Windows Runtime Library
 118 (WRL), some template rules have been relaxed or extended in Clang on Windows.
 119
 120 The first major semantic difference is that MSVC appears to defer all parsing
 121 an analysis of inline method bodies in class templates until instantiation
 122 time.  By default on Windows, Clang attempts to follow suit.  This behavior is
 123 controlled by the ``-fdelayed-template-parsing`` flag.  While Clang delays
 124 parsing of method bodies, it still parses the bodies *before* template argument
 125 substitution, which is not what MSVC does.  The following compatibility tweaks
 126 are necessary to parse the template in those cases.
 127
 128 MSVC allows some name lookup into dependent base classes.  Even on other
 129 platforms, this has been a `frequently asked question`_ for Clang users.  A
 130 dependent base class is a base class that depends on the value of a template
 131 parameter.  Clang cannot see any of the names inside dependent bases while it
 132 is parsing your template, so the user is sometimes required to use the
 133 ``typename`` keyword to assist the parser.  On Windows, Clang attempts to
 134 follow the normal lookup rules, but if lookup fails, it will assume that the
 135 user intended to find the name in a dependent base.  While parsing the
 136 following program, Clang will recover as if the user had written the
 137 commented-out code:
 138
 139 .. _frequently asked question:
 140   https://clang.llvm.org/compatibility.html#dep_lookup
 141
 142 .. code-block:: c++
 143
 144   template <typename T>
 145   struct Foo : T {
 146     void f() {
 147       /*typename*/ T::UnknownType x =  /*this->*/unknownMember;
 148     }
 149   };
 150
 151 After recovery, Clang warns the user that this code is non-standard and issues
 152 a hint suggesting how to fix the problem.
 153
 154 As of this writing, Clang is able to compile a simple ATL hello world
 155 application.  There are still issues parsing WRL headers for modern Windows 8
 156 apps, but they should be addressed soon.
 157
 158 __forceinline behavior
 159 ======================
 160
 161 ``__forceinline`` behaves like ``[[clang::always_inline]]``.
 162 Inlining is always attempted regardless of optimization level.
 163
 164 This differs from MSVC where ``__forceinline`` is only respected once inline expansion is enabled
 165 which allows any function marked implicitly or explicitly ``inline`` or ``__forceinline`` to be expanded.
 166 Therefore functions marked ``__forceinline`` will be expanded when the optimization level is ``/Od`` unlike
 167 MSVC where ``__forceinline`` will not be expanded under ``/Od``.
 168
 169 SIMD and instruction set intrinsic behavior
 170 ===========================================
 171
 172 Clang follows the GCC model for intrinsics and not the MSVC model.
 173 There are currently no plans to support the MSVC model.
 174
 175 MSVC intrinsics always emit the machine instruction the intrinsic models regardless of the compile time options specified.
 176 For example ``__popcnt`` always emits the x86 popcnt instruction even if the compiler does not have the option enabled to emit popcnt on its own volition.
 177
 178 There are two common cases where code that compiles with MSVC will need reworking to build on clang.
 179 Assume the examples are only built with `-msse2` so we do not have the intrinsics at compile time.
 180
 181 .. code-block:: c++
 182
 183   unsigned PopCnt(unsigned v) {
 184     if (HavePopCnt)
 185       return __popcnt(v);
 186     else
 187       return GenericPopCnt(v);
 188   }
 189
 190 .. code-block:: c++
 191
 192   __m128 dot4_sse3(__m128 v0, __m128 v1) {
 193     __m128 r = _mm_mul_ps(v0, v1);
 194     r = _mm_hadd_ps(r, r);
 195     r = _mm_hadd_ps(r, r);
 196     return r;
 197   }
 198
 199 Clang expects that either you have compile time support for the target features, `-msse3` and `-mpopcnt`, you mark the function with the expected target feature or use runtime detection with an indirect call.
 200
 201 .. code-block:: c++
 202
 203   __attribute__((__target__("sse3"))) __m128 dot4_sse3(__m128 v0, __m128 v1) {
 204     __m128 r = _mm_mul_ps(v0, v1);
 205     r = _mm_hadd_ps(r, r);
 206     r = _mm_hadd_ps(r, r);
 207     return r;
 208   }
 209
 210 The SSE3 dot product can be easily fixed by either building the translation unit with SSE3 support or using `__target__` to compile that specific function with SSE3 support.
 211
 212 .. code-block:: c++
 213
 214   unsigned PopCnt(unsigned v) {
 215     if (HavePopCnt)
 216       return __popcnt(v);
 217     else
 218       return GenericPopCnt(v);
 219   }
 220
 221 The above ``PopCnt`` example must be changed to work with clang. If we mark the function with `__target__("popcnt")` then the compiler is free to emit popcnt at will which we do not want. While this isn't a concern in our small example it is a concern in larger functions with surrounding code around the intrinsics. Similar reasoning for compiling the translation unit with `-mpopcnt`.
 222 We must split each branch into its own function that can be called indirectly instead of using the intrinsic directly.
 223
 224 .. code-block:: c++
 225
 226   __attribute__((__target__("popcnt"))) unsigned hwPopCnt(unsigned v) { return __popcnt(v); }
 227   unsigned (*PopCnt)(unsigned) = HavePopCnt ? hwPopCnt : GenericPopCnt;
 228
 229 .. code-block:: c++
 230
 231   __attribute__((__target__("popcnt"))) unsigned hwPopCnt(unsigned v) { return __popcnt(v); }
 232   unsigned PopCnt(unsigned v) {
 233     if (HavePopCnt)
 234       return hwPopCnt(v);
 235     else
 236       return GenericPopCnt(v);
 237   }
 238
 239 In the above example ``hwPopCnt`` will not be inlined into ``PopCnt`` since ``PopCnt`` doesn't have the popcnt target feature.
 240 With a larger function that does real work the function call overhead is negligible. However in our popcnt example there is the function call
 241 overhead. There is no analog for this specific MSVC behavior in clang.
 242
 243 For clang we effectively have to create the dispatch function ourselves to each specfic implementation.
 244
 245 SIMD vector types
 246 =================
 247
 248 Clang's simd vector types are builtin types and not user defined types as in MSVC. This does have some observable behavior changes.
 249 We will look at the x86 `__m128` type for the examples below but the statements apply to all vector types including ARM's `float32x4_t`.
 250
 251 There are no members that can be accessed on the vector types. Vector types are not structs in clang.
 252 You cannot use ``__m128.m128_f32[0]`` to access the first element of the `__m128`.
 253 This also means struct initialization like ``__m128{ { 0.0f, 0.0f, 0.0f, 0.0f } }`` will not compile with clang.
 254
 255 Since vector types are builtin types, clang implements operators on them natively.
 256
 257 .. code-block:: c++
 258
 259   #ifdef _MSC_VER
 260   __m128 operator+(__m128 a, __m128 b) { return _mm_add_ps(a, b); }
 261   #endif
 262
 263 The above code will fail to compile since overloaded 'operator+' must have at least one parameter of class or enumeration type.
 264 You will need to fix such code to have the check ``#if defined(_MSC_VER) && !defined(__clang__)``.
 265
 266 Since `__m128` is not a class type in clang any overloads after a template definition will not be considered.
 267
 268 .. code-block:: c++
 269
 270   template<class T>
 271   void foo(T) {}
 272
 273   template<class T>
 274   void bar(T t) {
 275     foo(t);
 276   }
 277
 278   void foo(__m128) {}
 279
 280   int main() {
 281     bar(_mm_setzero_ps());
 282   }
 283
 284 With MSVC ``foo(__m128)`` will be selected but with clang ``foo<__m128>()`` will be selected since on clang `__m128` is a builtin type.
 285
 286 In general the takeaway is `__m128` is a builtin type on clang while a class type on MSVC.