New users should be using the runtimes dir, not projects

[jroelofs]

Summary

Somewhat tangentially, is it time to deprecate building them from the projects dir?

[beanz]

The docs changes look good to me. I think if we want to deprecate llvm/projects for runtime libraries, we should have a discussion on llvm-dev & cfe-dev. I think too few people are using llvm/runtimes today as part of their regular builds for me to feel comfortable deprecating llvm/projects without giving some notice first and getting more people to try the runtimes directory.

[tstellar]

You should also update the test-release.sh script to use this new convention.

[jroelofs]

In D40734#942352, @beanz wrote:

The docs changes look good to me. I think if we want to deprecate llvm/projects for runtime libraries, we should have a discussion on llvm-dev & cfe-dev. I think too few people are using llvm/runtimes today as part of their regular builds for me to feel comfortable deprecating llvm/projects without giving some notice first and getting more people to try the runtimes directory.

Yeah, wasn't proposing hashing that out in this thread. Definitely agree.

In D40734#942360, @tstellar wrote:

You should also update the test-release.sh script to use this new convention.

Good call! I'll do that in another patch. Might take a week or so for me to get some spare cycles to do that.

docs/GettingStarted.rst

#. Checkout Polly Loop Optimizer **[Optional]**:
 
    * ``cd where-you-want-llvm-to-live``
    * ``cd llvm/tools``
    * ``svn co http://llvm.org/svn/llvm-project/polly/trunk polly``
 
 #. Checkout Compiler-RT (required to build the sanitizers) **[Optional]**:
 
    * ``cd where-you-want-llvm-to-live``
-   * ``cd llvm/projects``
+   * ``cd llvm/runtimes``
    * ``svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk compiler-rt``
 
 #. Checkout Libomp (required for OpenMP support) **[Optional]**:
 
    * ``cd where-you-want-llvm-to-live``
-   * ``cd llvm/projects``
+   * ``cd llvm/runtimes``
    * ``svn co http://llvm.org/svn/llvm-project/openmp/trunk openmp``
 
 #. Checkout libcxx and libcxxabi **[Optional]**:
 
    * ``cd where-you-want-llvm-to-live``
-   * ``cd llvm/projects``
+   * ``cd llvm/runtimes``
    * ``svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx``
    * ``svn co http://llvm.org/svn/llvm-project/libcxxabi/trunk libcxxabi``
 
 #. Get the Test Suite Source Code **[Optional]**
 
    * ``cd where-you-want-llvm-to-live``
    * ``cd llvm/projects``
    * ``svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite``
.. code-block:: console
 
   % cd llvm/tools
   % git clone https://git.llvm.org/git/clang.git/
 
 If you want to check out compiler-rt (required to build the sanitizers), run:
 
 .. code-block:: console
 
-  % cd llvm/projects
+  % cd llvm/runtimes
   % git clone https://git.llvm.org/git/compiler-rt.git/
 
 If you want to check out libomp (required for OpenMP support), run:
 
 .. code-block:: console
 
-  % cd llvm/projects
+  % cd llvm/runtimes
   % git clone https://git.llvm.org/git/openmp.git/
 
 If you want to check out libcxx and libcxxabi (optional), run:
 
 .. code-block:: console
 
-  % cd llvm/projects
+  % cd llvm/runtimes
   % git clone https://git.llvm.org/git/libcxx.git/
   % git clone https://git.llvm.org/git/libcxxabi.git/
 
 If you want to check out the Test Suite Source Code (optional), run:
 
 .. code-block:: console
 
   % cd llvm/projects

 
 ``llvm/projects``
 -----------------
 
 Projects not strictly part of LLVM but shipped with LLVM. This is also the
 directory for creating your own LLVM-based projects which leverage the LLVM
 build system.
 
+``llvm/runtimes``
+-----------------
+
+Runtime components that are linked against code generated by llvm. Placing the
+source of projects like ``libcxx`` and ``libunwind`` in this directory allows
+them to be built automatically during the llvm build, and they are built by the
+just-built clang, rather than the host compiler.
+
+
 ``llvm/test``
 -------------
 
 Feature and regression tests and other sanity checks on LLVM infrastructure. These
 are intended to run quickly and cover a lot of territory without being exhaustive.
 
 ``test-suite``
 --------------