docs/manual/customize-patches.txt

   1 // -*- mode:doc -*- ;
   2 // vim: set syntax=asciidoc:
   3
   4 [[customize-patches]]
   5 === Adding project-specific patches
   6
   7 It is sometimes useful to apply 'extra' patches to packages - on top of
   8 those provided in Buildroot. This might be used to support custom
   9 features in a project, for example, or when working on a new
  10 architecture.
  11
  12 The +BR2_GLOBAL_PATCH_DIR+ configuration option can be used to specify
  13 a space separated list of one or more directories containing package
  14 patches.
  15
  16 For a specific version +<packageversion>+ of a specific package
  17 +<packagename>+, patches are applied from +BR2_GLOBAL_PATCH_DIR+ as
  18 follows:
  19
  20 . For every directory - +<global-patch-dir>+ - that exists in
  21   +BR2_GLOBAL_PATCH_DIR+, a +<package-patch-dir>+ will be determined as
  22   follows:
  23 +
  24 * +<global-patch-dir>/<packagename>/<packageversion>/+ if the
  25   directory exists.
  26 +
  27 * Otherwise, +<global-patch-dir>/<packagename>+ if the directory
  28   exists.
  29
  30 . Patches will then be applied from a +<package-patch-dir>+ as
  31   follows:
  32 +
  33 * If a +series+ file exists in the package directory, then patches are
  34   applied according to the +series+ file;
  35 +
  36 * Otherwise, patch files matching +*.patch+ are applied in
  37   alphabetical order.  So, to ensure they are applied in the right
  38   order, it is highly recommended to name the patch files like this:
  39   +<number>-<description>.patch+, where +<number>+ refers to the
  40   'apply order'.
  41
  42 For information about how patches are applied for a package, see
  43 xref:patch-apply-order[]
  44
  45 The +BR2_GLOBAL_PATCH_DIR+ option is the preferred method for
  46 specifying a custom patch directory for packages. It can be used to
  47 specify a patch directory for any package in buildroot. It should also
  48 be used in place of the custom patch directory options that are
  49 available for packages such as U-Boot and Barebox. By doing this, it
  50 will allow a user to manage their patches from one top-level
  51 directory.
  52
  53 The exception to +BR2_GLOBAL_PATCH_DIR+ being the preferred method for
  54 specifying custom patches is +BR2_LINUX_KERNEL_PATCH+.
  55 +BR2_LINUX_KERNEL_PATCH+ should be used to specify kernel patches that
  56 are available at an URL. *Note:* +BR2_LINUX_KERNEL_PATCH+ specifies kernel
  57 patches that are applied after patches available in +BR2_GLOBAL_PATCH_DIR+,
  58 as it is done from a post-patch hook of the Linux package.
  59