diff options
author | 2021-01-11 15:31:56 +0000 | |
---|---|---|
committer | 2021-01-11 15:31:56 +0000 | |
commit | 16ff81ed8b1ed9aa06fb1a731a2446b66cc49bef (patch) | |
tree | 1a7dd8152b94f6f8cd318bfaf85aa40882854583 /lib/libcxx/docs | |
parent | sync (diff) | |
download | wireguard-openbsd-16ff81ed8b1ed9aa06fb1a731a2446b66cc49bef.tar.xz wireguard-openbsd-16ff81ed8b1ed9aa06fb1a731a2446b66cc49bef.zip |
Remove libc++ and libc++abi 8.0.0 now that we switched to version 10.0.1
in the gnu/ directory.
Diffstat (limited to 'lib/libcxx/docs')
-rw-r--r-- | lib/libcxx/docs/BuildingLibcxx.rst | 554 | ||||
-rw-r--r-- | lib/libcxx/docs/CMakeLists.txt | 9 | ||||
-rw-r--r-- | lib/libcxx/docs/DesignDocs/ABIVersioning.rst | 17 | ||||
-rw-r--r-- | lib/libcxx/docs/DesignDocs/AvailabilityMarkup.rst | 99 | ||||
-rw-r--r-- | lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst | 88 | ||||
-rw-r--r-- | lib/libcxx/docs/DesignDocs/DebugMode.rst | 100 | ||||
-rw-r--r-- | lib/libcxx/docs/DesignDocs/FeatureTestMacros.rst | 44 | ||||
-rw-r--r-- | lib/libcxx/docs/DesignDocs/FileTimeType.rst | 494 | ||||
-rw-r--r-- | lib/libcxx/docs/DesignDocs/ThreadingSupportAPI.rst | 83 | ||||
-rw-r--r-- | lib/libcxx/docs/DesignDocs/VisibilityMacros.rst | 218 | ||||
-rw-r--r-- | lib/libcxx/docs/FeatureTestMacroTable.rst | 200 | ||||
-rw-r--r-- | lib/libcxx/docs/Makefile.sphinx | 37 | ||||
-rw-r--r-- | lib/libcxx/docs/README.txt | 13 | ||||
-rw-r--r-- | lib/libcxx/docs/ReleaseNotes.rst | 48 | ||||
-rw-r--r-- | lib/libcxx/docs/TestingLibcxx.rst | 257 | ||||
-rw-r--r-- | lib/libcxx/docs/UsingLibcxx.rst | 317 | ||||
-rw-r--r-- | lib/libcxx/docs/conf.py | 251 | ||||
-rw-r--r-- | lib/libcxx/docs/index.rst | 194 |
18 files changed, 0 insertions, 3023 deletions
diff --git a/lib/libcxx/docs/BuildingLibcxx.rst b/lib/libcxx/docs/BuildingLibcxx.rst deleted file mode 100644 index a498c0027bd..00000000000 --- a/lib/libcxx/docs/BuildingLibcxx.rst +++ /dev/null @@ -1,554 +0,0 @@ -.. _BuildingLibcxx: - -=============== -Building libc++ -=============== - -.. contents:: - :local: - -.. _build instructions: - -Getting Started -=============== - -On Mac OS 10.7 (Lion) and later, the easiest way to get this library is to install -Xcode 4.2 or later. However if you want to install tip-of-trunk from here -(getting the bleeding edge), read on. - -The basic steps needed to build libc++ are: - -#. Checkout LLVM: - - * ``cd where-you-want-llvm-to-live`` - * ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm`` - -#. Checkout libc++: - - * ``cd where-you-want-llvm-to-live`` - * ``cd llvm/projects`` - * ``svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx`` - -#. Checkout libc++abi: - - * ``cd where-you-want-llvm-to-live`` - * ``cd llvm/projects`` - * ``svn co http://llvm.org/svn/llvm-project/libcxxabi/trunk libcxxabi`` - -#. Configure and build libc++ with libc++abi: - - CMake is the only supported configuration system. - - Clang is the preferred compiler when building and using libc++. - - * ``cd where you want to build llvm`` - * ``mkdir build`` - * ``cd build`` - * ``cmake -G <generator> [options] <path to llvm sources>`` - - For more information about configuring libc++ see :ref:`CMake Options`. - - * ``make cxx`` --- will build libc++ and libc++abi. - * ``make check-cxx check-cxxabi`` --- will run the test suites. - - Shared libraries for libc++ and libc++ abi should now be present in llvm/build/lib. - See :ref:`using an alternate libc++ installation <alternate libcxx>` - -#. **Optional**: Install libc++ and libc++abi - - If your system already provides a libc++ installation it is important to be - careful not to replace it. Remember Use the CMake option ``CMAKE_INSTALL_PREFIX`` to - select a safe place to install libc++. - - * ``make install-cxx install-cxxabi`` --- Will install the libraries and the headers - - .. warning:: - * Replacing your systems libc++ installation could render the system non-functional. - * Mac OS X will not boot without a valid copy of ``libc++.1.dylib`` in ``/usr/lib``. - - -The instructions are for building libc++ on -FreeBSD, Linux, or Mac using `libc++abi`_ as the C++ ABI library. -On Linux, it is also possible to use :ref:`libsupc++ <libsupcxx>` or libcxxrt. - -It is sometimes beneficial to build outside of the LLVM tree. An out-of-tree -build would look like this: - -.. code-block:: bash - - $ cd where-you-want-libcxx-to-live - $ # Check out llvm, libc++ and libc++abi. - $ ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm`` - $ ``svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx`` - $ ``svn co http://llvm.org/svn/llvm-project/libcxxabi/trunk libcxxabi`` - $ cd where-you-want-to-build - $ mkdir build && cd build - $ export CC=clang CXX=clang++ - $ cmake -DLLVM_PATH=path/to/llvm \ - -DLIBCXX_CXX_ABI=libcxxabi \ - -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxabi/include \ - path/to/libcxx - $ make - $ make check-libcxx # optional - - -Experimental Support for Windows --------------------------------- - -The Windows support requires building with clang-cl as cl does not support one -required extension: `#include_next`. Furthermore, VS 2015 or newer (19.00) is -required. In the case of clang-cl, we need to specify the "MS Compatibility -Version" as it defaults to 2014 (18.00). - -CMake + Visual Studio -~~~~~~~~~~~~~~~~~~~~~ - -Building with Visual Studio currently does not permit running tests. However, -it is the simplest way to build. - -.. code-block:: batch - - > cmake -G "Visual Studio 14 2015" ^ - -T "LLVM-vs2014" ^ - -DLIBCXX_ENABLE_SHARED=YES ^ - -DLIBCXX_ENABLE_STATIC=NO ^ - -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO ^ - \path\to\libcxx - > cmake --build . - -CMake + ninja -~~~~~~~~~~~~~ - -Building with ninja is required for development to enable tests. -Unfortunately, doing so requires additional configuration as we cannot -just specify a toolset. - -.. code-block:: batch - - > cmake -G Ninja ^ - -DCMAKE_MAKE_PROGRAM=/path/to/ninja ^ - -DCMAKE_SYSTEM_NAME=Windows ^ - -DCMAKE_C_COMPILER=clang-cl ^ - -DCMAKE_C_FLAGS="-fms-compatibility-version=19.00 --target=i686--windows" ^ - -DCMAKE_CXX_COMPILER=clang-cl ^ - -DCMAKE_CXX_FLAGS="-fms-compatibility-version=19.00 --target=i686--windows" ^ - -DLLVM_PATH=/path/to/llvm/tree ^ - -DLIBCXX_ENABLE_SHARED=YES ^ - -DLIBCXX_ENABLE_STATIC=NO ^ - -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO ^ - \path\to\libcxx - > /path/to/ninja cxx - > /path/to/ninja check-cxx - -Note that the paths specified with backward slashes must use the `\\` as the -directory separator as clang-cl may otherwise parse the path as an argument. - -.. _`libc++abi`: http://libcxxabi.llvm.org/ - - -.. _CMake Options: - -CMake Options -============= - -Here are some of the CMake variables that are used often, along with a -brief explanation and LLVM-specific notes. For full documentation, check the -CMake docs or execute ``cmake --help-variable VARIABLE_NAME``. - -**CMAKE_BUILD_TYPE**:STRING - Sets the build type for ``make`` based generators. Possible values are - Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio - the user sets the build type with the IDE settings. - -**CMAKE_INSTALL_PREFIX**:PATH - Path where LLVM will be installed if "make install" is invoked or the - "INSTALL" target is built. - -**CMAKE_CXX_COMPILER**:STRING - The C++ compiler to use when building and testing libc++. - - -.. _libcxx-specific options: - -libc++ specific options ------------------------ - -.. option:: LIBCXX_INSTALL_LIBRARY:BOOL - - **Default**: ``ON`` - - Toggle the installation of the library portion of libc++. - -.. option:: LIBCXX_INSTALL_HEADERS:BOOL - - **Default**: ``ON`` - - Toggle the installation of the libc++ headers. - -.. option:: LIBCXX_ENABLE_ASSERTIONS:BOOL - - **Default**: ``ON`` - - Build libc++ with assertions enabled. - -.. option:: LIBCXX_BUILD_32_BITS:BOOL - - **Default**: ``OFF`` - - Build libc++ as a 32 bit library. Also see `LLVM_BUILD_32_BITS`. - -.. option:: LIBCXX_ENABLE_SHARED:BOOL - - **Default**: ``ON`` - - Build libc++ as a shared library. Either `LIBCXX_ENABLE_SHARED` or - `LIBCXX_ENABLE_STATIC` has to be enabled. - -.. option:: LIBCXX_ENABLE_STATIC:BOOL - - **Default**: ``ON`` - - Build libc++ as a static library. Either `LIBCXX_ENABLE_SHARED` or - `LIBCXX_ENABLE_STATIC` has to be enabled. - -.. option:: LIBCXX_LIBDIR_SUFFIX:STRING - - Extra suffix to append to the directory where libraries are to be installed. - This option overrides `LLVM_LIBDIR_SUFFIX`. - -.. option:: LIBCXX_INSTALL_PREFIX:STRING - - **Default**: ``""`` - - Define libc++ destination prefix. - -.. option:: LIBCXX_HERMETIC_STATIC_LIBRARY:BOOL - - **Default**: ``OFF`` - - Do not export any symbols from the static libc++ library. This is useful when - This is useful when the static libc++ library is being linked into shared - libraries that may be used in with other shared libraries that use different - C++ library. We want to avoid avoid exporting any libc++ symbols in that case. - -.. _libc++experimental options: - -libc++experimental Specific Options ------------------------------------- - -.. option:: LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY:BOOL - - **Default**: ``ON`` - - Build and test libc++experimental.a. - -.. option:: LIBCXX_INSTALL_EXPERIMENTAL_LIBRARY:BOOL - - **Default**: ``LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY AND LIBCXX_INSTALL_LIBRARY`` - - Install libc++experimental.a alongside libc++. - - -.. option:: LIBCXX_ENABLE_FILESYSTEM:BOOL - - **Default**: ``ON`` - - Build filesystem as a standalone library libc++fs.a. - -.. option:: LIBCXX_INSTALL_FILESYSTEM_LIBRARY:BOOL - - **Default**: ``LIBCXX_ENABLE_FILESYSTEM AND LIBCXX_INSTALL_LIBRARY`` - - Install libc++fs.a alongside libc++. - -.. _ABI Library Specific Options: - -ABI Library Specific Options ----------------------------- - -.. option:: LIBCXX_CXX_ABI:STRING - - **Values**: ``none``, ``libcxxabi``, ``libcxxrt``, ``libstdc++``, ``libsupc++``. - - Select the ABI library to build libc++ against. - -.. option:: LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS - - Provide additional search paths for the ABI library headers. - -.. option:: LIBCXX_CXX_ABI_LIBRARY_PATH:PATH - - Provide the path to the ABI library that libc++ should link against. - -.. option:: LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL - - **Default**: ``OFF`` - - If this option is enabled, libc++ will try and link the selected ABI library - statically. - -.. option:: LIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL - - **Default**: ``ON`` by default on UNIX platforms other than Apple unless - 'LIBCXX_ENABLE_STATIC_ABI_LIBRARY' is ON. Otherwise the default value is ``OFF``. - - This option generate and installs a linker script as ``libc++.so`` which - links the correct ABI library. - -.. option:: LIBCXXABI_USE_LLVM_UNWINDER:BOOL - - **Default**: ``OFF`` - - Build and use the LLVM unwinder. Note: This option can only be used when - libc++abi is the C++ ABI library used. - - -libc++ Feature Options ----------------------- - -.. option:: LIBCXX_ENABLE_EXCEPTIONS:BOOL - - **Default**: ``ON`` - - Build libc++ with exception support. - -.. option:: LIBCXX_ENABLE_RTTI:BOOL - - **Default**: ``ON`` - - Build libc++ with run time type information. - -.. option:: LIBCXX_INCLUDE_BENCHMARKS:BOOL - - **Default**: ``ON`` - - Build the libc++ benchmark tests and the Google Benchmark library needed - to support them. - -.. option:: LIBCXX_BENCHMARK_TEST_ARGS:STRING - - **Default**: ``--benchmark_min_time=0.01`` - - A semicolon list of arguments to pass when running the libc++ benchmarks using the - ``check-cxx-benchmarks`` rule. By default we run the benchmarks for a very short amount of time, - since the primary use of ``check-cxx-benchmarks`` is to get test and sanitizer coverage, not to - get accurate measurements. - -.. option:: LIBCXX_BENCHMARK_NATIVE_STDLIB:STRING - - **Default**:: ``""`` - - **Values**:: ``libc++``, ``libstdc++`` - - Build the libc++ benchmark tests and Google Benchmark library against the - specified standard library on the platform. On linux this can be used to - compare libc++ to libstdc++ by building the benchmark tests against both - standard libraries. - -.. option:: LIBCXX_BENCHMARK_NATIVE_GCC_TOOLCHAIN:STRING - - Use the specified GCC toolchain and standard library when building the native - stdlib benchmark tests. - -.. option:: LIBCXX_HIDE_FROM_ABI_PER_TU_BY_DEFAULT:BOOL - - **Default**: ``OFF`` - - Pick the default for whether to constrain ABI-unstable symbols to - each individual translation unit. This setting controls whether - `_LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT` is defined by default -- - see the documentation of that macro for details. - - -libc++ ABI Feature Options --------------------------- - -The following options allow building libc++ for a different ABI version. - -.. option:: LIBCXX_ABI_VERSION:STRING - - **Default**: ``1`` - - Defines the target ABI version of libc++. - -.. option:: LIBCXX_ABI_UNSTABLE:BOOL - - **Default**: ``OFF`` - - Build the "unstable" ABI version of libc++. Includes all ABI changing features - on top of the current stable version. - -.. option:: LIBCXX_ABI_NAMESPACE:STRING - - **Default**: ``__n`` where ``n`` is the current ABI version. - - This option defines the name of the inline ABI versioning namespace. It can be used for building - custom versions of libc++ with unique symbol names in order to prevent conflicts or ODR issues - with other libc++ versions. - - .. warning:: - When providing a custom namespace, it's the users responsibility to ensure the name won't cause - conflicts with other names defined by libc++, both now and in the future. In particular, inline - namespaces of the form ``__[0-9]+`` are strictly reserved by libc++ and may not be used by users. - Doing otherwise could cause conflicts and hinder libc++ ABI evolution. - -.. option:: LIBCXX_ABI_DEFINES:STRING - - **Default**: ``""`` - - A semicolon-separated list of ABI macros to persist in the site config header. - See ``include/__config`` for the list of ABI macros. - -.. _LLVM-specific variables: - -LLVM-specific options ---------------------- - -.. option:: LLVM_LIBDIR_SUFFIX:STRING - - Extra suffix to append to the directory where libraries are to be - installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64`` - to install libraries to ``/usr/lib64``. - -.. option:: LLVM_BUILD_32_BITS:BOOL - - Build 32-bits executables and libraries on 64-bits systems. This option is - available only on some 64-bits unix systems. Defaults to OFF. - -.. option:: LLVM_LIT_ARGS:STRING - - Arguments given to lit. ``make check`` and ``make clang-test`` are affected. - By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on - others. - - -Using Alternate ABI libraries -============================= - - -.. _libsupcxx: - -Using libsupc++ on Linux ------------------------- - -You will need libstdc++ in order to provide libsupc++. - -Figure out where the libsupc++ headers are on your system. On Ubuntu this -is ``/usr/include/c++/<version>`` and ``/usr/include/c++/<version>/<target-triple>`` - -You can also figure this out by running - -.. code-block:: bash - - $ echo | g++ -Wp,-v -x c++ - -fsyntax-only - ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu" - ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include" - #include "..." search starts here: - #include <...> search starts here: - /usr/include/c++/4.7 - /usr/include/c++/4.7/x86_64-linux-gnu - /usr/include/c++/4.7/backward - /usr/lib/gcc/x86_64-linux-gnu/4.7/include - /usr/local/include - /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed - /usr/include/x86_64-linux-gnu - /usr/include - End of search list. - -Note that the first two entries happen to be what we are looking for. This -may not be correct on other platforms. - -We can now run CMake: - -.. code-block:: bash - - $ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \ - -DLIBCXX_CXX_ABI=libstdc++ \ - -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/" \ - -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr \ - <libc++-source-dir> - - -You can also substitute ``-DLIBCXX_CXX_ABI=libsupc++`` -above, which will cause the library to be linked to libsupc++ instead -of libstdc++, but this is only recommended if you know that you will -never need to link against libstdc++ in the same executable as libc++. -GCC ships libsupc++ separately but only as a static library. If a -program also needs to link against libstdc++, it will provide its -own copy of libsupc++ and this can lead to subtle problems. - -.. code-block:: bash - - $ make cxx - $ make install - -You can now run clang with -stdlib=libc++. - - -.. _libcxxrt_ref: - -Using libcxxrt on Linux ------------------------- - -You will need to keep the source tree of `libcxxrt`_ available -on your build machine and your copy of the libcxxrt shared library must -be placed where your linker will find it. - -We can now run CMake like: - -.. code-block:: bash - - $ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \ - -DLIBCXX_CXX_ABI=libcxxrt \ - -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src \ - -DCMAKE_BUILD_TYPE=Release \ - -DCMAKE_INSTALL_PREFIX=/usr \ - <libc++-source-directory> - $ make cxx - $ make install - -Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as -clang is set up to link for libc++ linked to libsupc++. To get around this -you'll have to set up your linker yourself (or patch clang). For example, - -.. code-block:: bash - - $ clang++ -stdlib=libc++ helloworld.cpp \ - -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc - -Alternately, you could just add libcxxrt to your libraries list, which in most -situations will give the same result: - -.. code-block:: bash - - $ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt - -.. _`libcxxrt`: https://github.com/pathscale/libcxxrt/ - - -Using a local ABI library installation ---------------------------------------- - -.. warning:: - This is not recommended in almost all cases. - -These instructions should only be used when you can't install your ABI library. - -Normally you must link libc++ against a ABI shared library that the -linker can find. If you want to build and test libc++ against an ABI -library not in the linker's path you needq to set -``-DLIBCXX_CXX_ABI_LIBRARY_PATH=/path/to/abi/lib`` when configuring CMake. - -An example build using libc++abi would look like: - -.. code-block:: bash - - $ CC=clang CXX=clang++ cmake \ - -DLIBCXX_CXX_ABI=libc++abi \ - -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/path/to/libcxxabi/include" \ - -DLIBCXX_CXX_ABI_LIBRARY_PATH="/path/to/libcxxabi-build/lib" \ - path/to/libcxx - $ make - -When testing libc++ LIT will automatically link against the proper ABI -library. diff --git a/lib/libcxx/docs/CMakeLists.txt b/lib/libcxx/docs/CMakeLists.txt deleted file mode 100644 index d679761a5ad..00000000000 --- a/lib/libcxx/docs/CMakeLists.txt +++ /dev/null @@ -1,9 +0,0 @@ - -if (LLVM_ENABLE_SPHINX) - include(AddSphinxTarget) - if (SPHINX_FOUND) - if (${SPHINX_OUTPUT_HTML}) - add_sphinx_target(html libcxx) - endif() - endif() -endif() diff --git a/lib/libcxx/docs/DesignDocs/ABIVersioning.rst b/lib/libcxx/docs/DesignDocs/ABIVersioning.rst deleted file mode 100644 index 5960dd18610..00000000000 --- a/lib/libcxx/docs/DesignDocs/ABIVersioning.rst +++ /dev/null @@ -1,17 +0,0 @@ - -==================== -Libc++ ABI stability -==================== - -Libc++ aims to preserve stable ABI to avoid subtle bugs when code built to the old ABI -is linked with the code build to the new ABI. At the same time, libc++ allows ABI-breaking -improvements and bugfixes for the scenarios when ABI change is not a issue. - -To support both cases, libc++ allows specifying the ABI version at the -build time. The version is defined with a cmake option -LIBCXX_ABI_VERSION. Another option LIBCXX_ABI_UNSTABLE can be used to -include all present ABI breaking features. These options translate -into C++ macro definitions _LIBCPP_ABI_VERSION, _LIBCPP_ABI_UNSTABLE. - -Any ABI-changing feature is placed under it's own macro, _LIBCPP_ABI_XXX, which is enabled -based on the value of _LIBCPP_ABI_VERSION. _LIBCPP_ABI_UNSTABLE, if set, enables all features at once. diff --git a/lib/libcxx/docs/DesignDocs/AvailabilityMarkup.rst b/lib/libcxx/docs/DesignDocs/AvailabilityMarkup.rst deleted file mode 100644 index 4e6d80b50bf..00000000000 --- a/lib/libcxx/docs/DesignDocs/AvailabilityMarkup.rst +++ /dev/null @@ -1,99 +0,0 @@ -=================== -Availability Markup -=================== - -.. contents:: - :local: - -Overview -======== - -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. - -Design -====== - -When a new feature is introduced that requires dylib support, a macro should be -created in include/__config to mark this feature as unavailable for all the -systems. For example:: - - // Define availability macros. - #if defined(_LIBCPP_USE_AVAILABILITY_APPLE) - # define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((unavailable)) - #else if defined(_LIBCPP_USE_AVAILABILITY_SOME_OTHER_VENDOR) - # define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((unavailable)) - #else - # define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS - #endif - -When the library is updated by the platform vendor, the markup can be updated. -For example:: - - #define _LIBCPP_AVAILABILITY_SHARED_MUTEX \ - __attribute__((availability(macosx,strict,introduced=10.12))) \ - __attribute__((availability(ios,strict,introduced=10.0))) \ - __attribute__((availability(tvos,strict,introduced=10.0))) \ - __attribute__((availability(watchos,strict,introduced=3.0))) - -In the source code, the macro can be added on a class if the full class requires -type info from the library for example:: - - _LIBCPP_BEGIN_NAMESPACE_EXPERIMENTAL - class _LIBCPP_EXCEPTION_ABI _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS bad_optional_access - : public std::logic_error { - -or on a particular symbol: - - _LIBCPP_OVERRIDABLE_FUNC_VIS _LIBCPP_AVAILABILITY_SIZED_NEW_DELETE void operator delete(void* __p, std::size_t __sz) _NOEXCEPT; - - -Testing -======= - -Some parameters can be passed to lit to run the test-suite and exercise the -availability. - -* The `platform` parameter controls the deployment target. For example lit can - be invoked with `--param=platform=macosx10.8`. Default is the current host. -* The `use_system_cxx_lib` parameter indicates to use another library than the - just built one. Invoking lit with `--param=use_system_cxx_lib=true` will run - the test-suite against the host system library. Alternatively a path to the - directory containing a specific prebuilt libc++ can be used, for example: - `--param=use_system_cxx_lib=/path/to/macOS/10.8/`. - -Tests can be marked as XFAIL based on multiple features made available by lit: - - -* if `--param=platform=macosx10.8` is passed, the following features will be available: - - - availability - - availability=x86_64 - - availability=macosx - - availability=x86_64-macosx - - availability=x86_64-apple-macosx10.8 - - availability=macosx10.8 - - This feature is used to XFAIL a test that *is* using a class or a method marked - as unavailable *and* that is expected to *fail* if deployed on an older system. - -* if `use_system_cxx_lib` and `--param=platform=macosx10.8` are passed to lit, - the following features will also be available: - - - with_system_cxx_lib - - with_system_cxx_lib=x86_64 - - with_system_cxx_lib=macosx - - with_system_cxx_lib=x86_64-macosx - - with_system_cxx_lib=x86_64-apple-macosx10.8 - - with_system_cxx_lib=macosx10.8 - - This feature is used to XFAIL a test that is *not* using a class or a method - marked as unavailable *but* that is expected to fail if deployed on an older - system. For example, if the test exhibits a bug in the libc on a particular - system version, or if the test uses a symbol that is not available on an - older version of the dylib (but for which there is no availability markup, - otherwise the XFAIL should use `availability` above). diff --git a/lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst b/lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst deleted file mode 100644 index 29156bff8bc..00000000000 --- a/lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst +++ /dev/null @@ -1,88 +0,0 @@ -======================================================= -Capturing configuration information during installation -======================================================= - -.. contents:: - :local: - -The Problem -=========== - -Currently the libc++ supports building the library with a number of different -configuration options. Unfortunately all of that configuration information is -lost when libc++ is installed. In order to support "persistent" -configurations libc++ needs a mechanism to capture the configuration options -in the INSTALLED headers. - - -Design Goals -============ - -* The solution should not INSTALL any additional headers. We don't want an extra - #include slowing everybody down. - -* The solution should not unduly affect libc++ developers. The problem is limited - to installed versions of libc++ and the solution should be as well. - -* The solution should not modify any existing headers EXCEPT during installation. - It makes developers lives harder if they have to regenerate the libc++ headers - every time they are modified. - -* The solution should not make any of the libc++ headers dependent on - files generated by the build system. The headers should be able to compile - out of the box without any modification. - -* The solution should not have ANY effect on users who don't need special - configuration options. The vast majority of users will never need this so it - shouldn't cost them. - - -The Solution -============ - -When you first configure libc++ using CMake we check to see if we need to -capture any options. If we haven't been given any "persistent" options then -we do NOTHING. - -Otherwise we create a custom installation rule that modifies the installed __config -header. The rule first generates a dummy "__config_site" header containing the required -#defines. The contents of the dummy header are then prepended to the installed -__config header. By manually prepending the files we avoid the cost of an -extra #include and we allow the __config header to be ignorant of the extra -configuration all together. An example "__config" header generated when --DLIBCXX_ENABLE_THREADS=OFF is given to CMake would look something like: - -.. code-block:: cpp - - //===----------------------------------------------------------------------===// - // - // The LLVM Compiler Infrastructure - // - // This file is dual licensed under the MIT and the University of Illinois Open - // Source Licenses. See LICENSE.TXT for details. - // - //===----------------------------------------------------------------------===// - - #ifndef _LIBCPP_CONFIG_SITE - #define _LIBCPP_CONFIG_SITE - - /* #undef _LIBCPP_HAS_NO_GLOBAL_FILESYSTEM_NAMESPACE */ - /* #undef _LIBCPP_HAS_NO_STDIN */ - /* #undef _LIBCPP_HAS_NO_STDOUT */ - #define _LIBCPP_HAS_NO_THREADS - /* #undef _LIBCPP_HAS_NO_MONOTONIC_CLOCK */ - /* #undef _LIBCPP_HAS_NO_THREAD_UNSAFE_C_FUNCTIONS */ - - #endif - // -*- C++ -*- - //===--------------------------- __config ---------------------------------===// - // - // The LLVM Compiler Infrastructure - // - // This file is dual licensed under the MIT and the University of Illinois Open - // Source Licenses. See LICENSE.TXT for details. - // - //===----------------------------------------------------------------------===// - - #ifndef _LIBCPP_CONFIG - #define _LIBCPP_CONFIG diff --git a/lib/libcxx/docs/DesignDocs/DebugMode.rst b/lib/libcxx/docs/DesignDocs/DebugMode.rst deleted file mode 100644 index 3b997d44607..00000000000 --- a/lib/libcxx/docs/DesignDocs/DebugMode.rst +++ /dev/null @@ -1,100 +0,0 @@ -========== -Debug Mode -========== - -.. contents:: - :local: - -.. _using-debug-mode: - -Using Debug Mode -================ - -Libc++ provides a debug mode that enables assertions meant to detect incorrect -usage of the standard library. By default these assertions are disabled but -they can be enabled using the ``_LIBCPP_DEBUG`` macro. - -**_LIBCPP_DEBUG** Macro ------------------------ - -**_LIBCPP_DEBUG**: - This macro is used to enable assertions and iterator debugging checks within - libc++. By default it is undefined. - - **Values**: ``0``, ``1`` - - Defining ``_LIBCPP_DEBUG`` to ``0`` or greater enables most of libc++'s - assertions. Defining ``_LIBCPP_DEBUG`` to ``1`` enables "iterator debugging" - which provides additional assertions about the validity of iterators used by - the program. - - Note that this option has no effect on libc++'s ABI - -**_LIBCPP_DEBUG_USE_EXCEPTIONS**: - When this macro is defined ``_LIBCPP_ASSERT`` failures throw - ``__libcpp_debug_exception`` instead of aborting. Additionally this macro - disables exception specifications on functions containing ``_LIBCPP_ASSERT`` - checks. This allows assertion failures to correctly throw through these - functions. - -Handling Assertion Failures ---------------------------- - -When a debug assertion fails the assertion handler is called via the -``std::__libcpp_debug_function`` function pointer. It is possible to override -this function pointer using a different handler function. Libc++ provides two -different assertion handlers, the default handler -``std::__libcpp_abort_debug_handler`` which aborts the program, and -``std::__libcpp_throw_debug_handler`` which throws an instance of -``std::__libcpp_debug_exception``. Libc++ can be changed to use the throwing -assertion handler as follows: - -.. code-block:: cpp - - #define _LIBCPP_DEBUG 1 - #include <string> - int main() { - std::__libcpp_debug_function = std::__libcpp_throw_debug_function; - try { - std::string::iterator bad_it; - std::string str("hello world"); - str.insert(bad_it, '!'); // causes debug assertion - } catch (std::__libcpp_debug_exception const&) { - return EXIT_SUCCESS; - } - return EXIT_FAILURE; - } - -Debug Mode Checks -================= - -Libc++'s debug mode offers two levels of checking. The first enables various -precondition checks throughout libc++. The second additionally enables -"iterator debugging" which checks the validity of iterators used by the program. - -Basic Checks -============ - -These checks are enabled when ``_LIBCPP_DEBUG`` is defined to either 0 or 1. - -The following checks are enabled by ``_LIBCPP_DEBUG``: - - * FIXME: Update this list - -Iterator Debugging Checks -========================= - -These checks are enabled when ``_LIBCPP_DEBUG`` is defined to 1. - -The following containers and STL classes support iterator debugging: - - * ``std::string`` - * ``std::vector<T>`` (``T != bool``) - * ``std::list`` - * ``std::unordered_map`` - * ``std::unordered_multimap`` - * ``std::unordered_set`` - * ``std::unordered_multiset`` - -The remaining containers do not currently support iterator debugging. -Patches welcome. diff --git a/lib/libcxx/docs/DesignDocs/FeatureTestMacros.rst b/lib/libcxx/docs/DesignDocs/FeatureTestMacros.rst deleted file mode 100644 index d55af96c674..00000000000 --- a/lib/libcxx/docs/DesignDocs/FeatureTestMacros.rst +++ /dev/null @@ -1,44 +0,0 @@ -=================== -Feature Test Macros -=================== - -.. contents:: - :local: - -Overview -======== - -Libc++ implements the C++ feature test macros as specified in the C++2a standard, -and before that in non-normative guiding documents (`See cppreference <https://en.cppreference.com/w/User:D41D8CD98F/feature_testing_macros>`) - -Design -====== - -Feature test macros are tricky to track, implement, test, and document correctly. -They must be available from a list of headers, they may have different values in -different dialects, and they may or may not be implemented by libc++. In order to -track all of these conditions correctly and easily, we want a Single Source of -Truth (SSoT) that defines each feature test macro, its values, the headers it -lives in, and whether or not is is implemented by libc++. From this SSoA we -have enough information to automatically generate the `<version>` header, -the tests, and the documentation. - -Therefore we maintain a SSoA in -`libcxx/test/std/language.support/support.limits/support.limits.general/generate_feature_test_macro_components.py` -which doubles as a script to generate the following components: - -* The `<version>` header. -* The version tests under `support.limits.general`. -* Documentation of libc++'s implementation of each macro. - -Usage -===== - -The `generate_feature_test_macro_components.py` script is used to track and -update feature test macros in libc++. - -Whenever a feature test macro is added or changed, the table should be updated -and the script should be re-ran. The script will clobber the existing test files -and the documentation and it will generate a new `<version>` header as a -temporary file. The generated `<version>` header should be merged with the -existing one.
\ No newline at end of file diff --git a/lib/libcxx/docs/DesignDocs/FileTimeType.rst b/lib/libcxx/docs/DesignDocs/FileTimeType.rst deleted file mode 100644 index 488ff174b34..00000000000 --- a/lib/libcxx/docs/DesignDocs/FileTimeType.rst +++ /dev/null @@ -1,494 +0,0 @@ -============== -File Time Type -============== - -.. contents:: - :local: - -.. _file-time-type-motivation: - -Motivation -========== - -The filesystem library provides interfaces for getting and setting the last -write time of a file or directory. The interfaces use the ``file_time_type`` -type, which is a specialization of ``chrono::time_point`` for the -"filesystem clock". According to [fs.filesystem.syn] - - trivial-clock is an implementation-defined type that satisfies the - Cpp17TrivialClock requirements ([time.clock.req]) and that is capable of - representing and measuring file time values. Implementations should ensure - that the resolution and range of file_Âtime_Âtype reflect the operating - system dependent resolution and range of file time values. - - -On POSIX systems, file times are represented using the ``timespec`` struct, -which is defined as follows: - -.. code-block:: cpp - - struct timespec { - time_t tv_sec; - long tv_nsec; - }; - -To represent the range and resolution of ``timespec``, we need to (A) have -nanosecond resolution, and (B) use more than 64 bits (assuming a 64 bit ``time_t``). - -As the standard requires us to use the ``chrono`` interface, we have to define -our own filesystem clock which specifies the period and representation of -the time points and duration it provides. It will look like this: - -.. code-block:: cpp - - struct _FilesystemClock { - using period = nano; - using rep = TBD; // What is this? - - using duration = chrono::duration<rep, period>; - using time_point = chrono::time_point<_FilesystemClock>; - - // ... // - }; - - using file_time_type = _FilesystemClock::time_point; - - -To get nanosecond resolution, we simply define ``period`` to be ``std::nano``. -But what type can we use as the arithmetic representation that is capable -of representing the range of the ``timespec`` struct? - -Problems To Consider -==================== - -Before considering solutions, let's consider the problems they should solve, -and how important solving those problems are: - - -Having a Smaller Range than ``timespec`` ----------------------------------------- - -One solution to the range problem is to simply reduce the resolution of -``file_time_type`` to be less than that of nanoseconds. This is what libc++'s -initial implementation of ``file_time_type`` did; it's also what -``std::system_clock`` does. As a result, it can represent time points about -292 thousand years on either side of the epoch, as opposed to only 292 years -at nanosecond resolution. - -``timespec`` can represent time points +/- 292 billion years from the epoch -(just in case you needed a time point 200 billion years before the big bang, -and with nanosecond resolution). - -To get the same range, we would need to drop our resolution to that of seconds -to come close to having the same range. - -This begs the question, is the range problem "really a problem"? Sane usages -of file time stamps shouldn't exceed +/- 300 years, so should we care to support it? - -I believe the answer is yes. We're not designing the filesystem time API, we're -providing glorified C++ wrappers for it. If the underlying API supports -a value, then we should too. Our wrappers should not place artificial restrictions -on users that are not present in the underlying filesystem. - -Having a smaller range that the underlying filesystem forces the -implementation to report ``value_too_large`` errors when it encounters a time -point that it can't represent. This can cause the call to ``last_write_time`` -to throw in cases where the user was confident the call should succeed. (See below) - - -.. code-block:: cpp - - #include <filesystem> - using namespace std::filesystem; - - // Set the times using the system interface. - void set_file_times(const char* path, struct timespec ts) { - timespec both_times[2]; - both_times[0] = ts; - both_times[1] = ts; - int result = ::utimensat(AT_FDCWD, path, both_times, 0); - assert(result != -1); - } - - // Called elsewhere to set the file time to something insane, and way - // out of the 300 year range we might expect. - void some_bad_persons_code() { - struct timespec new_times; - new_times.tv_sec = numeric_limits<time_t>::max(); - new_times.tv_nsec = 0; - set_file_times("/tmp/foo", new_times); // OK, supported by most FSes - } - - int main() { - path p = "/tmp/foo"; - file_status st = status(p); - if (!exists(st) || !is_regular_file(st)) - return 1; - if ((st.permissions() & perms::others_read) == perms::none) - return 1; - // It seems reasonable to assume this call should succeed. - file_time_type tp = last_write_time(p); // BAD! Throws value_too_large. - } - - -Having a Smaller Resolution than ``timespec`` ---------------------------------------------- - -As mentioned in the previous section, one way to solve the range problem -is by reducing the resolution. But matching the range of ``timespec`` using a -64 bit representation requires limiting the resolution to seconds. - -So we might ask: Do users "need" nanosecond precision? Is seconds not good enough? -I limit my consideration of the point to this: Why was it not good enough for -the underlying system interfaces? If it wasn't good enough for them, then it -isn't good enough for us. Our job is to match the filesystems range and -representation, not design it. - - -Having a Larger Range than ``timespec`` ----------------------------------------- - -We should also consider the opposite problem of having a ``file_time_type`` -that is able to represent a larger range than ``timespec``. At least in -this case ``last_write_time`` can be used to get and set all possible values -supported by the underlying filesystem; meaning ``last_write_time(p)`` will -never throw a overflow error when retrieving a value. - -However, this introduces a new problem, where users are allowed to attempt to -create a time point beyond what the filesystem can represent. Two particular -values which cause this are ``file_time_type::min()`` and -``file_time_type::max()``. As a result, the following code would throw: - -.. code-block:: cpp - - void test() { - last_write_time("/tmp/foo", file_time_type::max()); // Throws - last_write_time("/tmp/foo", file_time_type::min()); // Throws. - } - -Apart from cases explicitly using ``min`` and ``max``, I don't see users taking -a valid time point, adding a couple hundred billions of years in error, -and then trying to update a file's write time to that value very often. - -Compared to having a smaller range, this problem seems preferable. At least -now we can represent any time point the filesystem can, so users won't be forced -to revert back to system interfaces to avoid limitations in the C++ STL. - -I posit that we should only consider this concern *after* we have something -with at least the same range and resolution of the underlying filesystem. The -latter two problems are much more important to solve. - -Potential Solutions And Their Complications -=========================================== - -Source Code Portability Across Implementations ------------------------------------------------ - -As we've discussed, ``file_time_type`` needs a representation that uses more -than 64 bits. The possible solutions include using ``__int128_t``, emulating a -128 bit integer using a class, or potentially defining a ``timespec`` like -arithmetic type. All three will allow us to, at minimum, match the range -and resolution, and the last one might even allow us to match them exactly. - -But when considering these potential solutions we need to consider more than -just the values they can represent. We need to consider the effects they will -have on users and their code. For example, each of them breaks the following -code in some way: - -.. code-block:: cpp - - // Bug caused by an unexpected 'rep' type returned by count. - void print_time(path p) { - // __int128_t doesn't have streaming operators, and neither would our - // custom arithmetic types. - cout << last_write_time(p).time_since_epoch().count() << endl; - } - - // Overflow during creation bug. - file_time_type timespec_to_file_time_type(struct timespec ts) { - // woops! chrono::seconds and chrono::nanoseconds use a 64 bit representation - // this may overflow before it's converted to a file_time_type. - auto dur = seconds(ts.tv_sec) + nanoseconds(ts.tv_nsec); - return file_time_type(dur); - } - - file_time_type correct_timespec_to_file_time_type(struct timespec ts) { - // This is the correct version of the above example, where we - // avoid using the chrono typedefs as they're not sufficient. - // Can we expect users to avoid this bug? - using fs_seconds = chrono::duration<file_time_type::rep>; - using fs_nanoseconds = chrono::duration<file_time_type::rep, nano>; - auto dur = fs_seconds(ts.tv_sec) + fs_nanoseconds(tv.tv_nsec); - return file_time_type(dur); - } - - // Implicit truncation during conversion bug. - intmax_t get_time_in_seconds(path p) { - using fs_seconds = duration<file_time_type::rep, ratio<1, 1> >; - auto tp = last_write_time(p); - - // This works with truncation for __int128_t, but what does it do for - // our custom arithmetic types. - return duration_cast<fs_seconds>().count(); - } - - -Each of the above examples would require a user to adjust their filesystem code -to the particular eccentricities of the representation, hopefully only in such -a way that the code is still portable across implementations. - -At least some of the above issues are unavoidable, no matter what -representation we choose. But some representations may be quirkier than others, -and, as I'll argue later, using an actual arithmetic type (``__int128_t``) -provides the least aberrant behavior. - - -Chrono and ``timespec`` Emulation. ----------------------------------- - -One of the options we've considered is using something akin to ``timespec`` -to represent the ``file_time_type``. It only seems natural seeing as that's -what the underlying system uses, and because it might allow us to match -the range and resolution exactly. But would it work with chrono? And could -it still act at all like a ``timespec`` struct? - -For ease of consideration, let's consider what the implementation might -look like. - -.. code-block:: cpp - - struct fs_timespec_rep { - fs_timespec_rep(long long v) - : tv_sec(v / nano::den), tv_nsec(v % nano::den) - { } - private: - time_t tv_sec; - long tv_nsec; - }; - bool operator==(fs_timespec_rep, fs_timespec_rep); - fs_int128_rep operator+(fs_timespec_rep, fs_timespec_rep); - // ... arithmetic operators ... // - -The first thing to notice is that we can't construct ``fs_timespec_rep`` like -a ``timespec`` by passing ``{secs, nsecs}``. Instead we're limited to -constructing it from a single 64 bit integer. - -We also can't allow the user to inspect the ``tv_sec`` or ``tv_nsec`` values -directly. A ``chrono::duration`` represents its value as a tick period and a -number of ticks stored using ``rep``. The representation is unaware of the -tick period it is being used to represent, but ``timespec`` is setup to assume -a nanosecond tick period; which is the only case where the names ``tv_sec`` -and ``tv_nsec`` match the values they store. - -When we convert a nanosecond duration to seconds, ``fs_timespec_rep`` will -use ``tv_sec`` to represent the number of giga seconds, and ``tv_nsec`` the -remaining seconds. Let's consider how this might cause a bug were users allowed -to manipulate the fields directly. - -.. code-block:: cpp - - template <class Period> - timespec convert_to_timespec(duration<fs_time_rep, Period> dur) { - fs_timespec_rep rep = dur.count(); - return {rep.tv_sec, rep.tv_nsec}; // Oops! Period may not be nanoseconds. - } - - template <class Duration> - Duration convert_to_duration(timespec ts) { - Duration dur({ts.tv_sec, ts.tv_nsec}); // Oops! Period may not be nanoseconds. - return file_time_type(dur); - file_time_type tp = last_write_time(p); - auto dur = - } - - time_t extract_seconds(file_time_type tp) { - // Converting to seconds is a silly bug, but I could see it happening. - using SecsT = chrono::duration<file_time_type::rep, ratio<1, 1>>; - auto secs = duration_cast<Secs>(tp.time_since_epoch()); - // tv_sec is now representing gigaseconds. - return secs.count().tv_sec; // Oops! - } - -Despite ``fs_timespec_rep`` not being usable in any manner resembling -``timespec``, it still might buy us our goal of matching its range exactly, -right? - -Sort of. Chrono provides a specialization point which specifies the minimum -and maximum values for a custom representation. It looks like this: - -.. code-block:: cpp - - template <> - struct duration_values<fs_timespec_rep> { - static fs_timespec_rep zero(); - static fs_timespec_rep min(); - static fs_timespec_rep max() { // assume friendship. - fs_timespec_rep val; - val.tv_sec = numeric_limits<time_t>::max(); - val.tv_nsec = nano::den - 1; - return val; - } - }; - -Notice that ``duration_values`` doesn't tell the representation what tick -period it's actually representing. This would indeed correctly limit the range -of ``duration<fs_timespec_rep, nano>`` to exactly that of ``timespec``. But -nanoseconds isn't the only tick period it will be used to represent. For -example: - -.. code-block:: cpp - - void test() { - using rep = file_time_type::rep; - using fs_nsec = duration<rep, nano>; - using fs_sec = duration<rep>; - fs_nsec nsecs(fs_seconds::max()); // Truncates - } - -Though the above example may appear silly, I think it follows from the incorrect -notion that using a ``timespec`` rep in chrono actually makes it act as if it -were an actual ``timespec``. - -Interactions with 32 bit ``time_t`` ------------------------------------ - -Up until now we've only be considering cases where ``time_t`` is 64 bits, but what -about 32 bit systems/builds where ``time_t`` is 32 bits? (this is the common case -for 32 bit builds). - -When ``time_t`` is 32 bits, we can implement ``file_time_type`` simply using 64-bit -``long long``. There is no need to get either ``__int128_t`` or ``timespec`` emulation -involved. And nor should we, as it would suffer from the numerous complications -described by this paper. - -Obviously our implementation for 32-bit builds should act as similarly to the -64-bit build as possible. Code which compiles in one, should compile in the other. -This consideration is important when choosing between ``__int128_t`` and -emulating ``timespec``. The solution which provides the most uniformity with -the least eccentricity is the preferable one. - -Summary -======= - -The ``file_time_type`` time point is used to represent the write times for files. -Its job is to act as part of a C++ wrapper for less ideal system interfaces. The -underlying filesystem uses the ``timespec`` struct for the same purpose. - -However, the initial implementation of ``file_time_type`` could not represent -either the range or resolution of ``timespec``, making it unsuitable. Fixing -this requires an implementation which uses more than 64 bits to store the -time point. - -We primarily considered two solutions: Using ``__int128_t`` and using a -arithmetic emulation of ``timespec``. Each has its pros and cons, and both -come with more than one complication. - -The Potential Solutions ------------------------ - -``long long`` - The Status Quo -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Pros: - -* As a type ``long long`` plays the nicest with others: - - * It works with streaming operators and other library entities which support - builtin integer types, but don't support ``__int128_t``. - * Its the representation used by chrono's ``nanosecond`` and ``second`` typedefs. - -Cons: - -* It cannot provide the same resolution as ``timespec`` unless we limit it - to a range of +/- 300 years from the epoch. -* It cannot provide the same range as ``timespec`` unless we limit its resolution - to seconds. -* ``last_write_time`` has to report an error when the time reported by the filesystem - is unrepresentable. - -__int128_t -~~~~~~~~~~~ - -Pros: - -* It is an integer type. -* It makes the implementation simple and efficient. -* Acts exactly like other arithmetic types. -* Can be implicitly converted to a builtin integer type by the user. - - * This is important for doing things like: - - .. code-block:: cpp - - void c_interface_using_time_t(const char* p, time_t); - - void foo(path p) { - file_time_type tp = last_write_time(p); - time_t secs = duration_cast<seconds>(tp.time_since_epoch()).count(); - c_interface_using_time_t(p.c_str(), secs); - } - -Cons: - -* It isn't always available (but on 64 bit machines, it normally is). -* It causes ``file_time_type`` to have a larger range than ``timespec``. -* It doesn't always act the same as other builtin integer types. For example - with ``cout`` or ``to_string``. -* Allows implicit truncation to 64 bit integers. -* It can be implicitly converted to a builtin integer type by the user, - truncating its value. - -Arithmetic ``timespec`` Emulation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Pros: - -* It has the exact same range and resolution of ``timespec`` when representing - a nanosecond tick period. -* It's always available, unlike ``__int128_t``. - -Cons: - -* It has a larger range when representing any period longer than a nanosecond. -* Doesn't actually allow users to use it like a ``timespec``. -* The required representation of using ``tv_sec`` to store the giga tick count - and ``tv_nsec`` to store the remainder adds nothing over a 128 bit integer, - but complicates a lot. -* It isn't a builtin integer type, and can't be used anything like one. -* Chrono can be made to work with it, but not nicely. -* Emulating arithmetic classes come with their own host of problems regarding - overload resolution (Each operator needs three SFINAE constrained versions of - it in order to act like builtin integer types). -* It offers little over simply using ``__int128_t``. -* It acts the most differently than implementations using an actual integer type, - which has a high chance of breaking source compatibility. - - -Selected Solution - Using ``__int128_t`` -========================================= - -The solution I selected for libc++ is using ``__int128_t`` when available, -and otherwise falling back to using ``long long`` with nanosecond precision. - -When ``__int128_t`` is available, or when ``time_t`` is 32-bits, the implementation -provides same resolution and a greater range than ``timespec``. Otherwise -it still provides the same resolution, but is limited to a range of +/- 300 -years. This final case should be rather rare, as ``__int128_t`` -is normally available in 64-bit builds, and ``time_t`` is normally 32-bits -during 32-bit builds. - -Although falling back to ``long long`` and nanosecond precision is less than -ideal, it also happens to be the implementation provided by both libstdc++ -and MSVC. (So that makes it better, right?) - -Although the ``timespec`` emulation solution is feasible and would largely -do what we want, it comes with too many complications, potential problems -and discrepancies when compared to "normal" chrono time points and durations. - -An emulation of a builtin arithmetic type using a class is never going to act -exactly the same, and the difference will be felt by users. It's not reasonable -to expect them to tolerate and work around these differences. And once -we commit to an ABI it will be too late to change. Committing to this seems -risky. - -Therefore, ``__int128_t`` seems like the better solution. diff --git a/lib/libcxx/docs/DesignDocs/ThreadingSupportAPI.rst b/lib/libcxx/docs/DesignDocs/ThreadingSupportAPI.rst deleted file mode 100644 index 330ce74cf77..00000000000 --- a/lib/libcxx/docs/DesignDocs/ThreadingSupportAPI.rst +++ /dev/null @@ -1,83 +0,0 @@ -===================== -Threading Support API -===================== - -.. contents:: - :local: - -Overview -======== - -Libc++ supports using multiple different threading models and configurations -to implement the threading parts of libc++, including ``<thread>`` and ``<mutex>``. -These different models provide entirely different interfaces from each -other. To address this libc++ wraps the underlying threading API in a new and -consistent API, which it uses internally to implement threading primitives. - -The ``<__threading_support>`` header is where libc++ defines its internal -threading interface. It contains forward declarations of the internal threading -interface as well as definitions for the interface. - -External Threading API and the ``<__external_threading>`` header -================================================================ - -In order to support vendors with custom threading API's libc++ allows the -entire internal threading interface to be provided by an external, -vendor provided, header. - -When ``_LIBCPP_HAS_THREAD_API_EXTERNAL`` is defined the ``<__threading_support>`` -header simply forwards to the ``<__external_threading>`` header (which must exist). -It is expected that the ``<__external_threading>`` header provide the exact -interface normally provided by ``<__threading_support>``. - -External Threading Library -========================== - -libc++ can be compiled with its internal threading API delegating to an external -library. Such a configuration is useful for library vendors who wish to -distribute a thread-agnostic libc++ library, where the users of the library are -expected to provide the implementation of the libc++ internal threading API. - -On a production setting, this would be achieved through a custom -``<__external_threading>`` header, which declares the libc++ internal threading -API but leaves out the implementation. - -The ``-DLIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY`` option allows building libc++ in -such a configuration while allowing it to be tested on a platform that supports -any of the threading systems (e.g. pthread) supported in ``__threading_support`` -header. Therefore, the main purpose of this option is to allow testing of this -particular configuration of the library without being tied to a vendor-specific -threading system. This option is only meant to be used by libc++ library -developers. - -Threading Configuration Macros -============================== - -**_LIBCPP_HAS_NO_THREADS** - This macro is defined when libc++ is built without threading support. It - should not be manually defined by the user. - -**_LIBCPP_HAS_THREAD_API_EXTERNAL** - This macro is defined when libc++ should use the ``<__external_threading>`` - header to provide the internal threading API. This macro overrides - ``_LIBCPP_HAS_THREAD_API_PTHREAD``. - -**_LIBCPP_HAS_THREAD_API_PTHREAD** - This macro is defined when libc++ should use POSIX threads to implement the - internal threading API. - -**_LIBCPP_HAS_THREAD_API_WIN32** - This macro is defined when libc++ should use Win32 threads to implement the - internal threading API. - -**_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL** - This macro is defined when libc++ expects the definitions of the internal - threading API to be provided by an external library. When defined - ``<__threading_support>`` will only provide the forward declarations and - typedefs for the internal threading API. - -**_LIBCPP_BUILDING_THREAD_LIBRARY_EXTERNAL** - This macro is used to build an external threading library using the - ``<__threading_support>``. Specifically it exposes the threading API - definitions in ``<__threading_support>`` as non-inline definitions meant to - be compiled into a library. diff --git a/lib/libcxx/docs/DesignDocs/VisibilityMacros.rst b/lib/libcxx/docs/DesignDocs/VisibilityMacros.rst deleted file mode 100644 index d0d4f0adb22..00000000000 --- a/lib/libcxx/docs/DesignDocs/VisibilityMacros.rst +++ /dev/null @@ -1,218 +0,0 @@ -======================== -Symbol Visibility Macros -======================== - -.. contents:: - :local: - -Overview -======== - -Libc++ uses various "visibility" macros in order to provide a stable ABI in -both the library and the headers. These macros work by changing the -visibility and inlining characteristics of the symbols they are applied to. - -Visibility Macros -================= - -**_LIBCPP_HIDDEN** - Mark a symbol as hidden so it will not be exported from shared libraries. - -**_LIBCPP_FUNC_VIS** - Mark a symbol as being exported by the libc++ library. This attribute must - be applied to the declaration of all functions exported by the libc++ dylib. - -**_LIBCPP_EXPORTED_FROM_ABI** - Mark a symbol as being exported by the libc++ library. This attribute may - only be applied to objects defined in the libc++ runtime library. On Windows, - this macro applies `dllimport`/`dllexport` to the symbol, and on other - platforms it gives the symbol default visibility. - -**_LIBCPP_OVERRIDABLE_FUNC_VIS** - Mark a symbol as being exported by the libc++ library, but allow it to be - overridden locally. On non-Windows, this is equivalent to `_LIBCPP_FUNC_VIS`. - This macro is applied to all `operator new` and `operator delete` overloads. - - **Windows Behavior**: Any symbol marked `dllimport` cannot be overridden - locally, since `dllimport` indicates the symbol should be bound to a separate - DLL. All `operator new` and `operator delete` overloads are required to be - locally overridable, and therefore must not be marked `dllimport`. On Windows, - this macro therefore expands to `__declspec(dllexport)` when building the - library and has an empty definition otherwise. - -**_LIBCPP_HIDE_FROM_ABI** - Mark a function as not being part of the ABI of any final linked image that - uses it. - -**_LIBCPP_HIDE_FROM_ABI_AFTER_V1** - Mark a function as being hidden from the ABI (per `_LIBCPP_HIDE_FROM_ABI`) - when libc++ is built with an ABI version after ABI v1. This macro is used to - maintain ABI compatibility for symbols that have been historically exported - by libc++ in v1 of the ABI, but that we don't want to export in the future. - - This macro works as follows. When we build libc++, we either hide the symbol - from the ABI (if the symbol is not part of the ABI in the version we're - building), or we leave it included. From user code (i.e. when we're not - building libc++), the macro always marks symbols as internal so that programs - built using new libc++ headers stop relying on symbols that are removed from - the ABI in a future version. Each time we release a new stable version of the - ABI, we should create a new _LIBCPP_HIDE_FROM_ABI_AFTER_XXX macro, and we can - use it to start removing symbols from the ABI after that stable version. - -**_LIBCPP_HIDE_FROM_ABI_PER_TU** - This macro controls whether symbols hidden from the ABI with `_LIBCPP_HIDE_FROM_ABI` - are local to each translation unit in addition to being local to each final - linked image. This macro is defined to either 0 or 1. When it is defined to - 1, translation units compiled with different versions of libc++ can be linked - together, since all non ABI-facing functions are local to each translation unit. - This allows static archives built with different versions of libc++ to be linked - together. This also means that functions marked with `_LIBCPP_HIDE_FROM_ABI` - are not guaranteed to have the same address across translation unit boundaries. - - When the macro is defined to 0, there is no guarantee that translation units - compiled with different versions of libc++ can interoperate. However, this - leads to code size improvements, since non ABI-facing functions can be - deduplicated across translation unit boundaries. - - This macro can be defined by users to control the behavior they want from - libc++. The default value of this macro (0 or 1) is controlled by whether - `_LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT` is defined, which is intended to - be used by vendors only (see below). - -**_LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT** - This macro controls the default value for `_LIBCPP_HIDE_FROM_ABI_PER_TU`. - When the macro is defined, per TU ABI insulation is enabled by default, and - `_LIBCPP_HIDE_FROM_ABI_PER_TU` is defined to 1 unless overridden by users. - Otherwise, per TU ABI insulation is disabled by default, and - `_LIBCPP_HIDE_FROM_ABI_PER_TU` is defined to 0 unless overridden by users. - - This macro is intended for vendors to control whether they want to ship - libc++ with per TU ABI insulation enabled by default. Users can always - control the behavior they want by defining `_LIBCPP_HIDE_FROM_ABI_PER_TU` - appropriately. - - By default, this macro is not defined, which means that per TU ABI insulation - is not provided unless explicitly overridden by users. - -**_LIBCPP_TYPE_VIS** - Mark a type's typeinfo, vtable and members as having default visibility. - This attribute cannot be used on class templates. - -**_LIBCPP_TEMPLATE_VIS** - Mark a type's typeinfo and vtable as having default visibility. - This macro has no effect on the visibility of the type's member functions. - - **GCC Behavior**: GCC does not support Clang's `type_visibility(...)` - attribute. With GCC the `visibility(...)` attribute is used and member - functions are affected. - - **Windows Behavior**: DLLs do not support dllimport/export on class templates. - The macro has an empty definition on this platform. - - -**_LIBCPP_ENUM_VIS** - Mark the typeinfo of an enum as having default visibility. This attribute - should be applied to all enum declarations. - - **Windows Behavior**: DLLs do not support importing or exporting enumeration - typeinfo. The macro has an empty definition on this platform. - - **GCC Behavior**: GCC un-hides the typeinfo for enumerations by default, even - if `-fvisibility=hidden` is specified. Additionally applying a visibility - attribute to an enum class results in a warning. The macro has an empty - definition with GCC. - -**_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS** - Mark the member functions, typeinfo, and vtable of the type named in - a `_LIBCPP_EXTERN_TEMPLATE` declaration as being exported by the libc++ library. - This attribute must be specified on all extern class template declarations. - - This macro is used to override the `_LIBCPP_TEMPLATE_VIS` attribute - specified on the primary template and to export the member functions produced - by the explicit instantiation in the dylib. - - **GCC Behavior**: GCC ignores visibility attributes applied the type in - extern template declarations and applying an attribute results in a warning. - However since `_LIBCPP_TEMPLATE_VIS` is the same as - `__attribute__((visibility("default"))` the visibility is already correct. - The macro has an empty definition with GCC. - - **Windows Behavior**: `extern template` and `dllexport` are fundamentally - incompatible *on a class template* on Windows; the former suppresses - instantiation, while the latter forces it. Specifying both on the same - declaration makes the class template be instantiated, which is not desirable - inside headers. This macro therefore expands to `dllimport` outside of libc++ - but nothing inside of it (rather than expanding to `dllexport`); instead, the - explicit instantiations themselves are marked as exported. Note that this - applies *only* to extern *class* templates. Extern *function* templates obey - regular import/export semantics, and applying `dllexport` directly to the - extern template declaration (i.e. using `_LIBCPP_FUNC_VIS`) is the correct - thing to do for them. - -**_LIBCPP_CLASS_TEMPLATE_INSTANTIATION_VIS** - Mark the member functions, typeinfo, and vtable of an explicit instantiation - of a class template as being exported by the libc++ library. This attribute - must be specified on all class template explicit instantiations. - - It is only necessary to mark the explicit instantiation itself (as opposed to - the extern template declaration) as exported on Windows, as discussed above. - On all other platforms, this macro has an empty definition. - -**_LIBCPP_METHOD_TEMPLATE_IMPLICIT_INSTANTIATION_VIS** - Mark a symbol as hidden so it will not be exported from shared libraries. This - is intended specifically for method templates of either classes marked with - `_LIBCPP_TYPE_VIS` or classes with an extern template instantiation - declaration marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS`. - - When building libc++ with hidden visibility, we want explicit template - instantiations to export members, which is consistent with existing Windows - behavior. We also want classes annotated with `_LIBCPP_TYPE_VIS` to export - their members, which is again consistent with existing Windows behavior. - Both these changes are necessary for clients to be able to link against a - libc++ DSO built with hidden visibility without encountering missing symbols. - - An unfortunate side effect, however, is that method templates of classes - either marked `_LIBCPP_TYPE_VIS` or with extern template instantiation - declarations marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` also get default - visibility when instantiated. These methods are often implicitly instantiated - inside other libraries which use the libc++ headers, and will therefore end up - being exported from those libraries, since those implicit instantiations will - receive default visibility. This is not acceptable for libraries that wish to - control their visibility, and led to PR30642. - - Consequently, all such problematic method templates are explicitly marked - either hidden (via this macro) or inline, so that they don't leak into client - libraries. The problematic methods were found by running - `bad-visibility-finder <https://github.com/smeenai/bad-visibility-finder>`_ - against the libc++ headers after making `_LIBCPP_TYPE_VIS` and - `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` expand to default visibility. - -**_LIBCPP_EXCEPTION_ABI** - Mark the member functions, typeinfo, and vtable of the type as being exported - by the libc++ library. This macro must be applied to all *exception types*. - Exception types should be defined directly in namespace `std` and not the - versioning namespace. This allows throwing and catching some exception types - between libc++ and libstdc++. - -**_LIBCPP_INTERNAL_LINKAGE** - Mark the affected entity as having internal linkage (i.e. the `static` - keyword in C). This is only a best effort: when the `internal_linkage` - attribute is not available, we fall back to forcing the function to be - inlined, which approximates internal linkage since an externally visible - symbol is never generated for that function. This is an internal macro - used as an implementation detail by other visibility macros. Never mark - a function or a class with this macro directly. - -**_LIBCPP_ALWAYS_INLINE** - Forces inlining of the function it is applied to. For visibility purposes, - this macro is used to make sure that an externally visible symbol is never - generated in an object file when the `internal_linkage` attribute is not - available. This is an internal macro used by other visibility macros, and - it should not be used directly. - -Links -===== - -* `[cfe-dev] Visibility in libc++ - 1 <http://lists.llvm.org/pipermail/cfe-dev/2013-July/030610.html>`_ -* `[cfe-dev] Visibility in libc++ - 2 <http://lists.llvm.org/pipermail/cfe-dev/2013-August/031195.html>`_ -* `[libcxx] Visibility fixes for Windows <http://lists.llvm.org/pipermail/cfe-commits/Week-of-Mon-20130805/085461.html>`_ diff --git a/lib/libcxx/docs/FeatureTestMacroTable.rst b/lib/libcxx/docs/FeatureTestMacroTable.rst deleted file mode 100644 index d900497eba7..00000000000 --- a/lib/libcxx/docs/FeatureTestMacroTable.rst +++ /dev/null @@ -1,200 +0,0 @@ -.. _FeatureTestMacroTable: - -========================== -Feature Test Macro Support -========================== - -.. contents:: - :local: - -Overview -======== - -This file documents the feature test macros currently supported by libc++. - -.. _feature-status: - -Status -====== - -.. table:: Current Status - :name: feature-status-table - :widths: auto - - ================================================= ================= - Macro Name Value - ================================================= ================= - **C++ 14** - ------------------------------------------------------------------- - ``__cpp_lib_chrono_udls`` ``201304L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_complex_udls`` ``201309L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_exchange_function`` ``201304L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_generic_associative_lookup`` ``201304L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_integer_sequence`` ``201304L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_integral_constant_callable`` ``201304L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_is_final`` ``201402L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_is_null_pointer`` ``201309L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_make_reverse_iterator`` ``201402L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_make_unique`` ``201304L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_null_iterators`` ``201304L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_quoted_string_io`` ``201304L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_result_of_sfinae`` ``201210L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_robust_nonmodifying_seq_ops`` ``201304L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_shared_timed_mutex`` ``201402L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_string_udls`` ``201304L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_transformation_trait_aliases`` ``201304L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_transparent_operators`` ``201210L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_tuple_element_t`` ``201402L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_tuples_by_type`` ``201304L`` - ------------------------------------------------- ----------------- - **C++ 17** - ------------------------------------------------------------------- - ``__cpp_lib_addressof_constexpr`` ``201603L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_allocator_traits_is_always_equal`` ``201411L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_any`` ``201606L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_apply`` ``201603L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_array_constexpr`` ``201603L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_as_const`` ``201510L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_atomic_is_always_lock_free`` ``201603L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_bool_constant`` ``201505L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_boyer_moore_searcher`` *unimplemented* - ------------------------------------------------- ----------------- - ``__cpp_lib_byte`` ``201603L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_chrono`` ``201611L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_clamp`` ``201603L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_enable_shared_from_this`` ``201603L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_execution`` *unimplemented* - ------------------------------------------------- ----------------- - ``__cpp_lib_filesystem`` ``201703L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_gcd_lcm`` ``201606L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_hardware_interference_size`` ``201703L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_has_unique_object_representations`` ``201606L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_hypot`` ``201603L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_incomplete_container_elements`` ``201505L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_invoke`` ``201411L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_is_aggregate`` ``201703L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_is_invocable`` ``201703L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_is_swappable`` ``201603L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_launder`` ``201606L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_logical_traits`` ``201510L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_make_from_tuple`` ``201606L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_map_try_emplace`` ``201411L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_math_special_functions`` *unimplemented* - ------------------------------------------------- ----------------- - ``__cpp_lib_memory_resource`` *unimplemented* - ------------------------------------------------- ----------------- - ``__cpp_lib_node_extract`` ``201606L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_nonmember_container_access`` ``201411L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_not_fn`` ``201603L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_optional`` ``201606L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_parallel_algorithm`` *unimplemented* - ------------------------------------------------- ----------------- - ``__cpp_lib_raw_memory_algorithms`` ``201606L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_sample`` ``201603L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_scoped_lock`` ``201703L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_shared_mutex`` ``201505L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_shared_ptr_arrays`` *unimplemented* - ------------------------------------------------- ----------------- - ``__cpp_lib_shared_ptr_weak_type`` ``201606L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_string_view`` ``201606L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_to_chars`` *unimplemented* - ------------------------------------------------- ----------------- - ``__cpp_lib_transparent_operators`` ``201510L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_type_trait_variable_templates`` ``201510L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_uncaught_exceptions`` ``201411L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_unordered_map_try_emplace`` ``201411L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_variant`` ``201606L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_void_t`` ``201411L`` - ------------------------------------------------- ----------------- - **C++ 2a** - ------------------------------------------------------------------- - ``__cpp_lib_atomic_ref`` *unimplemented* - ------------------------------------------------- ----------------- - ``__cpp_lib_bind_front`` *unimplemented* - ------------------------------------------------- ----------------- - ``__cpp_lib_bit_cast`` *unimplemented* - ------------------------------------------------- ----------------- - ``__cpp_lib_char8_t`` ``201811L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_concepts`` *unimplemented* - ------------------------------------------------- ----------------- - ``__cpp_lib_constexpr_misc`` *unimplemented* - ------------------------------------------------- ----------------- - ``__cpp_lib_constexpr_swap_algorithms`` *unimplemented* - ------------------------------------------------- ----------------- - ``__cpp_lib_destroying_delete`` *unimplemented* - ------------------------------------------------- ----------------- - ``__cpp_lib_erase_if`` ``201811L`` - ------------------------------------------------- ----------------- - ``__cpp_lib_generic_unordered_lookup`` *unimplemented* - ------------------------------------------------- ----------------- - ``__cpp_lib_is_constant_evaluated`` *unimplemented* - ------------------------------------------------- ----------------- - ``__cpp_lib_list_remove_return_type`` *unimplemented* - ------------------------------------------------- ----------------- - ``__cpp_lib_ranges`` *unimplemented* - ------------------------------------------------- ----------------- - ``__cpp_lib_three_way_comparison`` *unimplemented* - ================================================= ================= - - diff --git a/lib/libcxx/docs/Makefile.sphinx b/lib/libcxx/docs/Makefile.sphinx deleted file mode 100644 index a34f0cc0bad..00000000000 --- a/lib/libcxx/docs/Makefile.sphinx +++ /dev/null @@ -1,37 +0,0 @@ -# Makefile for Sphinx documentation -# -# FIXME: This hack is only in place to allow the libcxx.llvm.org/docs builder -# to work with libcxx. This should be removed when that builder supports -# out-of-tree builds. - -# You can set these variables from the command line. -SPHINXOPTS = -n -W -v -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext default - -default: html - -help: - @echo "Please use \`make <target>' where <target> is one of" - @echo " html to make standalone HTML files" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @# FIXME: Remove this `cp` once HTML->Sphinx transition is completed. - @# Kind of a hack, but HTML-formatted docs are on the way out anyway. - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - diff --git a/lib/libcxx/docs/README.txt b/lib/libcxx/docs/README.txt deleted file mode 100644 index 06d94f5b5fc..00000000000 --- a/lib/libcxx/docs/README.txt +++ /dev/null @@ -1,13 +0,0 @@ -libc++ Documentation -==================== - -The libc++ documentation is written using the Sphinx documentation generator. It is -currently tested with Sphinx 1.1.3. - -To build the documents into html configure libc++ with the following cmake options: - - * -DLLVM_ENABLE_SPHINX=ON - * -DLIBCXX_INCLUDE_DOCS=ON - -After configuring libc++ with these options the make rule `docs-libcxx-html` -should be available. diff --git a/lib/libcxx/docs/ReleaseNotes.rst b/lib/libcxx/docs/ReleaseNotes.rst deleted file mode 100644 index ca5a534ae84..00000000000 --- a/lib/libcxx/docs/ReleaseNotes.rst +++ /dev/null @@ -1,48 +0,0 @@ -========================== -Libc++ 8.0.0 Release Notes -========================== - -.. contents:: - :local: - :depth: 2 - -Written by the `Libc++ Team <https://libcxx.llvm.org>`_ - -Introduction -============ - -This document contains the release notes for the libc++ C++ Standard Library, -part of the LLVM Compiler Infrastructure, release 8.0.0. Here we describe the -status of libc++ in some detail, including major improvements from the previous -release and new feature work. For the general LLVM release notes, see `the LLVM -documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM releases may -be downloaded from the `LLVM releases web site <https://releases.llvm.org/>`_. - -For more information about libc++, please see the `Libc++ Web Site -<https://libcxx.llvm.org>`_ or the `LLVM Web Site <https://llvm.org>`_. - -What's New in Libc++ 8.0.0? -=========================== - -API Changes ------------ -- Building libc++ for Mac OSX 10.6 is not supported anymore. -- Starting with LLVM 8.0.0, users that wish to link together translation units - built with different versions of libc++'s headers into the same final linked - image MUST define the _LIBCPP_HIDE_FROM_ABI_PER_TU macro to 1 when building - those translation units. Not defining _LIBCPP_HIDE_FROM_ABI_PER_TU to 1 and - linking translation units built with different versions of libc++'s headers - together may lead to ODR violations and ABI issues. On the flipside, code - size improvements should be expected for everyone not defining the macro. -- Starting with LLVM 8.0.0, std::dynarray has been removed from the library. - std::dynarray was a feature proposed for C++14 that was pulled from the - Standard at the last minute and was never standardized. Since there are no - plans to standardize this facility it is being removed. -- Starting with LLVM 8.0.0, std::bad_array_length has been removed from the - library. std::bad_array_length was a feature proposed for C++14 alongside - std::dynarray, but it never actually made it into the C++ Standard. There - are no plans to standardize this feature at this time. Formally speaking, - this removal constitutes an ABI break because the symbols were shipped in - the shared library. However, on macOS systems, the feature was not usable - because it was hidden behind availability annotations. We do not expect - any actual breakage to happen from this change. diff --git a/lib/libcxx/docs/TestingLibcxx.rst b/lib/libcxx/docs/TestingLibcxx.rst deleted file mode 100644 index ebbbf628ac0..00000000000 --- a/lib/libcxx/docs/TestingLibcxx.rst +++ /dev/null @@ -1,257 +0,0 @@ -============== -Testing libc++ -============== - -.. contents:: - :local: - -Getting Started -=============== - -libc++ uses LIT to configure and run its tests. The primary way to run the -libc++ tests is by using make check-libcxx. However since libc++ can be used -in any number of possible configurations it is important to customize the way -LIT builds and runs the tests. This guide provides information on how to use -LIT directly to test libc++. - -Please see the `Lit Command Guide`_ for more information about LIT. - -.. _LIT Command Guide: http://llvm.org/docs/CommandGuide/lit.html - -Setting up the Environment --------------------------- - -After building libc++ you must setup your environment to test libc++ using -LIT. - -#. Create a shortcut to the actual lit executable so that you can invoke it - easily from the command line. - - .. code-block:: bash - - $ alias lit='python path/to/llvm/utils/lit/lit.py' - -#. Tell LIT where to find your build configuration. - - .. code-block:: bash - - $ export LIBCXX_SITE_CONFIG=path/to/build-libcxx/test/lit.site.cfg - -Example Usage -------------- - -Once you have your environment set up and you have built libc++ you can run -parts of the libc++ test suite by simply running `lit` on a specified test or -directory. For example: - -.. code-block:: bash - - $ cd path/to/src/libcxx - $ lit -sv test/std/re # Run all of the std::regex tests - $ lit -sv test/std/depr/depr.c.headers/stdlib_h.pass.cpp # Run a single test - $ lit -sv test/std/atomics test/std/threads # Test std::thread and std::atomic - -Sometimes you'll want to change the way LIT is running the tests. Custom options -can be specified using the `--param=<name>=<val>` flag. The most common option -you'll want to change is the standard dialect (ie -std=c++XX). By default the -test suite will select the newest C++ dialect supported by the compiler and use -that. However if you want to manually specify the option like so: - -.. code-block:: bash - - $ lit -sv test/std/containers # Run the tests with the newest -std - $ lit -sv --param=std=c++03 test/std/containers # Run the tests in C++03 - -Occasionally you'll want to add extra compile or link flags when testing. -You can do this as follows: - -.. code-block:: bash - - $ lit -sv --param=compile_flags='-Wcustom-warning' - $ lit -sv --param=link_flags='-L/custom/library/path' - -Some other common examples include: - -.. code-block:: bash - - # Specify a custom compiler. - $ lit -sv --param=cxx_under_test=/opt/bin/g++ test/std - - # Enable warnings in the test suite - $ lit -sv --param=enable_warnings=true test/std - - # Use UBSAN when running the tests. - $ lit -sv --param=use_sanitizer=Undefined - - -LIT Options -=========== - -:program:`lit` [*options*...] [*filenames*...] - -Command Line Options --------------------- - -To use these options you pass them on the LIT command line as --param NAME or ---param NAME=VALUE. Some options have default values specified during CMake's -configuration. Passing the option on the command line will override the default. - -.. program:: lit - -.. option:: cxx_under_test=<path/to/compiler> - - Specify the compiler used to build the tests. - -.. option:: cxx_stdlib_under_test=<stdlib name> - - **Values**: libc++, libstdc++ - - Specify the C++ standard library being tested. Unless otherwise specified - libc++ is used. This option is intended to allow running the libc++ test - suite against other standard library implementations. - -.. option:: std=<standard version> - - **Values**: c++98, c++03, c++11, c++14, c++17, c++2a - - Change the standard version used when building the tests. - -.. option:: libcxx_site_config=<path/to/lit.site.cfg> - - Specify the site configuration to use when running the tests. This option - overrides the environment variable LIBCXX_SITE_CONFIG. - -.. option:: cxx_headers=<path/to/headers> - - Specify the c++ standard library headers that are tested. By default the - headers in the source tree are used. - -.. option:: cxx_library_root=<path/to/lib/> - - Specify the directory of the libc++ library to be tested. By default the - library folder of the build directory is used. This option cannot be used - when use_system_cxx_lib is provided. - - -.. option:: cxx_runtime_root=<path/to/lib/> - - Specify the directory of the libc++ library to use at runtime. This directory - is not added to the linkers search path. This can be used to compile tests - against one version of libc++ and run them using another. The default value - for this option is `cxx_library_root`. - -.. option:: use_system_cxx_lib=<bool> - - **Default**: False - - Enable or disable testing against the installed version of libc++ library. - Note: This does not use the installed headers. - -.. option:: use_lit_shell=<bool> - - Enable or disable the use of LIT's internal shell in ShTests. If the - environment variable LIT_USE_INTERNAL_SHELL is present then that is used as - the default value. Otherwise the default value is True on Windows and False - on every other platform. - -.. option:: compile_flags="<list-of-args>" - - Specify additional compile flags as a space delimited string. - Note: This options should not be used to change the standard version used. - -.. option:: link_flags="<list-of-args>" - - Specify additional link flags as a space delimited string. - -.. option:: debug_level=<level> - - **Values**: 0, 1 - - Enable the use of debug mode. Level 0 enables assertions and level 1 enables - assertions and debugging of iterator misuse. - -.. option:: use_sanitizer=<sanitizer name> - - **Values**: Memory, MemoryWithOrigins, Address, Undefined - - Run the tests using the given sanitizer. If LLVM_USE_SANITIZER was given when - building libc++ then that sanitizer will be used by default. - -.. option:: color_diagnostics - - Enable the use of colorized compile diagnostics. If the color_diagnostics - option is specified or the environment variable LIBCXX_COLOR_DIAGNOSTICS is - present then color diagnostics will be enabled. - - -Environment Variables ---------------------- - -.. envvar:: LIBCXX_SITE_CONFIG=<path/to/lit.site.cfg> - - Specify the site configuration to use when running the tests. - Also see `libcxx_site_config`. - -.. envvar:: LIBCXX_COLOR_DIAGNOSTICS - - If ``LIBCXX_COLOR_DIAGNOSTICS`` is defined then the test suite will attempt - to use color diagnostic outputs from the compiler. - Also see `color_diagnostics`. - -Benchmarks -========== - -Libc++ contains benchmark tests separately from the test of the test suite. -The benchmarks are written using the `Google Benchmark`_ library, a copy of which -is stored in the libc++ repository. - -For more information about using the Google Benchmark library see the -`official documentation <https://github.com/google/benchmark>`_. - -.. _`Google Benchmark`: https://github.com/google/benchmark - -Building Benchmarks -------------------- - -The benchmark tests are not built by default. The benchmarks can be built using -the ``cxx-benchmarks`` target. - -An example build would look like: - -.. code-block:: bash - - $ cd build - $ cmake [options] <path to libcxx sources> - $ make cxx-benchmarks - -This will build all of the benchmarks under ``<libcxx-src>/benchmarks`` to be -built against the just-built libc++. The compiled tests are output into -``build/benchmarks``. - -The benchmarks can also be built against the platforms native standard library -using the ``-DLIBCXX_BUILD_BENCHMARKS_NATIVE_STDLIB=ON`` CMake option. This -is useful for comparing the performance of libc++ to other standard libraries. -The compiled benchmarks are named ``<test>.libcxx.out`` if they test libc++ and -``<test>.native.out`` otherwise. - -Also See: - - * :ref:`Building Libc++ <build instructions>` - * :ref:`CMake Options` - -Running Benchmarks ------------------- - -The benchmarks must be run manually by the user. Currently there is no way -to run them as part of the build. - -For example: - -.. code-block:: bash - - $ cd build/benchmarks - $ make cxx-benchmarks - $ ./algorithms.libcxx.out # Runs all the benchmarks - $ ./algorithms.libcxx.out --benchmark_filter=BM_Sort.* # Only runs the sort benchmarks - -For more information about running benchmarks see `Google Benchmark`_. diff --git a/lib/libcxx/docs/UsingLibcxx.rst b/lib/libcxx/docs/UsingLibcxx.rst deleted file mode 100644 index 899656cca1d..00000000000 --- a/lib/libcxx/docs/UsingLibcxx.rst +++ /dev/null @@ -1,317 +0,0 @@ -============ -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 OS X 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 OS X) 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>`` and libc++fs -==================================== - -Libc++ provides the implementation of the filesystem library in a separate -library. Users of ``<filesystem>`` and ``<experimental/filesystem>`` are -required to link ``-lc++fs``. - -.. note:: - Prior to libc++ 7.0, users of ``<experimental/filesystem>`` were required - to link libc++experimental. - -.. warning:: - The Filesystem library is still experimental in nature. As such normal - guarantees about ABI stability and backwards compatibility do not yet apply - to it. In the future, this restriction will be removed. - - -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>`. - -Note that as of libc++ 7.0 using the ``<experimental/filesystem>`` requires linking -libc++fs instead of libc++experimental. - -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. - -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_ENABLE_DEPRECATION_WARNINGS**: - This macro enables warnings when using deprecated components. For example, - when compiling in C++11 mode, using `std::auto_ptr` with the macro defined - will trigger a warning saying that `std::auto_ptr` is deprecated. 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). - -* ``get_temporary_buffer`` diff --git a/lib/libcxx/docs/conf.py b/lib/libcxx/docs/conf.py deleted file mode 100644 index 50b372cf84e..00000000000 --- a/lib/libcxx/docs/conf.py +++ /dev/null @@ -1,251 +0,0 @@ -# -*- coding: utf-8 -*- -# -# libc++ documentation build configuration file. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys, os - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.todo'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'libc++' -copyright = u'2011-2018, LLVM Project' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '8.0' -# The full version, including alpha/beta/rc tags. -release = '8.0' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -today_fmt = '%Y-%m-%d' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -show_authors = True - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'friendly' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'haiku' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# "<project> v<release> documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a <link> tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'libcxxdoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('contents', 'libcxx.tex', u'libcxx Documentation', - u'LLVM project', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('contents', 'libc++', u'libc++ Documentation', - [u'LLVM project'], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------------ - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ('contents', 'libc++', u'libc++ Documentation', - u'LLVM project', 'libc++', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - - -# FIXME: Define intersphinx configuration. -intersphinx_mapping = {} - - -# -- Options for extensions ---------------------------------------------------- - -# Enable this if you want TODOs to show up in the generated documentation. -todo_include_todos = True diff --git a/lib/libcxx/docs/index.rst b/lib/libcxx/docs/index.rst deleted file mode 100644 index fddf74b66a9..00000000000 --- a/lib/libcxx/docs/index.rst +++ /dev/null @@ -1,194 +0,0 @@ -.. _index: - -============================= -"libc++" C++ Standard Library -============================= - -Overview -======== - -libc++ is a new implementation of the C++ standard library, targeting C++11 and -above. - -* 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 - - ReleaseNotes - UsingLibcxx - BuildingLibcxx - TestingLibcxx - - -.. toctree:: - :hidden: - - FeatureTestMacroTable - -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: - -* 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. - -Platform and Compiler Support ------------------------------ - -libc++ is 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 ABI Library -============ ==================== ============ ======================== -Mac OS X i386, x86_64 Clang, GCC libc++abi -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 -* GCC 4.7 and above. - -Anything older *may* work. - -C++ Dialect Support ---------------------- - -* C++11 - Complete -* `C++14 - Complete <http://libcxx.llvm.org/cxx1y_status.html>`__ -* `C++17 - In Progress <http://libcxx.llvm.org/cxx1z_status.html>`__ -* `Post C++14 Technical Specifications - In Progress <http://libcxx.llvm.org/ts1z_status.html>`__ -* :ref:`C++ Feature Test Macro Status <feature-status>` - -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. -* On OS X v10.8 and older the CMake option ``-DLIBCXX_LIBCPPABI_VERSION=""`` - must be used during configuration. - - -A full list of currently open libc++ bugs can be `found here`__. - -.. __: https://bugs.llvm.org/buglist.cgi?component=All%20Bugs&product=libc%2B%2B&query_format=advanced&resolution=---&order=changeddate%20DESC%2Cassigned_to%20DESC%2Cbug_status%2Cpriority%2Cbug_id&list_id=74184 - -Design Documents ----------------- - -.. toctree:: - :maxdepth: 1 - - DesignDocs/AvailabilityMarkup - DesignDocs/DebugMode - DesignDocs/CapturingConfigInfo - DesignDocs/ABIVersioning - DesignDocs/VisibilityMacros - DesignDocs/ThreadingSupportAPI - DesignDocs/FileTimeType - DesignDocs/FeatureTestMacros - -* `<atomic> design <http://libcxx.llvm.org/atomic_design.html>`_ -* `<type_traits> design <http://libcxx.llvm.org/type_traits_design.html>`_ -* `Notes by Marshall Clow`__ - -.. __: https://cplusplusmusings.wordpress.com/2012/07/05/clang-and-standard-libraries-on-mac-os-x/ - -Build Bots and Test Coverage ----------------------------- - -* `LLVM Buildbot Builders <http://lab.llvm.org:8011/console>`_ -* `Apple Jenkins Builders <http://lab.llvm.org:8080/green/view/Libcxx/>`_ -* `Windows Appveyor Builders <https://ci.appveyor.com/project/llvm-mirror/libcxx>`_ -* `Code Coverage Results <http://efcs.ca/libcxx-coverage>`_ - -Getting Involved -================ - -First please review our `Developer's Policy <http://llvm.org/docs/DeveloperPolicy.html>`__ -and `Getting started with LLVM <http://llvm.org/docs/GettingStarted.html>`__. - -**Bug Reports** - -If you think you've found a bug in libc++, please report it using -the `LLVM Bugzilla`_. If you're not sure, you -can post a message to the `libcxx-dev mailing list`_ or on IRC. - -**Patches** - -If you want to contribute a patch to libc++, the best place for that is -`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>`_. - -**Discussion and Questions** - -Send discussions and questions to the -`libcxx-dev mailing list <http://lists.llvm.org/mailman/listinfo/libcxx-dev>`_. - - - -Quick Links -=========== -* `LLVM Homepage <http://llvm.org/>`_ -* `libc++abi Homepage <http://libcxxabi.llvm.org/>`_ -* `LLVM Bugzilla <https://bugs.llvm.org/>`_ -* `libcxx-commits Mailing List`_ -* `libcxx-dev Mailing List`_ -* `Browse libc++ -- SVN <http://llvm.org/svn/llvm-project/libcxx/trunk/>`_ -* `Browse libc++ -- ViewVC <http://llvm.org/viewvc/llvm-project/libcxx/trunk/>`_ |