darlinghq/darling-libcxx
1
0
Fork 0
mirror of https://github.com/darlinghq/darling-libcxx.git synced 2024-11-27 13:50:23 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
41cdb89ec7
darling-libcxx/docs/index.rst

194 lines
6.6 KiB
ReStructuredText
Raw Normal View History

[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
.. _index:
=============================
"libc++" C++ Standard Library
=============================
Overview
========
[libcxx] Mentions "targeting C++11 and above" instead of "targeting C++11" in the doc git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@293071 91177308-0d34-0410-b5e6-96231b3b80d8
2017-01-25 17:00:30 +00:00
libc++ is a new implementation of the C++ standard library, targeting C++11 and
above.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
* Features and Goals
* Correctness as defined by the C++11 standard.
* Fast execution.
* Minimal memory use.
* Fast compile times.
* ABI compatibility with gcc's libstdc++ for some low-level features
such as exception objects, rtti and memory allocation.
* Extensive unit tests.
* Design and Implementation:
* Extensive unit tests
* Internal linker model can be dumped/read to textual format
* Additional linking features can be plugged in as "passes"
* OS specific and CPU specific code factored out
Getting Started with libc++
---------------------------
.. toctree::
:maxdepth: 2
[libc++] Add a link to the Release notes from the main libc++ documentation git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@341551 91177308-0d34-0410-b5e6-96231b3b80d8
2018-09-06 15:05:43 +00:00
ReleaseNotes
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
UsingLibcxx
BuildingLibcxx
TestingLibcxx
Test commit for builder git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@246910 91177308-0d34-0410-b5e6-96231b3b80d8
2015-09-05 05:29:23 +00:00
Implement feature test macros using a script. Summary: This patch implements all the feature test macros libc++ currently supports, as specified by the standard or cppreference prior to C++2a. The tests and `<version>` header are generated using a script. The script contains a table of each feature test macro, the headers it should be accessible from, and its values of each dialect of C++. When a new feature test macro is added or needed, the table should be updated and the script re-run. Reviewers: mclow.lists, jfb, serge-sans-paille Reviewed By: mclow.lists Subscribers: arphaman, jfb, ldionne, libcxx-commits Differential Revision: https://reviews.llvm.org/D56750 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@351286 91177308-0d34-0410-b5e6-96231b3b80d8
2019-01-16 01:37:43 +00:00
.. toctree::
:hidden:
FeatureTestMacroTable
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
Current Status
--------------
After its initial introduction, many people have asked "why start a new
library instead of contributing to an existing library?" (like Apache's
libstdcxx, GNU's libstdc++, STLport, etc). There are many contributing
reasons, but some of the major ones are:
Cleanup new documentation index and transfer more information from www/index.html git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@246913 91177308-0d34-0410-b5e6-96231b3b80d8
2015-09-05 06:50:03 +00:00
* From years of experience (including having implemented the standard
library before), we've learned many things about implementing
the standard containers which require ABI breakage and fundamental changes
to how they are implemented. For example, it is generally accepted that
building std::string using the "short string optimization" instead of
using Copy On Write (COW) is a superior approach for multicore
machines (particularly in C++11, which has rvalue references). Breaking
ABI compatibility with old versions of the library was
determined to be critical to achieving the performance goals of
libc++.
* Mainline libstdc++ has switched to GPL3, a license which the developers
of libc++ cannot use. libstdc++ 4.2 (the last GPL2 version) could be
independently extended to support C++11, but this would be a fork of the
codebase (which is often seen as worse for a project than starting a new
independent one). Another problem with libstdc++ is that it is tightly
integrated with G++ development, tending to be tied fairly closely to the
matching version of G++.
* STLport and the Apache libstdcxx library are two other popular
candidates, but both lack C++11 support. Our experience (and the
experience of libstdc++ developers) is that adding support for C++11 (in
particular rvalue references and move-only types) requires changes to
almost every class and function, essentially amounting to a rewrite.
Faced with a rewrite, we decided to start from scratch and evaluate every
design decision from first principles based on experience.
Further, both projects are apparently abandoned: STLport 5.2.1 was
released in Oct'08, and STDCXX 4.2.1 in May'08.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
Platform and Compiler Support
-----------------------------
refresh the libc++ homepage git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@342624 91177308-0d34-0410-b5e6-96231b3b80d8
2018-09-20 07:57:31 +00:00
libc++ is known to work on the following platforms, using gcc and
clang.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
Note that functionality provided by ``<atomic>`` is only functional with clang
and GCC.
============ ==================== ============ ========================
OS Arch Compilers ABI Library
============ ==================== ============ ========================
[Docs] Modernize references to macOS Summary: This updates all places in documentation that refer to "Mac OS X", "OS X", etc. to instead use the modern name "macOS" when no specific version number is mentioned. If a specific version is mentioned, this attempts to use the OS name at the time of that version: * Mac OS X for 10.0 - 10.7 * OS X for 10.8 - 10.11 * macOS for 10.12 - present Reviewers: JDevlieghere Subscribers: mgorny, christof, arphaman, cfe-commits, lldb-commits, libcxx-commits, llvm-commits Tags: #clang, #lldb, #libc, #llvm Differential Revision: https://reviews.llvm.org/D62654 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@362113 91177308-0d34-0410-b5e6-96231b3b80d8
2019-05-30 16:46:22 +00:00
macOS i386, x86_64 Clang, GCC libc++abi
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
FreeBSD 10+ i386, x86_64, ARM Clang, GCC libcxxrt, libc++abi
Linux i386, x86_64 Clang, GCC libc++abi
============ ==================== ============ ========================
The following minimum compiler versions are strongly recommended.
* Clang 3.5 and above
Make GCC in C++03 Unsupported Summary: This patch make G++03 explicitly unsupported with libc++, as discussed on the mailing lists. Below is the rational for this decision. ---------------------------------------------------------------------------------------------------- libc++ claims to support GCC with C++03 ("G++03"), and this is a problem for our users. Our C++03 users are all using Clang. They must be. Less than 9% of the C++03 tests pass with GCC [1][2]. No non-trivial C++ program could work. Attempting to support G++03 impacts our QoI considerably. Unlike Clang, G++03 offers almost no C++11 extensions. If we could remove all the fallbacks for G++03, it would mean libc++ could:: * Improve Correctness: Every `#ifdef _LIBCPP_HAS_NO_<C++11-feature>` is a bug manifest. It exists to admit for deviant semantics. * Achieve ABI stability between C++03 and C++11 Differences between our C++03 and C++Rest branches contain ABI bugs. For example `std::nullptr_t` and `std::function::operator()(...)` are currently incompatible between C++11 and C++03, but could be fixed. * Decrease Compile Times and Memory Usage: Writing efficient SFINAE requires C++11. Using alias templates, libc++ could reduce the number of instantiations it produces substantially. * Decrease Binary Size Similar to the last point, G++03 forces metaprogramming techniques that emit more debug information [3] [4]. Compared to libstdc++, debug information size increases of +10% are not uncommon. Reviewers: ldionne, mclow.lists, EricWF Reviewed By: ldionne, EricWF Subscribers: zoecarver, aprantl, dexonsmith, arphaman, libcxx-commits, #libc Differential Revision: https://reviews.llvm.org/D63154 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@363219 91177308-0d34-0410-b5e6-96231b3b80d8
2019-06-13 00:37:25 +00:00
* GCC 5.0 and above.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
Make GCC in C++03 Unsupported Summary: This patch make G++03 explicitly unsupported with libc++, as discussed on the mailing lists. Below is the rational for this decision. ---------------------------------------------------------------------------------------------------- libc++ claims to support GCC with C++03 ("G++03"), and this is a problem for our users. Our C++03 users are all using Clang. They must be. Less than 9% of the C++03 tests pass with GCC [1][2]. No non-trivial C++ program could work. Attempting to support G++03 impacts our QoI considerably. Unlike Clang, G++03 offers almost no C++11 extensions. If we could remove all the fallbacks for G++03, it would mean libc++ could:: * Improve Correctness: Every `#ifdef _LIBCPP_HAS_NO_<C++11-feature>` is a bug manifest. It exists to admit for deviant semantics. * Achieve ABI stability between C++03 and C++11 Differences between our C++03 and C++Rest branches contain ABI bugs. For example `std::nullptr_t` and `std::function::operator()(...)` are currently incompatible between C++11 and C++03, but could be fixed. * Decrease Compile Times and Memory Usage: Writing efficient SFINAE requires C++11. Using alias templates, libc++ could reduce the number of instantiations it produces substantially. * Decrease Binary Size Similar to the last point, G++03 forces metaprogramming techniques that emit more debug information [3] [4]. Compared to libstdc++, debug information size increases of +10% are not uncommon. Reviewers: ldionne, mclow.lists, EricWF Reviewed By: ldionne, EricWF Subscribers: zoecarver, aprantl, dexonsmith, arphaman, libcxx-commits, #libc Differential Revision: https://reviews.llvm.org/D63154 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@363219 91177308-0d34-0410-b5e6-96231b3b80d8
2019-06-13 00:37:25 +00:00
The C++03 dialect is only supported for Clang compilers.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
C++ Dialect Support
---------------------
* C++11 - Complete
Try to fix links for libcxx.llvm.org/docs again. git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@246950 91177308-0d34-0410-b5e6-96231b3b80d8
2015-09-06 23:09:54 +00:00
* `C++14 - Complete <http://libcxx.llvm.org/cxx1y_status.html>`__
refresh the libc++ homepage git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@342624 91177308-0d34-0410-b5e6-96231b3b80d8
2018-09-20 07:57:31 +00:00
* `C++17 - In Progress <http://libcxx.llvm.org/cxx1z_status.html>`__
Try to fix links for libcxx.llvm.org/docs again. git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@246950 91177308-0d34-0410-b5e6-96231b3b80d8
2015-09-06 23:09:54 +00:00
* `Post C++14 Technical Specifications - In Progress <http://libcxx.llvm.org/ts1z_status.html>`__
Implement feature test macros using a script. Summary: This patch implements all the feature test macros libc++ currently supports, as specified by the standard or cppreference prior to C++2a. The tests and `<version>` header are generated using a script. The script contains a table of each feature test macro, the headers it should be accessible from, and its values of each dialect of C++. When a new feature test macro is added or needed, the table should be updated and the script re-run. Reviewers: mclow.lists, jfb, serge-sans-paille Reviewed By: mclow.lists Subscribers: arphaman, jfb, ldionne, libcxx-commits Differential Revision: https://reviews.llvm.org/D56750 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@351286 91177308-0d34-0410-b5e6-96231b3b80d8
2019-01-16 01:37:43 +00:00
* :ref:`C++ Feature Test Macro Status <feature-status>`
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
Notes and Known Issues
----------------------
This list contains known issues with libc++
* Building libc++ with ``-fno-rtti`` is not supported. However
linking against it with ``-fno-rtti`` is supported.
Fix another bad link in the new docs git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@246951 91177308-0d34-0410-b5e6-96231b3b80d8
2015-09-06 23:22:02 +00:00
A full list of currently open libc++ bugs can be `found here`__.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
Update all bug URL's to point to https://bugs.llvm.org/... git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@295434 91177308-0d34-0410-b5e6-96231b3b80d8
2017-02-17 08:37:03 +00:00
.. __: 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
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
Design Documents
----------------
[libcxx] Capture configuration information when installing the libc++ headers Summary: Hi all, This patch is a successor to D11963. However it has changed dramatically and I felt it would be best to start a new review thread. Please read the design documentation added in this patch for a description of how it works. Reviewers: mclow.lists, danalbert, jroelofs, EricWF Subscribers: vkalintiris, rnk, ed, espositofulvio, asl, eugenis, cfe-commits Differential Revision: http://reviews.llvm.org/D13407 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@250235 91177308-0d34-0410-b5e6-96231b3b80d8
2015-10-13 22:12:02 +00:00
.. toctree::
:maxdepth: 1
Add markup for libc++ dylib availability Libc++ is used as a system library on macOS and iOS (amongst others). In order for users to be able to compile a binary that is intended to be deployed to an older version of the platform, clang provides the availability attribute <https://clang.llvm.org/docs/AttributeReference.html#availability>_ that can be placed on declarations to describe the lifecycle of a symbol in the library. See docs/DesignDocs/AvailabilityMarkup.rst for more information. Differential Revision: https://reviews.llvm.org/D31739 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@302172 91177308-0d34-0410-b5e6-96231b3b80d8
2017-05-04 17:08:54 +00:00
DesignDocs/AvailabilityMarkup
Implement a throwing version of _LIBCPP_ASSERT. This patch implements changes to allow _LIBCPP_ASSERT to throw on failure instead of aborting. The main changes needed to do this are: 1. Change _LIBCPP_ASSERT to call a handler via a replacable function pointer instead of calling abort directly. Additionally this patch implements two handler functions, one which aborts and another that throws an exception. 2. Add _NOEXCEPT_DEBUG macro for disabling noexcept spec on function which contain _LIBCPP_ASSERT. This is required in order to prevent assertion failures throwing through a noexcept function. This macro has no effect unless _LIBCPP_DEBUG_USE_EXCEPTIONS is defined. Having a non-aborting _LIBCPP_ASSERT is very important to allow sane testing of debug mode. Currently we can only have one test case per file, since the test case will cause the program to abort. Testing debug mode this way would require thousands of test files, most of which would be 95% boiler plate. I don't think this is a feasible strategy. Fortunately using a throwing debug handler solves these issues. Additionally this patch rewrites the documentation for debug mode. git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@290651 91177308-0d34-0410-b5e6-96231b3b80d8
2016-12-28 04:58:52 +00:00
DesignDocs/DebugMode
[libcxx] Capture configuration information when installing the libc++ headers Summary: Hi all, This patch is a successor to D11963. However it has changed dramatically and I felt it would be best to start a new review thread. Please read the design documentation added in this patch for a description of how it works. Reviewers: mclow.lists, danalbert, jroelofs, EricWF Subscribers: vkalintiris, rnk, ed, espositofulvio, asl, eugenis, cfe-commits Differential Revision: http://reviews.llvm.org/D13407 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@250235 91177308-0d34-0410-b5e6-96231b3b80d8
2015-10-13 22:12:02 +00:00
DesignDocs/CapturingConfigInfo
Use __config_site when building libc++. Also cleanup ABI versioning doc git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@250261 91177308-0d34-0410-b5e6-96231b3b80d8
2015-10-14 00:22:05 +00:00
DesignDocs/ABIVersioning
[libcxx] Slightly improved policy for handling experimental features Summary: Following the discussion on the libcxx-dev mailing list (http://lists.llvm.org/pipermail/libcxx-dev/2019-May/000358.html), this implements the new policy for handling experimental features and their deprecation. We basically add a deprecation warning for std::experimental::filesystem, and we remove a bunch of <experimental/*> headers that were now empty. Reviewers: mclow.lists, EricWF Subscribers: mgorny, christof, jkorous, dexonsmith, arphaman, libcxx-commits, jfb Tags: #libc Differential Revision: https://reviews.llvm.org/D62428 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@363072 91177308-0d34-0410-b5e6-96231b3b80d8
2019-06-11 14:48:40 +00:00
DesignDocs/ExperimentalFeatures
[libc++] Fix and document visibility attributes for Clang, GCC and Windows. Summary: This patch fixes a number of problems with the visibility macros across GCC (on Unix) and Windows (DLL import/export semantics). All of the visibility macros are now documented under `DesignDocs/VisibilityMacros.rst`. Now I'll no longer forget the subtleties of each! This patch adds two new visibility macros: * `_LIBCPP_ENUM_VIS` for controlling the typeinfo of enum types. Only Clang supports this. * `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` for redefining visibility on explicit instantiation declarations. Clang and Windows require this. After applying this patch GCC only emits one -Wattribute warning opposed to 30+. Reviewers: mclow.lists, EricWF Subscribers: beanz, mgorny, cfe-commits Differential Revision: https://reviews.llvm.org/D24602 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@281673 91177308-0d34-0410-b5e6-96231b3b80d8
2016-09-15 22:27:07 +00:00
DesignDocs/VisibilityMacros
[libc++] Cleanup and document <__threading_support> Summary: This patch attempts to clean up the macro configuration mess in `<__threading_support>`, specifically the mess involving external threading variants. Additionally this patch adds design documentation for `<__threading_support>` and the configuration macros it uses. The primary change in this patch is separating the idea of an "external API" provided by `<__external_threading>` and the idea of having an external threading library. Now `_LIBCPP_HAS_THREAD_API_EXTERNAL` means that libc++ should use `<__external_threading>` and that the header is expected to exist. Additionally the new macro `_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL` is now used to configure for using an "external library" with the default threading API. Reviewers: compnerd, rmaprath Subscribers: smeenai, cfe-commits, mgorny Differential Revision: https://reviews.llvm.org/D28316 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@291275 91177308-0d34-0410-b5e6-96231b3b80d8
2017-01-06 20:05:40 +00:00
DesignDocs/ThreadingSupportAPI
Add design docs for upcoming file_time_type change. In upcoming changes to filesystem I plan to change file_time_type to use __int128_t as its underlying representation, in order to allow it to have a range and resolution at least that of the timespec struct. There was some pushback against this decision, so I drafted a document explaining the problems, potential solutions, and the rational for the decision. However, it's probably easier to let people read the generated HTML rather than the raw restructured text. For this reason I'm commiting the design documents before hand, so they can be available during any subsequent discussion or code review. git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@337880 91177308-0d34-0410-b5e6-96231b3b80d8
2018-07-25 02:53:53 +00:00
DesignDocs/FileTimeType
Implement feature test macros using a script. Summary: This patch implements all the feature test macros libc++ currently supports, as specified by the standard or cppreference prior to C++2a. The tests and `<version>` header are generated using a script. The script contains a table of each feature test macro, the headers it should be accessible from, and its values of each dialect of C++. When a new feature test macro is added or needed, the table should be updated and the script re-run. Reviewers: mclow.lists, jfb, serge-sans-paille Reviewed By: mclow.lists Subscribers: arphaman, jfb, ldionne, libcxx-commits Differential Revision: https://reviews.llvm.org/D56750 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@351286 91177308-0d34-0410-b5e6-96231b3b80d8
2019-01-16 01:37:43 +00:00
DesignDocs/FeatureTestMacros
Add documentation and tests for Clangs C++11 extensions in C++03. As we gear up to drop support for GCC in C++03, we should make clear what our C++03 mode is, the C++11 extensions it provides, and the C++11 extensions it depends on. The section of this document discussing user-facing extensions has been left blank while the community discusses new directions. For now it's just a warning to users. Additionally, the document contains examples of how these extensions should be used and why. For example, using alias templates over class templates. git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@363110 91177308-0d34-0410-b5e6-96231b3b80d8
2019-06-11 22:53:49 +00:00
DesignDocs/ExtendedCXX03Support
[libcxx] Capture configuration information when installing the libc++ headers Summary: Hi all, This patch is a successor to D11963. However it has changed dramatically and I felt it would be best to start a new review thread. Please read the design documentation added in this patch for a description of how it works. Reviewers: mclow.lists, danalbert, jroelofs, EricWF Subscribers: vkalintiris, rnk, ed, espositofulvio, asl, eugenis, cfe-commits Differential Revision: http://reviews.llvm.org/D13407 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@250235 91177308-0d34-0410-b5e6-96231b3b80d8
2015-10-13 22:12:02 +00:00
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
* `<atomic> design <http://libcxx.llvm.org/atomic_design.html>`_
* `<type_traits> design <http://libcxx.llvm.org/type_traits_design.html>`_
Try to fix links for libcxx.llvm.org/docs again. git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@246950 91177308-0d34-0410-b5e6-96231b3b80d8
2015-09-06 23:09:54 +00:00
* `Notes by Marshall Clow`__
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
Try to fix links for libcxx.llvm.org/docs again. git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@246950 91177308-0d34-0410-b5e6-96231b3b80d8
2015-09-06 23:09:54 +00:00
.. __: https://cplusplusmusings.wordpress.com/2012/07/05/clang-and-standard-libraries-on-mac-os-x/
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
Add links to libc++ code coverage and builders git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@250361 91177308-0d34-0410-b5e6-96231b3b80d8
2015-10-15 03:27:02 +00:00
Build Bots and Test Coverage
----------------------------
Cleanup new documentation index and transfer more information from www/index.html git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@246913 91177308-0d34-0410-b5e6-96231b3b80d8
2015-09-05 06:50:03 +00:00
* `LLVM Buildbot Builders <http://lab.llvm.org:8011/console>`_
* `Apple Jenkins Builders <http://lab.llvm.org:8080/green/view/Libcxx/>`_
Update Appveyor bot link to point to new llvm-mirror Appveyor account git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@302128 91177308-0d34-0410-b5e6-96231b3b80d8
2017-05-04 07:40:23 +00:00
* `Windows Appveyor Builders <https://ci.appveyor.com/project/llvm-mirror/libcxx>`_
Add links to libc++ code coverage and builders git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@250361 91177308-0d34-0410-b5e6-96231b3b80d8
2015-10-15 03:27:02 +00:00
* `Code Coverage Results <http://efcs.ca/libcxx-coverage>`_
Cleanup new documentation index and transfer more information from www/index.html git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@246913 91177308-0d34-0410-b5e6-96231b3b80d8
2015-09-05 06:50:03 +00:00
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
Getting Involved
================
Cleanup new documentation index and transfer more information from www/index.html git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@246913 91177308-0d34-0410-b5e6-96231b3b80d8
2015-09-05 06:50:03 +00:00
First please review our `Developer's Policy <http://llvm.org/docs/DeveloperPolicy.html>`__
and `Getting started with LLVM <http://llvm.org/docs/GettingStarted.html>`__.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
**Bug Reports**
If you think you've found a bug in libc++, please report it using
Cleanup new documentation index and transfer more information from www/index.html git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@246913 91177308-0d34-0410-b5e6-96231b3b80d8
2015-09-05 06:50:03 +00:00
the `LLVM Bugzilla`_. If you're not sure, you
Correct docs to reference the new libc++ lists. We recently added libcxx-dev and libcxx-commits mailing lists. This patch updates the libc++ documentation to correctly reference the libc++ lists instead of the old Clang ones. git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@342816 91177308-0d34-0410-b5e6-96231b3b80d8
2018-09-22 19:49:29 +00:00
can post a message to the `libcxx-dev mailing list`_ or on IRC.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
**Patches**
If you want to contribute a patch to libc++, the best place for that is
Correct docs to reference the new libc++ lists. We recently added libcxx-dev and libcxx-commits mailing lists. This patch updates the libc++ documentation to correctly reference the libc++ lists instead of the old Clang ones. git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@342816 91177308-0d34-0410-b5e6-96231b3b80d8
2018-09-22 19:49:29 +00:00
`Phabricator <http://llvm.org/docs/Phabricator.html>`_. Please add `libcxx-commits` as a subscriber.
Also make sure you are subscribed to the `libcxx-commits mailing list <http://lists.llvm.org/mailman/listinfo/libcxx-commits>`_.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
**Discussion and Questions**
Try to fix links for libcxx.llvm.org/docs again. git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@246950 91177308-0d34-0410-b5e6-96231b3b80d8
2015-09-06 23:09:54 +00:00
Send discussions and questions to the
Correct docs to reference the new libc++ lists. We recently added libcxx-dev and libcxx-commits mailing lists. This patch updates the libc++ documentation to correctly reference the libc++ lists instead of the old Clang ones. git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@342816 91177308-0d34-0410-b5e6-96231b3b80d8
2018-09-22 19:49:29 +00:00
`libcxx-dev mailing list <http://lists.llvm.org/mailman/listinfo/libcxx-dev>`_.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
2015-08-22 19:40:49 +00:00
Cleanup new documentation index and transfer more information from www/index.html git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@246913 91177308-0d34-0410-b5e6-96231b3b80d8
2015-09-05 06:50:03 +00:00
Quick Links
===========
Try to fix links for libcxx.llvm.org/docs again. git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@246950 91177308-0d34-0410-b5e6-96231b3b80d8
2015-09-06 23:09:54 +00:00
* `LLVM Homepage <http://llvm.org/>`_
* `libc++abi Homepage <http://libcxxabi.llvm.org/>`_
Update all bug URL's to point to https://bugs.llvm.org/... git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@295434 91177308-0d34-0410-b5e6-96231b3b80d8
2017-02-17 08:37:03 +00:00
* `LLVM Bugzilla <https://bugs.llvm.org/>`_
Correct docs to reference the new libc++ lists. We recently added libcxx-dev and libcxx-commits mailing lists. This patch updates the libc++ documentation to correctly reference the libc++ lists instead of the old Clang ones. git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@342816 91177308-0d34-0410-b5e6-96231b3b80d8
2018-09-22 19:49:29 +00:00
* `libcxx-commits Mailing List`_
* `libcxx-dev Mailing List`_
Adjust documentation for git migration. This fixes most references to the paths: llvm.org/svn/ llvm.org/git/ llvm.org/viewvc/ github.com/llvm-mirror/ github.com/llvm-project/ reviews.llvm.org/diffusion/ to instead point to https://github.com/llvm/llvm-project. This is *not* a trivial substitution, because additionally, all the checkout instructions had to be migrated to instruct users on how to use the monorepo layout, setting LLVM_ENABLE_PROJECTS instead of checking out various projects into various subdirectories. I've attempted to not change any scripts here, only documentation. The scripts will have to be addressed separately. Additionally, I've deleted one document which appeared to be outdated and unneeded: lldb/docs/building-with-debug-llvm.txt Differential Revision: https://reviews.llvm.org/D57330 git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@352514 91177308-0d34-0410-b5e6-96231b3b80d8
2019-01-29 16:37:27 +00:00
* `Browse libc++ Sources <https://github.com/llvm/llvm-project/tree/master/libcxx/>`_
Reference in New Issue Copy Permalink