[Buildroot] [PATCH 5/9] manual: faq: add workaround to avoid rebuilding the buildroot toolchain after each clean

[Thomas Petazzoni <thomas.petazzoni@free-electrons.com>]

Dear Samuel Martin,

On Wed, 13 Feb 2013 23:59:06 +0100, Samuel Martin wrote:
> 
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
> ---
>  docs/manual/common-usage.txt        |  1 +
>  docs/manual/faq-troubleshooting.txt | 34 ++++++++++++++++++++++++++++++++++
>  2 files changed, 35 insertions(+)
> 
> diff --git a/docs/manual/common-usage.txt b/docs/manual/common-usage.txt
> index c7f511a..b36965f 100644
> --- a/docs/manual/common-usage.txt
> +++ b/docs/manual/common-usage.txt
> @@ -20,6 +20,7 @@ all sources that you previously selected in the configurator
>  You can now disconnect or copy the content of your +dl+
>  directory to the build-host.
>  
> +[[daily-oot-build]]
>  Building out-of-tree
>  ~~~~~~~~~~~~~~~~~~~~
>  
> diff --git a/docs/manual/faq-troubleshooting.txt b/docs/manual/faq-troubleshooting.txt
> index 8b0882a..f367275 100644
> --- a/docs/manual/faq-troubleshooting.txt
> +++ b/docs/manual/faq-troubleshooting.txt
> @@ -147,3 +147,37 @@ Using the internal Buildroot toolchain backend
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
>  These toolchains are currently *not relocatable*.
> +
> +However, it is possible to build a toolchain using the internal Buildroot
> +backend in another location (see xref:daily-oot-build[]), then use it as an
> +_external_ one to prevent from rebuilding it after issuing +make clean+
> +(see xref:faq-avoid-rebuild-toolchain[]).
> +
> +[[faq-avoid-rebuild-toolchain]]
> +How to avoid always rebuilding the toolchain?
> +---------------------------------------------
> +
> +When using the internal Buildroot toolchain backend or the
> +http://crosstool-ng.org[crosstool-NG] one, runnong +make clean+ not only
> +remove the built binaries, but also the whole toolchain.
> +
> +It is possible to prevent this by, first, building the toolchain in a
> +place different from the one  where the images will be built.
> +
> +To do so:
> +
> +1. Build the toolchain somewhere:
> ++
> +----------------------------
> +make toolchain O=/path/to/toolchain
> +----------------------------
> ++
> +1. Use this pre-built toolchain as an external one in a new and clean
> +   build (see xref:external-toolchain-backend[]) with a different output
> +   directory than the pre-built toolchain one.
> +
> +This way, you will not have to rebuild the toolchain after invoking
> ++make clean+.
> +
> +However, the toolchain should be regenerated after any change of the
> ++Target Architecture+ (or its _variant_), or done in the +Toolchain+ menu.

I think this text is misleading, because it suggests that the only way
to avoid rebuilding the toolchain over and over again is to build a
toolchain with Buildroot, and then use it as an external toolchain in
Buildroot. There are other options that are possible:
 * Use Crosstool-NG outside of Buildroot to generate a toolchain
 * Use a pre-built toolchain

I have the feeling that this new text doesn't articulate very well with
the text that was added in 401d323698266468e322471530ee1997835fc335.

We have to be careful to not add a set of random facts in the manual
one after the other, without keeping a consistency and ordering on the
different parts of the manual.

Thomas
-- 
Thomas Petazzoni, Free Electrons
Kernel, drivers, real-time and embedded Linux
development, consulting, training and support.
http://free-electrons.com