diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/BuildingLibcxx.rst | 114 | ||||
| -rw-r--r-- | docs/TestingLibcxx.rst | 35 | ||||
| -rw-r--r-- | docs/UsingLibcxx.rst | 36 | ||||
| -rw-r--r-- | docs/conf.py | 6 |
4 files changed, 173 insertions, 18 deletions
diff --git a/docs/BuildingLibcxx.rst b/docs/BuildingLibcxx.rst index f00ce4f9cff1..36866b13ef7b 100644 --- a/docs/BuildingLibcxx.rst +++ b/docs/BuildingLibcxx.rst @@ -1,3 +1,4 @@ +.. _BuildingLibcxx: =============== Building libc++ @@ -6,6 +7,8 @@ Building libc++ .. contents:: :local: +.. _build instructions: + Getting Started =============== @@ -34,8 +37,7 @@ The basic steps needed to build libc++ are: #. Configure and build libc++ with libc++abi: - CMake is the only supported configuration system. Unlike other LLVM - projects autotools is not supported for either libc++ or libc++abi. + CMake is the only supported configuration system. Clang is the preferred compiler when building and using libc++. @@ -120,6 +122,18 @@ CMake docs or execute ``cmake --help-variable VARIABLE_NAME``. 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`` @@ -144,6 +158,33 @@ libc++ specific options 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 @@ -304,3 +345,72 @@ own copy of libsupc++ and this can lead to subtle problems. $ 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/docs/TestingLibcxx.rst b/docs/TestingLibcxx.rst index 98162d9c2e05..9226ae17023e 100644 --- a/docs/TestingLibcxx.rst +++ b/docs/TestingLibcxx.rst @@ -98,7 +98,7 @@ configuration. Passing the option on the command line will override the default. .. program:: lit -.. option:: cxx_under_test=<path/to/compiler> +.. option:: --cxx_under_test=<path/to/compiler> Specify the compiler used to build the tests. @@ -108,37 +108,46 @@ configuration. Passing the option on the command line will override the default. Change the standard version used when building the tests. -.. option:: libcxx_site_config=<path/to/lit.site.cfg> +.. 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> +.. option:: --libcxx_headers=<path/to/headers> Specify the libc++ headers that are tested. By default the headers in the source tree are used. -.. option:: libcxx_library=<path/to/libc++.so> +.. option:: --cxx_library_root=<path/to/lib/> - Specify the libc++ library that is tested. By default the library in the - build directory is used. This option cannot be used when use_system_lib is - provided. + 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:: use_system_lib=<bool> + +.. 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> +.. 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> +.. option:: --no_default_flags=<bool> **Default**: False @@ -146,16 +155,16 @@ configuration. Passing the option on the command line will override the default. option is used only flags specified using the compile_flags and link_flags will be used. -.. option:: compile_flags="<list-of-args>" +.. 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>" +.. option:: --link_flags="<list-of-args>" Specify additional link flags as a space delimited string. -.. option:: debug_level=<level> +.. option:: --debug_level=<level> **Values**: 0, 1 diff --git a/docs/UsingLibcxx.rst b/docs/UsingLibcxx.rst index 2a117917638c..514ed14b7464 100644 --- a/docs/UsingLibcxx.rst +++ b/docs/UsingLibcxx.rst @@ -49,7 +49,30 @@ An example of using ``LD_LIBRARY_PATH``: $ 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 ===================== @@ -87,3 +110,16 @@ not just libstdc++ so they must be manually linked. For example: $ 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/docs/conf.py b/docs/conf.py index 915daa47a514..e385406b9923 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -40,16 +40,16 @@ master_doc = 'index' # General information about the project. project = u'libc++' -copyright = u'2011-2015, LLVM Project' +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.8' +version = '3.9' # The full version, including alpha/beta/rc tags. -release = '3.8' +release = '3.9' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. |