[libcxx] r271469 - Update libcxx.llvm.org documentation by linking to new docs.
Eric Fiselier via cfe-commits
cfe-commits at lists.llvm.org
Wed Jun 1 19:16:30 PDT 2016
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>
More information about the cfe-commits
mailing list