86a415df8a
Asciidoc supports two syntaxes for section titles: two-line titles (title
plus underline consisting of a particular symbol), and one-line titles
(title prefixed with a specific number of = signs).
The two-line title underlines are:
Level 0 (top level): ======================
Level 1: ----------------------
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level): ++++++++++++++++++++++
and the one-line title prefixes:
= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
The buildroot manual is currenly using the two-line titles, but this has
multiple disadvantages:
- asciidoc also uses some of the underline symbols for other purposes (like
preformatted code, example blocks, ...), which makes it difficult to do
mass replacements, such as a planned follow-up patch that needs to move
all sections one level down.
- it is difficult to remember which level a given underline symbol (=-~^+)
corresponds to, while counting = signs is easy.
This patch changes all two-level titles to one-level titles in the manual.
The bulk of the change was done with the following Python script, except for
the level 1 titles (-----) as these underlines are also used for literal
code blocks.
This patch only changes the titles, no other changes. In
adding-packages-directory.txt, I did add missing newlines between some
titles and their content.
----------------------------------------------------------------------------
#!/usr/bin/env python
import sys
import mmap
import re
for input in sys.argv[1:]:
f = open(input, 'r+')
f.flush()
s = mmap.mmap(f.fileno(), 0)
# Level 0 (top level): ====================== =
# Level 1: ---------------------- ==
# Level 2: ~~~~~~~~~~~~~~~~~~~~~~ ===
# Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ====
# Level 4 (bottom level): ++++++++++++++++++++++ =====
def replace_title(s, symbol, replacement):
pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE)
return pattern.sub(r'%s \1' % replacement, s)
new = s
new = replace_title(new, '=', '=')
new = replace_title(new, '+', '=====')
new = replace_title(new, '^', '====')
new = replace_title(new, '~', '===')
#new = replace_title(new, '-', '==')
s.seek(0)
s.write(new)
s.resize(s.tell())
s.close()
f.close()
----------------------------------------------------------------------------
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
147 lines
4.6 KiB
Plaintext
147 lines
4.6 KiB
Plaintext
// -*- 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. It is downloaded from the same site
|
|
as the package itself. It can be a single patch, or a tarball containing a
|
|
patch series.
|
|
|
|
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 +<packagename>-<number>-<description>.patch+.
|
|
|
|
A +series+ file, as used by +quilt+, may also be added in the
|
|
package directory. In that case, the +series+ file defines the patch
|
|
application order.
|
|
|
|
.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'.
|
|
|
|
==== 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:packages-custom[] 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 +<packagename>-*.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:
|
|
+<packagename>-<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 that is
|
|
modified.
|
|
|
|
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.
|
|
|
|
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"])
|
|
---------------
|
|
|
|
=== Integrating patches found on the Web
|
|
|
|
When integrating a patch of which you are not the author, you have to
|
|
add a few things in the header of the patch itself.
|
|
|
|
Depending on whether the patch has been obtained from the project
|
|
repository itself, or from somewhere on the web, add one of the
|
|
following tags:
|
|
|
|
---------------
|
|
Backported from: <some commit id>
|
|
---------------
|
|
|
|
or
|
|
|
|
---------------
|
|
Fetch from: <some url>
|
|
---------------
|
|
|
|
It is also sensible to add a few words about any changes to the patch
|
|
that may have been necessary.
|