diff options
Diffstat (limited to 'gnu/llvm/libcxx/docs')
20 files changed, 3363 insertions, 0 deletions
diff --git a/gnu/llvm/libcxx/docs/BuildingLibcxx.rst b/gnu/llvm/libcxx/docs/BuildingLibcxx.rst new file mode 100644 index 00000000000..f2fff0e1f30 --- /dev/null +++ b/gnu/llvm/libcxx/docs/BuildingLibcxx.rst @@ -0,0 +1,549 @@ +.. _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 following instructions describe how to checkout, build, test and +(optionally) 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++. + +.. warning:: + * Replacing your systems libc++ installation could render the system non-functional. + * macOS will not boot without a valid copy of ``libc++.1.dylib`` in ``/usr/lib``. + +.. code-block:: bash + + $ git clone https://github.com/llvm/llvm-project.git + $ cd llvm-project + $ mkdir build && cd build + $ cmake -DCMAKE_C_COMPILER=clang \ + -DCMAKE_CXX_COMPILER=clang++ \ + -DLLVM_ENABLE_PROJECTS="libcxx;libcxxabi" \ + ../llvm + $ make # Build + $ make check-cxx # Test + $ make install-cxx install-cxxabi # Install + +For more information about configuring libc++ see :ref:`CMake Options`. You may +also want to read the `LLVM getting started +<https://llvm.org/docs/GettingStarted.html>`_ documentation. + +Shared libraries for libc++ and libc++ abi should now be present in +``build/lib``. See :ref:`using an alternate libc++ installation <alternate +libcxx>` for information on how to use this libc++. + +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 possible to keep your LLVM and libc++ trees separate so you can avoid +rebuilding LLVM as often. An out-of-tree build would look like this: + +.. code-block:: bash + + $ cd where-you-want-libcxx-to-live + $ # Check out the sources (includes everything, but we'll only use libcxx) + $ ``git clone https://github.com/llvm/llvm-project.git`` + $ cd where-you-want-to-build + $ mkdir build && cd build + $ export CC=clang CXX=clang++ + $ cmake -DLLVM_PATH=path/to/separate/llvm \ + -DLIBCXX_CXX_ABI=libcxxabi \ + -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/separate/libcxxabi/include \ + path/to/llvm-project/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 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 exporting any libc++ symbols in that case. + +.. option:: LIBCXX_ENABLE_FILESYSTEM:BOOL + + **Default**: ``ON`` except on Windows. + + This option can be used to enable or disable the filesystem components on + platforms that may not support them. For example on Windows. + +.. _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++. + + +.. _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_TESTS:BOOL + + **Default**: ``ON`` (or value of ``LLVM_INCLUDE_DIR``) + + Build the libc++ tests. + +.. 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. + + +.. option:: LIBCXX_HAS_MERGED_TYPEINFO_NAMES_DEFAULT + + **Default**: ``None``. When defined this option overrides the libraries default configuration + for whether merged type info names are present. + + + Build ``std::type_info`` with the assumption that type info names for a type have been fully + merged are unique across the entire program. This may not be the case for libraries built with + ``-Bsymbolic`` or due to compiler or linker bugs (Ex. llvm.org/PR37398). + + When the value is ``ON`` typeinfo comparisons compare only the pointer value, otherwise ``strcmp`` + is used as a fallback. + + +.. _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 need 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/gnu/llvm/libcxx/docs/CMakeLists.txt b/gnu/llvm/libcxx/docs/CMakeLists.txt new file mode 100644 index 00000000000..d679761a5ad --- /dev/null +++ b/gnu/llvm/libcxx/docs/CMakeLists.txt @@ -0,0 +1,9 @@ + +if (LLVM_ENABLE_SPHINX) + include(AddSphinxTarget) + if (SPHINX_FOUND) + if (${SPHINX_OUTPUT_HTML}) + add_sphinx_target(html libcxx) + endif() + endif() +endif() diff --git a/gnu/llvm/libcxx/docs/DesignDocs/ABIVersioning.rst b/gnu/llvm/libcxx/docs/DesignDocs/ABIVersioning.rst new file mode 100644 index 00000000000..5960dd18610 --- /dev/null +++ b/gnu/llvm/libcxx/docs/DesignDocs/ABIVersioning.rst @@ -0,0 +1,17 @@ + +==================== +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/gnu/llvm/libcxx/docs/DesignDocs/AvailabilityMarkup.rst b/gnu/llvm/libcxx/docs/DesignDocs/AvailabilityMarkup.rst new file mode 100644 index 00000000000..f076dfecdaa --- /dev/null +++ b/gnu/llvm/libcxx/docs/DesignDocs/AvailabilityMarkup.rst @@ -0,0 +1,105 @@ +=================== +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; + +Furthermore, a lit feature should be added to match that availability macro, +so that tests depending on that feature can be marked to XFAIL if the feature +is not supported. This way, the test suite will work on platforms that have +not shipped the feature yet. This can be done by adding the appropriate lit +feature in test/config.py. + + +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/gnu/llvm/libcxx/docs/DesignDocs/CapturingConfigInfo.rst b/gnu/llvm/libcxx/docs/DesignDocs/CapturingConfigInfo.rst new file mode 100644 index 00000000000..8f2d0cd2dd6 --- /dev/null +++ b/gnu/llvm/libcxx/docs/DesignDocs/CapturingConfigInfo.rst @@ -0,0 +1,86 @@ +======================================================= +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 + + //===----------------------------------------------------------------------===// + // + // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. + // See https://llvm.org/LICENSE.txt for license information. + // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception + // + //===----------------------------------------------------------------------===// + + #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 ---------------------------------===// + // + // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. + // See https://llvm.org/LICENSE.txt for license information. + // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception + // + //===----------------------------------------------------------------------===// + + #ifndef _LIBCPP_CONFIG + #define _LIBCPP_CONFIG diff --git a/gnu/llvm/libcxx/docs/DesignDocs/DebugMode.rst b/gnu/llvm/libcxx/docs/DesignDocs/DebugMode.rst new file mode 100644 index 00000000000..e4d4e5b2d90 --- /dev/null +++ b/gnu/llvm/libcxx/docs/DesignDocs/DebugMode.rst @@ -0,0 +1,91 @@ +========== +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; but it does have broad + ODR implications. Users should compile their whole program at the same + debugging level. + +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 a +the default handler, ``std::__libcpp_abort_debug_handler``, which aborts the +program. The handler may not return. Libc++ can be changed to use a custom +assertion handler as follows. + +.. code-block:: cpp + + #define _LIBCPP_DEBUG 1 + #include <string> + void my_handler(std::__libcpp_debug_info const&); + int main(int, char**) { + std::__libcpp_debug_function = &my_handler; + + std::string::iterator bad_it; + std::string str("hello world"); + str.insert(bad_it, '!'); // causes debug assertion + // control flow doesn't return + } + +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/gnu/llvm/libcxx/docs/DesignDocs/ExperimentalFeatures.rst b/gnu/llvm/libcxx/docs/DesignDocs/ExperimentalFeatures.rst new file mode 100644 index 00000000000..2241496d594 --- /dev/null +++ b/gnu/llvm/libcxx/docs/DesignDocs/ExperimentalFeatures.rst @@ -0,0 +1,203 @@ +===================== +Experimental Features +===================== + +.. contents:: + :local: + +.. _experimental features: + +Overview +======== + +Libc++ implements technical specifications (TSes) and ships them as experimental +features that users are free to try out. The goal is to allow getting feedback +on those experimental features. + +However, libc++ does not provide the same guarantees about those features as +it does for the rest of the library. In particular, no ABI or API stability +is guaranteed, and experimental features are deprecated once the non-experimental +equivalent has shipped in the library. This document outlines the details of +that process. + +Background +========== + +The "end game" of a Technical Specification (TS) is to have the features in +there added to a future version of the C++ Standard. When this happens, the TS +can be retired. Sometimes, only part of at TS is added to the standard, and +the rest of the features may be incorporated into the next version of the TS. + +Adoption leaves library implementors with two implementations of a feature, +one in namespace ``std``, and the other in namespace ``std::experimental``. +The first one will continue to evolve (via issues and papers), while the other +will not. Gradually they will diverge. It's not good for users to have two +(subtly) different implementations of the same functionality in the same library. + +Design +====== + +When a feature is adopted into the main standard, we implement it in namespace +``std``. Once that implementation is complete, we then create a deprecation +warning for the corresponding experimental feature warning users to move off +of it and to the now-standardized feature. + +These deprecation warnings are guarded by a macro of the form +``_LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_<FEATURE>``, which +can be defined by users to disable the deprecation warning. Whenever +possible, deprecation warnings are put on a per-declaration basis +using the ``[[deprecated]]`` attribute, which also allows disabling +the warnings using ``-Wno-deprecated-declarations``. + +After **2 releases** of LLVM, the experimental feature is removed completely +(and the deprecation notice too). Using the experimental feature simply becomes +an error. Furthermore, when an experimental header becomes empty due to the +removal of the corresponding experimental feature, the header is removed. +Keeping the header around creates incorrect assumptions from users and breaks +``__has_include``. + + +Status of TSes +============== + +Library Fundamentals TS `V1 <https://wg21.link/N4480>`__ and `V2 <https://wg21.link/N4617>`__ +--------------------------------------------------------------------------------------------- + +Most (but not all) of the features of the LFTS were accepted into C++17. + ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| Section | Feature | Shipped in ``std`` | To be removed from ``std::experimental`` | Notes | ++=========+=======================================================+====================+==========================================+=========================+ +| 2.1 | ``uses_allocator construction`` | 5.0 | 7.0 | | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 3.1.2 | ``erased_type`` | | n/a | Not part of C++17 | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 3.2.1 | ``tuple_size_v`` | 5.0 | 7.0 | Removed | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 3.2.2 | ``apply`` | 5.0 | 7.0 | Removed | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 3.3.1 | All of the ``_v`` traits in ``<type_traits>`` | 5.0 | 7.0 | Removed | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 3.3.2 | ``invocation_type`` and ``raw_invocation_type`` | | n/a | Not part of C++17 | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 3.3.3 | Logical operator traits | 5.0 | 7.0 | Removed | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 3.3.3 | Detection Idiom | 5.0 | | Only partially in C++17 | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 3.4.1 | All of the ``_v`` traits in ``<ratio>`` | 5.0 | 7.0 | Removed | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 3.5.1 | All of the ``_v`` traits in ``<chrono>`` | 5.0 | 7.0 | Removed | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 3.6.1 | All of the ``_v`` traits in ``<system_error>`` | 5.0 | 7.0 | Removed | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 3.7 | ``propagate_const`` | | n/a | Not part of C++17 | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 4.2 | Enhancements to ``function`` | Not yet | | | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 4.3 | searchers | 7.0 | 9.0 | | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 5 | optional | 5.0 | 7.0 | Removed | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 6 | ``any`` | 5.0 | 7.0 | Removed | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 7 | ``string_view`` | 5.0 | 7.0 | Removed | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 8.2.1 | ``shared_ptr`` enhancements | Not yet | Never added | | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 8.2.2 | ``weak_ptr`` enhancements | Not yet | Never added | | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 8.5 | ``memory_resource`` | Not yet | | | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 8.6 | ``polymorphic_allocator`` | Not yet | | | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 8.7 | ``resource_adaptor`` | | n/a | Not part of C++17 | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 8.8 | Access to program-wide ``memory_resource`` objects | Not yet | | | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 8.9 | Pool resource classes | Not yet | | | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 8.10 | ``monotonic_buffer_resource`` | Not yet | | | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 8.11 | Alias templates using polymorphic memory resources | Not yet | | | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 8.12 | Non-owning pointers | | n/a | Not part of C++17 | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 11.2 | ``promise`` | | n/a | Not part of C++17 | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 11.3 | ``packaged_task`` | | n/a | Not part of C++17 | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 12.2 | ``search`` | 7.0 | 9.0 | | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 12.3 | ``sample`` | 5.0 | 7.0 | Removed | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 12.4 | ``shuffle`` | | | Not part of C++17 | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 13.1 | ``gcd`` and ``lcm`` | 5.0 | 7.0 | Removed | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 13.2 | Random number generation | | | Not part of C++17 | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +| 14 | Reflection Library | | | Not part of C++17 | ++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ + + +`FileSystem TS <https://wg21.link/N4100>`__ +------------------------------------------- +The FileSystem TS was accepted (in totality) for C++17. +The FileSystem TS implementation was shipped in namespace ``std`` in LLVM 7.0, and will be removed in LLVM 11.0 (due to the lack of deprecation warnings before LLVM 9.0). + +Parallelism TS `V1 <https://wg21.link/N4507>`__ and `V2 <https://wg21.link/N4706>`__ +------------------------------------------------------------------------------------ +Some (most) of the Parallelism TS was accepted for C++17. +We have not yet shipped an implementation of the Parallelism TS. + +`Coroutines TS <https://wg21.link/N4680>`__ +------------------------------------------- +The Coroutines TS is not yet part of a shipping standard. +We are shipping (as of v5.0) an implementation of the Coroutines TS in namespace ``std::experimental``. + +`Networking TS <https://wg21.link/N4656>`__ +------------------------------------------- +The Networking TS is not yet part of a shipping standard. +We have not yet shipped an implementation of the Networking TS. + +`Ranges TS <https://wg21.link/N4685>`__ +--------------------------------------- +The Ranges TS is not yet part of a shipping standard. +We have not yet shipped an implementation of the Ranges TS. + +`Concepts TS <https://wg21.link/N4641>`__ +----------------------------------------- +The Concepts TS is not yet part of a shipping standard, but it has been adopted into the C++20 working draft. +We have not yet shipped an implementation of the Concepts TS. + +`Concurrency TS <https://wg21.link/P0159>`__ +-------------------------------------------- +The Concurrency TS was adopted in Kona (2015). +None of the Concurrency TS was accepted for C++17. +We have not yet shipped an implementation of the Concurrency TS. + +.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +.. | Section | Feature | Shipped in ``std`` | To be removed from ``std::experimental`` | Notes | +.. +=========+=======================================================+====================+==========================================+=========================+ +.. | 2.3 | class template ``future`` | | | | +.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +.. | 2.4 | class template ``shared_future`` | | | | +.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +.. | 2.5 | class template ``promise`` | | | Only using ``future`` | +.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +.. | 2.6 | class template ``packaged_task`` | | | Only using ``future`` | +.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +.. | 2.7 | function template ``when_all`` | | | Not part of C++17 | +.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +.. | 2.8 | class template ``when_any_result`` | | | Not part of C++17 | +.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +.. | 2.9 | function template ``when_any`` | | | Not part of C++17 | +.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +.. | 2.10 | function template ``make_ready_future`` | | | Not part of C++17 | +.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +.. | 2.11 | function template ``make_exeptional_future`` | | | Not part of C++17 | +.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +.. | 3 | ``latches`` and ``barriers`` | | | Not part of C++17 | +.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ +.. | 4 | Atomic Smart Pointers | | | Adopted for C++20 | +.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ diff --git a/gnu/llvm/libcxx/docs/DesignDocs/ExtendedCXX03Support.rst b/gnu/llvm/libcxx/docs/DesignDocs/ExtendedCXX03Support.rst new file mode 100644 index 00000000000..e9e3fc4d230 --- /dev/null +++ b/gnu/llvm/libcxx/docs/DesignDocs/ExtendedCXX03Support.rst @@ -0,0 +1,118 @@ +======================= +Extended C++03 Support +======================= + +.. contents:: + :local: + +Overview +======== + +libc++ is an implementation of the C++ standard library targeting C++11 or later. + +In C++03, the library implements the C++11 standard using C++11 language extensions provided +by Clang. + +This document tracks the C++11 extensions libc++ requires, the C++11 extensions it provides, +and how to write minimal C++11 inside libc++. + +Required C++11 Compiler Extensions +================================== + +Clang provides a large subset of C++11 in C++03 as an extension. The features +libc++ expects Clang to provide are: + +* Variadic templates. +* RValue references and perfect forwarding. +* Alias templates +* defaulted and deleted Functions. +* reference qualified Functions + +There are also features that Clang *does not* provide as an extension in C++03 +mode. These include: + +* ``constexpr`` and ``noexcept`` +* ``auto`` +* Trailing return types. +* ``>>`` without a space. + + +Provided C++11 Library Extensions +================================= + +.. warning:: + The C++11 extensions libc++ provides in C++03 are currently undergoing change. Existing extensions + may be removed in the future. New users are strongly discouraged depending on these extension + in new code. + + This section will be updated once the libc++ developer community has further discussed the + future of C++03 with libc++. + + +Using Minimal C++11 in libc++ +============================= + +This section is for developers submitting patches to libc++. It describes idioms that should be +used in libc++ code, even in C++03, and the reasons behind them. + + +Use Alias Templates over Class Templates +---------------------------------------- + +Alias templates should be used instead of class templates in metaprogramming. Unlike class templates, +Alias templates do not produce a new instantiation every time they are used. This significantly +decreases the amount of memory used by the compiler. + +For example, libc++ should not use ``add_const`` internally. Instead it should use an alias template +like + +.. code-block:: cpp + + template <class _Tp> + using _AddConst = const _Tp; + +Use Default Template Parameters for SFINAE +------------------------------------------ + +There are three places in a function declaration that SFINAE may occur: In the template parameter list, +in the function parameter list, and in the return type. For example: + +.. code-block:: cpp + + template <class _Tp, class _ = enable_if_t</*...*/ > + void foo(_Tp); // #1 + + template <class _Tp> + void bar(_Tp, enable_if_t</*...*/>* = nullptr); // # 2 + + template <class _Tp> + enable_if_t</*...*/> baz(_Tp); // # 3 + +Using default template parameters for SFINAE (#1) should always be prefered. + +Option #2 has two problems. First, users can observe and accidentally pass values to the SFINAE +function argument. Second, the default arguement creates a live variable, which causes debug +information to be emitted containing the text of the SFINAE. + +Option #3 can also cause more debug information to be emitted than is needed, because the function +return type will appear in the debug information. + +Use ``unique_ptr`` when allocating memory +------------------------------------------ + +The standard library often needs to allocate memory and then construct a user type in it. +If the users constructor throws, the library needs to deallocate that memory. The idiomatic way to +achieve this is with ``unique_ptr``. + +``__builtin_new_allocator`` is an example of this idiom. Example usage would look like: + +.. code-block:: cpp + + template <class T> + T* __create() { + using _UniquePtr = unique_ptr<void*, __default_new_allocator::__default_new_deleter>; + _UniquePtr __p = __default_new_allocator::__allocate_bytes(sizeof(T), alignof(T)); + T* __res = ::new(__p.get()) T(); + (void)__p.release(); + return __res; + } diff --git a/gnu/llvm/libcxx/docs/DesignDocs/FeatureTestMacros.rst b/gnu/llvm/libcxx/docs/DesignDocs/FeatureTestMacros.rst new file mode 100644 index 00000000000..2fbba6547bb --- /dev/null +++ b/gnu/llvm/libcxx/docs/DesignDocs/FeatureTestMacros.rst @@ -0,0 +1,45 @@ +=================== +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/utils/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. diff --git a/gnu/llvm/libcxx/docs/DesignDocs/FileTimeType.rst b/gnu/llvm/libcxx/docs/DesignDocs/FileTimeType.rst new file mode 100644 index 00000000000..f1e9edd8735 --- /dev/null +++ b/gnu/llvm/libcxx/docs/DesignDocs/FileTimeType.rst @@ -0,0 +1,495 @@ +============== +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(int, char**) { + 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. + return 0; + } + + +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/gnu/llvm/libcxx/docs/DesignDocs/ThreadingSupportAPI.rst b/gnu/llvm/libcxx/docs/DesignDocs/ThreadingSupportAPI.rst new file mode 100644 index 00000000000..330ce74cf77 --- /dev/null +++ b/gnu/llvm/libcxx/docs/DesignDocs/ThreadingSupportAPI.rst @@ -0,0 +1,83 @@ +===================== +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/gnu/llvm/libcxx/docs/DesignDocs/VisibilityMacros.rst b/gnu/llvm/libcxx/docs/DesignDocs/VisibilityMacros.rst new file mode 100644 index 00000000000..d0d4f0adb22 --- /dev/null +++ b/gnu/llvm/libcxx/docs/DesignDocs/VisibilityMacros.rst @@ -0,0 +1,218 @@ +======================== +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/gnu/llvm/libcxx/docs/FeatureTestMacroTable.rst b/gnu/llvm/libcxx/docs/FeatureTestMacroTable.rst new file mode 100644 index 00000000000..3dd00fabf62 --- /dev/null +++ b/gnu/llvm/libcxx/docs/FeatureTestMacroTable.rst @@ -0,0 +1,204 @@ +.. _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`` ``201806L`` + ------------------------------------------------- ----------------- + ``__cpp_lib_endian`` ``201907L`` + ------------------------------------------------- ----------------- + ``__cpp_lib_erase_if`` ``201811L`` + ------------------------------------------------- ----------------- + ``__cpp_lib_generic_unordered_lookup`` *unimplemented* + ------------------------------------------------- ----------------- + ``__cpp_lib_interpolate`` ``201902L`` + ------------------------------------------------- ----------------- + ``__cpp_lib_is_constant_evaluated`` ``201811L`` + ------------------------------------------------- ----------------- + ``__cpp_lib_list_remove_return_type`` *unimplemented* + ------------------------------------------------- ----------------- + ``__cpp_lib_ranges`` *unimplemented* + ------------------------------------------------- ----------------- + ``__cpp_lib_three_way_comparison`` *unimplemented* + ================================================= ================= + + diff --git a/gnu/llvm/libcxx/docs/Makefile.sphinx b/gnu/llvm/libcxx/docs/Makefile.sphinx new file mode 100644 index 00000000000..a34f0cc0bad --- /dev/null +++ b/gnu/llvm/libcxx/docs/Makefile.sphinx @@ -0,0 +1,37 @@ +# 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/gnu/llvm/libcxx/docs/README.txt b/gnu/llvm/libcxx/docs/README.txt new file mode 100644 index 00000000000..06d94f5b5fc --- /dev/null +++ b/gnu/llvm/libcxx/docs/README.txt @@ -0,0 +1,13 @@ +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/gnu/llvm/libcxx/docs/ReleaseNotes.rst b/gnu/llvm/libcxx/docs/ReleaseNotes.rst new file mode 100644 index 00000000000..f57c915a445 --- /dev/null +++ b/gnu/llvm/libcxx/docs/ReleaseNotes.rst @@ -0,0 +1,30 @@ +=========================== +Libc++ 10.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 10.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://llvm.org/releases/>`_. + +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++ 10.0.0? +============================ + +Fixes +----- + +- Fixed use of non-default locales on Windows diff --git a/gnu/llvm/libcxx/docs/TestingLibcxx.rst b/gnu/llvm/libcxx/docs/TestingLibcxx.rst new file mode 100644 index 00000000000..eaba214390d --- /dev/null +++ b/gnu/llvm/libcxx/docs/TestingLibcxx.rst @@ -0,0 +1,268 @@ +============== +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. + +.. option:: llvm_unwinder + + Enable the use of LLVM unwinder instead of libgcc. + +.. option:: builtins_library + + Path to the builtins library to use instead of libgcc. + + +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/gnu/llvm/libcxx/docs/UsingLibcxx.rst b/gnu/llvm/libcxx/docs/UsingLibcxx.rst new file mode 100644 index 00000000000..05721bf271a --- /dev/null +++ b/gnu/llvm/libcxx/docs/UsingLibcxx.rst @@ -0,0 +1,348 @@ +============ +Using libc++ +============ + +.. contents:: + :local: + +Getting Started +=============== + +If you already have libc++ installed you can use it with clang. + +.. code-block:: bash + + $ clang++ -stdlib=libc++ test.cpp + $ clang++ -std=c++11 -stdlib=libc++ test.cpp + +On macOS and FreeBSD libc++ is the default standard library +and the ``-stdlib=libc++`` is not required. + +.. _alternate libcxx: + +If you want to select an alternate installation of libc++ you +can use the following options. + +.. code-block:: bash + + $ clang++ -std=c++11 -stdlib=libc++ -nostdinc++ \ + -I<libcxx-install-prefix>/include/c++/v1 \ + -L<libcxx-install-prefix>/lib \ + -Wl,-rpath,<libcxx-install-prefix>/lib \ + test.cpp + +The option ``-Wl,-rpath,<libcxx-install-prefix>/lib`` adds a runtime library +search path. Meaning that the systems dynamic linker will look for libc++ in +``<libcxx-install-prefix>/lib`` whenever the program is run. Alternatively the +environment variable ``LD_LIBRARY_PATH`` (``DYLD_LIBRARY_PATH`` on macOS) can +be used to change the dynamic linkers search paths after a program is compiled. + +An example of using ``LD_LIBRARY_PATH``: + +.. code-block:: bash + + $ clang++ -stdlib=libc++ -nostdinc++ \ + -I<libcxx-install-prefix>/include/c++/v1 + -L<libcxx-install-prefix>/lib \ + test.cpp -o + $ ./a.out # Searches for libc++ in the systems library paths. + $ export LD_LIBRARY_PATH=<libcxx-install-prefix>/lib + $ ./a.out # Searches for libc++ along LD_LIBRARY_PATH + +Using ``<filesystem>`` +====================== + +Prior to LLVM 9.0, libc++ provides the implementation of the filesystem library +in a separate static library. Users of ``<filesystem>`` and ``<experimental/filesystem>`` +are required to link ``-lc++fs``. Prior to libc++ 7.0, users of +``<experimental/filesystem>`` were required to link libc++experimental. + +Starting with LLVM 9.0, support for ``<filesystem>`` is provided in the main +library and nothing special is required to use ``<filesystem>``. + +Using libc++experimental and ``<experimental/...>`` +===================================================== + +Libc++ provides implementations of experimental technical specifications +in a separate library, ``libc++experimental.a``. Users of ``<experimental/...>`` +headers may be required to link ``-lc++experimental``. + +.. code-block:: bash + + $ clang++ -std=c++14 -stdlib=libc++ test.cpp -lc++experimental + +Libc++experimental.a may not always be available, even when libc++ is already +installed. For information on building libc++experimental from source see +:ref:`Building Libc++ <build instructions>` and +:ref:`libc++experimental CMake Options <libc++experimental options>`. + +Also see the `Experimental Library Implementation Status <http://libcxx.llvm.org/ts1z_status.html>`__ +page. + +.. warning:: + Experimental libraries are Experimental. + * The contents of the ``<experimental/...>`` headers and ``libc++experimental.a`` + library will not remain compatible between versions. + * No guarantees of API or ABI stability are provided. + * When we implement the standardized version of an experimental feature, + the experimental feature is removed two releases after the non-experimental + version has shipped. The full policy is explained :ref:`here <experimental features>`. + +Using libc++ on Linux +===================== + +On Linux libc++ can typically be used with only '-stdlib=libc++'. However +some libc++ installations require the user manually link libc++abi themselves. +If you are running into linker errors when using libc++ try adding '-lc++abi' +to the link line. For example: + +.. code-block:: bash + + $ clang++ -stdlib=libc++ test.cpp -lc++ -lc++abi -lm -lc -lgcc_s -lgcc + +Alternately, you could just add libc++abi to your libraries list, which in +most situations will give the same result: + +.. code-block:: bash + + $ clang++ -stdlib=libc++ test.cpp -lc++abi + + +Using libc++ with GCC +--------------------- + +GCC does not provide a way to switch from libstdc++ to libc++. You must manually +configure the compile and link commands. + +In particular you must tell GCC to remove the libstdc++ include directories +using ``-nostdinc++`` and to not link libstdc++.so using ``-nodefaultlibs``. + +Note that ``-nodefaultlibs`` removes all of the standard system libraries and +not just libstdc++ so they must be manually linked. For example: + +.. code-block:: bash + + $ g++ -nostdinc++ -I<libcxx-install-prefix>/include/c++/v1 \ + test.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc + + +GDB Pretty printers for libc++ +------------------------------ + +GDB does not support pretty-printing of libc++ symbols by default. Unfortunately +libc++ does not provide pretty-printers itself. However there are 3rd +party implementations available and although they are not officially +supported by libc++ they may be useful to users. + +Known 3rd Party Implementations Include: + +* `Koutheir's libc++ pretty-printers <https://github.com/koutheir/libcxx-pretty-printers>`_. + + +Libc++ Configuration Macros +=========================== + +Libc++ provides a number of configuration macros which can be used to enable +or disable extended libc++ behavior, including enabling "debug mode" or +thread safety annotations. + +**_LIBCPP_DEBUG**: + See :ref:`using-debug-mode` for more information. + +**_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS**: + This macro is used to enable -Wthread-safety annotations on libc++'s + ``std::mutex`` and ``std::lock_guard``. By default these annotations are + disabled and must be manually enabled by the user. + +**_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**: + This macro is used to disable all visibility annotations inside libc++. + Defining this macro and then building libc++ with hidden visibility gives a + build of libc++ which does not export any symbols, which can be useful when + building statically for inclusion into another library. + +**_LIBCPP_DISABLE_EXTERN_TEMPLATE**: + This macro is used to disable extern template declarations in the libc++ + headers. The intended use case is for clients who wish to use the libc++ + headers without taking a dependency on the libc++ library itself. + +**_LIBCPP_ENABLE_TUPLE_IMPLICIT_REDUCED_ARITY_EXTENSION**: + This macro is used to re-enable an extension in `std::tuple` which allowed + it to be implicitly constructed from fewer initializers than contained + elements. Elements without an initializer are default constructed. For example: + + .. code-block:: cpp + + std::tuple<std::string, int, std::error_code> foo() { + return {"hello world", 42}; // default constructs error_code + } + + + Since libc++ 4.0 this extension has been disabled by default. This macro + may be defined to re-enable it in order to support existing code that depends + on the extension. New use of this extension should be discouraged. + See `PR 27374 <http://llvm.org/PR27374>`_ for more information. + + Note: The "reduced-arity-initialization" extension is still offered but only + for explicit conversions. Example: + + .. code-block:: cpp + + auto foo() { + using Tup = std::tuple<std::string, int, std::error_code>; + return Tup{"hello world", 42}; // explicit constructor called. OK. + } + +**_LIBCPP_DISABLE_ADDITIONAL_DIAGNOSTICS**: + This macro disables the additional diagnostics generated by libc++ using the + `diagnose_if` attribute. These additional diagnostics include checks for: + + * Giving `set`, `map`, `multiset`, `multimap` and their `unordered_` + counterparts a comparator which is not const callable. + * Giving an unordered associative container a hasher that is not const + callable. + +**_LIBCPP_NO_VCRUNTIME**: + Microsoft's C and C++ headers are fairly entangled, and some of their C++ + headers are fairly hard to avoid. In particular, `vcruntime_new.h` gets pulled + in from a lot of other headers and provides definitions which clash with + libc++ headers, such as `nothrow_t` (note that `nothrow_t` is a struct, so + there's no way for libc++ to provide a compatible definition, since you can't + have multiple definitions). + + By default, libc++ solves this problem by deferring to Microsoft's vcruntime + headers where needed. However, it may be undesirable to depend on vcruntime + headers, since they may not always be available in cross-compilation setups, + or they may clash with other headers. The `_LIBCPP_NO_VCRUNTIME` macro + prevents libc++ from depending on vcruntime headers. Consequently, it also + prevents libc++ headers from being interoperable with vcruntime headers (from + the aforementioned clashes), so users of this macro are promising to not + attempt to combine libc++ headers with the problematic vcruntime headers. This + macro also currently prevents certain `operator new`/`operator delete` + replacement scenarios from working, e.g. replacing `operator new` and + expecting a non-replaced `operator new[]` to call the replaced `operator new`. + +**_LIBCPP_ENABLE_NODISCARD**: + Allow the library to add ``[[nodiscard]]`` attributes to entities not specified + as ``[[nodiscard]]`` by the current language dialect. This includes + backporting applications of ``[[nodiscard]]`` from newer dialects and + additional extended applications at the discretion of the library. All + additional applications of ``[[nodiscard]]`` are disabled by default. + See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` for + more information. + +**_LIBCPP_DISABLE_NODISCARD_EXT**: + This macro prevents the library from applying ``[[nodiscard]]`` to entities + purely as an extension. See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` + for more information. + +**_LIBCPP_DISABLE_DEPRECATION_WARNINGS**: + This macro disables warnings when using deprecated components. For example, + using `std::auto_ptr` when compiling in C++11 mode will normally trigger a + warning saying that `std::auto_ptr` is deprecated. If the macro is defined, + no warning will be emitted. By default, this macro is not defined. + +C++17 Specific Configuration Macros +----------------------------------- +**_LIBCPP_ENABLE_CXX17_REMOVED_FEATURES**: + This macro is used to re-enable all the features removed in C++17. The effect + is equivalent to manually defining each macro listed below. + +**_LIBCPP_ENABLE_CXX17_REMOVED_UNEXPECTED_FUNCTIONS**: + This macro is used to re-enable the `set_unexpected`, `get_unexpected`, and + `unexpected` functions, which were removed in C++17. + +**_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**: + This macro is used to re-enable `std::auto_ptr` in C++17. + +C++2a Specific Configuration Macros: +------------------------------------ +**_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17**: + This macro can be used to disable diagnostics emitted from functions marked + ``[[nodiscard]]`` in dialects after C++17. See :ref:`Extended Applications of [[nodiscard]] <nodiscard extension>` + for more information. + + +Libc++ Extensions +================= + +This section documents various extensions provided by libc++, how they're +provided, and any information regarding how to use them. + +.. _nodiscard extension: + +Extended applications of ``[[nodiscard]]`` +------------------------------------------ + +The ``[[nodiscard]]`` attribute is intended to help users find bugs where +function return values are ignored when they shouldn't be. After C++17 the +C++ standard has started to declared such library functions as ``[[nodiscard]]``. +However, this application is limited and applies only to dialects after C++17. +Users who want help diagnosing misuses of STL functions may desire a more +liberal application of ``[[nodiscard]]``. + +For this reason libc++ provides an extension that does just that! The +extension must be enabled by defining ``_LIBCPP_ENABLE_NODISCARD``. The extended +applications of ``[[nodiscard]]`` takes two forms: + +1. Backporting ``[[nodiscard]]`` to entities declared as such by the + standard in newer dialects, but not in the present one. + +2. Extended applications of ``[[nodiscard]]``, at the libraries discretion, + applied to entities never declared as such by the standard. + +Users may also opt-out of additional applications ``[[nodiscard]]`` using +additional macros. + +Applications of the first form, which backport ``[[nodiscard]]`` from a newer +dialect may be disabled using macros specific to the dialect it was added. For +example ``_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17``. + +Applications of the second form, which are pure extensions, may be disabled +by defining ``_LIBCPP_DISABLE_NODISCARD_EXT``. + + +Entities declared with ``_LIBCPP_NODISCARD_EXT`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section lists all extended applications of ``[[nodiscard]]`` to entities +which no dialect declares as such (See the second form described above). + +* ``adjacent_find`` +* ``all_of`` +* ``any_of`` +* ``binary_search`` +* ``clamp`` +* ``count_if`` +* ``count`` +* ``equal_range`` +* ``equal`` +* ``find_end`` +* ``find_first_of`` +* ``find_if_not`` +* ``find_if`` +* ``find`` +* ``get_temporary_buffer`` +* ``includes`` +* ``is_heap_until`` +* ``is_heap`` +* ``is_partitioned`` +* ``is_permutation`` +* ``is_sorted_until`` +* ``is_sorted`` +* ``lexicographical_compare`` +* ``lower_bound`` +* ``max_element`` +* ``max`` +* ``min_element`` +* ``min`` +* ``minmax_element`` +* ``minmax`` +* ``mismatch`` +* ``none_of`` +* ``remove_if`` +* ``remove`` +* ``search_n`` +* ``search`` +* ``unique`` +* ``upper_bound`` +* ``lock_guard``'s constructors diff --git a/gnu/llvm/libcxx/docs/conf.py b/gnu/llvm/libcxx/docs/conf.py new file mode 100644 index 00000000000..414f1bc3cc8 --- /dev/null +++ b/gnu/llvm/libcxx/docs/conf.py @@ -0,0 +1,251 @@ +# -*- 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 = '10.0' +# The full version, including alpha/beta/rc tags. +release = '10.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/gnu/llvm/libcxx/docs/index.rst b/gnu/llvm/libcxx/docs/index.rst new file mode 100644 index 00000000000..04df9cfcc4a --- /dev/null +++ b/gnu/llvm/libcxx/docs/index.rst @@ -0,0 +1,193 @@ +.. _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 +============ ==================== ============ ======================== +macOS 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 5.0 and above. + +The C++03 dialect is only supported for Clang compilers. + +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. + + +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/ExperimentalFeatures + DesignDocs/VisibilityMacros + DesignDocs/ThreadingSupportAPI + DesignDocs/FileTimeType + DesignDocs/FeatureTestMacros + DesignDocs/ExtendedCXX03Support + +* `<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++ Sources <https://github.com/llvm/llvm-project/tree/master/libcxx/>`_ |