This is an archive of the discontinued LLVM Phabricator instance.

Differential D19250

Update libcxx.llvm.org documentation by linking to new docs.
ClosedPublic

Authored by EricWF on Apr 18 2016, 6:17 PM.

Details

Reviewers
mclow.lists
Commits
rGe44604aec73c: Update libcxx.llvm.org documentation by linking to new docs.
rCXX271469: Update libcxx.llvm.org documentation by linking to new docs.
rL271469: 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?

Diff Detail

Event Timeline

EricWF updated this revision to Diff 54144.Apr 18 2016, 6:17 PM
EricWF retitled this revision from to Update libcxx.llvm.org documentation by linking to new docs..
EricWF updated this object.
EricWF added a reviewer: mclow.lists.
EricWF added a subscriber: mclow.lists.
EricWF added a subscriber: cfe-commits.
EricWF added a comment.May 24 2016, 12:53 AM

Ping. Marshall do you have any objections to this change.

mclow.lists accepted this revision.Jun 1 2016, 7:18 PM
mclow.lists edited edge metadata.

LGTM.

This revision is now accepted and ready to land.Jun 1 2016, 7:18 PM
EricWF closed this revision.Jun 1 2016, 7:22 PM

Revision Contents

PathSize
docs/
70 lines
www/
292 lines

Diff 54144

docs/BuildingLibcxx.rst

.. _BuildingLibcxx:
=============== ===============
Building libc++ Building libc++
Context not available.
$ make install $ make install
You can now run clang with -stdlib=libc++. 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.
No newline at end of file
Context not available.

www/index.html

Context not available.
<p>First please review our <p>First please review our
<a href="http://llvm.org/docs/DeveloperPolicy.html">Developer's Policy</a>. <a href="http://llvm.org/docs/DeveloperPolicy.html">Developer's Policy</a>.
<p> The documentation for building and using libc++ can be found below.
On Mac OS 10.7 (Lion) and later, the easiest way to get this library is to install <ul>
Xcode 4.2 or later. However if you want to install tip-of-trunk from here <li><a href="http://libcxx.llvm.org/docs/UsingLibcxx.html">
(getting the bleeding edge), read on. However, be warned that Mac OS <b>Using libc++</b></a>
10.7 will not boot without a valid copy of <code>libc++.1.dylib</code> in Documentation on using the library in your programs</li>
<code>/usr/lib</code>. <li><a href="http://libcxx.llvm.org/docs/BuildingLibcxx.html">
</p> <b>Building libc++</b></a>
Documentation on building the library using CMake</li>
<p>To check out the code, use:</p> <li><a href="http://libcxx.llvm.org/docs/TestingLibcxx.html">
<b>Testing libc++</b></a>
<ul> Documentation for developers wishing to test the library</li>
<li><code>svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx</code></li> </ul>
</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 &amp;&amp; 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 &amp;&amp; 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>
<!--=====================================================================--> <!--=====================================================================-->
<h3>Notes and Known Issues</h3> <h3>Notes and Known Issues</h3>
Context not available.
<a href="http://lists.llvm.org/mailman/listinfo/cfe-dev">clang mailing list</a>.</p> <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&lt;path-to-libcxx&gt;/include -L&lt;path-to-libcxx&gt;/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> <h2>Bug reports and patches</h2>
<!--=====================================================================--> <!--=====================================================================-->
Context not available.
</p> </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++/&lt;version&gt;</code> and
<code>/usr/include/c++/&lt;version&gt;/&lt;target-triple&gt;</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 &lt;...&gt; 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
&lt;libc++-source-dir&gt;</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="&lt;libcxxrt-source-dir&gt;/src"
-DCMAKE_BUILD_TYPE=Release
-DCMAKE_INSTALL_PREFIX=/usr
&lt;libc++-source-dir&gt;</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> <h2>Design Documents</h2>
<!--=====================================================================--> <!--=====================================================================-->
Context not available.
<li><a href="type_traits_design.html"><tt>&lt;type_traits&gt;</tt></a></li> <li><a href="type_traits_design.html"><tt>&lt;type_traits&gt;</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="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="debug_mode.html">Status of debug mode</a></li>
<li><a href="lit_usage.html">LIT usage guide</a></li>
</ul> </ul>
</div> </div>
Context not available.

www/lit_usage.html

  • This file was deleted.
<!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=&lt;path/to/lit.site.cfg&gt;</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=&lt;path/to/headers&gt;</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=&lt;path/to/libc++.so&gt;</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=&lt;bool&gt;</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=&lt;bool&gt;</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=&lt;bool&gt;</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="&lt;list-of-args&gt;"</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="&lt;list-of-args&gt;"</h3>
<blockquote class="lit-option-desc">
Specify additional link flags as a space delimited string.
</blockquote>
</p>
<p>
<h3 class="lit-option">std=&lt;standard version&gt;</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=&lt;level&gt;</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=&lt;sanitizer name&gt;</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>
www/index.html