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 90[[migrating-svn-externals]] 91=== Migrating to 2023.11 92 93Before Buildroot 2023.11, the subversion download backend unconditionally 94retrieved the external references (objects with an `svn:externals` 95property). Starting with 2023.11, externals are no longer retrieved by 96default; if you need them, set +LIBFOO_SVN_EXTERNALS+ to +YES+. This 97change implies that: 98 99* the generated archive content may change, and thus the hashes may need 100 to be updated appropriately; 101* the archive version suffix has been updated to +-br3+, so the hash 102 files must be updated appropriately. 103 104Before Buildroot 2023.11, it was possible (but undocumented and unused) 105to apply architecture-specific patches, by prefixing the patch filename 106with the architecture, e.g. `0001-some-changes.patch.arm` and such a 107patch would only be applied for that architecture. With Buildroot 2023.11, 108this is no longer supported, and such patches are no longer applied at 109all. 110 111If you still need per-architecture patches, then you may provide a 112xref:hooks[pre-patch hook] that copies the patches applicable to the 113configured architecture, e.g.: 114 115---- 116define LIBFOO_ARCH_PATCHES 117 $(foreach p,$(wildcard $(LIBFOO_PKGDIR)/*.patch.$(ARCH)), \ 118 cp -f $(p) $(patsubst %.$(ARCH),%,$(p)) 119 ) 120endef 121LIBFOO_PRE_PATCH_HOOKS += LIBFOO_ARCH_PATCHES 122---- 123 124Note that no package in Buildroot has architecture-specific patches, and 125that such patches will most probably not be accepted. 126 127[[migrating-git-attributes]] 128=== Migrating to 2024.05 129 130The download backends have been extended in various ways. 131 132* All locally generated tarballs are even more reproducible. Before 133 2024.05, it was possible that the access mode of files in the archives 134 were not consistent when the download directory has specific ACLs (e.g. 135 with the +default+ ACL set). This impacts the archives generated for 136 git and subversion repositories, as well as those for vendored cargo 137 and go packages. 138* The git download backend now properly expands the `export-subst` 139 https://git-scm.com/docs/gitattributes[git attribute] when generating 140 archives. 141* A newer +tar+ version, _1.35_, is required to generate the archives. 142 For compatibility reasons, +tar+ 1.35 changes the way it stores some 143 fields (`devmajor` and `devminor`), which has an impact in the metadata 144 stored in the archives (but the content of files is not affected). 145 146To accomodate those changes, the archive suffix has been updated or 147added: 148 149* for git: +-git4+ 150* for subversion: +-svn5+ 151* for cargo (rust) packages: +-cargo2+ 152* for go packages: +-go2+ 153 154Note that, if two such prefixes would apply to a generated archive, like 155for a cargo package downloaded from git, both suffixes need to be added, 156first the one for the download mechanism, then the one for the vendoring, 157e.g.: +libfoo-1.2.3-git4-cargo2.tar.gz+. 158 159Because of this, the hash file of any custom packages or custom versions 160for kernel and bootloaders must be updated. The following sed scripts can 161automate the rename in the hash file (assuming such files are kept under 162git): 163 164---- 165# For git and svn packages, which originally had -br2 resp. -br3 suffix 166sed -r -i -e 's/-br2/-git4/; s/-br3/-svn5/' $( 167 git grep -l -E -- '-br2|-br3' -- '*.hash' 168) 169 170# For go packages, which originally had no suffix 171sed -r -i -e 's/(\.tar\.gz)$/-go2\1/' $( 172 git grep -l -E '\$\(eval \$\((host-)?golang-package\)\)' -- '*.mk' \ 173 |sed -r -e 's/\.mk$/.hash/' \ 174 |sort -u 175) 176 177# For cargo packages, which originally had no suffix 178sed -r -i -e 's/(\.tar\.gz)$/-cargo2\1/' $( 179 git grep -l -E '\$\(eval \$\((host-)?cargo-package\)\)' -- '*.mk' \ 180 |sed -r -e 's/\.mk$/.hash/' \ 181 |sort -u 182) 183---- 184 185Note that the hash _will_ have changed, so that needs to be updated 186(manually) as well. 187