maxjhandsome
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Releases Wiki Activity
llvm-project/libcxx/docs/index.rst

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

223 lines
7.4 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 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
.. _index:
=============================
"libc++" C++ Standard Library
=============================
Overview
========
[libcxx] Mentions "targeting C++11 and above" instead of "targeting C++11" in the doc llvm-svn: 293071
2017-01-26 01:00:30 +08: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 llvm-svn: 245788
2015-08-23 03:40:49 +08: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 llvm-svn: 341551
2018-09-06 23:05:43 +08: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 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
UsingLibcxx
BuildingLibcxx
TestingLibcxx
[libc++] [docs] Update and move NOTES.txt to docs/Contributing.rst. Also, add notes about exporting ABI symbols. Later, we can add notes about using git-clang-format before sending a patch for review. Reviewed By: ldionne, #libc Differential Revision: https://reviews.llvm.org/D92300
2020-12-02 15:52:35 +08:00
Contributing
[libc++] [docs] Migrate C++ status pages to RestructuredText (RST). Currently, papers and issues are in separate .csv files (that is easier to update), but I can put them inline.Transforming current html tables into rst are done by the script (attached to the patch FYI but I'll remove it before committing). I'll of course update RST files before committing to match any modifications that may happen in master branch. This patch moves the status pages in www/ to RST format in docs/. It also does some other minor changes: fix copyright year and broken comment end, adds substitutions for coherence (and add colors, but that can be removed easily). It adds as well redirects from old to new status pages. Reviewed By: ldionne, #libc Differential Revision: https://reviews.llvm.org/D92076
2020-11-26 16:03:50 +08:00
Cxx1yStatus
Cxx1zStatus
Cxx2aStatus
[libc++] [docs] Add C++2b (to be C++23) status page. Also: * Fix header line in all status tables. * Use C++20 instead of C++2a. Reviewed By: ldionne, #libc, miscco Differential Revision: https://reviews.llvm.org/D92306
2020-12-03 16:17:14 +08:00
Cxx2bStatus
[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 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
Test commit for builder llvm-svn: 246910
2015-09-05 13:29:23 +08: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 llvm-svn: 351286
2019-01-16 09:37:43 +08:00
.. toctree::
:hidden:
[libc++] Add documentation for setting up new CI jobs
2020-11-20 03:22:28 +08:00
AddingNewCIJobs
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 llvm-svn: 351286
2019-01-16 09:37:43 +08:00
FeatureTestMacroTable
[libc++] Add documentation for setting up new CI jobs
2020-11-20 03:22:28 +08: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 llvm-svn: 245788
2015-08-23 03:40:49 +08: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 llvm-svn: 246913
2015-09-05 14:50:03 +08: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 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
Platform and Compiler Support
-----------------------------
[libc++] Remove workarounds for the lack of clock_gettime on older macOS platforms This increases the Mac OS requirement for building libc++ to 10.12. Note that it doesn't change whether the *headers* still support older platforms -- it's only that macOS >= 10.12 is required to build the dylib from sources. Differential Revision: https://reviews.llvm.org/D74489
2020-02-13 00:01:19 +08:00
For using the libc++ headers
############################
The libc++ headers are known to work on the following platforms, using GCC and
Clang. Note that functionality provided by ``<atomic>`` is only functional with
Clang and GCC.
============ ==================== ============
OS Arch Compilers
============ ==================== ============
macOS 10.9+ i386, x86_64 Clang, GCC
FreeBSD 10+ i386, x86_64, ARM Clang, GCC
Linux i386, x86_64 Clang, GCC
============ ==================== ============
The following minimum compiler versions are required:
* Clang 4.0 and above
* GCC 5.0 and above.
The C++03 dialect is only supported with Clang.
For building the libc++ library
###############################
Building the libc++ library (static or shared) requires some features from
the operating system. As such, it has its own set of (slightly different)
system requirements.
[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 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
============ ==================== ============ ========================
OS Arch Compilers ABI Library
============ ==================== ============ ========================
[libc++] Remove workarounds for the lack of clock_gettime on older macOS platforms This increases the Mac OS requirement for building libc++ to 10.12. Note that it doesn't change whether the *headers* still support older platforms -- it's only that macOS >= 10.12 is required to build the dylib from sources. Differential Revision: https://reviews.llvm.org/D74489
2020-02-13 00:01:19 +08:00
macOS 10.12+ 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 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
FreeBSD 10+ i386, x86_64, ARM Clang, GCC libcxxrt, libc++abi
Linux i386, x86_64 Clang, GCC libc++abi
============ ==================== ============ ========================
[libc++] Remove workarounds for the lack of clock_gettime on older macOS platforms This increases the Mac OS requirement for building libc++ to 10.12. Note that it doesn't change whether the *headers* still support older platforms -- it's only that macOS >= 10.12 is required to build the dylib from sources. Differential Revision: https://reviews.llvm.org/D74489
2020-02-13 00:01:19 +08:00
The following minimum compiler versions are required:
[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 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
[libc++] Bump Clang support for Clang 4 It's hard to imagine someone using a recent version of libc++ with a roughly 3 years old Clang. Since we're not testing libc++ with Clang 3.5 anyway, claiming support for it is somewhat of a lie. Note that we don't test Clang 4 either, however I have no reason to bump the requirement beyond Clang 4 at the moment, whereas removing Clang 3.5 allows simplifying the test suite. Differential Revision: https://reviews.llvm.org/D76618
2020-03-23 23:37:40 +08:00
* Clang 4.0 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 llvm-svn: 363219
2019-06-13 08:37:25 +08: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 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
C++ Dialect Support
---------------------
* C++11 - Complete
[libc++] [docs] Migrate C++ status pages to RestructuredText (RST). Currently, papers and issues are in separate .csv files (that is easier to update), but I can put them inline.Transforming current html tables into rst are done by the script (attached to the patch FYI but I'll remove it before committing). I'll of course update RST files before committing to match any modifications that may happen in master branch. This patch moves the status pages in www/ to RST format in docs/. It also does some other minor changes: fix copyright year and broken comment end, adds substitutions for coherence (and add colors, but that can be removed easily). It adds as well redirects from old to new status pages. Reviewed By: ldionne, #libc Differential Revision: https://reviews.llvm.org/D92076
2020-11-26 16:03:50 +08:00
* :ref:`C++14 - Complete <cxx1y-status>`
* :ref:`C++17 - In Progress <cxx1z-status>`
* :ref:`C++20 - In Progress <cxx2a-status>`
[libc++][doc] Update the release notes. Updates the libc++ release notes with the changes since the last release. Differential Revision: https://reviews.llvm.org/D95248
2021-01-23 02:03:14 +08:00
* :ref:`C++2b - In Progress <cxx2b-status>`
Try to fix links for libcxx.llvm.org/docs again. llvm-svn: 246950
2015-09-07 07:09:54 +08: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 llvm-svn: 351286
2019-01-16 09:37:43 +08: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 llvm-svn: 245788
2015-08-23 03:40:49 +08: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 llvm-svn: 246951
2015-09-07 07:22:02 +08: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 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
Update all bug URL's to point to https://bugs.llvm.org/... llvm-svn: 295434
2017-02-17 16:37:03 +08: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 llvm-svn: 245788
2015-08-23 03:40:49 +08: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 llvm-svn: 250235
2015-10-14 06:12:02 +08:00
.. toctree::
:maxdepth: 1
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. llvm-svn: 290651
2016-12-28 12:58:52 +08: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 llvm-svn: 250235
2015-10-14 06:12:02 +08:00
DesignDocs/CapturingConfigInfo
Use __config_site when building libc++. Also cleanup ABI versioning doc llvm-svn: 250261
2015-10-14 08:22:05 +08: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 llvm-svn: 363072
2019-06-11 22:48:40 +08: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 llvm-svn: 281673
2016-09-16 06:27:07 +08: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 llvm-svn: 291275
2017-01-07 04:05:40 +08: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. llvm-svn: 337880
2018-07-25 10:53:53 +08: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 llvm-svn: 351286
2019-01-16 09:37:43 +08: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. llvm-svn: 363110
2019-06-12 06:53:49 +08:00
DesignDocs/ExtendedCXX03Support
Reland [libcxx]Put clang::trivial_abi on smart pointers Reviewed By: ldionne,EricWF Tags: #libcxx Differential Revision: https://reviews.llvm.org/D82490
2020-07-14 00:34:37 +08:00
DesignDocs/UniquePtrTrivialAbi
[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 llvm-svn: 250235
2015-10-14 06:12:02 +08: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 llvm-svn: 245788
2015-08-23 03:40:49 +08: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. llvm-svn: 246950
2015-09-07 07:09:54 +08: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 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
Try to fix links for libcxx.llvm.org/docs again. llvm-svn: 246950
2015-09-07 07:09:54 +08: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 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
Add links to libc++ code coverage and builders llvm-svn: 250361
2015-10-15 11:27:02 +08:00
Build Bots and Test Coverage
----------------------------
Cleanup new documentation index and transfer more information from www/index.html llvm-svn: 246913
2015-09-05 14:50:03 +08:00
[libc++] Add documentation for setting up new CI jobs
2020-11-20 03:22:28 +08:00
* `Buildkite CI pipeline <https://buildkite.com/llvm-project/libcxx-ci>`_
* `LLVM Buildbot Builders <http://lab.llvm.org:8011>`_
* :ref:`Adding New CI Jobs <AddingNewCIJobs>`
Cleanup new documentation index and transfer more information from www/index.html llvm-svn: 246913
2015-09-05 14:50:03 +08: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 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
Getting Involved
================
Doc: Links should use https
2020-03-23 05:42:03 +08:00
First please review our `Developer's Policy <https://llvm.org/docs/DeveloperPolicy.html>`__
and `Getting started with LLVM <https://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 llvm-svn: 245788
2015-08-23 03:40:49 +08: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 llvm-svn: 246913
2015-09-05 14:50:03 +08: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. llvm-svn: 342816
2018-09-23 03:49:29 +08: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 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
**Patches**
If you want to contribute a patch to libc++, the best place for that is
Doc: Links should use https
2020-03-23 05:42:03 +08:00
`Phabricator <https://llvm.org/docs/Phabricator.html>`_. Please add `libcxx-commits` as a subscriber.
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. llvm-svn: 342816
2018-09-23 03:49:29 +08:00
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 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
**Discussion and Questions**
Try to fix links for libcxx.llvm.org/docs again. llvm-svn: 246950
2015-09-07 07:09:54 +08: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. llvm-svn: 342816
2018-09-23 03:49:29 +08: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 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
Cleanup new documentation index and transfer more information from www/index.html llvm-svn: 246913
2015-09-05 14:50:03 +08:00
Quick Links
===========
Doc: Links should use https
2020-03-23 05:42:03 +08:00
* `LLVM Homepage <https://llvm.org/>`_
Try to fix links for libcxx.llvm.org/docs again. llvm-svn: 246950
2015-09-07 07:09:54 +08:00
* `libc++abi Homepage <http://libcxxabi.llvm.org/>`_
Update all bug URL's to point to https://bugs.llvm.org/... llvm-svn: 295434
2017-02-17 16:37:03 +08: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. llvm-svn: 342816
2018-09-23 03:49:29 +08: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 llvm-svn: 352514
2019-01-30 00:37:27 +08:00
* `Browse libc++ Sources <https://github.com/llvm/llvm-project/tree/master/libcxx/>`_