Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 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++ |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 22 | ABIs are particularly large and complicated, and Clang's support for MSVC's C++ |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 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 | |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 46 | * Record layout: :good:`Complete`. We've tested this with a fuzzer and have |
| 47 | fixed all known bugs. |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 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 |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 52 | our tables are incompatible, but this is pretty well in hand. This feature |
| 53 | has also been fuzz tested. |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 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 | http://msdn.microsoft.com/en-us/library/83cch5a6.aspx |
| 72 | .. _/vm: http://msdn.microsoft.com/en-us/library/yad46a6z.aspx |
| 73 | .. _pointer to a member of a virtual base class: http://llvm.org/PR15713 |
| 74 | |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 75 | * Debug info: :partial:`Minimal`. Clang emits both CodeView line tables |
| 76 | (similar to what MSVC emits when given the ``/Z7`` flag) and DWARF debug |
| 77 | information into the object file. |
| 78 | Microsoft's link.exe will transform the CodeView line tables into a PDB, |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 79 | enabling stack traces in all modern Windows debuggers. Clang does not emit |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 80 | any CodeView-compatible type info or description of variable layout. |
| 81 | Binaries linked with either binutils' ld or LLVM's lld should be usable with |
| 82 | GDB however sophisticated C++ expressions are likely to fail. |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 83 | |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 84 | * RTTI: :good:`Complete`. Generation of RTTI data structures has been |
| 85 | finished, along with support for the ``/GR`` flag. |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 86 | |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame] | 87 | * Exceptions and SEH: :partial:`Minimal`. Clang can parse both constructs, but |
Pirama Arumuga Nainar | 3ea9e33 | 2015-04-08 08:57:32 -0700 | [diff] [blame^] | 88 | does not know how to emit compatible handlers. Clang can throw and rethrow |
| 89 | C++ exceptions. |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 90 | |
| 91 | * Thread-safe initialization of local statics: :none:`Unstarted`. We are ABI |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 92 | compatible with MSVC 2013, which does not support thread-safe local statics. |
| 93 | MSVC "14" changed the ABI to make initialization of local statics thread safe, |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 94 | and we have not yet implemented this. |
| 95 | |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 96 | * Lambdas: :good:`Mostly complete`. Clang is compatible with Microsoft's |
| 97 | implementation of lambdas except for providing overloads for conversion to |
| 98 | function pointer for different calling conventions. However, Microsoft's |
| 99 | extension is non-conforming. |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 100 | |
| 101 | Template instantiation and name lookup |
| 102 | ====================================== |
| 103 | |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 104 | MSVC allows many invalid constructs in class templates that Clang has |
| 105 | historically rejected. In order to parse widely distributed headers for |
| 106 | libraries such as the Active Template Library (ATL) and Windows Runtime Library |
| 107 | (WRL), some template rules have been relaxed or extended in Clang on Windows. |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 108 | |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 109 | The first major semantic difference is that MSVC appears to defer all parsing |
| 110 | an analysis of inline method bodies in class templates until instantiation |
| 111 | time. By default on Windows, Clang attempts to follow suit. This behavior is |
| 112 | controlled by the ``-fdelayed-template-parsing`` flag. While Clang delays |
| 113 | parsing of method bodies, it still parses the bodies *before* template argument |
| 114 | substitution, which is not what MSVC does. The following compatibility tweaks |
Pirama Arumuga Nainar | 3ea9e33 | 2015-04-08 08:57:32 -0700 | [diff] [blame^] | 115 | are necessary to parse the template in those cases. |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 116 | |
| 117 | MSVC allows some name lookup into dependent base classes. Even on other |
| 118 | platforms, this has been a `frequently asked question`_ for Clang users. A |
| 119 | dependent base class is a base class that depends on the value of a template |
| 120 | parameter. Clang cannot see any of the names inside dependent bases while it |
| 121 | is parsing your template, so the user is sometimes required to use the |
| 122 | ``typename`` keyword to assist the parser. On Windows, Clang attempts to |
| 123 | follow the normal lookup rules, but if lookup fails, it will assume that the |
| 124 | user intended to find the name in a dependent base. While parsing the |
| 125 | following program, Clang will recover as if the user had written the |
| 126 | commented-out code: |
| 127 | |
| 128 | .. _frequently asked question: |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 129 | http://clang.llvm.org/compatibility.html#dep_lookup |
| 130 | |
| 131 | .. code-block:: c++ |
| 132 | |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 133 | template <typename T> |
| 134 | struct Foo : T { |
| 135 | void f() { |
| 136 | /*typename*/ T::UnknownType x = /*this->*/unknownMember; |
| 137 | } |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 138 | }; |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 139 | |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 140 | After recovery, Clang warns the user that this code is non-standard and issues |
| 141 | a hint suggesting how to fix the problem. |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 142 | |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 143 | As of this writing, Clang is able to compile a simple ATL hello world |
| 144 | application. There are still issues parsing WRL headers for modern Windows 8 |
| 145 | apps, but they should be addressed soon. |