1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc: 3 4[[migrating-from-ol-versions]] 5== Migrating from older Buildroot versions 6 7Some versions have introduced backward incompatibilities. This section 8explains those incompatibilities, and for each explains what to do to 9complete the migration. 10 11[[migrating-approach]] 12=== General approach 13 14To migrate from an older Buildroot version, take the following steps. 15 16. For all your configurations, do a build in the old Buildroot 17 environment. Run +make graph-size+. Save 18 +graphs/file-size-stats.csv+ in a different location. Run +make 19 clean+ to remove the rest. 20. Review the specific migration notes below and make the required 21 adaptations to external packages and custom build scripts. 22. Update Buildroot. 23. Run +make menuconfig+ starting from the existing +.config+. 24. If anything is enabled in the Legacy menu, check its help text, 25 unselect it, and save the configuration. 26. For more details, review the git commit messages for the packages that 27 you need. Change into the +packages+ directory and run 28 +git log <old version>.. -- <your packages>+. 29. Build in the new Buildroot environment. 30. Fix build issues in external packages (usually due to updated 31 dependencies). 32. Run +make graph-size+. 33. Compare the new +file-size-stats.csv+ with the original one, to 34 check if no required files have disappeared and if no new big unneeded 35 files have appeared. 36. For configuration (and other) files in a custom overlay that overwrite 37 files created by Buildroot, check if there are changes in the 38 Buildroot-generated file that need to be propagated to your custom 39 file. 40 41[[br2-external-converting]] 42=== Migrating to 2016.11 43 44Before Buildroot 2016.11, it was possible to use only one br2-external 45tree at once. With Buildroot 2016.11 came the possibility to use more 46than one simultaneously (for details, see xref:outside-br-custom[]). 47 48This however means that older br2-external trees are not usable as-is. 49A minor change has to be made: adding a name to your br2-external tree. 50 51This can be done very easily in just a few steps: 52 53 * First, create a new file named +external.desc+, at the root of your 54 br2-external tree, with a single line defining the name of your 55 br2-external tree: 56+ 57---- 58$ echo 'name: NAME_OF_YOUR_TREE' >external.desc 59---- 60+ 61.Note 62Be careful when choosing a name: It has to be unique and be made 63with only ASCII characters from the set +[A-Za-z0-9_]+. 64 65 * Then, change every occurence of +BR2_EXTERNAL+ in your br2-external 66 tree with the new variable: 67+ 68---- 69$ find . -type f | xargs sed -i 's/BR2_EXTERNAL/BR2_EXTERNAL_NAME_OF_YOUR_TREE_PATH/g' 70---- 71 72Now, your br2-external tree can be used with Buildroot 2016.11 onward. 73 74.Note: 75This change makes your br2-external tree incompatible with Buildroot 76before 2016.11. 77 78[[migrating-host-usr]] 79=== Migrating to 2017.08 80 81Before Buildroot 2017.08, host packages were installed in +$(HOST_DIR)/usr+ 82(with e.g. the autotools' +--prefix=$(HOST_DIR)/usr+). With Buildroot 832017.08, they are now installed directly in +$(HOST_DIR)+. 84 85Whenever a package installs an executable that is linked with a library 86in +$(HOST_DIR)/lib+, it must have an RPATH pointing to that directory. 87 88An RPATH pointing to +$(HOST_DIR)/usr/lib+ is no longer accepted. 89