Index: docs/BuildingLibcxx.rst =================================================================== --- docs/BuildingLibcxx.rst +++ docs/BuildingLibcxx.rst @@ -1,3 +1,4 @@ +.. _BuildingLibcxx: =============== Building libc++ @@ -303,3 +304,72 @@ $ 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 \ + + $ 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. \ No newline at end of file Index: www/index.html =================================================================== --- www/index.html +++ www/index.html @@ -166,96 +166,18 @@

First please review our Developer's Policy. -

- 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. However, be warned that Mac OS - 10.7 will not boot without a valid copy of libc++.1.dylib in - /usr/lib. -

- -

To check out the code, use:

- - - -

- Note that for an in-tree build, you should check out libcxx to - llvm/projects. -

- -

- The following 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 - libsupc++ or libcxxrt. -

- -

In-tree build:

- - -

Out-of-tree buildc:

- - -

To run the tests:

- - -

If you wish to run a subset of the test suite:

- -

The above is currently quite inconvenient. Sorry! We're working on it!

- -

More information on using LIT can be found - here. For more - general information about the LLVM testing infrastructure, see the - LLVM Testing Infrastructure - Guide -

- -

- Shared libraries for libc++ should now be present in llvm/build/lib. Note - that it is safest to use this from its current location rather than - replacing your system's libc++ (if it has one, if not, go right ahead). -

- -

- Mac users, remember to be careful when replacing the system's libc++. - Your system will not be able to boot without a functioning - libc++. -

+ The documentation for building and using libc++ can be found below. +

Notes and Known Issues

@@ -279,65 +201,6 @@ clang mailing list.

-

Using libc++ in your programs

- - - -

FreeBSD and Mac OS X

- - -

- To use your system-installed libc++ with clang you can: -

- - - -

- To use your tip-of-trunk libc++ on Mac OS with clang you can: -

- - - - -

Linux

- - -

- You will need to keep the source tree of - libc++abi available on your build - machine and your copy of the libc++abi shared library must be placed where - your linker will find it. -

- -

- 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: -

- - - -

- Alternately, you could just add libc++abi to your libraries list, which in - most situations will give the same result: -

- - - -

Bug reports and patches

@@ -355,136 +218,6 @@

-

Build on Linux using CMake and libsupc++.

- - -

- 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 - 

-$ 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 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: -

-

- You can now run clang with -stdlib=libc++. -

-

- - -

Build on Linux using CMake and libcxxrt.

- - -

- 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: -

-

- 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, -

- Alternately, you could just add libcxxrt to your libraries list, which in most - situations will give the same result: - -

-

- - -

Using a local ABI library

- -

- Note: This is not recommended in almost all cases.
- Generally 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: -

-

-

- When testing libc++ LIT will automatically link against the proper ABI - library. -

- -

Design Documents

@@ -493,7 +226,6 @@
  • <type_traits>
  • Excellent notes by Marshall Clow
  • Status of debug mode
    • -
  • LIT usage guide
    • Index: www/lit_usage.html =================================================================== --- www/lit_usage.html +++ /dev/null @@ -1,207 +0,0 @@ - - - - - - Testing libc++ using LIT - - - - - - - - -
    - -

    Testing libc++ using LIT

    - -

    -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++. -

    -

    -Documentation for LIT can be found -here. -

    - - -

    Getting Started

    - -

    -After building libc++ use the following commands before you start using LIT to -test. -

    - -

    -You can now run the libc++ tests by running: -

    - -

    -To only run a subsection of the tests use: -

    - - -

    Customization Options

    - -

    -libc++'s testsuite provides multiple options to configure the way the tests -are build and run. 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. -

    - - -

    -

    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 -
    -

    - -

    -

    libcxx_headers=<path/to/headers>

    -
    -Specify the libc++ headers that are tested. By default the headers in the source -tree are used. -
    -

    - -

    -

    libcxx_library=<path/to/libc++.so>

    -
    -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. -
    -

    - -

    -

    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. -
    -

    - -

    -

    use_lit_shell=<bool>

    -
    -Enable or disable the use of LIT's internal shell in ShTests. If the enviroment -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. -
    -

    - -

    -

    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. -
    -

    - -

    -

    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. -
    -

    - -

    -

    link_flags="<list-of-args>"

    -
    -Specify additional link flags as a space delimited string. -
    -

    - -

    -

    std=<standard version>

    -
    -Values: c++98, c++03, c++11, c++14, c++1z
    -Change the standard version used when building the tests. -
    -

    - -

    -

    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. -
    -

    - -

    -

    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. -
    -

    - -

    -

    color_diagnostics

    -
    -Enable the use of colorized compile diagnostics. If the -color_diagnostics option is specified or the enviroment variable -LIBCXX_COLOR_DIAGNOSTICS is present then color diagnostics will be -enabled. -
    -

    - -
    - -