[bug#27389] [PATCH] doc: Explain how to use the GCC toolchain.

[bug#27389] [PATCH] doc: Explain how to use the GCC toolchain.

[Ricardo Wurmus]

* 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 97fa1b786..b9912a440 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}).
 
+@subsection The GCC toolchain
+
+@cindex GCC
+@cindex 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 'debug' output), Binutils, and a linker
+wrapper.
+
+@cindex 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 Guix 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
+@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES}.
+
 @c TODO What else?
 
 @c *********************************************************************
-- 
2.12.2

[bug#27389] [PATCH] doc: Explain how to use the GCC toolchain.

[Ludovic Courtès]

Ricardo Wurmus <rekado@elephly.net> skribis:

> * doc/guix.texi (Application Setup): Add subsection "The GCC toolchain".

[...]

> +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

s/library/Library/

> +debugging symbols in the 'debug' output), Binutils, and a linker

s/'debug'/@code{debug}/

> +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 Guix store to

s/Guix store/store/

> +ensure purity.  This can be annoying when using the toolchain to link

s/purity/``purity''/

I’m nitpicking but I think it’s great to add this section.  Thank you!

Ludo’.

[bug#27389] [PATCH] doc: Explain how to use the GCC toolchain.

[Alex Kost]

Ricardo Wurmus (2017-06-16 09:56 +0200) wrote:

> * 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 97fa1b786..b9912a440 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}).
>  
> +@subsection The GCC toolchain
> +
> +@cindex GCC
> +@cindex 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 'debug' output), Binutils, and a linker
> +wrapper.
> +
> +@cindex 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
                                                                       ^
Shouldn't there be a comma after "By default"?  Although, I see the
absence/presence of commas in such cases is inconsistent in
"guix.texi" anyway :-(

> +linker wrapper refuses to link to libraries outside the Guix 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
> +@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES}.

Great explanation!

-- 
Alex

[bug#27389] [PATCH] doc: Explain how to use the GCC toolchain.

[Ricardo Wurmus]

Alex Kost <alezost@gmail.com> writes:

>> +
>> +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
>                                                                        ^
> Shouldn't there be a comma after "By default"?  Although, I see the
> absence/presence of commas in such cases is inconsistent in
> "guix.texi" anyway :-(

Thanks, I’ve added the comma.

-- 
Ricardo

GPG: BCA6 89B6 3655 3801 C3C6  2150 197A 5888 235F ACAC
https://elephly.net

bug#27389: [PATCH] doc: Explain how to use the GCC toolchain.

[Ricardo Wurmus]

Ludovic Courtès <ludo@gnu.org> writes:

> I’m nitpicking but I think it’s great to add this section.  Thank you!

Thanks for the suggestions.  I’ve pushed the patch as 2f0c4b828 after
making the requested changes.

-- 
Ricardo
  
  GPG: BCA6 89B6 3655 3801 C3C6  2150 197A 5888 235F ACAC
  https://elephly.net