Import libc++ 10.0.1 release.

1 files changed, 348 insertions, 0 deletions

diff --git a/gnu/llvm/libcxx/docs/UsingLibcxx.rst b/gnu/llvm/libcxx/docs/UsingLibcxx.rst
new file mode 100644
index 00000000000..05721bf271a
--- /dev/null
+++ b/gnu/llvm/libcxx/docs/UsingLibcxx.rst
@@ -0,0 +1,348 @@
+============
+Using libc++
+============
+
+.. contents::
+  :local:
+
+Getting Started
+===============
+
+If you already have libc++ installed you can use it with clang.
+
+.. code-block:: bash
+
+    $ clang++ -stdlib=libc++ test.cpp
+    $ clang++ -std=c++11 -stdlib=libc++ test.cpp
+
+On macOS and FreeBSD libc++ is the default standard library
+and the ``-stdlib=libc++`` is not required.
+
+.. _alternate libcxx:
+
+If you want to select an alternate installation of libc++ you
+can use the following options.
+
+.. code-block:: bash
+
+  $ clang++ -std=c++11 -stdlib=libc++ -nostdinc++ \
+            -I<libcxx-install-prefix>/include/c++/v1 \
+            -L<libcxx-install-prefix>/lib \
+            -Wl,-rpath,<libcxx-install-prefix>/lib \
+            test.cpp
+
+The option ``-Wl,-rpath,<libcxx-install-prefix>/lib`` adds a runtime library
+search path. Meaning that the systems dynamic linker will look for libc++ in
+``<libcxx-install-prefix>/lib`` whenever the program is run. Alternatively the
+environment variable ``LD_LIBRARY_PATH`` (``DYLD_LIBRARY_PATH`` on macOS) can
+be used to change the dynamic linkers search paths after a program is compiled.
+
+An example of using ``LD_LIBRARY_PATH``:
+
+.. code-block:: bash
+
+  $ clang++ -stdlib=libc++ -nostdinc++ \
+            -I<libcxx-install-prefix>/include/c++/v1
+            -L<libcxx-install-prefix>/lib \
+            test.cpp -o
+  $ ./a.out # Searches for libc++ in the systems library paths.
+  $ export LD_LIBRARY_PATH=<libcxx-install-prefix>/lib
+  $ ./a.out # Searches for libc++ along LD_LIBRARY_PATH
+
+Using ``<filesystem>``
+======================
+
+Prior to LLVM 9.0, libc++ provides the implementation of the filesystem library
+in a separate static library. Users of ``<filesystem>`` and ``<experimental/filesystem>``
+are required to link ``-lc++fs``. Prior to libc++ 7.0, users of
+``<experimental/filesystem>`` were required to link libc++experimental.
+
+Starting with LLVM 9.0, support for ``<filesystem>`` is provided in the main
+library and nothing special is required to use ``<filesystem>``.
+
+Using libc++experimental and ``<experimental/...>``
+=====================================================
+
+Libc++ provides implementations of experimental technical specifications
+in a separate library, ``libc++experimental.a``. Users of ``<experimental/...>``
+headers may be required to link ``-lc++experimental``.
+
+.. code-block:: bash
+
+  $ clang++ -std=c++14 -stdlib=libc++ test.cpp -lc++experimental
+
+Libc++experimental.a may not always be available, even when libc++ is already
+installed. For information on building libc++experimental from source see
+:ref:`Building Libc++ <build instructions>` and
+:ref:`libc++experimental CMake Options <libc++experimental options>`.
+
+Also see the `Experimental Library Implementation Status <http://libcxx.llvm.org/ts1z_status.html>`__
+page.
+
+.. warning::
+  Experimental libraries are Experimental.
+    * The contents of the ``<experimental/...>`` headers and ``libc++experimental.a``
+      library will not remain compatible between versions.
+    * No guarantees of API or ABI stability are provided.
+    * When we implement the standardized version of an experimental feature,
+      the experimental feature is removed two releases after the non-experimental
+      version has shipped. The full policy is explained :ref:`here <experimental features>`.
+
+Using libc++ on Linux
+=====================
+
+On Linux libc++ can typically be used with only '-stdlib=libc++'. However
+some libc++ installations require the user manually link libc++abi themselves.
+If you are running into linker errors when using libc++ try adding '-lc++abi'
+to the link line.  For example:
+
+.. code-block:: bash
+
+  $ clang++ -stdlib=libc++ test.cpp -lc++ -lc++abi -lm -lc -lgcc_s -lgcc
+
+Alternately, you could just add libc++abi to your libraries list, which in
+most situations will give the same result:
+
+.. code-block:: bash
+
+  $ clang++ -stdlib=libc++ test.cpp -lc++abi
+
+
+Using libc++ with GCC
+---------------------
+
+GCC does not provide a way to switch from libstdc++ to libc++. You must manually
+configure the compile and link commands.
+
+In particular you must tell GCC to remove the libstdc++ include directories
+using ``-nostdinc++`` and to not link libstdc++.so using ``-nodefaultlibs``.
+
+Note that ``-nodefaultlibs`` removes all of the standard system libraries and
+not just libstdc++ so they must be manually linked. For example:
+
+.. code-block:: bash
+
+  $ g++ -nostdinc++ -I<libcxx-install-prefix>/include/c++/v1 \
+         test.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc
+
+
+GDB Pretty printers for libc++
+------------------------------
+
+GDB does not support pretty-printing of libc++ symbols by default. Unfortunately
+libc++ does not provide pretty-printers itself. However there are 3rd
+party implementations available and although they are not officially
+supported by libc++ they may be useful to users.
+
+Known 3rd Party Implementations Include:
+
+* `Koutheir's libc++ pretty-printers <https://github.com/koutheir/libcxx-pretty-printers>`_.
+
+
+Libc++ Configuration Macros
+===========================
+
+Libc++ provides a number of configuration macros which can be used to enable
+or disable extended libc++ behavior, including enabling "debug mode" or
+thread safety annotations.
+
+**_LIBCPP_DEBUG**:
+  See :ref:`using-debug-mode` for more information.
+
+**_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS**:
+  This macro is used to enable -Wthread-safety annotations on libc++'s
+  ``std::mutex`` and ``std::lock_guard``. By default these annotations are
+  disabled and must be manually enabled by the user.
+
+**_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**:
+  This macro is used to disable all visibility annotations inside libc++.
+  Defining this macro and then building libc++ with hidden visibility gives a
+  build of libc++ which does not export any symbols, which can be useful when
+  building statically for inclusion into another library.
+
+**_LIBCPP_DISABLE_EXTERN_TEMPLATE**:
+  This macro is used to disable extern template declarations in the libc++
+  headers. The intended use case is for clients who wish to use the libc++
+  headers without taking a dependency on the libc++ library itself.
+
+**_LIBCPP_ENABLE_TUPLE_IMPLICIT_REDUCED_ARITY_EXTENSION**:
+  This macro is used to re-enable an extension in `std::tuple` which allowed
+  it to be implicitly constructed from fewer initializers than contained
+  elements. Elements without an initializer are default constructed. For example:
+
+  .. code-block:: cpp
+
+    std::tuple<std::string, int, std::error_code> foo() {
+      return {"hello world", 42}; // default constructs error_code
+    }
+
+
+  Since libc++ 4.0 this extension has been disabled by default. This macro
+  may be defined to re-enable it in order to support existing code that depends
+  on the extension. New use of this extension should be discouraged.
+  See `PR 27374 <http://llvm.org/PR27374>`_ for more information.
+
+  Note: The "reduced-arity-initialization" extension is still offered but only
+  for explicit conversions. Example:
+
+  .. code-block:: cpp
+
+    auto foo() {
+      using Tup = std::tuple<std::string, int, std::error_code>;
+      return Tup{"hello world", 42}; // explicit constructor called. OK.
+    }
+
+**_LIBCPP_DISABLE_ADDITIONAL_DIAGNOSTICS**:
+  This macro disables the additional diagnostics generated by libc++ using the
+  `diagnose_if` attribute. These additional diagnostics include checks for:
+
+    * Giving `set`, `map`, `multiset`, `multimap` and their `unordered_`
+      counterparts a comparator which is not const callable.
+    * Giving an unordered associative container a hasher that is not const
+      callable.
+
+**_LIBCPP_NO_VCRUNTIME**:
+  Microsoft's C and C++ headers are fairly entangled, and some of their C++
+  headers are fairly hard to avoid. In particular, `vcruntime_new.h` gets pulled
+  in from a lot of other headers and provides definitions which clash with
+  libc++ headers, such as `nothrow_t` (note that `nothrow_t` is a struct, so
+  there's no way for libc++ to provide a compatible definition, since you can't
+  have multiple definitions).
+
+  By default, libc++ solves this problem by deferring to Microsoft's vcruntime
+  headers where needed. However, it may be undesirable to depend on vcruntime
+  headers, since they may not always be available in cross-compilation setups,
+  or they may clash with other headers. The `_LIBCPP_NO_VCRUNTIME` macro
+  prevents libc++ from depending on vcruntime headers. Consequently, it also
+  prevents libc++ headers from being interoperable with vcruntime headers (from
+  the aforementioned clashes), so users of this macro are promising to not
+  attempt to combine libc++ headers with the problematic vcruntime headers. This
+  macro also currently prevents certain `operator new`/`operator delete`
+  replacement scenarios from working, e.g. replacing `operator new` and
+  expecting a non-replaced `operator new[]` to call the replaced `operator new`.
+
+**_LIBCPP_ENABLE_NODISCARD**:
+  Allow the library to add ``[[nodiscard]]`` attributes to entities not specified
+  as ``[[nodiscard]]`` by the current language dialect. This includes
+  backporting applications of ``[[nodiscard]]`` from newer dialects and
+  additional extended applications at the discretion of the library. All
+  additional applications of ``[[nodiscard]]`` are disabled by default.
+  See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` for
+  more information.
+
+**_LIBCPP_DISABLE_NODISCARD_EXT**:
+  This macro prevents the library from applying ``[[nodiscard]]`` to entities
+  purely as an extension. See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>`
+  for more information.
+
+**_LIBCPP_DISABLE_DEPRECATION_WARNINGS**:
+  This macro disables warnings when using deprecated components. For example,
+  using `std::auto_ptr` when compiling in C++11 mode will normally trigger a
+  warning saying that `std::auto_ptr` is deprecated. If the macro is defined,
+  no warning will be emitted. By default, this macro is not defined.
+
+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.
+
+C++2a Specific Configuration Macros:
+------------------------------------
+**_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17**:
+  This macro can be used to disable diagnostics emitted from functions marked
+  ``[[nodiscard]]`` in dialects after C++17.  See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>`
+  for more information.
+
+
+Libc++ Extensions
+=================
+
+This section documents various extensions provided by libc++, how they're
+provided, and any information regarding how to use them.
+
+.. _nodiscard extension:
+
+Extended applications of ``[[nodiscard]]``
+------------------------------------------
+
+The ``[[nodiscard]]`` attribute is intended to help users find bugs where
+function return values are ignored when they shouldn't be. After C++17 the
+C++ standard has started to declared such library functions as ``[[nodiscard]]``.
+However, this application is limited and applies only to dialects after C++17.
+Users who want help diagnosing misuses of STL functions may desire a more
+liberal application of ``[[nodiscard]]``.
+
+For this reason libc++ provides an extension that does just that! The
+extension must be enabled by defining ``_LIBCPP_ENABLE_NODISCARD``. The extended
+applications of ``[[nodiscard]]`` takes two forms:
+
+1. Backporting ``[[nodiscard]]`` to entities declared as such by the
+   standard in newer dialects, but not in the present one.
+
+2. Extended applications of ``[[nodiscard]]``, at the libraries discretion,
+   applied to entities never declared as such by the standard.
+
+Users may also opt-out of additional applications ``[[nodiscard]]`` using
+additional macros.
+
+Applications of the first form, which backport ``[[nodiscard]]`` from a newer
+dialect may be disabled using macros specific to the dialect it was added. For
+example ``_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17``.
+
+Applications of the second form, which are pure extensions, may be disabled
+by defining ``_LIBCPP_DISABLE_NODISCARD_EXT``.
+
+
+Entities declared with ``_LIBCPP_NODISCARD_EXT``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section lists all extended applications of ``[[nodiscard]]`` to entities
+which no dialect declares as such (See the second form described above).
+
+* ``adjacent_find``
+* ``all_of``
+* ``any_of``
+* ``binary_search``
+* ``clamp``
+* ``count_if``
+* ``count``
+* ``equal_range``
+* ``equal``
+* ``find_end``
+* ``find_first_of``
+* ``find_if_not``
+* ``find_if``
+* ``find``
+* ``get_temporary_buffer``
+* ``includes``
+* ``is_heap_until``
+* ``is_heap``
+* ``is_partitioned``
+* ``is_permutation``
+* ``is_sorted_until``
+* ``is_sorted``
+* ``lexicographical_compare``
+* ``lower_bound``
+* ``max_element``
+* ``max``
+* ``min_element``
+* ``min``
+* ``minmax_element``
+* ``minmax``
+* ``mismatch``
+* ``none_of``
+* ``remove_if``
+* ``remove``
+* ``search_n``
+* ``search``
+* ``unique``
+* ``upper_bound``
+* ``lock_guard``'s constructors