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