[Buildroot] [RFC 1/2] docs/manual/migrating.txt: add section with general migrating tips

[Yann E. MORIN]

Arnout, All,

On 2021-08-02 18:22 +0200, Arnout Vandecappelle (Essensium/Mind) spake thusly:
> This is based on Arnout's experience with migrating Buildroot.

Except for the details, this also quite closely matches my own
experience.

> Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout at mind.be>
> ---
>  docs/manual/migrating.txt | 28 ++++++++++++++++++++++++++++
>  1 file changed, 28 insertions(+)
> 
> diff --git a/docs/manual/migrating.txt b/docs/manual/migrating.txt
> index 92e487c71e..9fd7d7e676 100644
> --- a/docs/manual/migrating.txt
> +++ b/docs/manual/migrating.txt
> @@ -8,6 +8,34 @@ Some versions have introduced backward incompatibilities. This section
>  explains those incompatibilities, and for each explains what to do to
>  complete the migration.
>  
> +[[migrating-approach]]
> +=== General approach
> +
> +To migrate from an older Buildroot version, take the following steps.
> +
> +. For all your configurations, do a build in the old Buildroot
> +  environment. Save the full +.config+ and
> +  +build/packages-file-list.txt+.

(read my comment below first, then come back here)
Maybe run 'make clean' here?

> +. Review the specific migration notes below and make the required
> +  adaptations to external packages and custom build scripts.
> +. In the new Buildroot environment, run +make menuconfig+ starting from
> +  the existing +.config+.
> +. If anything is enabled in the Legacy menu, check its help text,
> +  unselect it, and save the configuration.
> +. Review the CHANGES file to see if any of your packages and features
> +  are affected by the changes.
> +. Build in the new Buildroot environment.

Above, you said to start with a full build, so if folowing this sequence
to the letter, we still have a full build. We need to run 'make clean'
first (go back reading my comment, above).

> +. Fix build issues in external packages (usually due to updated
> +  dependencies).
> +. Compare the new +packages-file-list.txt+ with the original one, to
> +  check if no required files have disappeared.

Maybe also suggest graph-size et al. about investigating size changes,
too?

> +. For configuration (and other) files in a custom overlay that overwrite
> +  files created by Buildroot, check if there are changes in the
> +  Buildroot-generated file that need to be propagated to your custom
> +  file.
> +. Run +make savedefconfig+ and verify that what is selected really is
> +  what you intended to enable.

I am always wary instructing people to look at defconfig files; I always
consider them to be artefacts of the configuration.

Rather, I suggest people read the output of legal-info to check that all
the packages there are acceptable, and see graph-depends to see how a
package came to the build.

Regards,
Yann E. MORIN.

>  [[br2-external-converting]]
>  === Migrating to 2016.11
>  
> -- 
> 2.31.1
> 

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 561 099 427 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'