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