[llvm] r214565 - docs: Strongly recommend setting rpath when using a local GCC toolchain

[Reid Kleckner]

Author: rnk
Date: Fri Aug  1 16:40:53 2014
New Revision: 214565

URL: http://llvm.org/viewvc/llvm-project?rev=214565&view=rev
Log:
docs: Strongly recommend setting rpath when using a local GCC toolchain

Users keep emailing us about the difficulties of getting LD_LIBRARY_PATH
into their environment, which should be completely unecessary. Try to
strengthen the rpath recommentation by putting in an example cmake
invocation.

Speaking of which, we might want to make CMake the recommended build
system in GettingStarted.html.

Modified:
    llvm/trunk/docs/GettingStarted.rst

Modified: llvm/trunk/docs/GettingStarted.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/GettingStarted.rst?rev=214565&r1=214564&r2=214565&view=diff
==============================================================================
--- llvm/trunk/docs/GettingStarted.rst (original)
+++ llvm/trunk/docs/GettingStarted.rst Fri Aug  1 16:40:53 2014
@@ -331,10 +331,23 @@ of this information from.
 .. _GCC wiki entry:
   http://gcc.gnu.org/wiki/InstallingGCC
 
-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.
+Once you have a GCC toolchain, configure your build of LLVM to use the new
+toolchain for your host compiler and C++ standard library. Because the new
+version of libstdc++ is not on the system library search path, you need to pass
+extra linker flags so that it can be found at link time (``-L``) and at runtime
+(``-rpath``). If you are using CMake, this invocation should produce working
+binaries:
+
+.. code-block:: console
+
+  % mkdir build
+  % cd build
+  % CC=$HOME/toolchains/bin/gcc CXX=$HOME/toolchains/bin/g++ \
+    cmake .. -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$HOME/toolchains/lib64 -L$HOME/toolchains/lib64"
+
+If you fail to set rpath, most LLVM binaries will fail on startup with a message
+from the loader similar to ``libstdc++.so.6: version `GLIBCXX_3.4.20' not
+found``. This means you need to tweak the -rpath linker flag.
 
 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.