Author: ericwf Date: Wed Jun 1 21:16:28 2016 New Revision: 271469 URL: http://llvm.org/viewvc/llvm-project?rev=271469&view=rev Log: Update libcxx.llvm.org documentation by linking to new docs.
Summary: Currently much of the libcxx website is duplicated between the old www/ documentation and newer Sphinx docs. This patch changes the main libc++ webpage so that it links to the new documentation where possible. This means removing numerous sections from the landing page. @mclow.lists What do you think? Reviewers: mclow.lists Subscribers: cfe-commits, mclow.lists Differential Revision: http://reviews.llvm.org/D19250 Removed: libcxx/trunk/www/lit_usage.html Modified: libcxx/trunk/docs/BuildingLibcxx.rst libcxx/trunk/www/index.html Modified: libcxx/trunk/docs/BuildingLibcxx.rst URL: http://llvm.org/viewvc/llvm-project/libcxx/trunk/docs/BuildingLibcxx.rst?rev=271469&r1=271468&r2=271469&view=diff ============================================================================== --- libcxx/trunk/docs/BuildingLibcxx.rst (original) +++ libcxx/trunk/docs/BuildingLibcxx.rst Wed Jun 1 21:16:28 2016 @@ -1,3 +1,4 @@ +.. _BuildingLibcxx: =============== Building libc++ @@ -336,3 +337,72 @@ own copy of libsupc++ and this can lead $ 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. Modified: libcxx/trunk/www/index.html URL: http://llvm.org/viewvc/llvm-project/libcxx/trunk/www/index.html?rev=271469&r1=271468&r2=271469&view=diff ============================================================================== --- libcxx/trunk/www/index.html (original) +++ libcxx/trunk/www/index.html Wed Jun 1 21:16:28 2016 @@ -166,96 +166,18 @@ <p>First please review our <a href="http://llvm.org/docs/DeveloperPolicy.html";>Developer's Policy</a>. - <p> - 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 <code>libc++.1.dylib</code> in - <code>/usr/lib</code>. - </p> - - <p>To check out the code, use:</p> - - <ul> - <li><code>svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx</code></li> - </ul> - - <p> - Note that for an in-tree build, you should check out libcxx to - llvm/projects. - </p> - - <p> - The following instructions are for building libc++ on FreeBSD, Linux, or Mac - using <a href="http://libcxxabi.llvm.org/";>libc++abi</a> as the C++ ABI - library. On Linux, it is also possible to use - <a href="#libsupcxx">libsupc++</a> or <a href="#libcxxrt">libcxxrt</a>. - </p> - - <p>In-tree build:</p> - <ul> - <li><code>cd where-you-want-to-live</code></li> - <li>Check out libcxx and <a href="http://libcxxabi.llvm.org/";>libcxxabi</a> - into llvm/projects</li> - <li><code>cd where-you-want-to-build</code></li> - <li><code>mkdir build && cd build</code></li> - <li><code>cmake path/to/llvm # Linux may require -DCMAKE_C_COMPILER=clang - -DCMAKE_CXX_COMPILER=clang++</code></li> - <li><code>make cxx</code></li> - </ul> - - <p>Out-of-tree buildc:</p> - <ul> - <li><code>cd where-you-want-to-live</code></li> - <li>Check out libcxx and llvm</li> - <li>If not on a Mac, also check out - <a href="http://libcxxabi.llvm.org/";>libcxxabi</a></li> - <li><code>cd where-you-want-to-build</code></li> - <li><code>mkdir build && cd build</code></li> - <li><code>cmake -DLLVM_PATH=path/to/llvm - -DLIBCXX_CXX_ABI=libcxxabi - -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxabi/include - -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ - path/to/libcxx - </code></li> - <li><code>make</code></li> - </ul> - - <p>To run the tests:</p> - <ul> - <li><code>make check-libcxx</code></li> - </ul> - - <p>If you wish to run a subset of the test suite:</p> - <ul> - <li><code>cd path/to/libcxx/libcxx</code></li> - <li><code>alias lit='python path/to/llvm/utils/lit/lit.py'</code></li> - <li><code>export - LIBCXX_SITE_CONFIG=path/to/build/dir/projects/libcxx/test/lit.site.cfg - </code></li> - <li><code>lit -sv test/re/ # or whichever subset of tests you're interested - in</code></li> - </ul> - <p>The above is currently quite inconvenient. Sorry! We're working on it!</p> - - <p>More information on using LIT can be found - <a href="http://llvm.org/docs/CommandGuide/lit.html";>here</a>. For more - general information about the LLVM testing infrastructure, see the - <a href="http://llvm.org/docs/TestingGuide.html";>LLVM Testing Infrastructure - Guide</a> - </p> - - <p> - 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). - </p> - - <p> - Mac users, remember to be careful when replacing the system's libc++. - <strong>Your system will not be able to boot without a functioning - libc++.</strong> - </p> + The documentation for building and using libc++ can be found below. + <ul> + <li><a href="http://libcxx.llvm.org/docs/UsingLibcxx.html";> + <b>Using libc++</b></a> + Documentation on using the library in your programs</li> + <li><a href="http://libcxx.llvm.org/docs/BuildingLibcxx.html";> + <b>Building libc++</b></a> + Documentation on building the library using CMake</li> + <li><a href="http://libcxx.llvm.org/docs/TestingLibcxx.html";> + <b>Testing libc++</b></a> + Documentation for developers wishing to test the library</li> + </ul> <!--=====================================================================--> <h3>Notes and Known Issues</h3> @@ -279,65 +201,6 @@ <a href="http://lists.llvm.org/mailman/listinfo/cfe-dev";>clang mailing list</a>.</p> <!--=====================================================================--> - <h2>Using libc++ in your programs</h2> - <!--=====================================================================--> - - <!--=====================================================================--> - <h3>FreeBSD and Mac OS X</h3> - <!--=====================================================================--> - - <p> - To use your system-installed libc++ with clang you can: - </p> - - <ul> - <li><code>clang++ -stdlib=libc++ test.cpp</code></li> - <li><code>clang++ -std=c++11 -stdlib=libc++ test.cpp</code></li> - </ul> - - <p> - To use your tip-of-trunk libc++ on Mac OS with clang you can: - </p> - - <ul> - <li><code>export DYLD_LIBRARY_PATH=path/to/build/lib</code> - <li><code>clang++ -std=c++11 -stdlib=libc++ -nostdinc++ - -I<path-to-libcxx>/include -L<path-to-libcxx>/lib - test.cpp</code></li> - </ul> - - <!--=====================================================================--> - <h3>Linux</h3> - <!--=====================================================================--> - - <p> - You will need to keep the source tree of - <a href="http://libcxxabi.llvm.org";>libc++abi</a> available on your build - machine and your copy of the libc++abi shared library must be placed where - your linker will find it. - </p> - - <p> - 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: - </p> - - <ul> - <li><code>clang++ -stdlib=libc++ helloworld.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc</code></li> - </ul> - - <p> - Alternately, you could just add libc++abi to your libraries list, which in - most situations will give the same result: - </p> - - <ul> - <li><code>clang++ -stdlib=libc++ helloworld.cpp -lc++abi</code></li> - </ul> - - <!--=====================================================================--> <h2>Bug reports and patches</h2> <!--=====================================================================--> @@ -355,136 +218,6 @@ </p> <!--=====================================================================--> - <h2 id="libsupcxx">Build on Linux using CMake and libsupc++.</h2> - <!--=====================================================================--> - - <p> - You will need libstdc++ in order to provide libsupc++. - </p> - - <p> - Figure out where the libsupc++ headers are on your system. On Ubuntu this - is <code>/usr/include/c++/<version></code> and - <code>/usr/include/c++/<version>/<target-triple></code> - </p> - - <p> - You can also figure this out by running - <pre> -$ 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. - </pre> - - Note the first two entries happen to be what we are looking for. This - may not be correct on other platforms. - </p> - - <p> - We can now run CMake: - <ul> - <li><code>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></code></li> - <li>You can also substitute <code>-DLIBCXX_CXX_ABI=libsupc++</code> - 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. - <li><code>make</code></li> - <li><code>sudo make install</code></li> - </ul> - <p> - You can now run clang with -stdlib=libc++. - </p> - </p> - - <!--=====================================================================--> - <h2 id="libcxxrt">Build on Linux using CMake and libcxxrt.</h2> - <!--=====================================================================--> - - <p> - You will need to keep the source tree of - <a href="https://github.com/pathscale/libcxxrt/";>libcxxrt</a> available - on your build machine and your copy of the libcxxrt shared library must - be placed where your linker will find it. - </p> - - <p> - We can now run CMake: - <ul> - <li><code>CC=clang CXX=clang++ cmake -G "Unix Makefiles" - -DLIBCXX_CXX_ABI=libcxxrt - -DLIBCXX_CXX_ABI_INCLUDE_PATHS="<libcxxrt-source-dir>/src" - -DCMAKE_BUILD_TYPE=Release - -DCMAKE_INSTALL_PREFIX=/usr - <libc++-source-dir></code></li> - <li><code>make</code></li> - <li><code>sudo make install</code></li> - </ul> - <p> - 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, - <ul> - <li><code>clang++ -stdlib=libc++ helloworld.cpp -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc</code></li> - </ul> - Alternately, you could just add libcxxrt to your libraries list, which in most - situations will give the same result: - <ul> - <li><code>clang++ -stdlib=libc++ helloworld.cpp -lcxxrt</code></li> - </ul> - </p> - </p> - - <!--=====================================================================--> - <h2 id="local-abi">Using a local ABI library</h2> - <!--=====================================================================--> - <p> - <strong>Note: This is not recommended in almost all cases.</strong><br> - Generally these instructions should only be used when you can't install - your ABI library. - </p> - <p> - 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 - <code>-DLIBCXX_CXX_ABI_LIBRARY_PATH=/path/to/abi/lib</code> when - configuring CMake. - </p> - <p> - An example build using libc++abi would look like: - <ul> - <li><code>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</code></li> - <li><code>make</code></li> - </ul> - </p> - <p> - When testing libc++ LIT will automatically link against the proper ABI - library. - </p> - - <!--=====================================================================--> <h2>Design Documents</h2> <!--=====================================================================--> @@ -493,7 +226,6 @@ End of search list. <li><a href="type_traits_design.html"><tt><type_traits></tt></a></li> <li><a href="http://cplusplusmusings.wordpress.com/2012/07/05/clang-and-standard-libraries-on-mac-os-x/";>Excellent notes by Marshall Clow</a></li> <li><a href="debug_mode.html">Status of debug mode</a></li> -<li><a href="lit_usage.html">LIT usage guide</a></li> </ul> </div> Removed: libcxx/trunk/www/lit_usage.html URL: http://llvm.org/viewvc/llvm-project/libcxx/trunk/www/lit_usage.html?rev=271468&view=auto ============================================================================== --- libcxx/trunk/www/lit_usage.html (original) +++ libcxx/trunk/www/lit_usage.html (removed) @@ -1,207 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" - "http://www.w3.org/TR/html4/strict.dtd";> -<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ --> -<html> -<head> - <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> - <title>Testing libc++ using LIT</title> - <link type="text/css" rel="stylesheet" href="menu.css"> - <link type="text/css" rel="stylesheet" href="content.css"> - <style> - .lit-option { - padding-top: 0.5em; - margin-bottom: 0.0em; - font-size: medium; - color: #2d58b7 - } - .lit-option-desc { - display: block; - margin-top: 0em; - margin-bottom: 0em; - margin-left: 20px; - margin-right: 20px; - } - </style> -</head> - -<body> -<div id="menu"> - <div> - <a href="http://llvm.org/";>LLVM Home</a> - </div> - - <div class="submenu"> - <label>libc++ Info</label> - <a href="/index.html">About</a> - </div> - - <div class="submenu"> - <label>Quick Links</label> - <a href="http://lists.llvm.org/mailman/listinfo/cfe-dev";>cfe-dev</a> - <a href="http://lists.llvm.org/mailman/listinfo/cfe-commits";>cfe-commits</a> - <a href="http://llvm.org/bugs/";>Bug Reports</a> - <a href="http://llvm.org/svn/llvm-project/libcxx/trunk/";>Browse SVN</a> - <a href="http://llvm.org/viewvc/llvm-project/libcxx/trunk/";>Browse ViewVC</a> - </div> -</div> - -<div id="content"> -<!--*********************************************************************--> - <h1>Testing libc++ using LIT</h1> -<!--*********************************************************************--> -<p> -libc++ uses LIT to configure and run its tests. The primary way to run the -libc++ tests is by using <code>make check-libcxx</code>. 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++. -</p> -<p> -Documentation for LIT can be found -<a href="http://llvm.org/docs/CommandGuide/lit.html";>here</a>. -</p> - -<!--*********************************************************************--> - <h2>Getting Started</h2> -<!--*********************************************************************--> -<p> -After building libc++ use the following commands before you start using LIT to -test. -</p> -<ul> - <li><code>alias lit='python path/to/llvm/utils/lit/lit.py'</code></li> - <li><code>export LIBCXX_SITE_CONFIG=path/to/build-libcxx/test/lit.site.cfg</code></li> -</ul> -<p> -You can now run the libc++ tests by running: -</p> -<ul> - <li><code>cd path/to/libcxx</code></li> - <li><code>lit -sv ./test</code></li> -</ul> -<p> -To only run a subsection of the tests use: -<ul> - <li><code>lit -sv test/std/numerics # Run only the numeric tests</code></li> -</ul> - -<!--*********************************************************************--> - <h2>Customization Options</h2> -<!--*********************************************************************--> -<p> -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 <code>--param NAME</code> or <code>--param NAME=VALUE</code>. Some options -have default values specified during CMake's configuration. Passing the option -on the command line will override the default. -</p> - - -<p> -<h3 class="lit-option">libcxx_site_config=<path/to/lit.site.cfg></h3> -<blockquote class="lit-option-desc"> -Specify the site configuration to use when running the tests. This option -overrides the enviroment variable <code>LIBCXX_SITE_CONFIG</code> -</blockquote> -</p> - -<p> -<h3 class="lit-option">libcxx_headers=<path/to/headers></h3> -<blockquote class="lit-option-desc"> -Specify the libc++ headers that are tested. By default the headers in the source -tree are used. -</blockquote> -</p> - -<p> -<h3 class="lit-option">libcxx_library=<path/to/libc++.so></h3> -<blockquote class="lit-option-desc"> -Specify the libc++ library that is tested. By default the library in the build -directory is used. This option cannot be used when <code>use_system_lib</code> -is provided. -</blockquote> -</p> - -<p> -<h3 class="lit-option">use_system_lib=<bool></h3> -<blockquote class="lit-option-desc"> -<b>Default: </b><code>False</code></br> -Enable or disable testing against the installed version of libc++ library. -Note: This does not use the installed headers. -</blockquote> -</p> - -<p> -<h3 class="lit-option">use_lit_shell=<bool></h3> -<blockquote class="lit-option-desc"> -Enable or disable the use of LIT's internal shell in ShTests. If the enviroment -variable <code>LIT_USE_INTERNAL_SHELL</code> is present then that is used as the -default value. Otherwise the default value is <code>True</code> on Windows and -<code>False</code> on every other platform. -</blockquote> -</p> - -<p> -<h3 class="lit-option">no_default_flags=<bool></h3> -<blockquote class="lit-option-desc"> -<b>Default: </b><code>False</code></br> -Disable all default compile and link flags from being added. When this option is -used only flags specified using the <code>compile_flags</code> and -<code>link_flags</code> will be used. -</blockquote> -</p> - -<p> -<h3 class="lit-option">compile_flags="<list-of-args>"</h3> -<blockquote class="lit-option-desc"> -Specify additional compile flags as a space delimited string. -Note: This options should not be used to change the standard version used. -</blockquote> -</p> - -<p> -<h3 class="lit-option">link_flags="<list-of-args>"</h3> -<blockquote class="lit-option-desc"> -Specify additional link flags as a space delimited string. -</blockquote> -</p> - -<p> -<h3 class="lit-option">std=<standard version></h3> -<blockquote class="lit-option-desc"> -<b>Values: </b><code>c++98, c++03, c++11, c++14, c++1z</code></br> -Change the standard version used when building the tests. -</blockquote> -</p> - -<p> -<h3 class="lit-option">debug_level=<level></h3> -<blockquote class="lit-option-desc"> -<b>Values: </b><code>0, 1</code></br> -Enable the use of debug mode. Level 0 enables assertions and level 1 enables -assertions and debugging of iterator misuse. -</blockquote> -</p> - -<p> -<h3 class="lit-option">use_sanitizer=<sanitizer name></h3> -<blockquote class="lit-option-desc"> -<b>Values: </b><code>Memory, MemoryWithOrigins, Address, Undefined</code></br> -Run the tests using the given sanitizer. If <code>LLVM_USE_SANITIZER</code> -was given when building libc++ then that sanitizer will be used by default. -</blockquote> -</p> - -<p> -<h3 class="lit-option">color_diagnostics</h3> -<blockquote class="lit-option-desc"> -Enable the use of colorized compile diagnostics. If the -<code>color_diagnostics</code> option is specified or the enviroment variable -<code>LIBCXX_COLOR_DIAGNOSTICS</code> is present then color diagnostics will be -enabled. -</blockquote> -</p> - -</div> -</body> -</html> _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
