docs/manual/patch-policy.txt

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