cirros-testvm/src-cirros/buildroot-2015.05/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 +<packagename>-*.patch+
  77   are applied in alphabetical 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   +<packagename>-<number>-<description>.patch+, where +<number>+
  81   refers to the '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 that is
  94 modified.
  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 At the end, the patch should look like:
 110
 111 ---------------
 112 configure.ac: add C++ support test
 113
 114 Signed-off-by: John Doe <john.doe@noname.org>
 115
 116 --- configure.ac.orig
 117 +++ configure.ac
 118 @@ -40,2 +40,12 @@
 119
 120 AC_PROG_MAKE_SET
 121 +
 122 +AC_CACHE_CHECK([whether the C++ compiler works],
 123 +               [rw_cv_prog_cxx_works],
 124 +               [AC_LANG_PUSH([C++])
 125 +                AC_LINK_IFELSE([AC_LANG_PROGRAM([], [])],
 126 +                               [rw_cv_prog_cxx_works=yes],
 127 +                               [rw_cv_prog_cxx_works=no])
 128 +                AC_LANG_POP([C++])])
 129 +
 130 +AM_CONDITIONAL([CXX_WORKS], [test "x$rw_cv_prog_cxx_works" = "xyes"])
 131 ---------------
 132
 133 === Integrating patches found on the Web
 134
 135 When integrating a patch of which you are not the author, you have to
 136 add a few things in the header of the patch itself.
 137
 138 Depending on whether the patch has been obtained from the project
 139 repository itself, or from somewhere on the web, add one of the
 140 following tags:
 141
 142 ---------------
 143 Backported from: <some commit id>
 144 ---------------
 145
 146 or
 147
 148 ---------------
 149 Fetch from: <some url>
 150 ---------------
 151
 152 It is also sensible to add a few words about any changes to the patch
 153 that may have been necessary.