diff options
author | Reid Kleckner <reid@kleckner.net> | 2014-02-28 23:46:04 +0000 |
---|---|---|
committer | Reid Kleckner <reid@kleckner.net> | 2014-02-28 23:46:04 +0000 |
commit | fc0df2a8797905b5843da5cdd3911ee0abc64530 (patch) | |
tree | 0fa4bf32c1017bc1a7208624e8f50f416ee01ff0 /docs/MSVCCompatibility.rst | |
parent | f89c97e5806110219a6526fade2e690b3dd93ca8 (diff) | |
download | clang-fc0df2a8797905b5843da5cdd3911ee0abc64530.tar.gz |
Add Clang docs about MSVC compatibility
This documents some of the status of supported functionality in MSVC
quirks mode. Some of this should be in
http://clang.llvm.org/compatibility.html instead when things have
stabilized.
git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@202559 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs/MSVCCompatibility.rst')
-rw-r--r-- | docs/MSVCCompatibility.rst | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/docs/MSVCCompatibility.rst b/docs/MSVCCompatibility.rst new file mode 100644 index 0000000000..346b860e76 --- /dev/null +++ b/docs/MSVCCompatibility.rst @@ -0,0 +1,121 @@ +.. raw:: html + + <style type="text/css"> + .none { background-color: #FFCCCC } + .partial { background-color: #FFFF99 } + .good { background-color: #CCFF99 } + </style> + +.. role:: none +.. role:: partial +.. role:: good + +================== +MSVC compatibility +================== + +When Clang compiles C++ code for Windows, it attempts to be compatible with +MSVC. There are multiple dimensions to compatibility. + +First, Clang attempts to be ABI-compatible, meaning that Clang-compiled code +should be able to link against MSVC-compiled code successfully. However, C++ +ABIs are particular large and complicated, and Clang's support for MSVC's C++ +ABI is a work in progress. If you don't require MSVC ABI compatibility or don't +want to use Microsoft's C and C++ runtimes, the mingw32 toolchain might be a +better fit for your project. + +Second, Clang implements many MSVC language extensions, such as +``__declspec(dllexport)`` and a handful of pragmas. These are typically +controlled by ``-fms-extensions``. + +Finally, MSVC accepts some C++ code that Clang will typically diagnose as +invalid. When these constructs are present in widely included system headers, +Clang attempts to recover and continue compiling the user's program. Most +parsing and semantic compatibility tweaks are controlled by +``-fms-compatibility`` and ``-fdelayed-template-parsing``, and they are a work +in progress. + +ABI features +============ + +The status of major ABI-impacting C++ features: + +* Record layout: :good:`Mostly complete`. We've attacked this with a fuzzer, + and most of the remaining failures involve ``#pragma pack``, + ``__declspec(align(N))``, or other pragmas. + +* Class inheritance: :good:`Mostly complete`. This covers all of the standard + OO features you would expect: virtual method inheritance, multiple + inheritance, and virtual inheritance. Every so often we uncover a bug where + our tables are incompatible, but this is pretty well in hand. + +* Name mangling: :good:`Ongoing`. Every new C++ feature generally needs its own + mangling. For example, member pointer template arguments have an interesting + and distinct mangling. Fortunately, incorrect manglings usually do not result + in runtime errors. Non-inline functions with incorrect manglings usually + result in link errors, which are relatively easy to diagnose. Incorrect + manglings for inline functions and templates result in multiple copies in the + final image. The C++ standard requires that those addresses be equal, but few + programs rely on this. + +* Member pointers: :good:`Mostly complete`. Standard C++ member pointers are + fully implemented and should be ABI compatible. Both `#pragma + pointers_to_members`_ and the `/vm`_ flags are supported. However, MSVC + supports an extension to allow creating a `pointer to a member of a virtual + base class`_. Clang does not yet support this. + +.. _#pragma pointers_to_members: + http://msdn.microsoft.com/en-us/library/83cch5a6.aspx +.. _/vm: http://msdn.microsoft.com/en-us/library/yad46a6z.aspx +.. _pointer to a member of a virtual base class: http://llvm.org/PR15713 + +* Debug info: :partial:`Minimal`. Clang emits CodeView line tables into the + object file, similar to what MSVC emits when given the ``/Z7`` flag. + Microsoft's link.exe will read this information and use it to create a PDB, + enabling stack traces in all modern Windows debuggers. Clang does not emit + any type info or description of variable layout. + +* `RTTI`_: :none:`Unstarted`. See the bug for a discussion of what needs to + happen first. + +.. _RTTI: http://llvm.org/PR18951 + +* Exceptions and SEH: :none:`Unstarted`. Clang can parse both constructs, but + does not know how to emit compatible handlers. This depends on RTTI. + +* Thread-safe initialization of local statics: :none:`Unstarted`. We are ABI + compatible with MSVC 2012, which does not support thread-safe local statics. + MSVC 2013 changed the ABI to make initialization of local statics thread safe, + and we have not yet implemented this. + +* Lambdas in ABI boundaries: :none:`Infeasible`. It is unlikely that we will + ever be fully ABI compatible with lambdas declared in inline functions due to + what appears to be a hash code in the name mangling. Lambdas that are not + externally visible should work fine. + +Template instantiation and name lookup +====================================== + +In addition to the usual `dependent name lookup FAQs `_, Clang is often unable +to parse certain invalid C++ constructs that MSVC allows. As of this writing, +Clang will reject code with missing ``typename`` annotations: + +.. _dependent name lookup FAQs: + http://clang.llvm.org/compatibility.html#dep_lookup + +.. code-block:: c++ + + struct X { + typedef int type; + }; + template<typename T> int f() { + // missing typename keyword + return sizeof(/*typename*/ T::type); + } + template void f<X>(); + +Accepting code like this is ongoing work. Ultimately, it may be cleaner to +`implement a token-based template instantiation mode`_ than it is to add +compatibility hacks to the existing AST-based instantiation. + +.. _implement a token-based template instantiation mode: http://llvm.org/PR18714 |