From: Thomas De Schampheleire Date: Thu, 18 Sep 2014 19:39:31 +0000 (+0200) Subject: manual/user guide/customization: rename section 'Customizing packages' X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=69a5343bfb8369c88d2c70b18c635318065d7075;p=buildroot.git manual/user guide/customization: rename section 'Customizing packages' This small patch renames the section 'Customizing packages' to 'Adding project-specific patches'. Additionally, a minor change is done to the introduction of this section. To better reflect the contents, the source file is renamed. Signed-off-by: Thomas De Schampheleire Signed-off-by: Thomas Petazzoni --- diff --git a/docs/manual/customize-packages.txt b/docs/manual/customize-packages.txt deleted file mode 100644 index b4ed0b5a42..0000000000 --- a/docs/manual/customize-packages.txt +++ /dev/null @@ -1,96 +0,0 @@ -// -*- mode:doc -*- ; - -[[packages-custom]] -=== Customizing packages - -It is sometimes useful to apply 'extra' patches to packages - over and -above those provided in Buildroot. This might be used to support custom -features in a project, for example, or when working on a new architecture. - -The +BR2_GLOBAL_PATCH_DIR+ configuration option can be used to specify -a space separated list of one or more directories containing package -patches. By specifying multiple global patch directories, a user could -implement a layered approach to patches. This could be useful when a -user has multiple boards that share a common processor architecture. -It is often the case that a subset of patches for a package need to be -shared between the different boards a user has. However, each board -may require specific patches for the package that build on top of the -common subset of patches. - -For a specific version ++ of a specific package -++, patches are applied from +BR2_GLOBAL_PATCH_DIR+ as -follows: - -. For every directory - ++ - that exists in - +BR2_GLOBAL_PATCH_DIR+, a ++ will be determined as - follows: -+ -* +///+ if the - directory exists. -+ -* Otherwise, +/+ if the directory - exists. - -. Patches will then be applied from a ++ as - follows: -+ -* 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: - +--.patch+, where ++ - refers to the 'apply order'. - -For information about how patches are applied for a package, see -xref:patch-apply-order[] - -The +BR2_GLOBAL_PATCH_DIR+ option is the preferred method for -specifying a custom patch directory for packages. It can be used to -specify a patch directory for any package in buildroot. It should also -be used in place of the custom patch directory options that are -available for packages such as U-Boot and Barebox. By doing this, it -will allow a user to manage their patches from one top-level -directory. - -The exception to +BR2_GLOBAL_PATCH_DIR+ being the preferred method for -specifying custom patches is +BR2_LINUX_KERNEL_PATCH+. -+BR2_LINUX_KERNEL_PATCH+ should be used to specify kernel patches that -are available at an URL. *Note:* +BR2_LINUX_KERNEL_PATCH+ specifies kernel -patches that are applied after patches available in +BR2_GLOBAL_PATCH_DIR+, -as it is done from a post-patch hook of the Linux package. - -An example directory structure for where a user has multiple -directories specified for +BR2_GLOBAL_PATCH_DIR+ may look like this: - ------ -board/ -+-- common-fooarch -| +-- patches -| +-- linux -| | +-- linux-patch1.patch -| | +-- linux-patch2.patch -| +-- uboot -| +-- foopkg -+-- fooarch-board - +-- patches - +-- linux - | +-- linux-patch3.patch - +-- uboot - +-- foopkg ------ - -If the user has the +BR2_GLOBAL_PATCH_DIR+ configuration option set as -follows: - ------ -BR2_GLOBAL_PATCH_DIR="board/common-fooarch/patches board/fooarch-board/patches" ------ - -Then the patches would applied as follows for the Linux kernel: - -. board/common-fooarch/patches/linux/linux-patch1.patch -. board/common-fooarch/patches/linux/linux-patch2.patch -. board/fooarch-board/patches/linux/linux-patch3.patch diff --git a/docs/manual/customize-patches.txt b/docs/manual/customize-patches.txt new file mode 100644 index 0000000000..279d0794fc --- /dev/null +++ b/docs/manual/customize-patches.txt @@ -0,0 +1,97 @@ +// -*- mode:doc -*- ; + +[[customize-patches]] +=== Adding project-specific patches + +It is sometimes useful to apply 'extra' patches to packages - on top of +those provided in Buildroot. This might be used to support custom +features in a project, for example, or when working on a new +architecture. + +The +BR2_GLOBAL_PATCH_DIR+ configuration option can be used to specify +a space separated list of one or more directories containing package +patches. By specifying multiple global patch directories, a user could +implement a layered approach to patches. This could be useful when a +user has multiple boards that share a common processor architecture. +It is often the case that a subset of patches for a package need to be +shared between the different boards a user has. However, each board +may require specific patches for the package that build on top of the +common subset of patches. + +For a specific version ++ of a specific package +++, patches are applied from +BR2_GLOBAL_PATCH_DIR+ as +follows: + +. For every directory - ++ - that exists in + +BR2_GLOBAL_PATCH_DIR+, a ++ will be determined as + follows: ++ +* +///+ if the + directory exists. ++ +* Otherwise, +/+ if the directory + exists. + +. Patches will then be applied from a ++ as + follows: ++ +* 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: + +--.patch+, where ++ + refers to the 'apply order'. + +For information about how patches are applied for a package, see +xref:patch-apply-order[] + +The +BR2_GLOBAL_PATCH_DIR+ option is the preferred method for +specifying a custom patch directory for packages. It can be used to +specify a patch directory for any package in buildroot. It should also +be used in place of the custom patch directory options that are +available for packages such as U-Boot and Barebox. By doing this, it +will allow a user to manage their patches from one top-level +directory. + +The exception to +BR2_GLOBAL_PATCH_DIR+ being the preferred method for +specifying custom patches is +BR2_LINUX_KERNEL_PATCH+. ++BR2_LINUX_KERNEL_PATCH+ should be used to specify kernel patches that +are available at an URL. *Note:* +BR2_LINUX_KERNEL_PATCH+ specifies kernel +patches that are applied after patches available in +BR2_GLOBAL_PATCH_DIR+, +as it is done from a post-patch hook of the Linux package. + +An example directory structure for where a user has multiple +directories specified for +BR2_GLOBAL_PATCH_DIR+ may look like this: + +----- +board/ ++-- common-fooarch +| +-- patches +| +-- linux +| | +-- linux-patch1.patch +| | +-- linux-patch2.patch +| +-- uboot +| +-- foopkg ++-- fooarch-board + +-- patches + +-- linux + | +-- linux-patch3.patch + +-- uboot + +-- foopkg +----- + +If the user has the +BR2_GLOBAL_PATCH_DIR+ configuration option set as +follows: + +----- +BR2_GLOBAL_PATCH_DIR="board/common-fooarch/patches board/fooarch-board/patches" +----- + +Then the patches would applied as follows for the Linux kernel: + +. board/common-fooarch/patches/linux/linux-patch1.patch +. board/common-fooarch/patches/linux/linux-patch2.patch +. board/fooarch-board/patches/linux/linux-patch3.patch diff --git a/docs/manual/customize.txt b/docs/manual/customize.txt index 0a73988cb3..b389d7f7c6 100644 --- a/docs/manual/customize.txt +++ b/docs/manual/customize.txt @@ -53,6 +53,6 @@ include::customize-users-tables.txt[] include::customize-post-image.txt[] -include::customize-packages.txt[] +include::customize-patches.txt[] include::customize-store.txt[] diff --git a/docs/manual/patch-policy.txt b/docs/manual/patch-policy.txt index cb39821492..745f58d283 100644 --- a/docs/manual/patch-policy.txt +++ b/docs/manual/patch-policy.txt @@ -46,7 +46,7 @@ reference in their filename. 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 +containing global package patches. See xref:customize-patches[] for details. [[patch-apply-order]]