[docs] Add a big section with details about how to go about acquiring

a more modern host C++ toolchain for Linux distros where folks sometimes
don't have a good option to get one as part of their system.

This is a first cut, so feedback, testing, and suggestions are very,
very welcom. This is one of the last real documentation changes that was
specifically requested prior to switching LLVM and Clang to build in
C++11 mode by default.

llvm-svn: 202486

docs/GettingStarted.rst

@@ -275,6 +275,71 @@ contained `a bug <http://gcc.gnu.org/bugzilla/show_bug.cgi?id=53841>`__ which
 causes Clang to refuse to compile condition_variable header file.  At the time
 of writing, this breaks LLD build.
 
+Getting a Modern Host C++ Toolchain
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This section mostly applies to Linux and BSDs. On Mac OS X, you should have
+a sufficiently modern Xcode, or you will likely need to upgrade until you do.
+On Windows, just use Visual Studio 2012 as the host compiler, it is explicitly
+supported and widely available.
+
+However, on Linux and BSDs there are some notable distributions which have
+extremely old versions of GCC. These steps attempt to help you upgrade you
+compiler even on such a system. However, if at all possible, we encourage you
+to use a recent version of a distribution with a modern system compiler that
+meets these requirements. Note that it is tempting to to install a prior
+version of Clang and libc++ to be the host compiler, however libc++ was not
+well tested or set up to build on Linux until relatively recently. As
+a consequence, this guide suggests just using libstdc++ and a modern GCC as the
+initial host in a bootstrap, and then using Clang (and potentially libc++).
+
+The first step is to get a recent GCC toolchain installed. The most common
+distribution on which users have struggled with the version requirements is
+Ubuntu Precise, 12.04 LTS. For this distribution, one easy option is to install
+the `toolchain testing PPA
+<https://launchpad.net/~ubuntu-toolchain-r/+archive/test>` and use it to
+install a modern GCC. There is a really nice discussions of this on the `ask
+ubuntu stack exchange
+<http://askubuntu.com/questions/271388/how-to-install-gcc-4-8-in-ubuntu-12-04-from-the-terminal>`.
+However, not all users can use PPAs and there are many other distros, so it may
+be necessory (or just useful, if you're here you *are* doing compiler
+development after all) to build and install GCC from source. It is also quite
+easy to do these days.
+
+Easy steps for installing GCC 4.8.2:
+
+.. code-block:: console
+
+  wget ftp://ftp.gnu.org/gnu/gcc/gcc-4.8.2/gcc-4.8.2.tar.bz2
+  tar -xvjf gcc-4.8.2.tar.bz2
+  cd gcc-4.8.2
+  ./contrib/download_prerequisites
+  cd ..
+  mkdir gcc-4.8.2-build
+  cd gcc-4.8.2-build
+  %PWD/../gcc-4.8.2/configure --prefix=$HOME/toolchains --enable-languages=c,c++
+  make -j$(nproc)
+  make install
+
+For more details, check out the `excellent GCC wiki entry
+<http://gcc.gnu.org/wiki/InstallingGCC>`, where I got most of this information
+from.
+
+Once you have a GCC toolchain, use it as your host compiler. Things should
+generally "just work". You may need to pass a special linker flag,
+``-Wl,-rpath,$HOME/toolchains/lib`` or some variant thereof to get things to
+find the libstdc++ DSO in this toolchain.
+
+When you build Clang, you will need to give *it* access to modern C++11
+standard library in order to use it as your new host in part of a bootstrap.
+There are two easy ways to do this, either build (and install) libc++ along
+with Clang and then use it with the ``-stdlib=libc++`` compile and link flag,
+or install Clang into the same prefix (``$HOME/toolchains`` above) as GCC.
+Clang will look within its own prefix for libstdc++ and use it if found. You
+can also add an explicit prefix for Clang to look in for a GCC toolchain with
+the ``--gcc-toolchain=/opt/my/gcc/prefix`` flag, passing it to both compile and
+link commands when using your just-built-Clang to bootstrap.
+
 .. _Getting Started with LLVM:
 
 Getting Started with LLVM