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- The patch email subject prefix shall not be numbered. Patches shall 48 be generated with the +git format-patch -N+ command, since this 49 numbering is automatically added for series. For example, the patch 50 subject line should look like +Subject: [PATCH] foobar the buz+ rather 51 than +Subject: [PATCH n/m] foobar the buz+. 52- Previously, it was mandatory for patches to be prefixed with the name of 53 the package, like +<package>-<number>-<description>.patch+, but that is 54 no longer the case. Existing packages will be fixed as time passes. 'Do 55 not prefix patches with the package name.' 56- Previously, a +series+ file, as used by +quilt+, could also be added in 57 the package directory. In that case, the +series+ file defines the patch 58 application order. This is deprecated, and will be removed in the future. 59 'Do not use a series file.' 60 61 62==== Global patch directory 63 64The +BR2_GLOBAL_PATCH_DIR+ configuration file option can be 65used to specify a space separated list of one or more directories 66containing global package patches. See xref:customize-patches[] for 67details. 68 69[[patch-apply-order]] 70=== How patches are applied 71 72. Run the +<packagename>_PRE_PATCH_HOOKS+ commands if defined; 73 74. Cleanup the build directory, removing any existing +*.rej+ files; 75 76. If +<packagename>_PATCH+ is defined, then patches from these 77 tarballs are applied; 78 79. If there are some +*.patch+ files in the package's Buildroot 80 directory or in a package subdirectory named +<packageversion>+, 81 then: 82+ 83* If a +series+ file exists in the package directory, then patches are 84 applied according to the +series+ file; 85+ 86* Otherwise, patch files matching +*.patch+ are applied in alphabetical 87 order. 88 So, to ensure they are applied in the right order, it is highly 89 recommended to name the patch files like this: 90 +<number>-<description>.patch+, where +<number>+ refers to the 91 'apply order'. 92 93. If +BR2_GLOBAL_PATCH_DIR+ is defined, the directories will be 94 enumerated in the order they are specified. The patches are applied 95 as described in the previous step. 96 97. Run the +<packagename>_POST_PATCH_HOOKS+ commands if defined. 98 99If something goes wrong in the steps _3_ or _4_, then the build fails. 100 101=== Format and licensing of the package patches 102 103Patches are released under the same license as the software they apply 104to (see xref:legal-info-buildroot[]). 105 106A message explaining what the patch does, and why it is needed, should 107be added in the header commentary of the patch. 108 109You should add a +Signed-off-by+ statement in the header of the each 110patch to help with keeping track of the changes and to certify that the 111patch is released under the same license as the software that is modified. 112 113If the software is under version control, it is recommended to use the 114upstream SCM software to generate the patch set. 115 116Otherwise, concatenate the header with the output of the 117+diff -purN package-version.orig/ package-version/+ command. 118 119If you update an existing patch (e.g. when bumping the package version), 120make sure the existing From header and Signed-off-by tags are not 121removed, but do update the rest of the patch comment when appropriate. 122 123At the end, the patch should look like: 124 125--------------- 126configure.ac: add C++ support test 127 128Signed-off-by: John Doe <john.doe@noname.org> 129 130--- configure.ac.orig 131+++ configure.ac 132@@ -40,2 +40,12 @@ 133 134AC_PROG_MAKE_SET 135+ 136+AC_CACHE_CHECK([whether the C++ compiler works], 137+ [rw_cv_prog_cxx_works], 138+ [AC_LANG_PUSH([C++]) 139+ AC_LINK_IFELSE([AC_LANG_PROGRAM([], [])], 140+ [rw_cv_prog_cxx_works=yes], 141+ [rw_cv_prog_cxx_works=no]) 142+ AC_LANG_POP([C++])]) 143+ 144+AM_CONDITIONAL([CXX_WORKS], [test "x$rw_cv_prog_cxx_works" = "xyes"]) 145--------------- 146 147=== Additional patch documentation 148 149Ideally, all patches should document an upstream patch or patch submission, when 150applicable, via the +Upstream+ trailer. 151 152When backporting an upstream patch that has been accepted into mainline, it is 153preferred that the URL to the commit is referenced: 154 155--------------- 156Upstream: <URL to upstream commit> 157--------------- 158 159If a new issue is identified in Buildroot and upstream is generally affected by 160the issue (it's not a Buildroot specific issue), users should submit the patch 161upstream and provide a link to that submission when possible: 162 163--------------- 164Upstream: <URL to upstream mailing list submission or merge request> 165--------------- 166 167Patches that have been submitted but were denied upstream should note that and 168include comments about why the patch is being used despite the upstream status. 169 170Note: in any of the above scenarios, it is also sensible to add a few words 171about any changes to the patch that may have been necessary. 172 173If a patch does not apply upstream then this should be noted with a comment: 174 175--------------- 176Upstream: N/A <additional information about why patch is Buildroot specific> 177--------------- 178 179Adding this documentation helps streamline the patch review process during 180package version updates.