docs/manual: rename *.txt as *.adoc
by using this standard extension `adoc`, these files are rendered on gitlab & github Signed-off-by: Francois Perrad <francois.perrad@gadz.org> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
This commit is contained in:
Francois Perrad
committed by
Thomas Petazzoni
Thomas Petazzoni
parent
b1f9c51162
commit
32cec3be97
180
docs/manual/patch-policy.adoc
Normal file
180
docs/manual/patch-policy.adoc
Normal file
@@ -0,0 +1,180 @@
|
||||
// -*- mode:doc; -*-
|
||||
// vim: set syntax=asciidoc:
|
||||
|
||||
[[patch-policy]]
|
||||
|
||||
== Patching a package
|
||||
|
||||
While integrating a new package or updating an existing one, it may be
|
||||
necessary to patch the source of the software to get it cross-built within
|
||||
Buildroot.
|
||||
|
||||
Buildroot offers an infrastructure to automatically handle this during
|
||||
the builds. It supports three ways of applying patch sets: downloaded patches,
|
||||
patches supplied within buildroot and patches located in a user-defined
|
||||
global patch directory.
|
||||
|
||||
=== Providing patches
|
||||
|
||||
==== Downloaded
|
||||
|
||||
If it is necessary to apply a patch that is available for download, then add it
|
||||
to the +<packagename>_PATCH+ variable. If an entry contains +://+,
|
||||
then Buildroot will assume it is a full URL and download the patch
|
||||
from this location. Otherwise, Buildroot will assume that the patch should be
|
||||
downloaded from +<packagename>_SITE+. It can be a single patch,
|
||||
or a tarball containing a patch series.
|
||||
|
||||
Like for all downloads, a hash should be added to the +<packagename>.hash+
|
||||
file.
|
||||
|
||||
This method is typically used for packages from Debian.
|
||||
|
||||
==== Within Buildroot
|
||||
|
||||
Most patches are provided within Buildroot, in the package
|
||||
directory; these typically aim to fix cross-compilation, libc support,
|
||||
or other such issues.
|
||||
|
||||
These patch files should be named +<number>-<description>.patch+.
|
||||
|
||||
.Notes
|
||||
- The patch files coming with Buildroot should not contain any package version
|
||||
reference in their filename.
|
||||
- The field +<number>+ in the patch file name refers to the 'apply order',
|
||||
and shall start at 1; It is preferred to pad the number with zeros up to 4
|
||||
digits, like 'git-format-patch' does. E.g.: +0001-foobar-the-buz.patch+
|
||||
- The patch email subject prefix shall not be numbered. Patches shall
|
||||
be generated with the +git format-patch -N+ command, since this
|
||||
numbering is automatically added for series. For example, the patch
|
||||
subject line should look like +Subject: [PATCH] foobar the buz+ rather
|
||||
than +Subject: [PATCH n/m] foobar the buz+.
|
||||
- Previously, it was mandatory for patches to be prefixed with the name of
|
||||
the package, like +<package>-<number>-<description>.patch+, but that is
|
||||
no longer the case. Existing packages will be fixed as time passes. 'Do
|
||||
not prefix patches with the package name.'
|
||||
- Previously, a +series+ file, as used by +quilt+, could also be added in
|
||||
the package directory. In that case, the +series+ file defines the patch
|
||||
application order. This is deprecated, and will be removed in the future.
|
||||
'Do not use a series file.'
|
||||
|
||||
|
||||
==== Global patch directory
|
||||
|
||||
The +BR2_GLOBAL_PATCH_DIR+ configuration file option can be
|
||||
used to specify a space separated list of one or more directories
|
||||
containing global package patches. See xref:customize-patches[] for
|
||||
details.
|
||||
|
||||
[[patch-apply-order]]
|
||||
=== How patches are applied
|
||||
|
||||
. Run the +<packagename>_PRE_PATCH_HOOKS+ commands if defined;
|
||||
|
||||
. Cleanup the build directory, removing any existing +*.rej+ files;
|
||||
|
||||
. If +<packagename>_PATCH+ is defined, then patches from these
|
||||
tarballs are applied;
|
||||
|
||||
. If there are some +*.patch+ files in the package's Buildroot
|
||||
directory or in a package subdirectory named +<packageversion>+,
|
||||
then:
|
||||
+
|
||||
* If a +series+ file exists in the package directory, then patches are
|
||||
applied according to the +series+ file;
|
||||
+
|
||||
* Otherwise, patch files matching +*.patch+ are applied in alphabetical
|
||||
order.
|
||||
So, to ensure they are applied in the right order, it is highly
|
||||
recommended to name the patch files like this:
|
||||
+<number>-<description>.patch+, where +<number>+ refers to the
|
||||
'apply order'.
|
||||
|
||||
. If +BR2_GLOBAL_PATCH_DIR+ is defined, the directories will be
|
||||
enumerated in the order they are specified. The patches are applied
|
||||
as described in the previous step.
|
||||
|
||||
. Run the +<packagename>_POST_PATCH_HOOKS+ commands if defined.
|
||||
|
||||
If something goes wrong in the steps _3_ or _4_, then the build fails.
|
||||
|
||||
=== Format and licensing of the package patches
|
||||
|
||||
Patches are released under the same license as the software they apply
|
||||
to (see xref:legal-info-buildroot[]).
|
||||
|
||||
A message explaining what the patch does, and why it is needed, should
|
||||
be added in the header commentary of the patch.
|
||||
|
||||
You should add a +Signed-off-by+ statement in the header of the each
|
||||
patch to help with keeping track of the changes and to certify that the
|
||||
patch is released under the same license as the software that is modified.
|
||||
|
||||
If the software is under version control, it is recommended to use the
|
||||
upstream SCM software to generate the patch set.
|
||||
|
||||
Otherwise, concatenate the header with the output of the
|
||||
+diff -purN package-version.orig/ package-version/+ command.
|
||||
|
||||
If you update an existing patch (e.g. when bumping the package version),
|
||||
make sure the existing From header and Signed-off-by tags are not
|
||||
removed, but do update the rest of the patch comment when appropriate.
|
||||
|
||||
At the end, the patch should look like:
|
||||
|
||||
---------------
|
||||
configure.ac: add C++ support test
|
||||
|
||||
Signed-off-by: John Doe <john.doe@noname.org>
|
||||
|
||||
--- configure.ac.orig
|
||||
+++ configure.ac
|
||||
@@ -40,2 +40,12 @@
|
||||
|
||||
AC_PROG_MAKE_SET
|
||||
+
|
||||
+AC_CACHE_CHECK([whether the C++ compiler works],
|
||||
+ [rw_cv_prog_cxx_works],
|
||||
+ [AC_LANG_PUSH([C++])
|
||||
+ AC_LINK_IFELSE([AC_LANG_PROGRAM([], [])],
|
||||
+ [rw_cv_prog_cxx_works=yes],
|
||||
+ [rw_cv_prog_cxx_works=no])
|
||||
+ AC_LANG_POP([C++])])
|
||||
+
|
||||
+AM_CONDITIONAL([CXX_WORKS], [test "x$rw_cv_prog_cxx_works" = "xyes"])
|
||||
---------------
|
||||
|
||||
=== Additional patch documentation
|
||||
|
||||
Ideally, all patches should document an upstream patch or patch submission, when
|
||||
applicable, via the +Upstream+ trailer.
|
||||
|
||||
When backporting an upstream patch that has been accepted into mainline, it is
|
||||
preferred that the URL to the commit is referenced:
|
||||
|
||||
---------------
|
||||
Upstream: <URL to upstream commit>
|
||||
---------------
|
||||
|
||||
If a new issue is identified in Buildroot and upstream is generally affected by
|
||||
the issue (it's not a Buildroot specific issue), users should submit the patch
|
||||
upstream and provide a link to that submission when possible:
|
||||
|
||||
---------------
|
||||
Upstream: <URL to upstream mailing list submission or merge request>
|
||||
---------------
|
||||
|
||||
Patches that have been submitted but were denied upstream should note that and
|
||||
include comments about why the patch is being used despite the upstream status.
|
||||
|
||||
Note: in any of the above scenarios, it is also sensible to add a few words
|
||||
about any changes to the patch that may have been necessary.
|
||||
|
||||
If a patch does not apply upstream then this should be noted with a comment:
|
||||
|
||||
---------------
|
||||
Upstream: N/A <additional information about why patch is Buildroot specific>
|
||||
---------------
|
||||
|
||||
Adding this documentation helps streamline the patch review process during
|
||||
package version updates.
|
||||
Reference in New Issue
Block a user