docs/manual/patch-policy.txt

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