Clang Project

clang_source_code/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==================
14MSVC compatibility
15==================
16
17When Clang compiles C++ code for Windows, it attempts to be compatible with
18MSVC.  There are multiple dimensions to compatibility.
19
20First, Clang attempts to be ABI-compatible, meaning that Clang-compiled code
21should be able to link against MSVC-compiled code successfully.  However, C++
22ABIs are particularly large and complicated, and Clang's support for MSVC's C++
23ABI is a work in progress.  If you don't require MSVC ABI compatibility or don't
24want to use Microsoft's C and C++ runtimes, the mingw32 toolchain might be a
25better fit for your project.
26
27Second, Clang implements many MSVC language extensions, such as
28``__declspec(dllexport)`` and a handful of pragmas.  These are typically
29controlled by ``-fms-extensions``.
30
31Third, MSVC accepts some C++ code that Clang will typically diagnose as
32invalid.  When these constructs are present in widely included system headers,
33Clang attempts to recover and continue compiling the user's program.  Most
34parsing and semantic compatibility tweaks are controlled by
35``-fms-compatibility`` and ``-fdelayed-template-parsing``, and they are a work
36in progress.
37
38Finally, there is :ref:`clang-cl`, a driver program for clang that attempts to
39be compatible with MSVC's cl.exe.
40
41ABI features
42============
43
44The 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
112Template instantiation and name lookup
113======================================
114
115MSVC allows many invalid constructs in class templates that Clang has
116historically rejected.  In order to parse widely distributed headers for
117libraries 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
120The first major semantic difference is that MSVC appears to defer all parsing
121an analysis of inline method bodies in class templates until instantiation
122time.  By default on Windows, Clang attempts to follow suit.  This behavior is
123controlled by the ``-fdelayed-template-parsing`` flag.  While Clang delays
124parsing of method bodies, it still parses the bodies *before* template argument
125substitution, which is not what MSVC does.  The following compatibility tweaks
126are necessary to parse the template in those cases.
127
128MSVC allows some name lookup into dependent base classes.  Even on other
129platforms, this has been a `frequently asked question`_ for Clang users.  A
130dependent base class is a base class that depends on the value of a template
131parameter.  Clang cannot see any of the names inside dependent bases while it
132is parsing your template, so the user is sometimes required to use the
133``typename`` keyword to assist the parser.  On Windows, Clang attempts to
134follow the normal lookup rules, but if lookup fails, it will assume that the
135user intended to find the name in a dependent base.  While parsing the
136following program, Clang will recover as if the user had written the
137commented-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
151After recovery, Clang warns the user that this code is non-standard and issues
152a hint suggesting how to fix the problem.
153
154As of this writing, Clang is able to compile a simple ATL hello world
155application.  There are still issues parsing WRL headers for modern Windows 8
156apps, but they should be addressed soon.
157
CodeThinker, Enjoy your reading code