[Buildroot] [RFC 1/2] docs/manual/migrating.txt: add section with general migrating tips
Arnout Vandecappelle
arnout at mind.be
Tue Aug 3 15:18:32 UTC 2021
On 02/08/2021 22:55, Yann E. MORIN wrote:
> 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.
Excellent. I'll remove the RFC bit from v2 then.
>
>> 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?
Mentally I assumed there would be an "old" buildroot directory with its output
directory, and a "new" buildroot directory with its distinct output directory.
But I indeed didn't write that, and in fact I don't work like that myself. So
'make clean' it is!
>> +. 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?
Excellent idea. You can easily compare the csv files.
>> +. 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.
I agree with the principle. Unfortunately, I know of no better way of getting
the "top-level" packages.
> 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.
Theoretically, graph-depends gives the top-level packages as well (i.e. the
packages that ALL points to). However, for a reasonably-sized project with about
50 top-level packages, the graph is pretty much unreadable. 'grep -w _all
graphs/graph-depends.dot' is an alternative but it's not exactly user-friendly -
and it doesn't show the selected sub-options like the defconfig does.
The defconfig isn't great either, of course. For example, it doesn't show the
sub-options that default y, and also choices aren't expressed very clearly.
Actually, the main reason I use the defconfig is that it comes for free: 'make
savedefconfig; git diff'. So maybe I should mention that instead.
Since this is a bit controversial, however, I'll just drop this point.
Regarding legal-info: if it's just about getting a list of packages, graph-size
already gives that, so I think I will talk about graph-size but not about
legal-info.
Regards,
Arnout
>
> Regards,
> Yann E. MORIN.
>
>> [[br2-external-converting]]
>> === Migrating to 2016.11
>>
>> --
>> 2.31.1
>>
>
More information about the buildroot
mailing list