diff options
Diffstat (limited to 'lib/libcxx/docs')
| -rw-r--r-- | lib/libcxx/docs/BuildingLibcxx.rst | 416 | ||||
| -rw-r--r-- | lib/libcxx/docs/CMakeLists.txt | 9 | ||||
| -rw-r--r-- | lib/libcxx/docs/DesignDocs/ABIVersioning.rst | 17 | ||||
| -rw-r--r-- | lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst | 88 | ||||
| -rw-r--r-- | lib/libcxx/docs/Makefile.sphinx | 37 | ||||
| -rw-r--r-- | lib/libcxx/docs/README.txt | 13 | ||||
| -rw-r--r-- | lib/libcxx/docs/TestingLibcxx.rst | 200 | ||||
| -rw-r--r-- | lib/libcxx/docs/UsingLibcxx.rst | 125 | ||||
| -rw-r--r-- | lib/libcxx/docs/conf.py | 251 | ||||
| -rw-r--r-- | lib/libcxx/docs/index.rst | 185 |
10 files changed, 1341 insertions, 0 deletions
diff --git a/lib/libcxx/docs/BuildingLibcxx.rst b/lib/libcxx/docs/BuildingLibcxx.rst new file mode 100644 index 00000000000..36866b13ef7 --- /dev/null +++ b/lib/libcxx/docs/BuildingLibcxx.rst @@ -0,0 +1,416 @@ +.. _BuildingLibcxx: + +=============== +Building libc++ +=============== + +.. contents:: + :local: + +.. _build instructions: + +Getting Started +=============== + +On Mac OS 10.7 (Lion) and later, the easiest way to get this library is to install +Xcode 4.2 or later. However if you want to install tip-of-trunk from here +(getting the bleeding edge), read on. + +The basic steps needed to build libc++ are: + +#. Checkout LLVM: + + * ``cd where-you-want-llvm-to-live`` + * ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm`` + +#. Checkout libc++: + + * ``cd where-you-want-llvm-to-live`` + * ``cd llvm/projects`` + * ``svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx`` + +#. Checkout libc++abi: + + * ``cd where-you-want-llvm-to-live`` + * ``cd llvm/projects`` + * ``svn co http://llvm.org/svn/llvm-project/libcxxabi/trunk libcxxabi`` + +#. Configure and build libc++ with libc++abi: + + CMake is the only supported configuration system. + + Clang is the preferred compiler when building and using libc++. + + * ``cd where you want to build llvm`` + * ``mkdir build`` + * ``cd build`` + * ``cmake -G <generator> [options] <path to llvm sources>`` + + For more information about configuring libc++ see :ref:`CMake Options`. + + * ``make cxx`` --- will build libc++ and libc++abi. + * ``make check-libcxx check-libcxxabi`` --- will run the test suites. + + Shared libraries for libc++ and libc++ abi should now be present in llvm/build/lib. + See :ref:`using an alternate libc++ installation <alternate libcxx>` + +#. **Optional**: Install libc++ and libc++abi + + If your system already provides a libc++ installation it is important to be + careful not to replace it. Remember Use the CMake option ``CMAKE_INSTALL_PREFIX`` to + select a safe place to install libc++. + + * ``make install-libcxx install-libcxxabi`` --- Will install the libraries and the headers + + .. warning:: + * Replacing your systems libc++ installation could render the system non-functional. + * Mac OS X will not boot without a valid copy of ``libc++.1.dylib`` in ``/usr/lib``. + + +The instructions are for building libc++ on +FreeBSD, Linux, or Mac using `libc++abi`_ as the C++ ABI library. +On Linux, it is also possible to use :ref:`libsupc++ <libsupcxx>` or libcxxrt. + +It is sometimes beneficial to build outside of the LLVM tree. An out-of-tree +build would look like this: + +.. code-block:: bash + + $ cd where-you-want-libcxx-to-live + $ # Check out llvm, libc++ and libc++abi. + $ ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm`` + $ ``svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx`` + $ ``svn co http://llvm.org/svn/llvm-project/libcxxabi/trunk libcxxabi`` + $ cd where-you-want-to-build + $ mkdir build && cd build + $ export CC=clang CXX=clang++ + $ cmake -DLLVM_PATH=path/to/llvm \ + -DLIBCXX_CXX_ABI=libcxxabi \ + -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxabi/include \ + path/to/libcxx + $ make + $ make check-libcxx # optional + + +.. _`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 :option:`LLVM_BUILD_32_BITS`. + +.. option:: LIBCXX_ENABLE_SHARED:BOOL + + **Default**: ``ON`` + + Build libc++ as a shared library. If ``OFF`` is specified then libc++ is + built as a static library. + +.. option:: LIBCXX_LIBDIR_SUFFIX:STRING + + Extra suffix to append to the directory where libraries are to be installed. + This option overrides :option:`LLVM_LIBDIR_SUFFIX`. + + +.. _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**: ``OFF`` + + Install libc++experimental.a alongside libc++. + + +.. option:: LIBCXX_ENABLE_FILESYSTEM:BOOL + + **Default**: ``LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY`` + + Build filesystem as part of libc++experimental.a. This allows filesystem + to be disabled without turning off the entire experimental library. + + +.. _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. + + +libc++ 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. + +.. _LLVM-specific variables: + +LLVM-specific options +--------------------- + +.. option:: LLVM_LIBDIR_SUFFIX:STRING + + Extra suffix to append to the directory where libraries are to be + installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64`` + to install libraries to ``/usr/lib64``. + +.. option:: LLVM_BUILD_32_BITS:BOOL + + Build 32-bits executables and libraries on 64-bits systems. This option is + available only on some 64-bits unix systems. Defaults to OFF. + +.. option:: LLVM_LIT_ARGS:STRING + + Arguments given to lit. ``make check`` and ``make clang-test`` are affected. + By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on + others. + + +Using Alternate ABI libraries +============================= + + +.. _libsupcxx: + +Using libsupc++ on Linux +------------------------ + +You will need libstdc++ in order to provide libsupc++. + +Figure out where the libsupc++ headers are on your system. On Ubuntu this +is ``/usr/include/c++/<version>`` and ``/usr/include/c++/<version>/<target-triple>`` + +You can also figure this out by running + +.. code-block:: bash + + $ echo | g++ -Wp,-v -x c++ - -fsyntax-only + ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu" + ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include" + #include "..." search starts here: + #include <...> search starts here: + /usr/include/c++/4.7 + /usr/include/c++/4.7/x86_64-linux-gnu + /usr/include/c++/4.7/backward + /usr/lib/gcc/x86_64-linux-gnu/4.7/include + /usr/local/include + /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed + /usr/include/x86_64-linux-gnu + /usr/include + End of search list. + +Note that the first two entries happen to be what we are looking for. This +may not be correct on other platforms. + +We can now run CMake: + +.. code-block:: bash + + $ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \ + -DLIBCXX_CXX_ABI=libstdc++ \ + -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/" \ + -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr \ + <libc++-source-dir> + + +You can also substitute ``-DLIBCXX_CXX_ABI=libsupc++`` +above, which will cause the library to be linked to libsupc++ instead +of libstdc++, but this is only recommended if you know that you will +never need to link against libstdc++ in the same executable as libc++. +GCC ships libsupc++ separately but only as a static library. If a +program also needs to link against libstdc++, it will provide its +own copy of libsupc++ and this can lead to subtle problems. + +.. code-block:: bash + + $ make cxx + $ make install + +You can now run clang with -stdlib=libc++. + + +.. _libcxxrt_ref: + +Using libcxxrt on Linux +------------------------ + +You will need to keep the source tree of `libcxxrt`_ available +on your build machine and your copy of the libcxxrt shared library must +be placed where your linker will find it. + +We can now run CMake like: + +.. code-block:: bash + + $ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \ + -DLIBCXX_CXX_ABI=libcxxrt \ + -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_INSTALL_PREFIX=/usr \ + <libc++-source-directory> + $ make cxx + $ make install + +Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as +clang is set up to link for libc++ linked to libsupc++. To get around this +you'll have to set up your linker yourself (or patch clang). For example, + +.. code-block:: bash + + $ clang++ -stdlib=libc++ helloworld.cpp \ + -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc + +Alternately, you could just add libcxxrt to your libraries list, which in most +situations will give the same result: + +.. code-block:: bash + + $ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt + +.. _`libcxxrt`: https://github.com/pathscale/libcxxrt/ + + +Using a local ABI library installation +--------------------------------------- + +.. warning:: + This is not recommended in almost all cases. + +These instructions should only be used when you can't install your ABI library. + +Normally you must link libc++ against a ABI shared library that the +linker can find. If you want to build and test libc++ against an ABI +library not in the linker's path you needq to set +``-DLIBCXX_CXX_ABI_LIBRARY_PATH=/path/to/abi/lib`` when configuring CMake. + +An example build using libc++abi would look like: + +.. code-block:: bash + + $ CC=clang CXX=clang++ cmake \ + -DLIBCXX_CXX_ABI=libc++abi \ + -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/path/to/libcxxabi/include" \ + -DLIBCXX_CXX_ABI_LIBRARY_PATH="/path/to/libcxxabi-build/lib" \ + path/to/libcxx + $ make + +When testing libc++ LIT will automatically link against the proper ABI +library. diff --git a/lib/libcxx/docs/CMakeLists.txt b/lib/libcxx/docs/CMakeLists.txt new file mode 100644 index 00000000000..f63ee00a5a0 --- /dev/null +++ b/lib/libcxx/docs/CMakeLists.txt @@ -0,0 +1,9 @@ + +if (LLVM_ENABLE_SPHINX) + if (SPHINX_FOUND) + include(AddSphinxTarget) + if (${SPHINX_OUTPUT_HTML}) + add_sphinx_target(html libcxx) + endif() + endif() +endif()
\ No newline at end of file diff --git a/lib/libcxx/docs/DesignDocs/ABIVersioning.rst b/lib/libcxx/docs/DesignDocs/ABIVersioning.rst new file mode 100644 index 00000000000..5960dd18610 --- /dev/null +++ b/lib/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/lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst b/lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst new file mode 100644 index 00000000000..73378a21c0a --- /dev/null +++ b/lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst @@ -0,0 +1,88 @@ +======================================================= +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 dependant 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 prependend to the installed +__config header. By manually prepending the files we avoid the cost of an +extra #include and we allow the __config header to be ignorant of the extra +configuration all together. An example "__config" header generated when +-DLIBCXX_ENABLE_THREADS=OFF is given to CMake would look something like: + +.. code-block:: cpp + + //===----------------------------------------------------------------------===// + // + // The LLVM Compiler Infrastructure + // + // This file is dual licensed under the MIT and the University of Illinois Open + // Source Licenses. See LICENSE.TXT for details. + // + //===----------------------------------------------------------------------===// + + #ifndef _LIBCPP_CONFIG_SITE + #define _LIBCPP_CONFIG_SITE + + /* #undef _LIBCPP_HAS_NO_GLOBAL_FILESYSTEM_NAMESPACE */ + /* #undef _LIBCPP_HAS_NO_STDIN */ + /* #undef _LIBCPP_HAS_NO_STDOUT */ + #define _LIBCPP_HAS_NO_THREADS + /* #undef _LIBCPP_HAS_NO_MONOTONIC_CLOCK */ + /* #undef _LIBCPP_HAS_NO_THREAD_UNSAFE_C_FUNCTIONS */ + + #endif + // -*- C++ -*- + //===--------------------------- __config ---------------------------------===// + // + // The LLVM Compiler Infrastructure + // + // This file is dual licensed under the MIT and the University of Illinois Open + // Source Licenses. See LICENSE.TXT for details. + // + //===----------------------------------------------------------------------===// + + #ifndef _LIBCPP_CONFIG + #define _LIBCPP_CONFIG diff --git a/lib/libcxx/docs/Makefile.sphinx b/lib/libcxx/docs/Makefile.sphinx new file mode 100644 index 00000000000..2ca1e4d3faf --- /dev/null +++ b/lib/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 = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext default + +default: html + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @# FIXME: Remove this `cp` once HTML->Sphinx transition is completed. + @# Kind of a hack, but HTML-formatted docs are on the way out anyway. + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + diff --git a/lib/libcxx/docs/README.txt b/lib/libcxx/docs/README.txt new file mode 100644 index 00000000000..06d94f5b5fc --- /dev/null +++ b/lib/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/lib/libcxx/docs/TestingLibcxx.rst b/lib/libcxx/docs/TestingLibcxx.rst new file mode 100644 index 00000000000..9226ae17023 --- /dev/null +++ b/lib/libcxx/docs/TestingLibcxx.rst @@ -0,0 +1,200 @@ +============== +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:: std=<standard version> + + **Values**: c++98, c++03, c++11, c++14, c++1z + + 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 enviroment variable LIBCXX_SITE_CONFIG. + +.. option:: --libcxx_headers=<path/to/headers> + + Specify the libc++ 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_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`. This option cannot be used + when use_system_lib is provided. + +.. option:: --use_system_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:: --no_default_flags=<bool> + + **Default**: False + + Disable all default compile and link flags from being added. When this + option is used only flags specified using the compile_flags and link_flags + will be used. + +.. option:: --compile_flags="<list-of-args>" + + Specify additional compile flags as a space delimited string. + Note: This options should not be used to change the standard version used. + +.. option:: --link_flags="<list-of-args>" + + Specify additional link flags as a space delimited string. + +.. option:: --debug_level=<level> + + **Values**: 0, 1 + + Enable the use of debug mode. Level 0 enables assertions and level 1 enables + assertions and debugging of iterator misuse. + +.. option:: use_sanitizer=<sanitizer name> + + **Values**: Memory, MemoryWithOrigins, Address, Undefined + + Run the tests using the given sanitizer. If LLVM_USE_SANITIZER was given when + building libc++ then that sanitizer will be used by default. + +.. option:: color_diagnostics + + Enable the use of colorized compile diagnostics. If the color_diagnostics + option is specified or the environment variable LIBCXX_COLOR_DIAGNOSTICS is + present then color diagnostics will be enabled. + + +Environment Variables +--------------------- + +.. envvar:: LIBCXX_SITE_CONFIG=<path/to/lit.site.cfg> + + Specify the site configuration to use when running the tests. + Also see :option:`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 :option:`color_diagnostics`. diff --git a/lib/libcxx/docs/UsingLibcxx.rst b/lib/libcxx/docs/UsingLibcxx.rst new file mode 100644 index 00000000000..514ed14b746 --- /dev/null +++ b/lib/libcxx/docs/UsingLibcxx.rst @@ -0,0 +1,125 @@ +============ +Using libc++ +============ + +.. contents:: + :local: + +Getting Started +=============== + +If you already have libc++ installed you can use it with clang. + +.. code-block:: bash + + $ clang++ -stdlib=libc++ test.cpp + $ clang++ -std=c++11 -stdlib=libc++ test.cpp + +On OS X and FreeBSD libc++ is the default standard library +and the ``-stdlib=libc++`` is not required. + +.. _alternate libcxx: + +If you want to select an alternate installation of libc++ you +can use the following options. + +.. code-block:: bash + + $ clang++ -std=c++11 -stdlib=libc++ -nostdinc++ \ + -I<libcxx-install-prefix>/include/c++/v1 \ + -L<libcxx-install-prefix>/lib \ + -Wl,-rpath,<libcxx-install-prefix>/lib \ + test.cpp + +The option ``-Wl,-rpath,<libcxx-install-prefix>/lib`` adds a runtime library +search path. Meaning that the systems dynamic linker will look for libc++ in +``<libcxx-install-prefix>/lib`` whenever the program is run. Alternatively the +environment variable ``LD_LIBRARY_PATH`` (``DYLD_LIBRARY_PATH`` on OS X) can +be used to change the dynamic linkers search paths after a program is compiled. + +An example of using ``LD_LIBRARY_PATH``: + +.. code-block:: bash + + $ clang++ -stdlib=libc++ -nostdinc++ \ + -I<libcxx-install-prefix>/include/c++/v1 + -L<libcxx-install-prefix>/lib \ + test.cpp -o + $ ./a.out # Searches for libc++ in the systems library paths. + $ export LD_LIBRARY_PATH=<libcxx-install-prefix>/lib + $ ./a.out # Searches for libc++ along LD_LIBRARY_PATH + +Using 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. + +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>`_. diff --git a/lib/libcxx/docs/conf.py b/lib/libcxx/docs/conf.py new file mode 100644 index 00000000000..e385406b992 --- /dev/null +++ b/lib/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-2016, 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 = '3.9' +# The full version, including alpha/beta/rc tags. +release = '3.9' + +# 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 configration. +intersphinx_mapping = {} + + +# -- Options for extensions ---------------------------------------------------- + +# Enable this if you want TODOs to show up in the generated documentation. +todo_include_todos = True diff --git a/lib/libcxx/docs/index.rst b/lib/libcxx/docs/index.rst new file mode 100644 index 00000000000..b0c8b813f57 --- /dev/null +++ b/lib/libcxx/docs/index.rst @@ -0,0 +1,185 @@ +.. _index: + +============================= +"libc++" C++ Standard Library +============================= + +Overview +======== + +libc++ is a new implementation of the C++ standard library, targeting C++11. + +* 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 + + UsingLibcxx + BuildingLibcxx + TestingLibcxx + + +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-4.2 and +clang (lack of C++11 language support disables some functionality). +Note that functionality provided by ``<atomic>`` is only functional with clang +and GCC. + +============ ==================== ============ ======================== +OS Arch Compilers ABI Library +============ ==================== ============ ======================== +Mac OS X i386, x86_64 Clang, GCC libc++abi +FreeBSD 10+ i386, x86_64, ARM Clang, GCC libcxxrt, libc++abi +Linux i386, x86_64 Clang, GCC libc++abi +============ ==================== ============ ======================== + +The following minimum compiler versions are strongly recommended. + +* Clang 3.5 and above +* GCC 4.7 and above. + +Anything older *may* work. + +C++ Dialect Support +--------------------- + +* C++11 - Complete +* `C++14 - Complete <http://libcxx.llvm.org/cxx1y_status.html>`__ +* `C++1z - In Progress <http://libcxx.llvm.org/cxx1z_status.html>`__ +* `Post C++14 Technical Specifications - In Progress <http://libcxx.llvm.org/ts1z_status.html>`__ + +Notes and Known Issues +---------------------- + +This list contains known issues with libc++ + +* Building libc++ with ``-fno-rtti`` is not supported. However + linking against it with ``-fno-rtti`` is supported. +* On OS X v10.8 and older the CMake option ``-DLIBCXX_LIBCPPABI_VERSION=""`` + must be used during configuration. + + +A full list of currently open libc++ bugs can be `found here`__. + +.. __: https://llvm.org/bugs/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/CapturingConfigInfo + DesignDocs/ABIVersioning + + +* `<atomic> design <http://libcxx.llvm.org/atomic_design.html>`_ +* `<type_traits> design <http://libcxx.llvm.org/type_traits_design.html>`_ +* `Status of debug mode <http://libcxx.llvm.org/debug_mode.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/>`_ +* `EricWF's Nightly Builders <http://ds2.efcs.ca:8080/console>`_ +* `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 `cfe-dev mailing list`_ or on IRC. +Please include "libc++" in your subject. + +**Patches** + +If you want to contribute a patch to libc++, the best place for that is +`Phabricator <http://llvm.org/docs/Phabricator.html>`_. Please include [libcxx] in the subject and +add `cfe-commits` as a subscriber. Also make sure you are subscribed to the +`cfe-commits mailing list <http://lists.llvm.org/mailman/listinfo/cfe-commits>`_. + +**Discussion and Questions** + +Send discussions and questions to the +`cfe-dev mailing list <http://lists.llvm.org/mailman/listinfo/cfe-dev>`_. +Please include [libcxx] in the subject. + + + +Quick Links +=========== +* `LLVM Homepage <http://llvm.org/>`_ +* `libc++abi Homepage <http://libcxxabi.llvm.org/>`_ +* `LLVM Bugzilla <http://llvm.org/bugs/>`_ +* `cfe-commits Mailing List`_ +* `cfe-dev Mailing List`_ +* `Browse libc++ -- SVN <http://llvm.org/svn/llvm-project/libcxx/trunk/>`_ +* `Browse libc++ -- ViewVC <http://llvm.org/viewvc/llvm-project/libcxx/trunk/>`_ |