From patchwork Tue Dec 17 09:00:27 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ryan Barnett X-Patchwork-Id: 302052 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from fraxinus.osuosl.org (fraxinus.osuosl.org [140.211.166.137]) by ozlabs.org (Postfix) with ESMTP id D6AC32C009D for ; Tue, 17 Dec 2013 20:01:09 +1100 (EST) Received: from localhost (localhost [127.0.0.1]) by fraxinus.osuosl.org (Postfix) with ESMTP id 2A7B889697; Tue, 17 Dec 2013 09:01:09 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from fraxinus.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id S_-Jx7UYiI7c; Tue, 17 Dec 2013 09:01:07 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by fraxinus.osuosl.org (Postfix) with ESMTP id 03E4E89689; Tue, 17 Dec 2013 09:01:07 +0000 (UTC) X-Original-To: buildroot@lists.busybox.net Delivered-To: buildroot@osuosl.org Received: from whitealder.osuosl.org (whitealder.osuosl.org [140.211.166.138]) by ash.osuosl.org (Postfix) with ESMTP id B6B321BFA3E for ; Tue, 17 Dec 2013 09:01:03 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by whitealder.osuosl.org (Postfix) with ESMTP id B0D8A881B5 for ; Tue, 17 Dec 2013 09:01:03 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from whitealder.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id Cq5O33TPcxI6 for ; Tue, 17 Dec 2013 09:01:03 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from secvs02.rockwellcollins.com (secvs02.rockwellcollins.com [205.175.225.241]) by whitealder.osuosl.org (Postfix) with ESMTPS id C5F878B384 for ; Tue, 17 Dec 2013 09:01:02 +0000 (UTC) Received: from nosuchhost.198.131.in-addr.arpa (HELO collinscrsmtp01.rockwellcollins.com) ([131.198.63.132]) by mail-virt.rockwellcollins.com with ESMTP; 17 Dec 2013 03:01:01 -0600 Received: from nunkun.rockwellcollins.com ([131.198.63.11]) by collinscrsmtp01.rockwellcollins.com (Lotus Domino Release 8.5.2FP2 HF162) with ESMTP id 2013121703010084-2502583 ; Tue, 17 Dec 2013 03:01:00 -0600 From: Ryan Barnett To: buildroot@busybox.net Date: Tue, 17 Dec 2013 03:00:27 -0600 Message-Id: <1387270827-4379-2-git-send-email-rjbarnet@rockwellcollins.com> X-Mailer: git-send-email 1.7.9.5 In-Reply-To: <1387270827-4379-1-git-send-email-rjbarnet@rockwellcollins.com> References: <1387270827-4379-1-git-send-email-rjbarnet@rockwellcollins.com> X-MIMETrack: Itemize by SMTP Server on CollinsCRSMTP01/CedarRapids/Collins/Rockwell(Release 8.5.2FP2 HF162|May 16, 2011) at 12/17/2013 03:01:00 AM, Serialize by Router on CollinsCRSMTP01/CedarRapids/Collins/Rockwell(Release 8.5.2FP2 HF162|May 16, 2011) at 12/17/2013 03:01:01 AM, Serialize complete at 12/17/2013 03:01:01 AM X-TNEFEvaluated: 1 Subject: [Buildroot] [PATCH v4 2/2] manual: update for multiple global patch dirs X-BeenThere: buildroot@busybox.net X-Mailman-Version: 2.1.14 Precedence: list List-Id: Discussion and development of buildroot List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: buildroot-bounces@busybox.net Sender: buildroot-bounces@busybox.net Updating the documentation to reflect that multiple directories can now be specified for BR2_GLOBAL_PATCH_DIR. Along with giving an example use case of how to use multiple global patch directories. Signed-off-by: Ryan Barnett Cc: Thomas De Schampheleire Cc: Arnout Vandecappelle --- Changes v3 -> v4: - Fixed minor spelling mistakes and wording (suggested by Arnout) - Reword section about order that patches are applied along with making it clearer about when to use BR2_GLOBAL_PATCH_DIR (suggested by Arnout) Changes v2 -> v3: - None Changes v1 -> v2: - Fixed minor spelling mistakes and wording (suggested by Thomas D) --- docs/manual/customize-packages.txt | 91 ++++++++++++++++++++++++++++++++---- docs/manual/patch-policy.txt | 20 +++++--- 2 files changed, 95 insertions(+), 16 deletions(-) diff --git a/docs/manual/customize-packages.txt b/docs/manual/customize-packages.txt index 1820c54..43ccecd 100644 --- a/docs/manual/customize-packages.txt +++ b/docs/manual/customize-packages.txt @@ -8,16 +8,89 @@ 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 file option can be -used to specify a directory containing global package patches. +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 as follows. +For a specific version ++ of a specific package +++, patches are applied from +BR2_GLOBAL_PATCH_DIR+ as +follows: -First, the default Buildroot patch set for the package is applied. +. 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. -If the directory +$(BR2_GLOBAL_PATCH_DIR)//+ -exists, then all +*.patch+ files in the directory will be applied. +. 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'. -Otherwise, if the directory +$(BR2_GLOBAL_PATCH_DIR)/+ -exists, then all +*.patch+ files in the directory will be applied. +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_PATCHES+ are applied +after patches available in +BR2_GLOBAL_PATCH_DIR+ as it is a patch +post-hook step for 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 +| +-- u-boot +| +-- foopkg ++-- fooarch-board + +-- patches + +-- linux + | +-- linux-patch3.patch + +-- u-boot + +-- foopkg +----- + +If the user has the +BR2_GLOBAL_PATCH_DIR+ configuration option set as +follows: + +----- +BR2_GLOBAL_PATCH_DIR="board/common-fooarch board/fooarch-board" +----- + +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/patch-policy.txt b/docs/manual/patch-policy.txt index d9bc8ca..9041081 100644 --- a/docs/manual/patch-policy.txt +++ b/docs/manual/patch-policy.txt @@ -50,10 +50,11 @@ Global patch directory ^^^^^^^^^^^^^^^^^^^^^^ The +BR2_GLOBAL_PATCH_DIR+ configuration file option can be -used to specify a directory containing global package patches. See -xref:packages-custom[] for details. - +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 ~~~~~~~~~~~~~~~~~~~~~~~ @@ -64,19 +65,24 @@ How patches are applied . If +_PATCH+ is defined, then patches from these tarballs are applied; -. If there are some +*.patch+ files in the package directory or in the - a package subdirectory named ++, then: +. If there are some +*.patch+ files in the package's Buildroot + directory or in a package subdirectory named ++, + 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 hightly - recommended to named the patch files like this: + 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'. +. If +BR2_GLOABL_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 +_POST_PATCH_HOOKS+ commands if defined. If something goes wrong in the steps _3_ or _4_, then the build fails.