diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/BuildingLibcxx.rst | 51 | ||||
-rw-r--r-- | docs/DesignDocs/DebugMode.rst | 2 | ||||
-rw-r--r-- | docs/DesignDocs/VisibilityMacros.rst | 40 | ||||
-rw-r--r-- | docs/UsingLibcxx.rst | 12 | ||||
-rw-r--r-- | docs/index.rst | 4 |
5 files changed, 100 insertions, 9 deletions
diff --git a/docs/BuildingLibcxx.rst b/docs/BuildingLibcxx.rst index b00bbdd78..c7b5e9642 100644 --- a/docs/BuildingLibcxx.rst +++ b/docs/BuildingLibcxx.rst @@ -92,6 +92,57 @@ build would look like this: $ make check-libcxx # optional +Experimental Support for Windows +-------------------------------- + +The Windows support requires building with clang-cl as cl does not support one +required extension: `#include_next`. Furthermore, VS 2015 or newer (19.00) is +required. In the case of clang-cl, we need to specify the "MS Compatibility +Version" as it defaults to 2014 (18.00). + +CMake + Visual Studio +~~~~~~~~~~~~~~~~~~~~~ + +Building with Visual Studio currently does not permit running tests. However, +it is the simplest way to build. + +.. code-block:: batch + + > cmake -G "Visual Studio 14 2015" ^ + -T "LLVM-vs2014" ^ + -DLIBCXX_ENABLE_SHARED=YES ^ + -DLIBCXX_ENABLE_STATIC=NO ^ + -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO ^ + \path\to\libcxx + > cmake --build . + +CMake + ninja +~~~~~~~~~~~~~ + +Building with ninja is required for development to enable tests. +Unfortunately, doing so requires additional configuration as we cannot +just specify a toolset. + +.. code-block:: batch + + > cmake -G Ninja ^ + -DCMAKE_MAKE_PROGRAM=/path/to/ninja ^ + -DCMAKE_SYSTEM_NAME=Windows ^ + -DCMAKE_C_COMPILER=clang-cl ^ + -DCMAKE_C_FLAGS="-fms-compatibility-version=19.00 --target=i686--windows" ^ + -DCMAKE_CXX_COMPILER=clang-c ^ + -DCMAKE_CXX_FLAGS="-fms-compatibility-version=19.00 --target=i686--windows" ^ + -DLLVM_PATH=/path/to/llvm/tree ^ + -DLIBCXX_ENABLE_SHARED=YES ^ + -DLIBCXX_ENABLE_STATIC=NO ^ + -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO ^ + \path\to\libcxx + > /path/to/ninja cxx + > /path/to/ninja check-cxx + +Note that the paths specified with backward slashes must use the `\\` as the +directory separator as clang-cl may otherwise parse the path as an argument. + .. _`libc++abi`: http://libcxxabi.llvm.org/ diff --git a/docs/DesignDocs/DebugMode.rst b/docs/DesignDocs/DebugMode.rst index 166c733e6..3b997d446 100644 --- a/docs/DesignDocs/DebugMode.rst +++ b/docs/DesignDocs/DebugMode.rst @@ -3,7 +3,7 @@ Debug Mode ========== .. contents:: - :local + :local: .. _using-debug-mode: diff --git a/docs/DesignDocs/VisibilityMacros.rst b/docs/DesignDocs/VisibilityMacros.rst index 12c1d56b3..694882dd2 100644 --- a/docs/DesignDocs/VisibilityMacros.rst +++ b/docs/DesignDocs/VisibilityMacros.rst @@ -47,18 +47,17 @@ Visibility Macros A synonym for `_LIBCPP_INLINE_VISIBILITY` **_LIBCPP_TYPE_VIS** + Mark a type's typeinfo, vtable and members as having default visibility. + This attribute cannot be used on class templates. + +**_LIBCPP_TEMPLATE_VIS** Mark a type's typeinfo and vtable as having default visibility. - `_LIBCPP_TYPE_VIS`. This macro has no effect on the visibility of the - type's member functions. This attribute cannot be used on class templates. + This macro has no effect on the visibility of the type's member functions. **GCC Behavior**: GCC does not support Clang's `type_visibility(...)` attribute. With GCC the `visibility(...)` attribute is used and member functions are affected. -**_LIBCPP_TEMPLATE_VIS** - The same as `_LIBCPP_TYPE_VIS` except that it may be applied to class - templates. - **Windows Behavior**: DLLs do not support dllimport/export on class templates. The macro has an empty definition on this platform. @@ -110,6 +109,35 @@ Visibility Macros the extern template declaration) as exported on Windows, as discussed above. On all other platforms, this macro has an empty definition. +**_LIBCPP_METHOD_TEMPLATE_IMPLICIT_INSTANTIATION_VIS** + Mark a symbol as hidden so it will not be exported from shared libraries. This + is intended specifically for method templates of either classes marked with + `_LIBCPP_TYPE_VIS` or classes with an extern template instantiation + declaration marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS`. + + When building libc++ with hidden visibility, we want explicit template + instantiations to export members, which is consistent with existing Windows + behavior. We also want classes annotated with `_LIBCPP_TYPE_VIS` to export + their members, which is again consistent with existing Windows behavior. + Both these changes are necessary for clients to be able to link against a + libc++ DSO built with hidden visibility without encountering missing symbols. + + An unfortunate side effect, however, is that method templates of classes + either marked `_LIBCPP_TYPE_VIS` or with extern template instantiation + declarations marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` also get default + visibility when instantiated. These methods are often implicitly instantiated + inside other libraries which use the libc++ headers, and will therefore end up + being exported from those libraries, since those implicit instantiations will + receive default visibility. This is not acceptable for libraries that wish to + control their visibility, and led to PR30642. + + Consequently, all such problematic method templates are explicitly marked + either hidden (via this macro) or inline, so that they don't leak into client + libraries. The problematic methods were found by running + `bad-visibility-finder <https://github.com/smeenai/bad-visibility-finder>`_ + against the libc++ headers after making `_LIBCPP_TYPE_VIS` and + `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` expand to default visibility. + **_LIBCPP_EXTERN_TEMPLATE_INLINE_VISIBILITY** Mark a member function of a class template as visible and always inline. This macro should only be applied to member functions of class templates that are diff --git a/docs/UsingLibcxx.rst b/docs/UsingLibcxx.rst index 6d910ca6f..fe32f5e6b 100644 --- a/docs/UsingLibcxx.rst +++ b/docs/UsingLibcxx.rst @@ -180,3 +180,15 @@ thread safety annotations. * Giving `set`, `map`, `multiset`, `multimap` a comparator which is not const callable. +C++17 Specific Configuration Macros +----------------------------------- +**_LIBCPP_ENABLE_CXX17_REMOVED_FEATURES**: + This macro is used to re-enable all the features removed in C++17. The effect + is equivalent to manually defining each macro listed below. + +**_LIBCPP_ENABLE_CXX17_REMOVED_UNEXPECTED_FUNCTIONS**: + This macro is used to re-enable the `set_unexpected`, `get_unexpected`, and + `unexpected` functions, which were removed in C++17. + +**_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**: + This macro is used to re-enable `std::auto_ptr` in C++17. diff --git a/docs/index.rst b/docs/index.rst index 20838a517..58043f5a4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -120,7 +120,7 @@ This list contains known issues with libc++ A full list of currently open libc++ bugs can be `found here`__. -.. __: https://llvm.org/bugs/buglist.cgi?component=All%20Bugs&product=libc%2B%2B&query_format=advanced&resolution=---&order=changeddate%20DESC%2Cassigned_to%20DESC%2Cbug_status%2Cpriority%2Cbug_id&list_id=74184 +.. __: https://bugs.llvm.org/buglist.cgi?component=All%20Bugs&product=libc%2B%2B&query_format=advanced&resolution=---&order=changeddate%20DESC%2Cassigned_to%20DESC%2Cbug_status%2Cpriority%2Cbug_id&list_id=74184 Design Documents ---------------- @@ -180,7 +180,7 @@ Quick Links =========== * `LLVM Homepage <http://llvm.org/>`_ * `libc++abi Homepage <http://libcxxabi.llvm.org/>`_ -* `LLVM Bugzilla <http://llvm.org/bugs/>`_ +* `LLVM Bugzilla <https://bugs.llvm.org/>`_ * `cfe-commits Mailing List`_ * `cfe-dev Mailing List`_ * `Browse libc++ -- SVN <http://llvm.org/svn/llvm-project/libcxx/trunk/>`_ |