patch-policy.txt 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162
  1. // -*- mode:doc; -*-
  2. // vim: set syntax=asciidoc:
  3. [[patch-policy]]
  4. == Patching a package
  5. While integrating a new package or updating an existing one, it may be
  6. necessary to patch the source of the software to get it cross-built within
  7. Buildroot.
  8. Buildroot offers an infrastructure to automatically handle this during
  9. the builds. It supports three ways of applying patch sets: downloaded patches,
  10. patches supplied within buildroot and patches located in a user-defined
  11. global patch directory.
  12. === Providing patches
  13. ==== Downloaded
  14. If it is necessary to apply a patch that is available for download, then add it
  15. to the +<packagename>_PATCH+ variable. If an entry contains +://+,
  16. then Buildroot will assume it is a full URL and download the patch
  17. from this location. Otherwise, Buildroot will assume that the patch should be
  18. downloaded from +<packagename>_SITE+. It can be a single patch,
  19. or a tarball containing a patch series.
  20. Like for all downloads, a hash should be added to the +<packagename>.hash+
  21. file.
  22. This method is typically used for packages from Debian.
  23. ==== Within Buildroot
  24. Most patches are provided within Buildroot, in the package
  25. directory; these typically aim to fix cross-compilation, libc support,
  26. or other such issues.
  27. These patch files should be named +<number>-<description>.patch+.
  28. .Notes
  29. - The patch files coming with Buildroot should not contain any package version
  30. reference in their filename.
  31. - The field +<number>+ in the patch file name refers to the 'apply order',
  32. and shall start at 1; It is preferred to pad the number with zeros up to 4
  33. digits, like 'git-format-patch' does. E.g.: +0001-foobar-the-buz.patch+
  34. - Previously, it was mandatory for patches to be prefixed with the name of
  35. the package, like +<package>-<number>-<description>.patch+, but that is
  36. no longer the case. Existing packages will be fixed as time passes. 'Do
  37. not prefix patches with the package name.'
  38. - Previously, a +series+ file, as used by +quilt+, could also be added in
  39. the package directory. In that case, the +series+ file defines the patch
  40. application order. This is deprecated, and will be removed in the future.
  41. 'Do not use a series file.'
  42. ==== Global patch directory
  43. The +BR2_GLOBAL_PATCH_DIR+ configuration file option can be
  44. used to specify a space separated list of one or more directories
  45. containing global package patches. See xref:customize-patches[] for
  46. details.
  47. [[patch-apply-order]]
  48. === How patches are applied
  49. . Run the +<packagename>_PRE_PATCH_HOOKS+ commands if defined;
  50. . Cleanup the build directory, removing any existing +*.rej+ files;
  51. . If +<packagename>_PATCH+ is defined, then patches from these
  52. tarballs are applied;
  53. . If there are some +*.patch+ files in the package's Buildroot
  54. directory or in a package subdirectory named +<packageversion>+,
  55. then:
  56. +
  57. * If a +series+ file exists in the package directory, then patches are
  58. applied according to the +series+ file;
  59. +
  60. * Otherwise, patch files matching +*.patch+ are applied in alphabetical
  61. order.
  62. So, to ensure they are applied in the right order, it is highly
  63. recommended to name the patch files like this:
  64. +<number>-<description>.patch+, where +<number>+ refers to the
  65. 'apply order'.
  66. . If +BR2_GLOBAL_PATCH_DIR+ is defined, the directories will be
  67. enumerated in the order they are specified. The patches are applied
  68. as described in the previous step.
  69. . Run the +<packagename>_POST_PATCH_HOOKS+ commands if defined.
  70. If something goes wrong in the steps _3_ or _4_, then the build fails.
  71. === Format and licensing of the package patches
  72. Patches are released under the same license as the software they apply
  73. to (see xref:legal-info-buildroot[]).
  74. A message explaining what the patch does, and why it is needed, should
  75. be added in the header commentary of the patch.
  76. You should add a +Signed-off-by+ statement in the header of the each
  77. patch to help with keeping track of the changes and to certify that the
  78. patch is released under the same license as the software that is modified.
  79. If the software is under version control, it is recommended to use the
  80. upstream SCM software to generate the patch set.
  81. Otherwise, concatenate the header with the output of the
  82. +diff -purN package-version.orig/ package-version/+ command.
  83. If you update an existing patch (e.g. when bumping the package version),
  84. make sure the existing From header and Signed-off-by tags are not
  85. removed, but do update the rest of the patch comment when appropriate.
  86. At the end, the patch should look like:
  87. ---------------
  88. configure.ac: add C++ support test
  89. Signed-off-by: John Doe <john.doe@noname.org>
  90. --- configure.ac.orig
  91. +++ configure.ac
  92. @@ -40,2 +40,12 @@
  93. AC_PROG_MAKE_SET
  94. +
  95. +AC_CACHE_CHECK([whether the C++ compiler works],
  96. + [rw_cv_prog_cxx_works],
  97. + [AC_LANG_PUSH([C++])
  98. + AC_LINK_IFELSE([AC_LANG_PROGRAM([], [])],
  99. + [rw_cv_prog_cxx_works=yes],
  100. + [rw_cv_prog_cxx_works=no])
  101. + AC_LANG_POP([C++])])
  102. +
  103. +AM_CONDITIONAL([CXX_WORKS], [test "x$rw_cv_prog_cxx_works" = "xyes"])
  104. ---------------
  105. === Integrating patches found on the Web
  106. When integrating a patch of which you are not the author, you have to
  107. add a few things in the header of the patch itself.
  108. Depending on whether the patch has been obtained from the project
  109. repository itself, or from somewhere on the web, add one of the
  110. following tags:
  111. ---------------
  112. Backported from: <some commit id>
  113. ---------------
  114. or
  115. ---------------
  116. Fetch from: <some url>
  117. ---------------
  118. It is also sensible to add a few words about any changes to the patch
  119. that may have been necessary.