01/01: doc: Explain how to use the GCC toolchain.

[Ricardo Wurmus]

rekado pushed a commit to branch master
in repository guix.

commit 2f0c4b82843ab41793b675267ede13c169399f86
Author: Ricardo Wurmus <address@hidden>
Date:   Fri Jun 16 09:55:00 2017 +0200

    doc: Explain how to use the GCC toolchain.
    
    * doc/guix.texi (Application Setup): Add subsection "The GCC toolchain".
---
 doc/guix.texi | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index 97fa1b7..cb5821e 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -1441,6 +1441,30 @@ some reason, you want to avoid auto-loading Emacs 
packages installed
 with Guix, you can do so by running Emacs with @code{--no-site-file}
 option (@pxref{Init File,,, emacs, The GNU Emacs Manual}).
 
address@hidden The GCC toolchain
+
address@hidden GCC
address@hidden ld-wrapper
+
+Guix offers individual compiler packages such as @code{gcc} but if you
+are in need of a complete toolchain for compiling and linking source
+code what you really want is the @code{gcc-toolchain} package.  This
+package provides a complete GCC toolchain for C/C++ development,
+including GCC itself, the GNU C Library (headers and binaries, plus
+debugging symbols in the @code{debug} output), Binutils, and a linker
+wrapper.
+
address@hidden attempt to use impure library, error message
+
+The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches
+passed to the linker, add corresponding @code{-rpath} arguments, and
+invoke the actual linker with this new set of arguments.  By default,
+the linker wrapper refuses to link to libraries outside the store to
+ensure ``purity''.  This can be annoying when using the toolchain to
+link with local libraries.  To allow references to libraries outside the
+store you need to define the environment variable
address@hidden
+
 @c TODO What else?
 
 @c *********************************************************************