[4/9] manual: add information about buildroot toolchain not being relocable and put some hints to use it

Signed-off-by: A.R.D. <contact@team-ard.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>

---
Changes v2 -> v3:
- rephrase how to use buildroot toochain as an external one

Changes v1 -> v2:
- rephrase commit message
- wrap line at 70-80 chars
- misc. typo and formating fixes
- misc. rewordings

Signed-off-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/customize-toolchain.txt | 72 +++++++++++++++++++++++++++++--------
 1 file changed, 57 insertions(+), 15 deletions(-)

Dear Samuel Martin,

This commit is again mixing a number of different things: removing
details about Crosstool-NG, improving details about the Buildroot
backend, and adding informations on re-using a Buildroot built
toolchain as an external toolchain.

We'll need to synchronize on the Crosstool-NG bits, because I have a
patch series that removes the Crosstool-NG backend entirely, and which
includes the corresponding update to the manual.

On Sat,  5 Oct 2013 21:49:09 +0200, Samuel Martin wrote:

> +It is possible to only build the toolchain by running:
> +
> +---------------------------------------
> +make toolchain
> +---------------------------------------
> +
> +To avoid to rebuild the toolchain (when using the 'internal Buildroot toolchain
> +backend') after executing +make clean+, you can build the toolchain in some
> +place, then use this prebuilt toolchain as an 'external toolchain' in another
> +buildroot configuration.
> +
> +1. Configure the toolchain using the 'internal Buildroot toolchain backend'
> +  to meet your needs:
> ++
> +---------------------------------------
> +make O=/path/to/somewhere menuconfig
> +---------------------------------------
> ++
> +1. Build the toolchain:
> ++
> +---------------------------------------
> +make O=/path/to/somewhere toolchain
> +---------------------------------------
> ++
> +1. Configure target configuration using the prebuilt toolchain as an
> +   'external toolchain':
> ++
> +---------------------------------------
> +make O=/path/to/somewhere_else menuconfig
> +---------------------------------------
> ++
> +In the 'Toolchain' menu, set:
> ++
> +* 'Toolchain type': +External toolchain+ (+BR2_TOOLCHAIN_EXTERNAL+)
> +* 'Toolchain': +Custom toolchain+ (+BR2_TOOLCHAIN_EXTERNAL_CUSTOM+)
> +* 'Toolchain origin': +Pre-installed toolchain+
> +  (+BR2_TOOLCHAIN_EXTERNAL_PREINSTALLED+)
> +* 'Toolchain path': +/path/to/somewhere/host/usr+
> +  (+BR2_TOOLCHAIN_EXTERNAL_PATH+)
> +* and set the external toolchain properties accordingly to the ones set for
> +  the prebuilt toolchain.
> ++
> +1. Build the target binaries:
> ++
> +---------------------------------------
> +make O=/path/to/somewhere_else
> +---------------------------------------
> +
> +Note that toolchains built using the 'internal Buildroot toolchain backend' are
> +*not* relocable, so if you plan to share it with other machines, you will
> +*have to* install it in the same location (i.e.: in +/path/to/somewhere+).

I am not sure this part should be in the "Customize toolchain" part.
I'm actually not sure where to put this information in the manual.

Best regards,

Thomas

Thomas,


2013/10/6 Thomas Petazzoni <thomas.petazzoni@free-electrons.com>

> Dear Samuel Martin,
>
> This commit is again mixing a number of different things: removing
> details about Crosstool-NG, improving details about the Buildroot
> backend, and adding informations on re-using a Buildroot built
> toolchain as an external toolchain.
>
Arf :( Sorry about that.


> We'll need to synchronize on the Crosstool-NG bits,

Indeed.

> because I have a
> patch series that removes the Crosstool-NG backend entirely, and which
> includes the corresponding update to the manual.
>
Well, I did this patch set WRT the current Buildroot tree state.
In case your series is merged soon, this part of the patch and the next one
(5/9) are useless.


>
> On Sat,  5 Oct 2013 21:49:09 +0200, Samuel Martin wrote:
>
> > +It is possible to only build the toolchain by running:
> > +
> > +---------------------------------------
> > +make toolchain
> > +---------------------------------------
> > +
> > +To avoid to rebuild the toolchain (when using the 'internal Buildroot
> toolchain
> > +backend') after executing +make clean+, you can build the toolchain in
> some
> > +place, then use this prebuilt toolchain as an 'external toolchain' in
> another
> > +buildroot configuration.
> > +
> > +1. Configure the toolchain using the 'internal Buildroot toolchain
> backend'
> > +  to meet your needs:
> > ++
> > +---------------------------------------
> > +make O=/path/to/somewhere menuconfig
> > +---------------------------------------
> > ++
> > +1. Build the toolchain:
> > ++
> > +---------------------------------------
> > +make O=/path/to/somewhere toolchain
> > +---------------------------------------
> > ++
> > +1. Configure target configuration using the prebuilt toolchain as an
> > +   'external toolchain':
> > ++
> > +---------------------------------------
> > +make O=/path/to/somewhere_else menuconfig
> > +---------------------------------------
> > ++
> > +In the 'Toolchain' menu, set:
> > ++
> > +* 'Toolchain type': +External toolchain+ (+BR2_TOOLCHAIN_EXTERNAL+)
> > +* 'Toolchain': +Custom toolchain+ (+BR2_TOOLCHAIN_EXTERNAL_CUSTOM+)
> > +* 'Toolchain origin': +Pre-installed toolchain+
> > +  (+BR2_TOOLCHAIN_EXTERNAL_PREINSTALLED+)
> > +* 'Toolchain path': +/path/to/somewhere/host/usr+
> > +  (+BR2_TOOLCHAIN_EXTERNAL_PATH+)
> > +* and set the external toolchain properties accordingly to the ones set
> for
> > +  the prebuilt toolchain.
> > ++
> > +1. Build the target binaries:
> > ++
> > +---------------------------------------
> > +make O=/path/to/somewhere_else
> > +---------------------------------------
> > +
> > +Note that toolchains built using the 'internal Buildroot toolchain
> backend' are
> > +*not* relocable, so if you plan to share it with other machines, you
> will
> > +*have to* install it in the same location (i.e.: in
> +/path/to/somewhere+).
>
> I am not sure this part should be in the "Customize toolchain" part.
> I'm actually not sure where to put this information in the manual.
>
Hmm... I'm not entirely convinced myself by putting this here.
Could be included in the response of faq entry...

How about that?
"How to avoid rebuild toolchain after 'make clean'?"
Use a prebuilt toolchain with the external toolchain backend.
This prebuilt toolchain can be:
- one of the list BR already supports
- one retrieved by some other way
- one built outside BR  with crosstool-NG
- one built using the internal BR backend somewhere else (the above
solution)

Anyway, all opinion about this is welcome.


Regards,

Hi Samuel,

Here are some comments on the current version of the patch. Maybe some
parts will be altered after the comments of ThomasP, but anyway...

On Sat, Oct 5, 2013 at 9:49 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> Signed-off-by: A.R.D. <contact@team-ard.com>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> ---
> Changes v2 -> v3:
> - rephrase how to use buildroot toochain as an external one
>
> Changes v1 -> v2:
> - rephrase commit message
> - wrap line at 70-80 chars
> - misc. typo and formating fixes
> - misc. rewordings
>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
> ---
>  docs/manual/customize-toolchain.txt | 72 +++++++++++++++++++++++++++++--------
>  1 file changed, 57 insertions(+), 15 deletions(-)
>
> diff --git a/docs/manual/customize-toolchain.txt b/docs/manual/customize-toolchain.txt
> index 82ecc28..324afd2 100644
> --- a/docs/manual/customize-toolchain.txt
> +++ b/docs/manual/customize-toolchain.txt
> @@ -31,28 +31,70 @@ set the environment variable BR_DEBUG_WRAPPER to either one of:
>  Using the internal Buildroot toolchain backend
>  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> -The internal Buildroot toolchain backend *only* allows to generate
> -*http://www.uclibc.org/[uClibc]-based toolchains*.
> +The internal Buildroot toolchain backend allows to generate any C-library-based
> +toolchains. 'eglibc' and 'glibc' -based toolchain generation support is still
> +experimental in Buildroot

'any' is a bold statement. Apparently there now exists a musl C
library, and until Thomas' patches we did not have support for it. So
I would rephrase to:

The internal Buildroot toolchain backend allows to generate toolchains
based on uClibc, glibc and eglibc. Generation of (e)glibc-based
toolchains is still experimental in Buildroot.

(and when the musl patches are merged, we would add musl here too).

>
> -However, it allows to tune major settings, such as:
> +It allows to tune major settings, such as:
>
>  * Linux headers version;
>
> -* http://www.uclibc.org/[uClibc] configuration (see xref:uclibc-custom[uClibc]);
> +* C library configuration (only available for
> +  http://www.uclibc.org/[uClibc], see xref:uclibc-custom[uClibc]);
>
>  * Binutils, GCC, Gdb and toolchain options.
>
>  These settings are available after selecting the +Buildroot toolchain+ type in
>  the menu +Toolchain+.
>
> -Using the Crosstool-NG backend
> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> -
> -The http://crosstool-ng.org[crosstool-NG] toolchain backend enables a rather
> -limited set of settings under the Buildroot +Toolchain+ menu:
> -
> -* The http://crosstool-ng.org[crosstool-NG] configuration file
> -
> -* Gdb and some toolchain options
> -
> -Then, the toolchain can be fine-tuned by invoking +make ctng-menuconfig+.
> +It is possible to only build the toolchain by running:
> +
> +---------------------------------------
> +make toolchain
> +---------------------------------------
> +
> +To avoid to rebuild the toolchain (when using the 'internal Buildroot toolchain
> +backend') after executing +make clean+, you can build the toolchain in some
> +place, then use this prebuilt toolchain as an 'external toolchain' in another
> +buildroot configuration.

I would rephrase as:
To avoid rebuilding the toolchain after executing +make clean+ (when
using the internal Buildroot toolchain backend), you can build the
toolchain in one location, then use this prebuilt toolchain ...

(note that I explicitly removed the apostrophes ' around internal
Buildroot toolchain backend; I don't think this is needed).

> +
> +1. Configure the toolchain using the 'internal Buildroot toolchain backend'

same comment on apostrophes

> +  to meet your needs:
> ++
> +---------------------------------------
> +make O=/path/to/somewhere menuconfig
> +---------------------------------------
> ++
> +1. Build the toolchain:
> ++
> +---------------------------------------
> +make O=/path/to/somewhere toolchain
> +---------------------------------------
> ++
> +1. Configure target configuration using the prebuilt toolchain as an
> +   'external toolchain':
> ++
> +---------------------------------------
> +make O=/path/to/somewhere_else menuconfig
> +---------------------------------------
> ++
> +In the 'Toolchain' menu, set:
> ++
> +* 'Toolchain type': +External toolchain+ (+BR2_TOOLCHAIN_EXTERNAL+)
> +* 'Toolchain': +Custom toolchain+ (+BR2_TOOLCHAIN_EXTERNAL_CUSTOM+)
> +* 'Toolchain origin': +Pre-installed toolchain+
> +  (+BR2_TOOLCHAIN_EXTERNAL_PREINSTALLED+)
> +* 'Toolchain path': +/path/to/somewhere/host/usr+
> +  (+BR2_TOOLCHAIN_EXTERNAL_PATH+)
> +* and set the external toolchain properties accordingly to the ones set for
> +  the prebuilt toolchain.

according

> ++
> +1. Build the target binaries:
> ++
> +---------------------------------------
> +make O=/path/to/somewhere_else
> +---------------------------------------
> +
> +Note that toolchains built using the 'internal Buildroot toolchain backend' are

apostrophes

> +*not* relocable, so if you plan to share it with other machines, you will
> +*have to* install it in the same location (i.e.: in +/path/to/somewhere+).

relocatable

and I would rephrase as:
..., so if you plan to use these toolchains on different machines, you
will ...... in the same location (..) on every machine.

Best regards,
Thomas