Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 1 | // -*- mode:doc; -*- |
Samuel Martin | 3edb027 | 2013-02-13 12:59:02 +0000 | [diff] [blame] | 2 | // vim: set syntax=asciidoc: |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 3 | |
| 4 | [[patch-policy]] |
| 5 | |
Thomas De Schampheleire | 86a415d | 2014-05-02 07:47:30 +0200 | [diff] [blame] | 6 | == Patching a package |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 7 | |
| 8 | While integrating a new package or updating an existing one, it may be |
Arnout Vandecappelle (Essensium/Mind) | 1d989fa | 2012-11-27 11:59:16 +0000 | [diff] [blame] | 9 | necessary to patch the source of the software to get it cross-built within |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 10 | Buildroot. |
| 11 | |
| 12 | Buildroot offers an infrastructure to automatically handle this during |
Simon Dawson | 5538e47 | 2013-03-17 23:13:47 +0000 | [diff] [blame] | 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. |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 16 | |
Thomas De Schampheleire | 86a415d | 2014-05-02 07:47:30 +0200 | [diff] [blame] | 17 | === Providing patches |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 18 | |
Thomas De Schampheleire | 86a415d | 2014-05-02 07:47:30 +0200 | [diff] [blame] | 19 | ==== Downloaded |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 20 | |
Peter Korsgaard | 4bfb52c | 2013-09-16 09:00:15 +0200 | [diff] [blame] | 21 | If it is necessary to apply a patch that is available for download, then add it |
Alexander Mukhin | 48934ed | 2017-09-14 17:47:42 +0300 | [diff] [blame] | 22 | to the +<packagename>_PATCH+ variable. If an entry contains +://+, |
| 23 | then Buildroot will assume it is a full URL and download the patch |
| 24 | from this location. Otherwise, Buildroot will assume that the patch should be |
| 25 | downloaded from +<packagename>_SITE+. It can be a single patch, |
| 26 | or a tarball containing a patch series. |
| 27 | |
| 28 | Like for all downloads, a hash should be added to the +<packagename>.hash+ |
| 29 | file. |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 30 | |
Arnout Vandecappelle (Essensium/Mind) | 65f66c1 | 2012-11-27 11:59:17 +0000 | [diff] [blame] | 31 | This method is typically used for packages from Debian. |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 32 | |
Thomas De Schampheleire | 86a415d | 2014-05-02 07:47:30 +0200 | [diff] [blame] | 33 | ==== Within Buildroot |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 34 | |
Simon Dawson | ecd2353 | 2012-11-16 04:54:19 +0000 | [diff] [blame] | 35 | Most patches are provided within Buildroot, in the package |
Arnout Vandecappelle (Essensium/Mind) | 1d989fa | 2012-11-27 11:59:16 +0000 | [diff] [blame] | 36 | directory; these typically aim to fix cross-compilation, libc support, |
Simon Dawson | ecd2353 | 2012-11-16 04:54:19 +0000 | [diff] [blame] | 37 | or other such issues. |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 38 | |
Yann E. MORIN | 8e7d179 | 2014-12-05 19:06:24 +0100 | [diff] [blame] | 39 | These patch files should be named +<number>-<description>.patch+. |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 40 | |
Samuel Martin | 7a26f2f | 2013-02-28 11:24:26 +0000 | [diff] [blame] | 41 | .Notes |
| 42 | - The patch files coming with Buildroot should not contain any package version |
Yann E. MORIN | 8e7d179 | 2014-12-05 19:06:24 +0100 | [diff] [blame] | 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 | |
Samuel Martin | 7a26f2f | 2013-02-28 11:24:26 +0000 | [diff] [blame] | 56 | |
Thomas De Schampheleire | 86a415d | 2014-05-02 07:47:30 +0200 | [diff] [blame] | 57 | ==== Global patch directory |
Simon Dawson | 5538e47 | 2013-03-17 23:13:47 +0000 | [diff] [blame] | 58 | |
| 59 | The +BR2_GLOBAL_PATCH_DIR+ configuration file option can be |
Ryan Barnett | b3a9393 | 2013-12-18 04:25:02 -0600 | [diff] [blame] | 60 | used to specify a space separated list of one or more directories |
Thomas De Schampheleire | 69a5343 | 2014-09-18 21:39:31 +0200 | [diff] [blame] | 61 | containing global package patches. See xref:customize-patches[] for |
Ryan Barnett | b3a9393 | 2013-12-18 04:25:02 -0600 | [diff] [blame] | 62 | details. |
Simon Dawson | 5538e47 | 2013-03-17 23:13:47 +0000 | [diff] [blame] | 63 | |
Ryan Barnett | b3a9393 | 2013-12-18 04:25:02 -0600 | [diff] [blame] | 64 | [[patch-apply-order]] |
Thomas De Schampheleire | 86a415d | 2014-05-02 07:47:30 +0200 | [diff] [blame] | 65 | === How patches are applied |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 66 | |
| 67 | . Run the +<packagename>_PRE_PATCH_HOOKS+ commands if defined; |
| 68 | |
Simon Dawson | ecd2353 | 2012-11-16 04:54:19 +0000 | [diff] [blame] | 69 | . Cleanup the build directory, removing any existing +*.rej+ files; |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 70 | |
| 71 | . If +<packagename>_PATCH+ is defined, then patches from these |
| 72 | tarballs are applied; |
| 73 | |
Ryan Barnett | b3a9393 | 2013-12-18 04:25:02 -0600 | [diff] [blame] | 74 | . If there are some +*.patch+ files in the package's Buildroot |
| 75 | directory or in a package subdirectory named +<packageversion>+, |
| 76 | then: |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 77 | + |
| 78 | * If a +series+ file exists in the package directory, then patches are |
| 79 | applied according to the +series+ file; |
| 80 | + |
Gary Bisson | fe7babe | 2016-08-09 15:33:04 +0200 | [diff] [blame] | 81 | * Otherwise, patch files matching +*.patch+ are applied in alphabetical |
| 82 | order. |
Ryan Barnett | b3a9393 | 2013-12-18 04:25:02 -0600 | [diff] [blame] | 83 | So, to ensure they are applied in the right order, it is highly |
| 84 | recommended to name the patch files like this: |
Gary Bisson | fe7babe | 2016-08-09 15:33:04 +0200 | [diff] [blame] | 85 | +<number>-<description>.patch+, where +<number>+ refers to the |
| 86 | 'apply order'. |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 87 | |
Ryan Barnett | b3a9393 | 2013-12-18 04:25:02 -0600 | [diff] [blame] | 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 | |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 92 | . Run the +<packagename>_POST_PATCH_HOOKS+ commands if defined. |
| 93 | |
| 94 | If something goes wrong in the steps _3_ or _4_, then the build fails. |
| 95 | |
Thomas De Schampheleire | 86a415d | 2014-05-02 07:47:30 +0200 | [diff] [blame] | 96 | === Format and licensing of the package patches |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 97 | |
Luca Ceresoli | 8ab41ae | 2016-02-01 23:19:53 +0100 | [diff] [blame] | 98 | Patches are released under the same license as the software they apply |
Luca Ceresoli | 2004003 | 2016-03-01 12:01:04 +0100 | [diff] [blame] | 99 | to (see xref:legal-info-buildroot[]). |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 100 | |
Simon Dawson | ecd2353 | 2012-11-16 04:54:19 +0000 | [diff] [blame] | 101 | A message explaining what the patch does, and why it is needed, should |
| 102 | be added in the header commentary of the patch. |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 103 | |
Arnout Vandecappelle (Essensium/Mind) | 65f66c1 | 2012-11-27 11:59:17 +0000 | [diff] [blame] | 104 | You should add a +Signed-off-by+ statement in the header of the each |
| 105 | patch to help with keeping track of the changes and to certify that the |
| 106 | patch is released under the same license as the software that is modified. |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 107 | |
Simon Dawson | ecd2353 | 2012-11-16 04:54:19 +0000 | [diff] [blame] | 108 | If the software is under version control, it is recommended to use the |
Arnout Vandecappelle (Essensium/Mind) | 65f66c1 | 2012-11-27 11:59:17 +0000 | [diff] [blame] | 109 | upstream SCM software to generate the patch set. |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 110 | |
| 111 | Otherwise, concatenate the header with the output of the |
Arnout Vandecappelle (Essensium/Mind) | 65f66c1 | 2012-11-27 11:59:17 +0000 | [diff] [blame] | 112 | +diff -purN package-version.orig/ package-version/+ command. |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 113 | |
Arnout Vandecappelle | aafff45 | 2015-12-02 23:13:26 +0100 | [diff] [blame] | 114 | If you update an existing patch (e.g. when bumping the package version), |
| 115 | make sure the existing From header and Signed-off-by tags are not |
| 116 | removed, but do update the rest of the patch comment when appropriate. |
| 117 | |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 118 | At the end, the patch should look like: |
| 119 | |
| 120 | --------------- |
| 121 | configure.ac: add C++ support test |
| 122 | |
Ralph Siemsen | f7da9ee | 2013-09-16 09:07:28 -0400 | [diff] [blame] | 123 | Signed-off-by: John Doe <john.doe@noname.org> |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 124 | |
| 125 | --- configure.ac.orig |
| 126 | +++ configure.ac |
| 127 | @@ -40,2 +40,12 @@ |
| 128 | |
| 129 | AC_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 | |
Thomas De Schampheleire | 86a415d | 2014-05-02 07:47:30 +0200 | [diff] [blame] | 142 | === Integrating patches found on the Web |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 143 | |
Simon Dawson | ecd2353 | 2012-11-16 04:54:19 +0000 | [diff] [blame] | 144 | When integrating a patch of which you are not the author, you have to |
| 145 | add a few things in the header of the patch itself. |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 146 | |
Simon Dawson | ecd2353 | 2012-11-16 04:54:19 +0000 | [diff] [blame] | 147 | Depending on whether the patch has been obtained from the project |
Samuel Martin | 6c61000 | 2012-11-11 03:14:56 +0000 | [diff] [blame] | 148 | repository itself, or from somewhere on the web, add one of the |
| 149 | following tags: |
| 150 | |
| 151 | --------------- |
| 152 | Backported from: <some commit id> |
| 153 | --------------- |
| 154 | |
| 155 | or |
| 156 | |
| 157 | --------------- |
| 158 | Fetch from: <some url> |
| 159 | --------------- |
| 160 | |
Simon Dawson | ecd2353 | 2012-11-16 04:54:19 +0000 | [diff] [blame] | 161 | It is also sensible to add a few words about any changes to the patch |
| 162 | that may have been necessary. |