migrating.txt 3.2 KB

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