blob: e704a0d3f3db06bb0f795014ae33003564c12477 [file] [log] [blame]
Samuel Martin6c610002012-11-11 03:14:56 +00001// -*- mode:doc; -*-
Samuel Martin3edb0272013-02-13 12:59:02 +00002// vim: set syntax=asciidoc:
Samuel Martin6c610002012-11-11 03:14:56 +00003
4[[patch-policy]]
5
Thomas De Schampheleire86a415d2014-05-02 07:47:30 +02006== Patching a package
Samuel Martin6c610002012-11-11 03:14:56 +00007
8While integrating a new package or updating an existing one, it may be
Arnout Vandecappelle (Essensium/Mind)1d989fa2012-11-27 11:59:16 +00009necessary to patch the source of the software to get it cross-built within
Samuel Martin6c610002012-11-11 03:14:56 +000010Buildroot.
11
12Buildroot offers an infrastructure to automatically handle this during
Simon Dawson5538e472013-03-17 23:13:47 +000013the 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.
Samuel Martin6c610002012-11-11 03:14:56 +000016
Thomas De Schampheleire86a415d2014-05-02 07:47:30 +020017=== Providing patches
Samuel Martin6c610002012-11-11 03:14:56 +000018
Thomas De Schampheleire86a415d2014-05-02 07:47:30 +020019==== Downloaded
Samuel Martin6c610002012-11-11 03:14:56 +000020
Peter Korsgaard4bfb52c2013-09-16 09:00:15 +020021If it is necessary to apply a patch that is available for download, then add it
Alexander Mukhin48934ed2017-09-14 17:47:42 +030022to 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.
Samuel Martin6c610002012-11-11 03:14:56 +000030
Arnout Vandecappelle (Essensium/Mind)65f66c12012-11-27 11:59:17 +000031This method is typically used for packages from Debian.
Samuel Martin6c610002012-11-11 03:14:56 +000032
Thomas De Schampheleire86a415d2014-05-02 07:47:30 +020033==== Within Buildroot
Samuel Martin6c610002012-11-11 03:14:56 +000034
Simon Dawsonecd23532012-11-16 04:54:19 +000035Most patches are provided within Buildroot, in the package
Arnout Vandecappelle (Essensium/Mind)1d989fa2012-11-27 11:59:16 +000036directory; these typically aim to fix cross-compilation, libc support,
Simon Dawsonecd23532012-11-16 04:54:19 +000037or other such issues.
Samuel Martin6c610002012-11-11 03:14:56 +000038
Yann E. MORIN8e7d1792014-12-05 19:06:24 +010039These patch files should be named +<number>-<description>.patch+.
Samuel Martin6c610002012-11-11 03:14:56 +000040
Samuel Martin7a26f2f2013-02-28 11:24:26 +000041.Notes
42- The patch files coming with Buildroot should not contain any package version
Yann E. MORIN8e7d1792014-12-05 19:06:24 +010043 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 Martin7a26f2f2013-02-28 11:24:26 +000056
Thomas De Schampheleire86a415d2014-05-02 07:47:30 +020057==== Global patch directory
Simon Dawson5538e472013-03-17 23:13:47 +000058
59The +BR2_GLOBAL_PATCH_DIR+ configuration file option can be
Ryan Barnettb3a93932013-12-18 04:25:02 -060060used to specify a space separated list of one or more directories
Thomas De Schampheleire69a53432014-09-18 21:39:31 +020061containing global package patches. See xref:customize-patches[] for
Ryan Barnettb3a93932013-12-18 04:25:02 -060062details.
Simon Dawson5538e472013-03-17 23:13:47 +000063
Ryan Barnettb3a93932013-12-18 04:25:02 -060064[[patch-apply-order]]
Thomas De Schampheleire86a415d2014-05-02 07:47:30 +020065=== How patches are applied
Samuel Martin6c610002012-11-11 03:14:56 +000066
67. Run the +<packagename>_PRE_PATCH_HOOKS+ commands if defined;
68
Simon Dawsonecd23532012-11-16 04:54:19 +000069. Cleanup the build directory, removing any existing +*.rej+ files;
Samuel Martin6c610002012-11-11 03:14:56 +000070
71. If +<packagename>_PATCH+ is defined, then patches from these
72 tarballs are applied;
73
Ryan Barnettb3a93932013-12-18 04:25:02 -060074. If there are some +*.patch+ files in the package's Buildroot
75 directory or in a package subdirectory named +<packageversion>+,
76 then:
Samuel Martin6c610002012-11-11 03:14:56 +000077+
78* If a +series+ file exists in the package directory, then patches are
79 applied according to the +series+ file;
80+
Gary Bissonfe7babe2016-08-09 15:33:04 +020081* Otherwise, patch files matching +*.patch+ are applied in alphabetical
82 order.
Ryan Barnettb3a93932013-12-18 04:25:02 -060083 So, to ensure they are applied in the right order, it is highly
84 recommended to name the patch files like this:
Gary Bissonfe7babe2016-08-09 15:33:04 +020085 +<number>-<description>.patch+, where +<number>+ refers to the
86 'apply order'.
Samuel Martin6c610002012-11-11 03:14:56 +000087
Ryan Barnettb3a93932013-12-18 04:25:02 -060088. 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 Martin6c610002012-11-11 03:14:56 +000092. 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
Thomas De Schampheleire86a415d2014-05-02 07:47:30 +020096=== Format and licensing of the package patches
Samuel Martin6c610002012-11-11 03:14:56 +000097
Luca Ceresoli8ab41ae2016-02-01 23:19:53 +010098Patches are released under the same license as the software they apply
Luca Ceresoli20040032016-03-01 12:01:04 +010099to (see xref:legal-info-buildroot[]).
Samuel Martin6c610002012-11-11 03:14:56 +0000100
Simon Dawsonecd23532012-11-16 04:54:19 +0000101A message explaining what the patch does, and why it is needed, should
102be added in the header commentary of the patch.
Samuel Martin6c610002012-11-11 03:14:56 +0000103
Arnout Vandecappelle (Essensium/Mind)65f66c12012-11-27 11:59:17 +0000104You 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.
Samuel Martin6c610002012-11-11 03:14:56 +0000107
Simon Dawsonecd23532012-11-16 04:54:19 +0000108If the software is under version control, it is recommended to use the
Arnout Vandecappelle (Essensium/Mind)65f66c12012-11-27 11:59:17 +0000109upstream SCM software to generate the patch set.
Samuel Martin6c610002012-11-11 03:14:56 +0000110
111Otherwise, concatenate the header with the output of the
Arnout Vandecappelle (Essensium/Mind)65f66c12012-11-27 11:59:17 +0000112+diff -purN package-version.orig/ package-version/+ command.
Samuel Martin6c610002012-11-11 03:14:56 +0000113
Arnout Vandecappelleaafff452015-12-02 23:13:26 +0100114If 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
Samuel Martin6c610002012-11-11 03:14:56 +0000118At the end, the patch should look like:
119
120---------------
121configure.ac: add C++ support test
122
Ralph Siemsenf7da9ee2013-09-16 09:07:28 -0400123Signed-off-by: John Doe <john.doe@noname.org>
Samuel Martin6c610002012-11-11 03:14:56 +0000124
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
Thomas De Schampheleire86a415d2014-05-02 07:47:30 +0200142=== Integrating patches found on the Web
Samuel Martin6c610002012-11-11 03:14:56 +0000143
Simon Dawsonecd23532012-11-16 04:54:19 +0000144When integrating a patch of which you are not the author, you have to
145add a few things in the header of the patch itself.
Samuel Martin6c610002012-11-11 03:14:56 +0000146
Simon Dawsonecd23532012-11-16 04:54:19 +0000147Depending on whether the patch has been obtained from the project
Samuel Martin6c610002012-11-11 03:14:56 +0000148repository 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
Simon Dawsonecd23532012-11-16 04:54:19 +0000161It is also sensible to add a few words about any changes to the patch
162that may have been necessary.