[libcxx] Update libc++ docs to include instructions for LIT.

[danalbert]

Summary

Okay, so this actually does more than just that. I've rearranged most of the
information on the page to try to make it more helpful and flow better.
Essentially, the differences between Mac and Linux, the various ABI libraries,
and in-tree versus out-of-tree builds were cluttering things. To clean up, I've
done the following:

• Only describe the cmake process. buildit doesn't work out of the box on Linux, and we need to stop having duplicates for every process.
• Use libc++abi for the default instructions. This works on the major platforms.
• Describe both in-tree and out-of-tree builds. Previously it wasn't clear that in-tree builds were even possible for libc++.
• Separate the documentation about using libc++ from that about building and testing libc++.

[EricWF]

You can build libc++ in-tree? I did not know that!

1. I like that we are documenting the uniform CMake build system as the primary one. I'm not sure we should remove the buildit documentation right away though.
2. I agree that we should move towards using libc++abi as the primary ABI on linux as opposed to libsupc++ even though it must be explicitly linked.
3. I'm interested to hear what Mac users think about this patch. The documentation seems to reflect how I build and test libc++ on linux but that may not be the case on OS X.

I'll go through the actual instructions step-by-step tonight to do and in-tree build and out-of-tree build just to make sure nothing was omitted.

P.S. Sorry about hijacking this to deal with other documentation issues.

www/index.html

107–110

I don't have access to a mac with g++-4.2 but is that still supported? libc++ requires a c++11 compiler to build so I'm skeptical GCC 4.2 works.
Along the same lines I don't think the comment about lack of C++11 is correct. I think we should update this to say that a C++11 compiler is required to build libc++.

114–115

When do you think we can say we officially support linux?

155–159

While I like documenting the CMake build system as the primary one since it is uniform across all systems should we be so quick to remove the documentation for the buildit script?

202–207

I'm very happy to see these instructions make it into the documentation. Since we are encouraging people to modify the source tree can we set up SVN to ignore libcxx/test/lit.site.cfg? (ex like a .gitignore file)

[danalbert]

3. I'm interested to hear what Mac users think about this patch. The documentation seems to reflect how I build and test libc++ on linux but that may not be the case on OS X.

AIUI this works for Mac as well. It may not be what has become the typical flow for them, but this is probably more because the docs never mentioned anything other than buildit for Mac.

www/index.html

107–110

_Building_ libc++ requires a C++11 compiler (for that matter, I think it requires clang specifically). I believe this paragraph is actually about users of libc++, which is still supported for older standard versions, and from gcc.

114–115

I considered adding them. A few of the remaining test failures seem like blockers to me (though they might be innocuous, I haven't investigated).

155–159

I was wondering this myself. It's still present in the system, though perhaps that's not obvious enough. I expect that this probably has a wide range of users, but again I wonder how many of them use it simply because it was what the docs said first. As with testit, it's also non-parallel.

Anyone have a good reason we should keep it in the docs?

[thakis]

Awesome :-)

www/index.html

159–160

s/checkout/check/
(there's already an "out" right after it)

209

How much work is it to not require people to change lit.site.cfg? The ln -s is a bit gnarly, it'd be nice if it wouldn't have to be in the docs.

[mclow.lists]

Mostly good; a few comments.
I'd like to see more about using lit :-)

www/index.html

109

Typo: 'functinality'.

216

I would add something here about using DYLD_LIBRARY_PATH to interpose the newly built dylib (say, for testing purposes).

Should probably remind people that (on a Mac) blindly copying these dylibs to /usr/lib will, if any error occurs, result in a system that will not boot.

[danalbert]

www/index.html

209

I haven't really looked in to that yet. One obvious solution is to just have cmake do the symlink for you (probably by generating the lit.site.cfg in place and creating the symlink in build/test/). It'll be another patch though. I'll make sure I update the docs when I do fix this.

216

The former is down below under "Using libc++ in your programs" (not obvious from the diff, but pretty clear on the webpage). I've added the extra warning for Mac.

[danalbert]

Addressed some review comments.

[danalbert]

Ping.

[emaste]

www/index.html

114

Also:
<li>FreeBSD 10+ i386</li>
<li>FreeBSD 10+ amd64</li>
<li>FreeBSD 10+ arm</li>

I could add these in a separate commit.

164–167

on FreeBSD, Linux, or Mac

tests have some issues on FreeBSD at the moment

254

these instructions are valid for FreeBSD too

[danalbert]

emaste: Thanks. I wasn't sure about the status of this stuff for any of the BSDs.

[emaste]

@danalbert: For background, we switched to Clang + libc++ in FreeBSD 10.0 (released Jan 2014) on i386/amd64/arm. GCC and libstdc++ are not installed by default. Work is ongoing for mips, powerpc, and sparc.

[danalbert]

• Don't forget FreeBSD!

[EricWF]

LGTM.

[danalbert]

Submitted as r215358.

www/index.html

<li><p>STLport and the Apache libstdcxx library are two other popular
       released in Oct'08, and STDCXX 4.2.1 in May'08.</p>
 
     </ul>
 
   <!--=====================================================================-->
   <h2 id="requirements">Platform Support</h2>
   <!--=====================================================================-->
 
-   <p>libc++ is known to work on the following platforms, using g++-4.2 and
-      clang (lack of C++11 language support disables some functionality).</p>
+  <p>
+    libc++ is known to work on the following platforms, using g++-4.2 and
+    clang (lack of C++11 language support disables some functionality). Note
+    that functionality provided by &lt;atomic&gt; is only functional with
+    clang.
+  </p>
 
-    <ul>
-     <li>Mac OS X i386</li>
-     <li>Mac OS X x86_64</li>
-    </ul>
+    <li>FreeBSD 10+ i386</li>
+    <li>FreeBSD 10+ x86_64</li>
+    <li>FreeBSD 10+ ARM</li>
 
   <!--=====================================================================-->
   <h2 id="dir-structure">Current Status</h2>
   <!--=====================================================================-->
 
    <p>libc++ is a 100% complete C++11 implementation on Apple's OS X. </p>
    <p>LLVM and Clang can self host in C++ and C++11 mode with libc++ on Linux.</p>
    <p>libc++ is also a 100% complete C++14 implementation. A list of new features and changes for 
       C++14 can be found <a href="cxx1y_status.html">here</a>.</p>
    <p>Implementation of the post-c++14 Technical Specifications is in progress. A list of features and
       the current status of these features can be found <a href="ts1z_status.html">here</a>.</p>
    <p>
    Ports to other platforms are underway. Here are recent test
    results for <a href="results.Windows.html">Windows</a>
    and <a href="results.Linux.html">Linux</a>.
    </p>
 
   <!--=====================================================================-->
   <h2>Get it and get involved!</h2>
   <!--=====================================================================-->
 
   <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>
-     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>.
+    Note that for an in-tree build, you should check out libcxx to
+    llvm/projects.
   </p>
 
   <p>
-     Next:
+    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>Check out libcxx and <a href="http://libcxxabi.llvm.org/">libcxxabi</a>
+      into llvm/projects</li>
+    <li><code>cd llvm</code></li>
+    <li><code>mkdir build &amp;&amp; cd build</code></li>
+    <li><code>cmake .. # Linux may require -DCMAKE_C_COMPILER=clang
+        -DCMAKE_CXX_COMPILER=clang++</code></li>
+    <li><code>make cxx</code></li>
+  </ul>
+
+  <p>Out-of-tree build:</p>
+  <ul>
+    <li>Check out libcxx</li>
+    <li>If not on a Mac, also check out
+      <a href="http://libcxxabi.llvm.org/">libcxxabi</a></li>
+    <li><code>cd libcxx</code></li>
+    <li><code>mkdir build &amp;&amp; cd build</code></li>
+    <li><code>cmake -DLIBCXX_CXX_ABI=libcxxabi
+        -DLIBCXX_LIBCXXABI_INCLUDE_PATHS=path/to/libcxxabi/include
+        -DLIT_EXECUTABLE=path/to/llvm/utils/lit/lit.py .. # Linux may require
+        -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++</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 libcxx/lib</code></li>
-    <li><code>export TRIPLE=-apple-</code></li>
-    <li><code>./buildit</code></li>
-    <li><code>ln -sf libc++.1.dylib libc++.dylib</code></li>
+    <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>ln -s path/to/build/dir/projects/libcxx/test/lit.site.cfg
+        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 funcioning
+    libc++.</strong>
+  </p>
+
+  <!--=====================================================================-->
+  <h3>Notes</h3>
+  <!--=====================================================================-->
   <p>
-     That should result in a libc++.1.dylib and libc++.dylib.  The safest thing
-     to do is to use it from where your libcxx is installed instead of replacing
-     these in your Mac OS.
+    Building libc++ with <code>-fno-rtti</code> is not supported.  However
+    linking against it with <code>-fno-rtti</code> is supported.
   </p>
 
+  <p>Send discussions to the
+    <a href="http://lists.cs.uiuc.edu/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=&lt;path-to-libcxx&gt;/lib</code>
+    <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>
 
-  <p>To run the libc++ test suite (recommended):</p>
+  <!--=====================================================================-->
+  <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>cd libcxx/test</code></li>
-  <li><code>./testit</code></li>
-     <ul>
-       <li>You can alter the command line options <code>testit</code> uses
-       with <code>export OPTIONS="whatever you need"</code></li>
-     </ul>
+    <li><code>clang++ -stdlib=libc++ helloworld.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc</code></li>
   </ul>
 
-  <!--=====================================================================-->
-  <h3>Notes</h3>
-  <!--=====================================================================-->
-
   <p>
-Building libc++ with <code>-fno-rtti</code> is not supported.  However linking
-against it with <code>-fno-rtti</code> is supported.
+    Alternately, you could just add libc++abi to your libraries list, which in
+    most situations will give the same result:
   </p>
 
-  <p>Send discussions to the
-  (<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">clang mailing list</a>).</p>
+  <ul>
+    <li><code>clang++ -stdlib=libc++ helloworld.cpp -lc++abi</code></li>
+  </ul>
 
   <!--=====================================================================-->
   <h2>Bug reports and patches</h2>
   <!--=====================================================================-->
 
 <p>
 If you think you've found a bug in libc++, please report it using 
 the <a href="http://llvm.org/bugs">LLVM Bugzilla</a>. If you're not sure, you
 can post a message to the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">cfe-dev</a> 
 mailing list or on IRC. Please include "libc++" in your subject.
 </p>
 
 <p>
 If you want to contribute a patch to libc++, the best place for that is the
 <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits">cfe-commits</a> 
 mailing list. Please include "libc++" and "PATCH" in your subject.
 </p>
 
   <!--=====================================================================-->
-  <h2>Build on Linux using CMake and libsupc++.</h2>
+  <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
<ul>
        <li><code>sudo make install</code></li>
      </ul>
      <p>
         You can now run clang with -stdlib=libc++.
      </p>
   </p>
 
   <!--=====================================================================-->
-  <h2>Build on Linux using CMake and libc++abi.</h2>
-  <!--=====================================================================-->
-
-  <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>
-     We can now run CMake:
-     <ul>
-       <li><code>CC=clang CXX=clang++ cmake -G "Unix Makefiles"
-                -DLIBCXX_CXX_ABI=libcxxabi
-                -DLIBCXX_LIBCXXABI_INCLUDE_PATHS="&lt;libc++abi-source-dir&gt;/include"
-                -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++ -lc++abi -lm -lc -lgcc_s -lgcc</code></li>
-        </ul>
-        Alternately, you could just add libc++abi to your libraries list, which in most
-        situations will give the same result:
-        <ul>
-          <li><code>clang++ -stdlib=libc++ helloworld.cpp -lc++abi</code></li>
-        </ul>
-     </p>
-  </p>
-
-  <!--=====================================================================-->
-  <h2>Build on Linux using CMake and libcxxrt.</h2>
+  <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>